@askdb/introspect 0.3.0-beta.2 → 0.3.0-beta.20

package/README.md

@@ -7,13 +7,17 @@ Engine-agnostic introspection orchestrator for AskDB. Defines the `Connector` co
 ## Install
 
 ```bash
-pnpm add @askdb/introspect @askdb/core
+# `ai` (Vercel AI SDK 6 or 7) is a required peer dependency of @askdb/core
+pnpm add @askdb/introspect @askdb/core ai
 # Plus an integration package for the engine you're targeting, e.g.:
 pnpm add @askdb/postgres pg
-# Or for Prisma schema-file introspection:
-pnpm add @askdb/prisma
+# Or for Prisma schema-file introspection (pnpm 11 must approve the @prisma/engines build;
+# --allow-build needs pnpm 10.4 or later):
+pnpm add --allow-build=@prisma/engines @askdb/prisma
 ```
 
+See [the Prisma guide](https://askdb.tools/guides/integrations/prisma/#install) for other package managers.
+
 ## Programmatic usage
 
 ```ts
@@ -42,6 +46,8 @@ const result = await introspect(
 );
 ```
 
+To get the exact `schema.json` bytes without writing anything (for previews or drift checks), use `renderSchemaV2Body(result.schema, { schemaId, provider: result.provider, existingArtifactDir })`. It is the same function `renderToSchemaV2` writes through — including the merge that carries human-set `sensitive` flags over from an existing artifact — and it backs `askdb introspect --out`, `--print`, and `--diff`.
+
 ## CLI
 
 The user-facing CLI for introspection ships in the [`askdb`](https://www.npmjs.com/package/askdb) package as `askdb introspect`. `@askdb/introspect` does not provide a standalone binary.
@@ -54,3 +60,69 @@ A `Connector<TInput>` has two methods:
 - `templates?(): SqlTemplateBundle` — optional; only relevant for engines that introspect via catalog SQL.
 
 The integration package owns its own input type (e.g. `PostgresIntrospectionInput`, `PrismaIntrospectionInput`). `@askdb/introspect` does not assume a live catalog runner exists, a bundle path exists, a schema-file path exists, or a template suite exists.
+
+### Connector registry
+
+Hosts that pick the engine from configuration use the connector provider registry. The example below also uses `@askdb/config` (for `getAskDbRuntimeConfig()`) and `@askdb/mysql`; install the engine packages you register, and `@askdb/config` when you resolve connections from `askdb.config.ts`. Every engine package exports an adapter: `postgresConnectorProvider`, `mysqlConnectorProvider`, `sqliteConnectorProvider`, `sqlServerConnectorProvider`, `prismaConnectorProvider`. Provider ids are open strings (`ConnectorProviderId`), so a third-party engine package can export `{ provider: "oracle", ... }` and register it the same way.
+
+```ts
+import { getAskDbRuntimeConfig } from "@askdb/config";
+import { createConnectorRegistry, introspect } from "@askdb/introspect";
+import { postgresConnectorProvider } from "@askdb/postgres";
+import { mysqlConnectorProvider } from "@askdb/mysql";
+
+const registry = createConnectorRegistry([postgresConnectorProvider, mysqlConnectorProvider]);
+
+// The adapter merges explicit values with askdb.config/env (explicit wins).
+const resolved = registry.resolveConnection("mysql", { runtime: getAskDbRuntimeConfig() });
+if (!resolved.ok) throw new Error(resolved.error);
+console.log(`Introspecting ${resolved.sourceLabel}`); // host, port and database only
+
+const { connector, input } = registry.createConnector({ provider: "mysql", ...resolved.connection });
+await introspect(input, { outDir: "./askdb", schemaId: "shop" }, { connector });
+```
+
+`ConnectorProviderAdapter` is `{ provider, createConnector(config), getTemplates?(), resolveConnection?(request), connectionLabelParts?(connection) }`. `resolveConnection` returns only the connection (or an error); the registry adds `sourceLabel`, which it always builds with `formatConnectionLabel` from the adapter's `connectionLabelParts` (host, port, database, or a file path). No adapter supplies label text, so `sourceLabel` is safe to display for any adapter; one without `connectionLabelParts` gets `configured <provider> connection` ([ADR 0011](https://github.com/Ygilany/AskDB/blob/main/docs/adrs/0011-connection-labels-from-parsed-parts.md)). See [Connector authoring](https://github.com/Ygilany/AskDB/blob/main/docs/integration/connectors.md#registering-with-askdb-hosts) for writing an adapter.
+
+An engine package your users may not have installed registers as a **lazy entry**, `{ provider, load }`, where `load()` imports the package and returns its adapter. `hasProvider()` and `providers()` list it without loading. Call `await registry.load(provider)` once the engine is selected: it imports the package once, shares concurrent calls, retries after a failure, and checks the adapter's `provider`. Until then the other methods throw for that entry. The `askdb` CLI and Studio register `@askdb/prisma` this way, with `createOptionalDriverLoader` and `connectorPackageMissingMessage({ provider, packageName, allowBuilds })` for the install hint ([ADR 0008](https://github.com/Ygilany/AskDB/blob/main/docs/adrs/0008-engine-packages-and-connector-registry.md), 2026-11 amendment):
+
+```ts
+const registry = createConnectorRegistry([
+  postgresConnectorProvider,
+  { provider: "prisma", load: async () => (await import("@askdb/prisma")).prismaConnectorProvider },
+]);
+await registry.load(engine); // a no-op for an adapter object
+```
+
+This bare `import()` surfaces Node's own module-not-found error when the package is missing. To give an install hint instead, wrap the import in `createOptionalDriverLoader`, as [Registering an engine that may not be installed](https://github.com/Ygilany/AskDB/blob/main/docs/integration/connectors.md#registering-an-engine-that-may-not-be-installed) shows.
+
+### Engine kit (`@askdb/introspect/kit`)
+
+The `@askdb/introspect/kit` subpath holds the engine-agnostic helpers every first-party engine package uses, so a new engine does not copy them:
+
+| Helper | Purpose |
+| --- | --- |
+| `createOptionalDriverLoader({ packageName, specifier?, importDriver, missingMessage })`, `isDriverInstalled(packageName, { resolveFrom? })`, `missingDriverMessage({ engine, packageName })`, `rethrowDriverImportError` | Lazy, cached loading of an optional driver peer (`pg`, `mysql2`, …): the engine package's own `import()` first, then the caller's project (`resolveFrom`, default `process.cwd()`). A missing peer rejects with an `AskDbError`; the failed cache slot is cleared so a later call retries. `missingDriverMessage` is the first-party engines' message (it suggests a one-off `askdb` command, which registers only those engines); a third-party engine passes its own `missingMessage`. Chain `.catch(rethrowDriverImportError)` on your `import()` so bundlers such as esbuild treat the peer as optional. |
+| `compileTableFilters(patterns)`, `ambiguousFilterWarnings(patterns, qualifiedNames)` | `IntrospectionFilters.tables` glob matching (`*`, `?`) and the `ambiguous_filter` warning for patterns that match nothing. |
+| `makeTableId(schema, table)`, `makeColumnId(schema, table, column)` | Schema v2 ids (`table:<schema>.<name>`, `table:<schema>.<name>#<column>`). |
+| `rowsToRecords(result, { expectedColumns?, source? })`, `groupBy`, `buildOrderedGroups`, `byName`, `sortedUnique`, `mapFkAction` | Folding positional `CatalogQueryResult` rows into Schema v2 tables, constraints, and indexes. |
+| `formatConnectionLabel`, `parseConnectionUrl`, `ConnectionLabelParts` | `ConnectionLabelParts` is what an adapter's `connectionLabelParts` hook returns (take the parts from your driver's own parser where it has one; `parseConnectionUrl` is a strict fallback for a standard URL). `formatConnectionLabel` is what `registry.connectionLabel()` applies to those parts: host, port and database (or a file path), else `configured <engine> connection` ([ADR 0011](https://github.com/Ygilany/AskDB/blob/main/docs/adrs/0011-connection-labels-from-parsed-parts.md)). |
+| `defineLiveConnectorProvider({ provider, displayName, runtimeKey, connectionNoun, missingConnection, fromExportUnsupported?, createConnector, createRunner, connectionLabelParts })` | The full `ConnectorProviderAdapter` for an engine that only introspects through a live `CatalogQueryRunner`. `@askdb/mysql`, `@askdb/sqlite`, and `@askdb/sqlserver` use it. |
+| `runtimeIntrospectionString(runtime, key)` | A non-empty string from `runtime.introspection[key]`, the per-engine values `@askdb/config` resolves (for example `postgresDatabaseUrl`). |
+
+```ts
+import { createOptionalDriverLoader, rethrowDriverImportError } from "@askdb/introspect/kit";
+
+const driver = createOptionalDriverLoader<typeof import("my-driver")>({
+  packageName: "my-driver",
+  // Keep the import literal in *your* package, where the peer is declared, with the
+  // rethrowing .catch() on it, so bundlers treat the peer as optional.
+  importDriver: () => import("my-driver").catch(rethrowDriverImportError),
+  missingMessage:
+    "The MyEngine connector requires the optional `my-driver` peer dependency. Install it in your project (e.g. `pnpm add my-driver`).",
+});
+```
+
+## License
+
+Apache-2.0 © [Yahya Gilany](https://yahyagilany.io). See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { SqlSchema, SqlNamespace, SqlTable, SqlColumn, SqlForeignKey, SqlForeignKeyAction, SqlUnique, SqlIndex, SqlCheck, SqlEnum, SqlSequence, SqlView, IntrospectionFilters, IntrospectionResult, IntrospectionWarning, SqlTemplate, SqlTemplateBundle, CatalogQueryResult, CatalogQueryRunner, Connector, } from "./types.js";
-export type { RenderOptions, RenderResult } from "./render/types.js";
+export type { RenderOptions, RenderResult, RenderBodyOptions, RenderBodyResult, } from "./render/types.js";
 export { introspect, type IntrospectOptions, type IntrospectResult, } from "./introspect.js";
-export { renderToSchemaV2, toV2SchemaJson, compactPostgresType } from "./render/render.js";
+export { BUILT_IN_CONNECTOR_PROVIDERS, connectorPackageMissingMessage, connectorProviderMissingMessage, createConnectorRegistry, type BuiltInConnectorProvider, type ConnectorConfig, type ConnectorConnection, type ConnectorConnectionRequest, type ConnectorConnectionResolution, type ConnectorConnectionResult, type ConnectorProviderAdapter, type ConnectorProviderAdapters, type ConnectorProviderEntry, type ConnectorProviderId, type ConnectorRegistry, type ConnectorResult, type ConnectorRuntimeConfig, type LazyConnectorProviderAdapter, } from "./registry.js";
+export { renderToSchemaV2, renderSchemaV2Body, isSchemaV2Json, toV2SchemaJson, compactPostgresType, } from "./render/render.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,WAAW,EACX,OAAO,EACP,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,WAAW,EACX,OAAO,EACP,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,+BAA+B,EAC/B,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,GAClC,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,mBAAmB,GACpB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { introspect, } from "./introspect.js";
-export { renderToSchemaV2, toV2SchemaJson, compactPostgresType } from "./render/render.js";
+export { BUILT_IN_CONNECTOR_PROVIDERS, connectorPackageMissingMessage, connectorProviderMissingMessage, createConnectorRegistry, } from "./registry.js";
+export { renderToSchemaV2, renderSchemaV2Body, isSchemaV2Json, toV2SchemaJson, compactPostgresType, } from "./render/render.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,OAAO,EACL,UAAU,GAGX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA8BA,OAAO,EACL,UAAU,GAGX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,EAC9B,+BAA+B,EAC/B,uBAAuB,GAexB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,mBAAmB,GACpB,MAAM,oBAAoB,CAAC"}

package/dist/kit/driver.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Where to resolve an optional driver peer from when the engine package itself
+ * cannot see it. Defaults to `process.cwd()` — the caller's project root.
+ */
+export type DriverLoadOptions = {
+    resolveFrom?: string;
+};
+export type OptionalDriverSpec<T> = {
+    /** npm package name of the optional peer (e.g. `"pg"`, `"mysql2"`). */
+    packageName: string;
+    /**
+     * Module specifier to import when falling back to the project root. Defaults
+     * to `packageName`; set it for subpath entry points such as `"mysql2/promise"`.
+     */
+    specifier?: string;
+    /**
+     * Imports the driver relative to the *engine package*. Must be a literal
+     * `() => import("pg").catch(rethrowDriverImportError)` written in the engine package, not
+     * here: the peer is declared (and installed next to) the engine package, and
+     * bundlers only see the dependency when the import is lexically in that
+     * package. The `.catch()` chained on the `import()` (any handler that
+     * rethrows the error unchanged) is how bundlers such as esbuild tell an
+     * optional import from a required one; the catch inside this loader is
+     * invisible to them.
+     */
+    importDriver: () => Promise<T>;
+    /** Message of the `AskDbError` thrown when the peer cannot be resolved from anywhere. */
+    missingMessage: string;
+};
+export type OptionalDriverLoader<T> = {
+    /**
+     * Resolve the driver: first through the engine package's own import, then
+     * from `resolveFrom` (default `process.cwd()`). Successful loads are cached
+     * per `resolveFrom`; failures clear the cache slot so a later call retries
+     * (e.g. after the user runs `pnpm add pg`). Rejects with an `AskDbError`
+     * carrying `missingMessage` when the peer is missing everywhere, and with an
+     * `AskDbError` naming the real failure (`cause` set) when the peer is
+     * installed but fails to load.
+     *
+     * Node 24 and later can keep a failed package lookup until the process exits,
+     * so a retry may still miss a peer installed after the first attempt. When
+     * the peer is on disk under `resolveFrom` but Node can't resolve it, the
+     * `AskDbError` says to restart the process instead of to install it.
+     */
+    load(options?: DriverLoadOptions): Promise<T>;
+};
+/**
+ * Build a lazy, cached loader for an optional database-driver peer. Engine
+ * packages call this once at module scope, so each engine keeps its own cache.
+ */
+export declare function createOptionalDriverLoader<T>(spec: OptionalDriverSpec<T>): OptionalDriverLoader<T>;
+/**
+ * True when `packageName` resolves from `resolveFrom` (default `process.cwd()`).
+ * A cheap, synchronous capability probe — it does not load the driver.
+ */
+export declare function isDriverInstalled(packageName: string, options?: DriverLoadOptions): boolean;
+/**
+ * The install hint the first-party engines' built-in catalog runners throw when
+ * their driver peer is missing, e.g.
+ * `missingDriverMessage({ engine: "Postgres", packageName: "pg" })`. It
+ * suggests a one-off `askdb` command, and the `askdb` binary registers only the
+ * first-party engines, so a third-party engine writes its own `missingMessage`.
+ */
+export declare function missingDriverMessage(input: {
+    engine: string;
+    packageName: string;
+}): string;
+/**
+ * The handler an engine chains on its driver's `import()`:
+ * `() => import("pg").catch(rethrowDriverImportError)`. It rethrows unchanged,
+ * so the loader still classifies the error; its job is to sit on the
+ * `import()` expression, which is how bundlers such as esbuild tell an
+ * optional peer from a required one.
+ */
+export declare function rethrowDriverImportError(error: unknown): never;
+//# sourceMappingURL=driver.d.ts.map

package/dist/kit/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/kit/driver.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAClC,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,YAAY,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/B,yFAAyF;IACzF,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI;IACpC;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/C,CAAC;AA0DF;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CA0DlG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAQ3F;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAQ3F;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAE9D"}

package/dist/kit/driver.js

@@ -0,0 +1,156 @@
+import { AskDbError } from "@askdb/core";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+/**
+ * True when `cause` (or any error in its `cause` chain) is a Node module
+ * resolution failure (`ERR_MODULE_NOT_FOUND` / `MODULE_NOT_FOUND`) for the
+ * driver itself: the specifier Node could not find (`Cannot find package 'pg'`,
+ * `Cannot find module 'mysql2/promise'`, or Yarn PnP's `tried to access pg`)
+ * must be `packageName` or `specifier`, the entry point the loader asks for
+ * (default `packageName`). A different missing package whose name merely
+ * contains it (`pg-connection-string`), a path that happens to contain it
+ * (`/home/mssqluser/…`), or another file of the package (`pg/lib/missing`,
+ * which the installed driver failed to load) does not count. Anything else is a
+ * real error and must surface.
+ */
+function isModuleResolutionFailure(cause, packageName, specifier = packageName) {
+    if (!(cause instanceof Error))
+        return false;
+    const nestedCause = cause.cause;
+    if (nestedCause && nestedCause !== cause && isModuleResolutionFailure(nestedCause, packageName, specifier)) {
+        return true;
+    }
+    const code = cause.code;
+    if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND")
+        return false;
+    const missing = 
+    // Node: `Cannot find package 'pg' imported from …` / `Cannot find module 'mysql2/promise'`.
+    /Cannot find (?:module|package) '([^']+)'/.exec(cause.message)?.[1] ??
+        // Yarn PnP: `… tried to access pg, but it isn't declared in its dependencies …`.
+        /tried to access ([^\s,]+)/.exec(cause.message)?.[1];
+    return missing === packageName || missing === specifier;
+}
+/** The driver resolves from neither the engine package nor `resolveFrom`. */
+class DriverNotFoundError extends AggregateError {
+}
+/** Node can't resolve the driver, but it is on disk in `nodeModules` (see `OptionalDriverLoader.load`). */
+class DriverUnresolvableError extends AggregateError {
+    nodeModules;
+    constructor(errors, nodeModules) {
+        super(errors, "Optional peer dependency is installed but does not resolve");
+        this.nodeModules = nodeModules;
+    }
+}
+/**
+ * The `node_modules` directory under `fromDir` or one of its parents that holds
+ * `packageName`, checked on disk rather than through Node's resolver.
+ */
+function nodeModulesHolding(fromDir, packageName) {
+    for (let dir = fromDir;; dir = dirname(dir)) {
+        if (existsSync(join(dir, "node_modules", packageName, "package.json")))
+            return join(dir, "node_modules");
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+}
+/**
+ * Build a lazy, cached loader for an optional database-driver peer. Engine
+ * packages call this once at module scope, so each engine keeps its own cache.
+ */
+export function createOptionalDriverLoader(spec) {
+    const { packageName, importDriver, missingMessage } = spec;
+    const specifier = spec.specifier ?? packageName;
+    const cache = new Map();
+    async function importOptional(options) {
+        try {
+            return await importDriver();
+        }
+        catch (cause) {
+            if (!isModuleResolutionFailure(cause, packageName, specifier))
+                throw cause;
+            const fromDir = options?.resolveFrom ?? process.cwd();
+            const projectRequire = createRequire(join(fromDir, "package.json"));
+            let resolved;
+            try {
+                resolved = projectRequire.resolve(specifier);
+            }
+            catch (projectCause) {
+                if (!isModuleResolutionFailure(projectCause, packageName, specifier))
+                    throw projectCause;
+                const nodeModules = nodeModulesHolding(fromDir, packageName);
+                if (nodeModules)
+                    throw new DriverUnresolvableError([cause, projectCause], nodeModules);
+                throw new DriverNotFoundError([cause, projectCause], `Unable to resolve optional \`${packageName}\` peer dependency`);
+            }
+            // Resolved in the project: any failure from here on is the installed
+            // driver failing to load, never "not installed".
+            return (await import(pathToFileURL(resolved).href));
+        }
+    }
+    return {
+        load(options) {
+            const key = options?.resolveFrom;
+            let promise = cache.get(key);
+            if (!promise) {
+                promise = importOptional(options).catch((cause) => {
+                    cache.delete(key);
+                    // Only a driver that resolves nowhere gets the install hint. A driver
+                    // that is installed but fails to load (a missing dependency of its
+                    // own, a native build error, …) reports that failure instead.
+                    if (cause instanceof DriverNotFoundError)
+                        throw new AskDbError(missingMessage, cause);
+                    if (cause instanceof DriverUnresolvableError) {
+                        throw new AskDbError(`\`${packageName}\` is in ${cause.nodeModules}, but Node can't load it in this process. ` +
+                            "If it was installed while the process was running, restart the process: " +
+                            "Node 24 and later can keep a failed package lookup until the process exits.", cause);
+                    }
+                    const detail = cause instanceof Error ? cause.message : String(cause);
+                    throw new AskDbError(`The optional \`${packageName}\` peer dependency failed to load: ${detail}`, cause);
+                });
+                cache.set(key, promise);
+            }
+            return promise;
+        },
+    };
+}
+/**
+ * True when `packageName` resolves from `resolveFrom` (default `process.cwd()`).
+ * A cheap, synchronous capability probe — it does not load the driver.
+ */
+export function isDriverInstalled(packageName, options) {
+    try {
+        const req = createRequire(join(options?.resolveFrom ?? process.cwd(), "package.json"));
+        req.resolve(packageName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The install hint the first-party engines' built-in catalog runners throw when
+ * their driver peer is missing, e.g.
+ * `missingDriverMessage({ engine: "Postgres", packageName: "pg" })`. It
+ * suggests a one-off `askdb` command, and the `askdb` binary registers only the
+ * first-party engines, so a third-party engine writes its own `missingMessage`.
+ */
+export function missingDriverMessage(input) {
+    const { engine, packageName } = input;
+    return (`The built-in ${engine} catalog query runner requires the optional \`${packageName}\` peer dependency. ` +
+        `Install it in your project (e.g. \`pnpm add ${packageName}\`) or include it in the same one-off command ` +
+        `(e.g. \`pnpm dlx -p askdb -p ${packageName} askdb ...\` or \`npx -p askdb -p ${packageName} askdb ...\`). ` +
+        `You can also pass a custom catalog query runner to the ${engine} connector.`);
+}
+/**
+ * The handler an engine chains on its driver's `import()`:
+ * `() => import("pg").catch(rethrowDriverImportError)`. It rethrows unchanged,
+ * so the loader still classifies the error; its job is to sit on the
+ * `import()` expression, which is how bundlers such as esbuild tell an
+ * optional peer from a required one.
+ */
+export function rethrowDriverImportError(error) {
+    throw error;
+}
+//# sourceMappingURL=driver.js.map

package/dist/kit/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/kit/driver.ts"],"names":[],"mappings":"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"}

package/dist/kit/filters.d.ts

@@ -0,0 +1,29 @@
+import type { IntrospectionWarning } from "../types.js";
+/**
+ * Minimal glob matcher for `IntrospectionFilters.tables`. Patterns match
+ * against `"<schema>.<name>"` strings; supported wildcards:
+ *
+ *   *   matches any run of characters (including dots)
+ *   ?   matches a single character
+ *
+ * Brace expansion (`{a,b}`) and character classes (`[abc]`) are intentionally
+ * not supported — keeping the surface small avoids a glob dependency. If a
+ * filter looks valid but matches nothing, emit an `ambiguous_filter` warning
+ * (see {@link ambiguousFilterWarnings}).
+ */
+export declare function compileGlob(pattern: string): RegExp;
+export type GlobMatcher = (qualifiedName: string) => boolean;
+/**
+ * Returns a matcher that accepts a `"<schema>.<name>"` and returns true when
+ * any pattern matches. When `patterns` is empty or undefined, the matcher
+ * always returns true (no filtering).
+ */
+export declare function compileTableFilters(patterns: ReadonlyArray<string> | undefined): GlobMatcher;
+/**
+ * One `ambiguous_filter` warning per declared `tables` pattern that matches
+ * none of the emitted objects. `qualifiedNames` are the `"<schema>.<name>"` of
+ * every table and view that made it into the result. Warnings keep the
+ * declared pattern order (duplicates included).
+ */
+export declare function ambiguousFilterWarnings(patterns: ReadonlyArray<string> | undefined, qualifiedNames: Iterable<string>): IntrospectionWarning[];
+//# sourceMappingURL=filters.d.ts.map

package/dist/kit/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/kit/filters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUnD;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,GAAG,WAAW,CAI5F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,EAC3C,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC/B,oBAAoB,EAAE,CAWxB"}

package/dist/kit/filters.js

@@ -0,0 +1,58 @@
+/**
+ * Minimal glob matcher for `IntrospectionFilters.tables`. Patterns match
+ * against `"<schema>.<name>"` strings; supported wildcards:
+ *
+ *   *   matches any run of characters (including dots)
+ *   ?   matches a single character
+ *
+ * Brace expansion (`{a,b}`) and character classes (`[abc]`) are intentionally
+ * not supported — keeping the surface small avoids a glob dependency. If a
+ * filter looks valid but matches nothing, emit an `ambiguous_filter` warning
+ * (see {@link ambiguousFilterWarnings}).
+ */
+export function compileGlob(pattern) {
+    let out = "^";
+    for (const ch of pattern) {
+        if (ch === "*")
+            out += ".*";
+        else if (ch === "?")
+            out += ".";
+        else if (/[.+^${}()|[\]\\]/.test(ch))
+            out += "\\" + ch;
+        else
+            out += ch;
+    }
+    out += "$";
+    return new RegExp(out);
+}
+/**
+ * Returns a matcher that accepts a `"<schema>.<name>"` and returns true when
+ * any pattern matches. When `patterns` is empty or undefined, the matcher
+ * always returns true (no filtering).
+ */
+export function compileTableFilters(patterns) {
+    if (!patterns || patterns.length === 0)
+        return () => true;
+    const compiled = patterns.map(compileGlob);
+    return (qualifiedName) => compiled.some((re) => re.test(qualifiedName));
+}
+/**
+ * One `ambiguous_filter` warning per declared `tables` pattern that matches
+ * none of the emitted objects. `qualifiedNames` are the `"<schema>.<name>"` of
+ * every table and view that made it into the result. Warnings keep the
+ * declared pattern order (duplicates included).
+ */
+export function ambiguousFilterWarnings(patterns, qualifiedNames) {
+    if (!patterns || patterns.length === 0)
+        return [];
+    const names = [...qualifiedNames];
+    const warnings = [];
+    for (const pattern of patterns) {
+        const re = compileGlob(pattern);
+        if (!names.some((name) => re.test(name))) {
+            warnings.push({ code: "ambiguous_filter", filter: pattern });
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=filters.js.map

package/dist/kit/filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.js","sourceRoot":"","sources":["../../src/kit/filters.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,IAAI,EAAE,KAAK,GAAG;YAAE,GAAG,IAAI,IAAI,CAAC;aACvB,IAAI,EAAE,KAAK,GAAG;YAAE,GAAG,IAAI,GAAG,CAAC;aAC3B,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC;;YAClD,GAAG,IAAI,EAAE,CAAC;IACjB,CAAC;IACD,GAAG,IAAI,GAAG,CAAC;IACX,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAID;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA2C;IAC7E,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC;IAC1D,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC3C,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAA2C,EAC3C,cAAgC;IAEhC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClD,MAAM,KAAK,GAAG,CAAC,GAAG,cAAc,CAAC,CAAC;IAClC,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/kit/ids.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Schema v2 ID conventions (see docs/contracts/schema-v2.md):
+ *
+ *   table:<schema>.<name>
+ *   table:<schema>.<name>#<col>
+ *
+ * The schema prefix is always included (even for `public`) so cross-schema
+ * tables are unambiguous and IDs survive a future move between schemas
+ * without colliding. The `#` separator is reserved for column suffixes.
+ * Engines without Postgres-style schemas use `"public"` so IDs stay stable
+ * across engines: SQLite always, and MySQL for the connection's own database
+ * (with a database list, MySQL uses each database's name instead).
+ */
+export declare function makeTableId(schemaName: string, tableName: string): string;
+export declare function makeColumnId(schemaName: string, tableName: string, columnName: string): string;
+//# sourceMappingURL=ids.d.ts.map

package/dist/kit/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/kit/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE9F"}

package/dist/kit/ids.js

@@ -0,0 +1,20 @@
+/**
+ * Schema v2 ID conventions (see docs/contracts/schema-v2.md):
+ *
+ *   table:<schema>.<name>
+ *   table:<schema>.<name>#<col>
+ *
+ * The schema prefix is always included (even for `public`) so cross-schema
+ * tables are unambiguous and IDs survive a future move between schemas
+ * without colliding. The `#` separator is reserved for column suffixes.
+ * Engines without Postgres-style schemas use `"public"` so IDs stay stable
+ * across engines: SQLite always, and MySQL for the connection's own database
+ * (with a database list, MySQL uses each database's name instead).
+ */
+export function makeTableId(schemaName, tableName) {
+    return `table:${schemaName}.${tableName}`;
+}
+export function makeColumnId(schemaName, tableName, columnName) {
+    return `table:${schemaName}.${tableName}#${columnName}`;
+}
+//# sourceMappingURL=ids.js.map

package/dist/kit/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/kit/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,UAAkB,EAAE,SAAiB;IAC/D,OAAO,SAAS,UAAU,IAAI,SAAS,EAAE,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,SAAiB,EAAE,UAAkB;IACpF,OAAO,SAAS,UAAU,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;AAC1D,CAAC"}

package/dist/kit/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@askdb/introspect/kit` — shared building blocks for engine integration
+ * packages (`@askdb/postgres`, `@askdb/mysql`, `@askdb/sqlite`,
+ * `@askdb/sqlserver`, `@askdb/prisma`, and third-party engines).
+ *
+ * Nothing here is engine-specific: catalog SQL, row shapes, and dialect rules
+ * stay in each engine package. The kit only removes the mechanical code every
+ * engine would otherwise copy — optional-driver loading, table-glob filters,
+ * Schema v2 IDs, catalog-row folding, connection labels, and the
+ * connector-provider adapter for live-catalog-only engines.
+ */
+export { createOptionalDriverLoader, isDriverInstalled, missingDriverMessage, rethrowDriverImportError, type DriverLoadOptions, type OptionalDriverLoader, type OptionalDriverSpec, } from "./driver.js";
+export { ambiguousFilterWarnings, compileTableFilters, type GlobMatcher, } from "./filters.js";
+export { makeColumnId, makeTableId } from "./ids.js";
+export { buildOrderedGroups, byName, groupBy, mapFkAction, rowsToRecords, sortedUnique, type RowsToRecordsOptions, } from "./rows.js";
+export { defineLiveConnectorProvider, runtimeIntrospectionString, type LiveCatalogInput, type LiveConnectorProviderSpec, } from "./provider.js";
+export { formatConnectionLabel, parseConnectionUrl, type ConnectionLabelParts, } from "./label.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/kit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/kit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,WAAW,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAErD,OAAO,EACL,kBAAkB,EAClB,MAAM,EACN,OAAO,EACP,WAAW,EACX,aAAa,EACb,YAAY,EACZ,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/kit/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@askdb/introspect/kit` — shared building blocks for engine integration
+ * packages (`@askdb/postgres`, `@askdb/mysql`, `@askdb/sqlite`,
+ * `@askdb/sqlserver`, `@askdb/prisma`, and third-party engines).
+ *
+ * Nothing here is engine-specific: catalog SQL, row shapes, and dialect rules
+ * stay in each engine package. The kit only removes the mechanical code every
+ * engine would otherwise copy — optional-driver loading, table-glob filters,
+ * Schema v2 IDs, catalog-row folding, connection labels, and the
+ * connector-provider adapter for live-catalog-only engines.
+ */
+export { createOptionalDriverLoader, isDriverInstalled, missingDriverMessage, rethrowDriverImportError, } from "./driver.js";
+export { ambiguousFilterWarnings, compileTableFilters, } from "./filters.js";
+export { makeColumnId, makeTableId } from "./ids.js";
+export { buildOrderedGroups, byName, groupBy, mapFkAction, rowsToRecords, sortedUnique, } from "./rows.js";
+export { defineLiveConnectorProvider, runtimeIntrospectionString, } from "./provider.js";
+export { formatConnectionLabel, parseConnectionUrl, } from "./label.js";
+//# sourceMappingURL=index.js.map

package/dist/kit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/kit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,GAIzB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,GAEpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAErD,OAAO,EACL,kBAAkB,EAClB,MAAM,EACN,OAAO,EACP,WAAW,EACX,aAAa,EACb,YAAY,GAEb,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,GAG3B,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,qBAAqB,EACrB,kBAAkB,GAEnB,MAAM,YAAY,CAAC"}

package/dist/kit/label.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Connection labels: the credential-free text shown for a configured database
+ * connection (Studio's `GET /api/introspect/status` `sourceLabel`).
+ *
+ * A label is built only from parts an engine's parser extracted cleanly — host,
+ * port, database, or a SQLite file path — and only when each part passes the
+ * allowlist below. No other substring of the input is ever copied. Input that
+ * does not parse cleanly, or a part that fails its allowlist, becomes
+ * `configured <engine> connection`. Nothing here masks: see
+ * docs/adrs/0011-connection-labels-from-parsed-parts.md for why.
+ */
+/** What an engine's parser may hand to `formatConnectionLabel`. */
+export type ConnectionLabelParts = {
+    host?: string;
+    port?: string;
+    database?: string;
+} | {
+    file: string;
+};
+/**
+ * Build a connection label from parsed parts: `<engine>://host[:port][/database]`
+ * for network engines, the path itself for a file. Returns
+ * `configured <engine> connection` when `parts` is `undefined` (the input did
+ * not parse) or any part fails its allowlist. The shape is checked at runtime
+ * too, because a plain-JS adapter can return anything: a value that isn't a
+ * plain object (a string, an array, a `URL`), or a part that isn't a string,
+ * also gets the fallback instead of throwing.
+ */
+export declare function formatConnectionLabel(engine: string, parts: ConnectionLabelParts | undefined): string;
+/**
+ * Parse a standard `scheme://[user[:password]@]host[:port][/database][?query]`
+ * connection URL (Postgres, MySQL, SQL Server `mssql://`) into label parts.
+ * Userinfo and the query string are never returned. Returns `undefined` —
+ * so the label falls back — when:
+ *
+ * - the scheme is not one of `schemes` (so `jdbc:postgresql://…`, a quoted
+ *   URL, and `postgres:/…` all fall back);
+ * - the input contains whitespace, a control character, or a `#`;
+ * - an `@` appears after the authority (a password containing `/`, `?` or `#`
+ *   cut the authority short, so where it ends is unknown);
+ * - the host is not a single `host[:port]`, or the path has more than one segment.
+ */
+export declare function parseConnectionUrl(input: string, schemes: readonly string[]): ConnectionLabelParts | undefined;
+//# sourceMappingURL=label.d.ts.map

package/dist/kit/label.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label.d.ts","sourceRoot":"","sources":["../../src/kit/label.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AASrB;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,oBAAoB,GAAG,SAAS,GACtC,MAAM,CAmBR;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,oBAAoB,GAAG,SAAS,CAiBlC"}