config-resolver

Config Resolver

Overview

Resolve the active configuration for the database coding agent by merging config file settings with per-invocation overrides, then validating governance constraints.

Resolution Order (highest priority wins)

1. Per-invocation override — extracted from the user's prompt (e.g., "use PostgreSQL with Flyway")
2. Directory mapping — from .db-agent.json directoryMapping, matched against the current file/directory
3. Auto-detection — from the db-detection skill (file extensions, config files, connection strings)
4. Config defaults — defaults.engine from .db-agent.json
5. Plugin defaults — engine module's defaults/coding-guidelines.md

Guardrails Handoff Check

Before running any governance checks, inspect the workspace root for .guardrails-agent.json.

If .guardrails-agent.json exists:

• Set internal flag guardrailsActive: true
• Skip the entire Governance section below — those checks are now handled by the policy-enforcement skill via the agent's adapter skill.
• Continue with: engine resolution, migration-tool detection, guidelines path resolution, and LSP startup only.

If .guardrails-agent.json does not exist:

• guardrailsActive: false
• Proceed with all sections below as normal (backwards-compatible mode).

Process

1. Read config file:

   • Look for .db-agent.json in the workspace root
   • If not found, skip to auto-detection (step 3)
   • Validate against JSON Schema at schemas/db-agent.schema.json

2. Check per-invocation override:

   • Parse the user's prompt for engine/framework mentions
   • Supported patterns: "in SQL Server", "using Flyway", "with Mongoose", "in PostgreSQL", "use Cosmos DB", "with Alembic"
   • If found, these take highest priority

3. Check directory mapping:

   • If the current file path matches a key in directoryMapping, use that engine
   • Match is prefix-based: file at src/postgres/migrations/001.sql matches src/postgres

4. Run auto-detection (if enabled):

   • Delegate to db-detection skill
   • Returns detected engine based on file extensions, config files, and connection string patterns in scope

5. Apply config defaults:

   • If no engine resolved yet, use defaults.engine from config

6. Resolve framework, migration tool, SDK, guidelines path:

   • Once engine is known, read its entry from engines.<engine> in config
   • If no config entry, use plugin module defaults

7. Governance validation:

   • If organization.governance.approvedEngines is set and resolved engine is NOT in the list → STOP. Surface error: "Engine <engine> is not in your organization's approved engines: [list]. Contact your admin."
   • If organization.governance.mandatoryGuidelines is true and no guidelines file exists at the resolved path → STOP. Surface error: "Mandatory guidelines file not found at <path>. Create the file or update your .db-agent.json."
   • If organization.governance.enforceLsp is true and the engine module's LSP is not installed or fails to start → STOP. Surface error: "LSP is required by org policy but is not available for <engine>. Install the @Vensure-Devops-QA/db-<engine> plugin."
   • If organization.governance.approvedFrameworks.<engine> is set and resolved framework is NOT in the list → STOP. Surface error: "Framework <framework> is not approved for <engine>. Approved: [list]."

8. Fetch org policy (if configured):

   • If organization.governance.orgPolicyEndpoint is set in config, call it:
     • GET <endpoint> with headers X-Plugin-Name: db-coding-agent, X-Plugin-Version: 1.0.0, X-Requested-Engine: <engine>, X-Requested-Framework: <framework>
   • On 200 OK: merge response into governance config (remote overrides local)
   • On timeout (>5s) / 5xx: fail-closed — STOP with error: "Cannot reach org policy endpoint. Contact your admin."
   • On 4xx: log warning, proceed with local governance
   • If endpoint not configured: skip, use local governance only

9. Return resolved config:

   • Engine, framework, migration tool, SDK version, test framework, guidelines file path, LSP enabled flag

Output Format

After resolution, state the resolved config clearly:

Resolved config:
- Engine: <engine>
- Framework: <framework>
- Migration tool: <migrationTool>
- SDK: <sdk>
- Test framework: <testFramework>
- Guidelines: <path or "plugin defaults">
- LSP: <enabled/disabled>
- Source: <which resolution level determined the engine>
- Governance: <local / remote policy endpoint>