@elkindev/dbgraph 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ElkinDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,317 @@
+# dbgraph
+
+> A codegraph for your database. dbgraph indexes a database catalog into a local
+> graph of tables, columns, constraints, views, procedures, functions, triggers and
+> their relationships, and serves it to AI agents over MCP — so one tool call answers
+> what would otherwise cost several exploratory queries.
+
+dbgraph reads a database's catalog (never its data), normalizes it into an
+engine-agnostic graph, and persists that graph in a local SQLite + FTS5 index. AI
+agents then query the graph over the Model Context Protocol (MCP) instead of
+re-discovering the schema by hand.
+
+- **Read-only by construction.** No command issues any write, DDL or DML against the
+  target database — only catalog `SELECT`s through the adapter port
+  (`openspec/specs/cli-config/spec.md` — "Read-only-against-target is INVIOLABLE").
+- **100% local.** The graph lives in a local SQLite + FTS5 index; nothing leaves the
+  machine (`openspec/specs/graph-storage/spec.md`).
+- **Served over MCP.** The eight tools `dbgraph_explore`, `dbgraph_search`,
+  `dbgraph_object`, `dbgraph_related`, `dbgraph_impact`, `dbgraph_path`,
+  `dbgraph_precheck` and `dbgraph_status` expose the graph to agents over the official
+  `@modelcontextprotocol/sdk` stdio transport
+  (`openspec/specs/mcp-server/spec.md` — Purpose).
+
+> **Status.** This repository runs **from source today**. There is no published npm
+> package or binary yet — the release workflow exists but has never been fired (see
+> [Limitations](#limitations)). Standalone win-x64 / linux-x64 binaries are planned for
+> v1.0.
+
+## What it models
+
+Every catalog object becomes a node; every relationship becomes an edge.
+
+- **Nodes** (`openspec/specs/graph-model/spec.md` — Node taxonomy): `database`,
+  `schema`, `table`, `column`, `view`, `trigger`, `procedure`, `function`, `index`,
+  and `field` (for document stores).
+- **Edges** (`openspec/specs/graph-model/spec.md` — Edge taxonomy): `references`
+  (declared foreign keys, plus an aggregated table→table form), `depends_on` (view
+  dependencies), `reads_from` / `writes_to` (parsed from module bodies), `fires_on`
+  (triggers, carrying the DML event), `indexes`, and `inferred_reference` (opt-in,
+  carrying `confidence: inferred` and a numeric `score`).
+
+Every edge is classified by `confidence` — `declared`, `parsed`, or `inferred` — so
+the graph never hides how it knows something. A module whose body cannot be analyzed
+is flagged `has_dynamic_sql: true` rather than guessing its edges
+(`openspec/specs/graph-normalization/spec.md` — "Dynamic SQL declares blindness").
+
+## Feature matrix
+
+Five engines are supported. Each cell below is transcribed from the engine's canonical
+extraction spec and its truthful `CapabilityMatrix` — not from memory.
+
+| Engine | Tables & columns | Views | Indexes | Constraints / FKs | Procedures / functions | Triggers | Inferred relationships | Connectivity |
+|--------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---|
+| **SQLite** | ✓ | ✓ | ✓ | FK¹ | — | ✓ | ○ | local file (`better-sqlite3` / `node:sqlite`) |
+| **SQL Server** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ○ | SQL auth · NTLM · integrated (via `sqlcmd`) |
+| **PostgreSQL** | ✓ | ✓² | ✓ | ✓ | ✓ | ✓ | ○ | host/port/db/user/password · optional SSL |
+| **MySQL / MariaDB** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ○ | host/port/db/user/password · optional SSL |
+| **MongoDB** | collections + sampled fields³ | — | ✓ | —⁴ | — | — | ✓⁵ | `${env:VAR}` URI · database · sampleSize · TLS |
+
+**Legend:** ✓ extracted · ○ opt-in, off by default · — not supported by the engine
+(explicitly declared unsupported in its `CapabilityMatrix`).
+
+**Per-cell sources:**
+
+- **SQLite** — tables/columns, foreign keys (incl. composite), indexes
+  (unique/partial/expression), views and triggers per
+  `openspec/specs/sqlite-extraction/spec.md`. Its `CapabilityMatrix` declares
+  procedures, functions, sequences and collections **unsupported** (same spec —
+  "Truthful SQLite CapabilityMatrix"; `openspec/specs/cli-config/spec.md` — "SQLite
+  offers no procedures").
+  ¹ SQLite exposes foreign keys (including composite) and primary-key membership on
+  columns; it has no separate named CHECK/UNIQUE constraint objects.
+- **SQL Server** — tables/columns (types, nullability, defaults, computed); PK, FK
+  (composite), unique and check constraints; indexes (clustered/nonclustered, filtered,
+  included); views, procedures, functions and triggers with bodies per level; trigger
+  `fires_on` plus its read/write effects — per
+  `openspec/specs/mssql-extraction/spec.md`. Connectivity via SQL auth and NTLM, with
+  integrated security handled through an external `sqlcmd` strategy (same spec; Kerberos
+  SSO is unsupported).
+- **PostgreSQL** — tables/columns (types, nullability, defaults, identity, generated);
+  PK, FK (composite), unique and CHECK constraints; indexes (partial, expression,
+  included); functions and procedures; triggers (event + timing) — per
+  `openspec/specs/pg-extraction/spec.md`.
+  ² Views include materialized views.
+- **MySQL / MariaDB** — tables/columns (types, nullability, defaults, AUTO_INCREMENT);
+  PK, FK (composite), unique and CHECK constraints; indexes (composite, uniqueness);
+  views, functions, procedures and triggers — per
+  `openspec/specs/mysql-extraction/spec.md`.
+- **MongoDB** — collections via `listCollections`, with field structure **inferred by
+  sampling** documents through `$sample` (dotted paths, union BSON types, presence
+  frequency); indexes via `listIndexes`; `$jsonSchema` validators carried in `extra` —
+  per `openspec/specs/mongodb-extraction/spec.md`. Its `CapabilityMatrix` declares
+  `table`, `column`, `constraint`, `view`, `procedure`, `function`, `trigger` and
+  `sequence` **unsupported** (`supportsBodies: false`; same spec — "Truthful MongoDB
+  CapabilityMatrix"; `openspec/specs/cli-config/spec.md` — "MongoDB offers no
+  triggers").
+  ³ Field structure is a statistical inference over a finite sample — honest only about
+  what the sample observed. Sampled **values are never persisted** (only field names,
+  types and frequencies).
+  ⁴ MongoDB has no foreign keys; top-level `$jsonSchema` validators are carried in the
+  collection's `extra`.
+  ⁵ For MongoDB, `inferred_reference` edges are the **only** relationships produced (an
+  `<entity>_id` field infers a reference to the target collection's `_id`) and inference
+  is auto-enabled by the presence of collection/field nodes.
+
+**Inferred relationships** (the `○` cells) come from an opt-in, pure-core inference
+engine that is **off by default** for the SQL engines. When enabled it emits
+`inferred_reference` edges from column names and declared types alone — `<entity>_id`,
+`<entity>Id`, `id_<entity>` resolved against real target tables and gated by type
+compatibility — never by reading data values
+(`openspec/specs/graph-normalization/spec.md` — "Opt-in structural inference of
+references", "Inference is opt-in and OFF by default").
+
+## Quickstart (from source)
+
+There is no published package yet, so run from source. Requires **Node.js >= 22**.
+
+```bash
+git clone <this-repo> dbgraph
+cd dbgraph
+npm ci
+npm run build
+```
+
+Then point dbgraph at a database and build its graph. Using SQLite as an example:
+
+```bash
+# 1. Initialize: validates the connection, writes dbgraph.config.json at the project
+#    root (with ${env:VAR} references only — never plaintext secrets), gitignores the
+#    local .dbgraph index, and runs the first sync.
+dbgraph init --dialect sqlite --file ./app.db
+
+# 2. Re-sync after schema changes (incremental — skips extraction when the catalog
+#    fingerprint is unchanged; --full forces a rebuild).
+dbgraph sync
+
+# 3. Query the graph.
+dbgraph query orders            # ranked hits, each with its type and qualified name
+dbgraph query orders --json     # deterministic, machine-parseable JSON
+dbgraph explore main.orders     # a node and its grouped neighbors (use the QUALIFIED name)
+dbgraph status                  # counts, last snapshot, and live drift
+```
+
+`init` writes an env-only config: every connection-identity field (host, port, user,
+password, URL) is stored as a `${env:VAR}` reference and resolved from `process.env` at
+runtime — a plaintext credential is rejected
+(`openspec/specs/cli-config/spec.md` — "Plaintext credentials are rejected").
+
+## CLI reference
+
+`dbgraph <command> [options]`. Run `dbgraph --help` for the full banner, or
+`dbgraph <command> --help` for per-command options.
+
+| Command | What it does |
+|---------|--------------|
+| `init` | Initialize the graph index for a database (writes config, gitignores `.dbgraph`, runs first sync). |
+| `sync` | Synchronize the graph with the database — incremental by fingerprint; `--full` forces a rebuild. |
+| `status` | Show current graph counts, the last snapshot, and whether the live schema has drifted. |
+| `query <term>` | Full-text search the graph; prints type + qualified name per hit. Exits 1 on zero hits. |
+| `explore <qname>` | Show a node and its grouped neighbors. `--detail brief\|normal\|full`. |
+| `diff <a> <b>` | Compare two snapshots per object (added/removed/modified). `--last` compares the two most recent. Exits 1 when changes exist (CI-gate). |
+| `affected <script.sql>` | Analyze a DDL script and report impacted objects. `--json` for machine output; exits 1 when anything is affected. |
+| `doctor` | Run a content-free connectivity self-test (safe to share). |
+| `install` | Wire `dbgraph-mcp` into supported MCP agents. `--project` for project scope, `--remove` to undo. |
+
+Global flags: `--json` (machine-parseable output where supported), `--quiet` / `-q`
+(suppress info/progress, keep warnings/errors), `--help` / `-h`, `--version` / `-v`.
+`--json` payloads on stdout are deterministic and byte-identical for the same graph and
+input (`openspec/specs/cli-config/spec.md`; `src/cli/cli.ts` `USAGE_TEXT`;
+`src/cli/dispatch.ts` `COMMAND_TABLE`).
+
+Exit codes map to a fixed contract (`openspec/specs/cli-config/spec.md`): `0` success ·
+`1` a "negative" result (zero query hits, or diff/affected found changes) · `2`
+connection failure · `3` permission failure · `4` unsupported dialect.
+
+## MCP integration
+
+`dbgraph install` wires an idempotent `dbgraph-mcp` server entry into every supported
+agent's MCP config, driven by a single `AGENT_TABLE` source of truth
+(`openspec/specs/mcp-server/spec.md` — "dbgraph install idempotently wires the agent MCP
+config"; `src/cli/commands/install.ts`).
+
+```bash
+dbgraph install               # wire user-level config for every detected agent
+dbgraph install --project     # write project-scoped config in the current directory
+dbgraph install --remove      # remove the dbgraph-mcp entry from every detected agent
+```
+
+The written entry is `command` + `args` only (`npx -y dbgraph-mcp`) — never a secret.
+Global install configures an agent **only if** its config file already exists;
+`--project` (US-038) re-roots resolution at the current directory and **creates** absent
+project files for the supported agents.
+
+### Supported agents
+
+| Agent | Config key & shape | Project-scoped file (`--project`) |
+|-------|--------------------|-----------------------------------|
+| Claude Code | `mcpServers.dbgraph-mcp = { command, args }` | `.mcp.json` |
+| Cursor | `mcpServers.dbgraph-mcp = { command, args }` | `.cursor/mcp.json` |
+| Gemini CLI | `mcpServers.dbgraph-mcp = { command, args }` | `.gemini/settings.json` |
+| VS Code | `servers.dbgraph-mcp = { type: 'stdio', command, args }` | `.vscode/mcp.json` |
+| opencode | `mcp.dbgraph-mcp = { type: 'local', command: [...] }` | `opencode.json` |
+| Codex CLI | TOML `[mcp_servers.dbgraph-mcp]` | `.codex/config.toml` |
+
+**Codex is trust-gated.** Codex loads project-scoped MCP servers only for **trusted**
+projects, so `--project` reports it with a caveat verbatim:
+
+```text
+codex → written (requires trusted project: set trust_level in ~/.codex/config.toml)
+```
+
+### Env-var interpolation per agent
+
+The `dbgraph-mcp` entry itself uses no interpolation (only `command` + `args`). But if
+you hand-edit a config to add another server that needs a secret, each agent has its own
+native env syntax — reference variables, never inline a credential:
+
+| Agent | Config file | Env-var interpolation syntax |
+|-------|-------------|------------------------------|
+| Claude Code | `.mcp.json` | `${VAR}` |
+| Cursor | `.cursor/mcp.json` | `${env:VAR}` |
+| VS Code | `.vscode/mcp.json` | `${env:VAR}` + `inputs` |
+| Gemini CLI | `.gemini/settings.json` | `$VAR` / `${VAR}` |
+| opencode | `opencode.json` | `{env:VAR}` |
+| Codex CLI | `.codex/config.toml` | TOML `env` tables — no string interpolation |
+
+If no agent config is detected, `dbgraph install` prints a manual snippet for all six
+formats and exits successfully.
+
+### Serve over HTTP
+
+`dbgraph mcp` speaks **stdio** by default. Add `--http` to serve the same read-only
+8-tool surface over **Streamable HTTP** from one host, for several remote agents:
+
+```bash
+dbgraph mcp --http                 # endpoint at http://127.0.0.1:7423/mcp (loopback default)
+dbgraph mcp --http --host 0.0.0.0  # bind all interfaces — prints a no-auth warning
+```
+
+**No authentication ships in v1** and the default bind is loopback (`127.0.0.1`) — that
+loopback default is the primary containment. For any non-loopback exposure, front the
+endpoint with a reverse proxy (TLS + auth) or network controls. HTTP mode adds no write
+path and diagnostics stay content-free.
+
+HTTP client config is **not** auto-wired (`dbgraph install` wires the stdio entry only) —
+add the server by hand. Two shapes bite if copied across agents: **Gemini CLI** needs
+`httpUrl` (a plain `url` silently selects deprecated SSE), and **Cursor** takes **no**
+`type` field (it is inferred from the `url`). The verified 6/6 per-agent matrix, the
+reverse-proxy model, and the pinned `--host 0.0.0.0` warning are in
+[`docs/mcp-http.md`](docs/mcp-http.md).
+
+## Troubleshooting
+
+Run `dbgraph doctor` first — it prints a **content-free** capability report (engine,
+native-driver presence, detected CLI tools with versions, ODBC presence, resolved
+environment profile, and the strategy it would choose). It contains no schema name,
+identifier, query result, or secret, so it is safe to paste into a bug report
+(`openspec/specs/connectivity-diagnostics/spec.md` — "dbgraph doctor reports diagnostics
+content-free"; `src/core/present/doctor.ts` `DoctorView`).
+
+The real-world SQL Server connectivity breaks below are documented in
+`docs/findings/connectivity-environments.md` (F-1..F-7) and handled by the
+connectivity-strategy system (`openspec/specs/connectivity/spec.md`,
+`openspec/specs/connectivity-diagnostics/spec.md`):
+
+| # | Symptom | `doctor` field | Fix |
+|---|---------|----------------|-----|
+| F-1 | `sync` fails on an integrated-security SQL Server (no SQL login; the pure-JS driver can't do SSPI) | `cliTools` (sqlcmd absent) / `chosenStrategy: unavailable` | Install `sqlcmd`; dbgraph shells out with `sqlcmd -E` for integrated auth. |
+| F-2 | Wrong `sqlcmd` flags for the installed variant/version | `resolvedProfile: <variant>@<versionRange>` | dbgraph selects flags per detected variant; if it reports an unrecognized profile, share the `doctor` output. |
+| F-3 | Truncated / failed `FOR JSON` on a legacy `sqlcmd` | `resolvedProfile` (legacy) | dbgraph adapts flags per profile (e.g. `-y 0` alone on legacy 15.x). |
+| F-4 | JSON parse fails at a chunk boundary | `resolvedProfile` (output shape) | dbgraph reassembles the 2033-char `FOR JSON` chunks without trimming. |
+| F-5 | Non-ASCII characters corrupt the JSON stream | `resolvedProfile` (encoding) | dbgraph forces the `sqlcmd` output to codepage 65001 (`-f o:65001`). |
+| F-6 | Malformed / partial tool output | actionable error (what was received, first N chars) — never a raw stack trace | Run `dbgraph doctor` and paste the content-free report. |
+| F-7 | These `sqlcmd` transport breaks aren't caught by CI | — | Covered by recorded fixtures and an opt-in `sqlcmd` CI lane — see [CONTRIBUTING](CONTRIBUTING.md) and [Limitations](#limitations). |
+
+A missing database driver surfaces the exact install command, not a stack trace —
+`Required driver '<name>' is not installed. Run: npm i <name>`
+(`openspec/specs/binary-distribution/spec.md`). A connection failure yields a typed,
+non-blocking outcome offering at least three actionable options (run the catalog
+`SELECT`s yourself, consented install, or import a manual dump) — never an unhandled
+exception (`openspec/specs/connectivity-diagnostics/spec.md`).
+
+## Limitations
+
+Stated plainly, and by design:
+
+- **No published release yet.** The package version is `0.0.0` and the `release.yml`
+  workflow, though written and trigger-guarded, has never been fired — no tag has been
+  pushed (`openspec/specs/binary-distribution/spec.md` — "release.yml is trigger-guarded
+  ... and never fired"). Run from source today; standalone win-x64 / linux-x64 binaries
+  are planned for v1.0.
+- **MongoDB structure is inferred, not declared.** Field structure comes from `$sample`;
+  it is honest only about what the sample observed. Sampled document **values are never
+  persisted** — only field names, types and presence frequencies survive
+  (`openspec/specs/cli-config/spec.md` — sampling is "structural only ... values never
+  stored"; `openspec/specs/mongodb-extraction/spec.md`).
+- **Inferred relationships are opt-in.** For the SQL engines, inference is off by
+  default and must be enabled explicitly; it never reads data values
+  (`openspec/specs/graph-normalization/spec.md`).
+- **SQL Server integrated auth needs `sqlcmd`.** The pure-JS driver cannot do
+  SSPI/Kerberos; integrated security is handled by shelling out to `sqlcmd -E`
+  (`openspec/specs/mssql-extraction/spec.md`; `docs/findings/connectivity-environments.md`
+  F-1).
+- **The `sqlcmd` transport has a CI coverage gap.** Flag combinations, output shape,
+  chunking and encoding only surface on a real `sqlcmd` run; they are covered by recorded
+  fixtures and an opt-in CI lane, not the default unit matrix
+  (`docs/findings/connectivity-environments.md` F-7).
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the per-batch quality gate, the strict
+TDD and spec-driven workflow, and the test tiers. Security posture and disclosure are in
+[SECURITY.md](SECURITY.md).
+
+## License
+
+MIT

package/dist/chunk-2ESYSVXG.js

@@ -0,0 +1,48 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+export {
+  __require,
+  __esm,
+  __commonJS,
+  __export,
+  __toESM,
+  __toCommonJS
+};

package/dist/chunk-CK6XTW3E.js

@@ -0,0 +1,31 @@
+// src/adapters/engines/_shared/connectivity-outcome.ts
+function buildConnectivityOutcome(args) {
+  const options = [
+    {
+      kind: "run-it-yourself",
+      description: "Run these read-only catalog SELECT statements in your own client to extract the schema.",
+      queries: args.runItYourselfQueries
+    },
+    {
+      kind: "consented-install",
+      description: `Install the '${args.installTool}' driver or tool from the official source. Nothing is installed automatically \u2014 explicit consent required.`,
+      tool: args.installTool,
+      docUrl: args.installDocUrl
+    },
+    {
+      kind: "manual-dump",
+      description: `Import a combined JSON dump you produced externally. Place the file at: ${args.dumpPath}`,
+      outputPath: args.dumpPath
+    }
+  ];
+  return {
+    engine: args.engine,
+    summary: args.summary,
+    attempts: args.attempts,
+    options
+  };
+}
+
+export {
+  buildConnectivityOutcome
+};

package/dist/chunk-JN26WCE7.js

@@ -0,0 +1,231 @@
+import {
+  ConfigError,
+  UnsupportedDialectError
+} from "./chunk-TH4OVS4W.js";
+
+// src/infra/config/schema.ts
+var VALID_LEVELS = ["off", "metadata", "full"];
+var SUPPORTED_DIALECTS = ["sqlite", "mssql", "pg", "mysql", "mongodb"];
+
+// src/infra/config/parse-config.ts
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function requireString(obj, field, context) {
+  const v = obj[field];
+  if (typeof v !== "string" || v.length === 0) {
+    throw new ConfigError(
+      `${context}: field "${field}" is required and must be a non-empty string.`
+    );
+  }
+  return v;
+}
+function optionalString(obj, field, context) {
+  const v = obj[field];
+  if (v === void 0) return void 0;
+  if (typeof v !== "string") {
+    throw new ConfigError(`${context}: field "${field}" must be a string when provided.`);
+  }
+  return v;
+}
+function parseLevels(raw) {
+  if (raw === void 0) return void 0;
+  if (!isRecord(raw)) {
+    throw new ConfigError(
+      'Config: "levels" must be an object mapping object type names to level strings.'
+    );
+  }
+  const result = {};
+  for (const [key, val] of Object.entries(raw)) {
+    if (!VALID_LEVELS.includes(val)) {
+      throw new ConfigError(
+        `Config: levels."${key}" must be one of ${VALID_LEVELS.join(", ")} \u2014 got "${String(val)}".`
+      );
+    }
+    result[key] = val;
+  }
+  return result;
+}
+function parseSqliteSource(raw) {
+  if (!isRecord(raw)) {
+    throw new ConfigError('Config: "source" must be an object for dialect "sqlite".');
+  }
+  const file = requireString(raw, "file", "source (sqlite)");
+  return { file };
+}
+function parseMssqlSource(raw) {
+  if (!isRecord(raw)) {
+    throw new ConfigError('Config: "source" must be an object for dialect "mssql".');
+  }
+  const server = requireString(raw, "server", "source (mssql)");
+  const database = requireString(raw, "database", "source (mssql)");
+  const port = optionalString(raw, "port", "source (mssql)");
+  const authRaw = raw["auth"];
+  let auth;
+  if (authRaw !== void 0) {
+    if (authRaw !== "sql" && authRaw !== "ntlm" && authRaw !== "integrated") {
+      throw new ConfigError(
+        'source (mssql): field "auth" must be one of "sql", "ntlm", or "integrated".'
+      );
+    }
+    auth = authRaw;
+  }
+  if (auth === "integrated") {
+    const result2 = { server, database, auth };
+    if (port !== void 0) result2.port = port;
+    return result2;
+  }
+  const user = requireString(raw, "user", "source (mssql)");
+  const password = requireString(raw, "password", "source (mssql)");
+  const domain = optionalString(raw, "domain", "source (mssql)");
+  const resolvedAuth = auth ?? (domain !== void 0 ? "ntlm" : "sql");
+  const result = { server, database, user, password, auth: resolvedAuth };
+  if (port !== void 0) result.port = port;
+  if (domain !== void 0) result.domain = domain;
+  return result;
+}
+var ENV_REF_RE = /^\$\{env:[A-Z_][A-Z0-9_]*\}$/;
+function isEnvRef(value) {
+  return ENV_REF_RE.test(value);
+}
+function parsePgSource(raw) {
+  if (!isRecord(raw)) {
+    throw new ConfigError('Config: "source" must be an object for dialect "pg".');
+  }
+  const host = requireString(raw, "host", "source (pg)");
+  const database = requireString(raw, "database", "source (pg)");
+  const user = requireString(raw, "user", "source (pg)");
+  const password = requireString(raw, "password", "source (pg)");
+  if (!isEnvRef(password)) {
+    throw new ConfigError(
+      'source (pg): field "password" must be a ${env:VAR} reference, not a literal value. Use an environment variable reference such as ${env:PG_PASSWORD}.'
+    );
+  }
+  const port = optionalString(raw, "port", "source (pg)");
+  const ssl = optionalString(raw, "ssl", "source (pg)");
+  const schema = optionalString(raw, "schema", "source (pg)");
+  const result = { host, database, user, password };
+  if (port !== void 0) result.port = port;
+  if (ssl !== void 0) result.ssl = ssl;
+  if (schema !== void 0) result.schema = schema;
+  return result;
+}
+function parseMysqlSource(raw) {
+  if (!isRecord(raw)) {
+    throw new ConfigError('Config: "source" must be an object for dialect "mysql".');
+  }
+  const host = requireString(raw, "host", "source (mysql)");
+  const database = requireString(raw, "database", "source (mysql)");
+  const user = requireString(raw, "user", "source (mysql)");
+  const password = requireString(raw, "password", "source (mysql)");
+  if (!isEnvRef(password)) {
+    throw new ConfigError(
+      'source (mysql): field "password" must be a ${env:VAR} reference, not a literal value. Use an environment variable reference such as ${env:MYSQL_PASSWORD}.'
+    );
+  }
+  const port = optionalString(raw, "port", "source (mysql)");
+  const ssl = optionalString(raw, "ssl", "source (mysql)");
+  const result = { host, database, user, password };
+  if (port !== void 0) result.port = port;
+  if (ssl !== void 0) result.ssl = ssl;
+  return result;
+}
+function parseMongodbSource(raw) {
+  if (!isRecord(raw)) {
+    throw new ConfigError('Config: "source" must be an object for dialect "mongodb".');
+  }
+  const uri = requireString(raw, "uri", "source (mongodb)");
+  const database = requireString(raw, "database", "source (mongodb)");
+  if (!isEnvRef(uri)) {
+    throw new ConfigError(
+      'source (mongodb): field "uri" must be a ${env:VAR} reference, not a literal value. Use an environment variable reference such as ${env:MONGODB_URI}.'
+    );
+  }
+  const sampleSizeRaw = raw["sampleSize"];
+  let sampleSize;
+  if (sampleSizeRaw !== void 0) {
+    if (typeof sampleSizeRaw !== "number" || !Number.isFinite(sampleSizeRaw) || sampleSizeRaw <= 0) {
+      throw new ConfigError(
+        'source (mongodb): field "sampleSize" must be a positive number when provided.'
+      );
+    }
+    sampleSize = sampleSizeRaw;
+  }
+  const tlsRaw = raw["tls"];
+  let tls;
+  if (tlsRaw !== void 0) {
+    if (typeof tlsRaw !== "boolean") {
+      throw new ConfigError(
+        'source (mongodb): field "tls" must be a boolean when provided.'
+      );
+    }
+    tls = tlsRaw;
+  }
+  const result = { uri, database };
+  if (sampleSize !== void 0) result.sampleSize = sampleSize;
+  if (tls !== void 0) result.tls = tls;
+  return result;
+}
+function parseConfig(raw) {
+  if (!isRecord(raw)) {
+    throw new ConfigError(
+      "Config: root must be a JSON object. Got " + (raw === null ? "null" : typeof raw) + "."
+    );
+  }
+  const dialectRaw = raw["dialect"];
+  if (typeof dialectRaw !== "string" || dialectRaw.length === 0) {
+    throw new ConfigError(
+      `Config: field "dialect" is required and must be a non-empty string (supported: ${SUPPORTED_DIALECTS.join(", ")}).`
+    );
+  }
+  if (!SUPPORTED_DIALECTS.includes(dialectRaw)) {
+    throw new UnsupportedDialectError(dialectRaw);
+  }
+  if (!("source" in raw)) {
+    throw new ConfigError('Config: field "source" is required.');
+  }
+  const levels = parseLevels(raw["levels"]);
+  switch (dialectRaw) {
+    case "sqlite": {
+      const source = parseSqliteSource(raw["source"]);
+      const driverRaw = raw["driver"];
+      let driver;
+      if (driverRaw !== void 0) {
+        if (driverRaw !== "better-sqlite3" && driverRaw !== "node:sqlite") {
+          throw new ConfigError(
+            'Config: "driver" must be one of "better-sqlite3" or "node:sqlite".'
+          );
+        }
+        driver = driverRaw;
+      }
+      const cfg = levels !== void 0 ? driver !== void 0 ? { dialect: "sqlite", source, levels, driver } : { dialect: "sqlite", source, levels } : driver !== void 0 ? { dialect: "sqlite", source, driver } : { dialect: "sqlite", source };
+      return cfg;
+    }
+    case "mssql": {
+      const source = parseMssqlSource(raw["source"]);
+      const cfg = levels !== void 0 ? { dialect: "mssql", source, levels } : { dialect: "mssql", source };
+      return cfg;
+    }
+    case "pg": {
+      const source = parsePgSource(raw["source"]);
+      const cfg = levels !== void 0 ? { dialect: "pg", source, levels } : { dialect: "pg", source };
+      return cfg;
+    }
+    case "mysql": {
+      const source = parseMysqlSource(raw["source"]);
+      const cfg = levels !== void 0 ? { dialect: "mysql", source, levels } : { dialect: "mysql", source };
+      return cfg;
+    }
+    case "mongodb": {
+      const source = parseMongodbSource(raw["source"]);
+      const cfg = levels !== void 0 ? { dialect: "mongodb", source, levels } : { dialect: "mongodb", source };
+      return cfg;
+    }
+    default:
+      throw new UnsupportedDialectError(dialectRaw);
+  }
+}
+
+export {
+  parseConfig
+};