@onreza/sqlx-js 0.3.0 → 0.5.0

package/dist/src/commands/doctor.js

@@ -0,0 +1,196 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import ts from "typescript";
+import { assertCacheManifest } from "../cache.js";
+import { assertSupportedRuntime, envFilePath, loadConfigInfo, nativeTypeScriptEnabled, prepareConfigHash, runtimeVersion, } from "../config.js";
+import { decodeText, parseDatabaseUrl, PgClient } from "../pg/wire.js";
+import { probePgschema } from "./pgschema.js";
+function decodeBoolean(value) {
+    const text = decodeText(value ?? null);
+    return text === "t" || text === "true" || text === "1";
+}
+function tsconfigIncludes(root, file) {
+    const path = join(root, "tsconfig.json");
+    if (!existsSync(path))
+        return { ok: false, message: `tsconfig.json not found at ${path}` };
+    const target = resolve(file);
+    const visited = new Set();
+    const visit = (configPath) => {
+        const resolvedConfig = resolve(configPath);
+        if (visited.has(resolvedConfig))
+            return { included: false };
+        visited.add(resolvedConfig);
+        const read = ts.readConfigFile(resolvedConfig, ts.sys.readFile);
+        if (read.error) {
+            return { included: false, error: ts.flattenDiagnosticMessageText(read.error.messageText, "\n") };
+        }
+        const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, resolve(resolvedConfig, ".."), undefined, resolvedConfig);
+        if (parsed.errors.length > 0) {
+            return {
+                included: false,
+                error: parsed.errors.map((error) => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("; "),
+            };
+        }
+        if (parsed.fileNames.some((name) => resolve(name) === target))
+            return { included: true };
+        for (const reference of parsed.projectReferences ?? []) {
+            const result = visit(ts.resolveProjectReferencePath(reference));
+            if (result.included || result.error)
+                return result;
+        }
+        return { included: false };
+    };
+    const result = visit(path);
+    if (result.error)
+        return { ok: false, message: result.error };
+    const included = result.included;
+    return included
+        ? { ok: true, message: `${file} is included by tsconfig.json` }
+        : { ok: false, message: `${file} is not included by tsconfig.json` };
+}
+export async function inspectDoctor(opts) {
+    const checks = [];
+    const runtime = runtimeVersion();
+    try {
+        assertSupportedRuntime();
+        checks.push({
+            name: "runtime",
+            status: "ok",
+            message: `${runtime.runtime} ${runtime.version} satisfies the supported baseline`,
+        });
+    }
+    catch (e) {
+        checks.push({ name: "runtime", status: "error", message: e.message });
+    }
+    let config = {};
+    let configLoaded = true;
+    try {
+        const info = await loadConfigInfo(opts.root);
+        config = info.config;
+        const nativeTs = nativeTypeScriptEnabled();
+        if (info.path && /\.m?ts$/.test(info.path) && nativeTs === false) {
+            checks.push({ name: "config", status: "error", message: "native TypeScript execution is disabled" });
+        }
+        else {
+            checks.push({
+                name: "config",
+                status: "ok",
+                message: info.path ? `loaded ${info.path}` : "no config file; defaults are active",
+            });
+        }
+    }
+    catch (e) {
+        configLoaded = false;
+        checks.push({ name: "config", status: "error", message: e.message });
+    }
+    const envPath = envFilePath(opts.root);
+    checks.push(opts.envError
+        ? { name: "env", status: "error", message: opts.envError }
+        : existsSync(envPath) && !opts.databaseUrl
+            ? { name: "env", status: "error", message: `${envPath} exists but DATABASE_URL is missing` }
+            : existsSync(envPath)
+                ? { name: "env", status: "ok", message: `loaded environment file ${envPath}` }
+                : opts.databaseUrl
+                    ? { name: "env", status: "ok", message: "DATABASE_URL is provided by the process environment" }
+                    : { name: "env", status: "error", message: `DATABASE_URL is missing and ${envPath} does not exist` });
+    if (!configLoaded) {
+        checks.push({ name: "cache", status: "warning", message: "cache config-hash check skipped because config failed to load" });
+    }
+    else {
+        try {
+            assertCacheManifest(opts.cacheDir, prepareConfigHash(config));
+            checks.push({ name: "cache", status: "ok", message: "cache manifest and config hash are current" });
+        }
+        catch (e) {
+            checks.push({ name: "cache", status: "error", message: e.message });
+        }
+    }
+    const tsconfig = tsconfigIncludes(opts.root, opts.dtsPath);
+    checks.push({
+        name: "tsconfig",
+        status: tsconfig.ok ? "ok" : "error",
+        message: tsconfig.message,
+    });
+    if (!opts.databaseUrl) {
+        checks.push({ name: "database", status: "error", message: "DATABASE_URL is required for the database check" });
+    }
+    else {
+        const client = new PgClient(parseDatabaseUrl(opts.databaseUrl));
+        try {
+            await client.connect();
+            await client.describe("SELECT 1");
+            const result = await client.simpleQueryAll(`
+        SELECT current_setting('server_version'), current_user, current_database(),
+          (SELECT (rolcreatedb OR rolsuper)::text FROM pg_roles WHERE rolname = current_user),
+          COALESCE(has_schema_privilege(current_user, current_schema(), 'USAGE'), false)::text
+      `);
+            const row = result.rows[0];
+            const canCreateDatabase = decodeBoolean(row[3]);
+            const hasSchemaUsage = decodeBoolean(row[4]);
+            const shadowDatabaseUrl = process.env.SHADOW_DATABASE_URL;
+            const shadowAdminDatabaseUrl = process.env.SHADOW_ADMIN_DATABASE_URL;
+            const hasShadowFallback = Boolean(shadowDatabaseUrl || shadowAdminDatabaseUrl);
+            const needsShadowCreate = config.schema?.provider !== "pgschema";
+            checks.push({
+                name: "database",
+                status: "ok",
+                message: `connected to ${decodeText(row[2])} as ${decodeText(row[1])}`,
+                details: {
+                    serverVersion: decodeText(row[0]),
+                    describe: true,
+                    schemaUsage: hasSchemaUsage,
+                },
+            });
+            checks.push({
+                name: "permissions",
+                status: hasSchemaUsage && (!needsShadowCreate || canCreateDatabase || hasShadowFallback) ? "ok" : "warning",
+                message: !hasSchemaUsage
+                    ? "current user lacks USAGE on the current schema"
+                    : !needsShadowCreate
+                        ? "current user can use the current schema; pgschema does not require shadow-database creation"
+                        : canCreateDatabase
+                            ? "current user can use the current schema and create shadow databases"
+                            : hasShadowFallback
+                                ? "current user cannot create databases; a shadow database fallback is configured"
+                                : "current user cannot create shadow databases; configure SHADOW_ADMIN_DATABASE_URL or SHADOW_DATABASE_URL",
+                details: {
+                    schemaUsage: hasSchemaUsage,
+                    createDatabase: canCreateDatabase,
+                    shadowDatabaseConfigured: Boolean(shadowDatabaseUrl),
+                    shadowAdminConfigured: Boolean(shadowAdminDatabaseUrl),
+                },
+            });
+        }
+        catch (e) {
+            checks.push({ name: "database", status: "error", message: e.message });
+        }
+        finally {
+            await client.end().catch(() => { });
+        }
+    }
+    if (!configLoaded) {
+        checks.push({ name: "pgschema", status: "warning", message: "schema-provider check skipped because config failed to load" });
+    }
+    else if (config.schema?.provider === "pgschema") {
+        const probe = probePgschema(opts.root, config);
+        checks.push({ name: "pgschema", status: probe.ok ? "ok" : "error", message: probe.message });
+    }
+    else {
+        checks.push({ name: "pgschema", status: "ok", message: "built-in migration provider is active" });
+    }
+    return checks;
+}
+export async function runDoctor(opts) {
+    const checks = await inspectDoctor(opts);
+    const ok = checks.every((check) => check.status !== "error");
+    if (opts.json) {
+        console.log(JSON.stringify({ formatVersion: 1, ok, checks }, null, 2));
+    }
+    else {
+        for (const check of checks) {
+            console.log(`${check.status.padEnd(7)} ${check.name}: ${check.message}`);
+        }
+    }
+    if (!ok)
+        process.exitCode = 1;
+}

package/dist/src/commands/init.d.ts

@@ -1,5 +1,6 @@
 export type InitOptions = {
     root: string;
+    schemaProvider?: "builtin" | "pgschema";
     log?: (msg: string) => void;
 };
 export declare function runInit(opts: InitOptions): void;

package/dist/src/commands/init.js

@@ -1,23 +1,38 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-const CONFIG_TEMPLATE = `import type { SqlxJsConfig } from "@onreza/sqlx-js";
+const CONFIG_TEMPLATE = `import { defineConfig } from "@onreza/sqlx-js";
 
-const config: SqlxJsConfig = {
+export default defineConfig({
   // Map jsonb columns/params to TypeScript types declared in a .d.ts, e.g.
   //   "users.settings": "SqlxJsJson.UserSettings",
   jsonbTypes: {},
   // Map PostgreSQL type names to TypeScript types, e.g.
   //   geometry: "GeoJSON.Geometry",
   customTypes: {},
-};
+});
+`;
+const PGSCHEMA_CONFIG_TEMPLATE = `import { defineConfig } from "@onreza/sqlx-js";
 
-export default config;
+export default defineConfig({
+  schema: {
+    provider: "pgschema",
+    file: "schema.sql",
+    schemas: ["public"],
+  },
+  jsonbTypes: {},
+  customTypes: {},
+});
 `;
 const ENV_TEMPLATE = `# Connection string used by sqlx-js prepare/migrate and the runtime.
 DATABASE_URL=postgres://user:password@localhost:5432/your_db
 # Managed Postgres with TLS:
 # DATABASE_URL=postgres://user:password@db.example.com:5432/your_db?sslmode=verify-full
 `;
+const PGSCHEMA_TEMPLATE = `-- Desired PostgreSQL schema managed by pgschema.
+-- Edit this file, then run:
+--   sqlx-js db plan -- --output-json plan.json
+--   sqlx-js db apply -- --auto-approve
+`;
 export function runInit(opts) {
     const log = opts.log ?? console.log;
     const created = [];
@@ -41,8 +56,12 @@ export function runInit(opts) {
         mkdirSync(full, { recursive: true });
         created.push(`${rel}/`);
     };
-    ensureFile("sqlx-js.config.ts", CONFIG_TEMPLATE);
-    ensureDir("migrations");
+    const schemaProvider = opts.schemaProvider ?? "builtin";
+    ensureFile("sqlx-js.config.ts", schemaProvider === "pgschema" ? PGSCHEMA_CONFIG_TEMPLATE : CONFIG_TEMPLATE);
+    if (schemaProvider === "pgschema")
+        ensureFile("schema.sql", PGSCHEMA_TEMPLATE);
+    else
+        ensureDir("migrations");
     ensureFile(".env.example", ENV_TEMPLATE);
     for (const f of created)
         log(`created ${f}`);
@@ -51,7 +70,15 @@ export function runInit(opts) {
     log("");
     log("Next steps:");
     log("  1. Set DATABASE_URL (see .env.example).");
-    log("  2. Add a migration:  sqlx-js migrate add init");
-    log("  3. Make sure tsconfig.json \"include\" covers sqlx-js-env.d.ts.");
-    log("  4. Develop locally:  sqlx-js migrate dev");
+    if (schemaProvider === "pgschema") {
+        log("  2. Install managed pgschema:  sqlx-js db install");
+        log("  3. Verify it:  sqlx-js db check");
+        log("  4. Edit schema.sql, then review:  sqlx-js db plan");
+        log("  5. After applying schema changes, run:  sqlx-js prepare");
+    }
+    else {
+        log("  2. Add a migration:  sqlx-js migrate add init");
+        log("  3. Make sure tsconfig.json \"include\" covers sqlx-js-env.d.ts.");
+        log("  4. Develop locally:  sqlx-js migrate dev");
+    }
 }

package/dist/src/commands/migrate.js

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { PgClient, parseDatabaseUrl, decodeText } from "../pg/wire.js";
-import { openSession, prepareOnce } from "./prepare.js";
+import { openSession, prepareOnce, verifyPrepareArtifacts } from "./prepare.js";
 import { introspectConnected, schemaSnapshotEqual, } from "../schema-snapshot.js";
 const SQUASH_PREFIX = "-- sqlx-js-squash:";
 export const DEFAULT_MIGRATE_LOCK_KEY = 18750938867203960n;
@@ -512,31 +512,16 @@ async function prepareWorkflowArtifacts(opts, databaseUrl) {
     }
 }
 async function prepareInTemporaryArtifacts(opts, databaseUrl) {
-    const tmp = mkdtempSync(join(tmpdir(), "sqlx-js-verify-"));
-    const cacheDir = join(tmp, "cache");
-    const dtsPath = join(tmp, "sqlx-js-env.d.ts");
-    const prepareOpts = {
+    const verification = await verifyPrepareArtifacts({
         root: opts.root,
         databaseUrl,
-        cacheDir,
-        dtsPath,
+        cacheDir: opts.cacheDir,
+        dtsPath: opts.dtsPath,
         check: false,
+        verify: true,
         prune: true,
-    };
-    const session = await openSession(prepareOpts);
-    try {
-        const r = await prepareOnce(prepareOpts, session);
-        if (r.failures > 0) {
-            console.error(`\n${r.failures} query/queries failed to prepare`);
-            return false;
-        }
-        console.log(`shadow: prepared ${r.entries} unique query/queries`);
-        return true;
-    }
-    finally {
-        await session.client.end();
-        rmSync(tmp, { recursive: true, force: true });
-    }
+    });
+    return verification.ok;
 }
 function effectiveSquashReplacements(all) {
     const covered = squashCoveredVersions(all);

package/dist/src/commands/pgschema.d.ts

@@ -0,0 +1,31 @@
+import type { SqlxJsConfig } from "../config.js";
+export type PgschemaSubcommand = "check" | "plan" | "apply";
+export declare const PGSCHEMA_VERSION = "1.12.0";
+export type PgschemaAsset = {
+    key: string;
+    name: string;
+    sha256: string;
+};
+export type PgschemaCommandOptions = {
+    root: string;
+    databaseUrl: string;
+    config: SqlxJsConfig;
+    subcommand: PgschemaSubcommand;
+    passthrough?: string[];
+};
+export type PgschemaInstallOptions = {
+    root: string;
+    asset?: PgschemaAsset;
+    baseUrl?: string;
+    log?: (msg: string) => void;
+};
+export type PgschemaProbe = {
+    ok: boolean;
+    command?: string;
+    message: string;
+};
+export declare function resolvePgschemaAsset(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): PgschemaAsset;
+export declare function managedPgschemaPath(root: string, asset?: PgschemaAsset): string;
+export declare function probePgschema(root: string, config: SqlxJsConfig): PgschemaProbe;
+export declare function runPgschemaInstall(opts: PgschemaInstallOptions): Promise<void>;
+export declare function runPgschemaCommand(opts: PgschemaCommandOptions): void;

package/dist/src/commands/pgschema.js

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseDatabaseUrl } from "../pg/wire.js";
+export const PGSCHEMA_VERSION = "1.12.0";
+const PGSCHEMA_BASE_URL = `https://github.com/pgplex/pgschema/releases/download/v${PGSCHEMA_VERSION}`;
+const WINDOWS_UNSUPPORTED = "sqlx-js db: pgschema is not supported on Windows. Run sqlx-js under WSL/Linux/macOS or use the built-in sqlx-js migrate workflow.";
+const PGSCHEMA_ASSETS = {
+    "darwin:x64": {
+        key: "darwin-amd64",
+        name: `pgschema-${PGSCHEMA_VERSION}-darwin-amd64`,
+        sha256: "c64b2ac24c4246344908910e892c4123be282bbb449f0b535079ff41d0f47c8f",
+    },
+    "darwin:arm64": {
+        key: "darwin-arm64",
+        name: `pgschema-${PGSCHEMA_VERSION}-darwin-arm64`,
+        sha256: "f01ea488f21700752d5747bc013c406daa583a68b631739f33af430d5d3ec449",
+    },
+    "linux:x64": {
+        key: "linux-amd64",
+        name: `pgschema-${PGSCHEMA_VERSION}-linux-amd64`,
+        sha256: "12610adf748b0dafe4e488ee7e9e68e6ffbef1f4e0f038dda36cf0138eede598",
+    },
+    "linux:arm64": {
+        key: "linux-arm64",
+        name: `pgschema-${PGSCHEMA_VERSION}-linux-arm64`,
+        sha256: "58ec57023954a0239cf9d607c4e5432da6dd0b279399d1c318204120619a221d",
+    },
+};
+export function resolvePgschemaAsset(platform = process.platform, arch = process.arch) {
+    if (platform === "win32")
+        throw new Error(WINDOWS_UNSUPPORTED);
+    const asset = PGSCHEMA_ASSETS[`${platform}:${arch}`];
+    if (!asset)
+        throw new Error(`sqlx-js db install: unsupported platform ${platform}/${arch}`);
+    return asset;
+}
+function pgschemaConfig(config) {
+    if (config.schema?.provider !== "pgschema") {
+        throw new Error("sqlx-js db: set schema.provider = \"pgschema\" in sqlx-js.config.ts");
+    }
+    return config.schema;
+}
+export function managedPgschemaPath(root, asset = resolvePgschemaAsset()) {
+    return join(root, "node_modules/.cache/sqlx-js/pgschema", `v${PGSCHEMA_VERSION}`, asset.key, "pgschema");
+}
+function maybeManagedPgschemaPath(root) {
+    try {
+        const asset = resolvePgschemaAsset();
+        const managed = managedPgschemaPath(root, asset);
+        if (!existsSync(managed))
+            return undefined;
+        if (sha256(readFileSync(managed)) !== asset.sha256) {
+            throw new Error(`sqlx-js db: managed pgschema checksum mismatch at ${managed}. Run sqlx-js db install.`);
+        }
+        chmodSync(managed, 0o755);
+        return managed;
+    }
+    catch (e) {
+        if (e.message.includes("checksum mismatch"))
+            throw e;
+        return undefined;
+    }
+}
+function commandName(root, config) {
+    if (process.platform === "win32")
+        throw new Error(WINDOWS_UNSUPPORTED);
+    if (config.command)
+        return config.command;
+    const managed = maybeManagedPgschemaPath(root);
+    if (managed && existsSync(managed))
+        return managed;
+    return "pgschema";
+}
+export function probePgschema(root, config) {
+    try {
+        const schema = pgschemaConfig(config);
+        const command = commandName(root, schema);
+        const child = spawnSync(command, ["--help"], {
+            encoding: "utf8",
+            env: process.env,
+            timeout: 5_000,
+        });
+        if (child.error) {
+            const code = child.error.code;
+            return {
+                ok: false,
+                command,
+                message: code === "ENOENT"
+                    ? installHint(command)
+                    : code === "ETIMEDOUT"
+                        ? `${command} --help timed out after 5000ms`
+                        : child.error.message,
+            };
+        }
+        if (child.status !== 0) {
+            return { ok: false, command, message: `${command} --help exited with ${child.status}` };
+        }
+        return { ok: true, command, message: `pgschema is available: ${command}` };
+    }
+    catch (e) {
+        return { ok: false, message: e.message };
+    }
+}
+function schemaFile(root, config) {
+    return resolve(root, config.file ?? "schema.sql");
+}
+function appliesPlan(subcommand, passthrough) {
+    return subcommand === "apply" && (passthrough ?? []).some((arg) => arg === "--plan" || arg.startsWith("--plan="));
+}
+function installHint(command) {
+    return `sqlx-js db: ${command} was not found. Run sqlx-js db install or set schema.command in sqlx-js.config.ts.`;
+}
+function run(command, args, env) {
+    const child = spawnSync(command, args, { encoding: "utf8", env, stdio: "inherit" });
+    if (child.error) {
+        const code = child.error.code;
+        if (code === "ENOENT")
+            throw new Error(installHint(command));
+        throw child.error;
+    }
+    if (child.signal)
+        throw new Error(`sqlx-js db: ${command} terminated by signal ${child.signal}`);
+    if (child.status && child.status !== 0)
+        process.exit(child.status);
+}
+function pgschemaEnv(db) {
+    return {
+        ...process.env,
+        ...(db.password ? { PGPASSWORD: db.password } : {}),
+        ...(db.sslmode ? { PGSSLMODE: db.sslmode } : {}),
+        ...(db.sslRootCert ? { PGSSLROOTCERT: db.sslRootCert } : {}),
+        ...(db.sslCert ? { PGSSLCERT: db.sslCert } : {}),
+        ...(db.sslKey ? { PGSSLKEY: db.sslKey } : {}),
+    };
+}
+function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+export async function runPgschemaInstall(opts) {
+    const asset = opts.asset ?? resolvePgschemaAsset();
+    const baseUrl = opts.baseUrl ?? PGSCHEMA_BASE_URL;
+    const log = opts.log ?? console.log;
+    const target = managedPgschemaPath(opts.root, asset);
+    if (existsSync(target) && sha256(readFileSync(target)) === asset.sha256) {
+        chmodSync(target, 0o755);
+        log(`pgschema v${PGSCHEMA_VERSION} already installed at ${target}`);
+        return;
+    }
+    const url = `${baseUrl.replace(/\/$/, "")}/${asset.name}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`sqlx-js db install: failed to download pgschema v${PGSCHEMA_VERSION}: HTTP ${response.status}`);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const actual = sha256(bytes);
+    if (actual !== asset.sha256) {
+        throw new Error(`sqlx-js db install: checksum mismatch for ${asset.name}`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(tmp, bytes, { mode: 0o755 });
+        chmodSync(tmp, 0o755);
+        renameSync(tmp, target);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw e;
+    }
+    writeFileSync(`${target}.json`, JSON.stringify({ version: PGSCHEMA_VERSION, asset: asset.name, sha256: asset.sha256 }, null, 2) + "\n");
+    log(`installed pgschema v${PGSCHEMA_VERSION} to ${target}`);
+}
+export function runPgschemaCommand(opts) {
+    const config = pgschemaConfig(opts.config);
+    const command = commandName(opts.root, config);
+    if (opts.subcommand === "check") {
+        run(command, ["--help"], process.env);
+        return;
+    }
+    if (!opts.databaseUrl)
+        throw new Error("DATABASE_URL is required for sqlx-js db commands");
+    const file = appliesPlan(opts.subcommand, opts.passthrough) ? undefined : schemaFile(opts.root, config);
+    if (file && !existsSync(file))
+        throw new Error(`sqlx-js db: schema file not found: ${file}`);
+    const db = parseDatabaseUrl(opts.databaseUrl);
+    const schemas = pgschemaSchemas(config);
+    const args = [
+        opts.subcommand,
+        "--host", db.host,
+        "--port", String(db.port),
+        "--db", db.database,
+        "--user", db.user,
+    ];
+    if (file)
+        args.push("--file", file);
+    args.push("--schema", schemas[0]);
+    args.push(...opts.passthrough ?? []);
+    run(command, args, pgschemaEnv(db));
+}
+function pgschemaSchemas(config) {
+    const schemas = config.schemas?.length ? config.schemas : ["public"];
+    if (schemas.length > 1) {
+        throw new Error("sqlx-js db: pgschema 1.12.0 supports exactly one --schema value; split plan/apply per schema or use a single schema in sqlx-js.config.ts");
+    }
+    return schemas;
+}

package/dist/src/commands/prepare.d.ts

@@ -7,8 +7,42 @@ export type PrepareOptions = {
     cacheDir: string;
     dtsPath: string;
     check: boolean;
+    verify?: boolean;
+    json?: boolean;
     prune?: boolean;
 };
+export type PrepareDiagnosticPhase = "config" | "connect" | "shadow" | "scan" | "describe" | "introspect" | "analyze" | "param-map" | "cache" | "verify";
+export declare class PrepareFatalError extends Error {
+    readonly phase: PrepareDiagnosticPhase;
+    readonly file?: string;
+    readonly line?: number;
+    readonly column?: number;
+    constructor(phase: PrepareDiagnosticPhase, message: string, location?: {
+        file?: string;
+        line?: number;
+        column?: number;
+    }, options?: ErrorOptions);
+}
+export type PrepareDiagnostic = {
+    severity: "error" | "warning";
+    phase: PrepareDiagnosticPhase;
+    message: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    query?: string;
+    code?: string;
+    position?: number;
+    hint?: string;
+};
+export type PrepareResult = {
+    sites: number;
+    entries: number;
+    failures: number;
+    pruned: number;
+    functions: number;
+    diagnostics: PrepareDiagnostic[];
+};
 export type PrepareSession = {
     client: PgClient;
     schema: SchemaCache;
@@ -28,10 +62,11 @@ export declare function describeAll(cfg: ConnConfig, sessionClient: PgClient, qu
     fp: string;
     query: string;
 }[], concurrency: number): Promise<Map<string, DescribeOutcome>>;
-export declare function prepareOnce(opts: PrepareOptions, session: PrepareSession, log?: (msg: string) => void, err?: (msg: string) => void, concurrency?: number): Promise<{
-    entries: number;
-    failures: number;
-    pruned: number;
-}>;
+export declare function prepareOnce(opts: PrepareOptions, session: PrepareSession, log?: (msg: string) => void, err?: (msg: string) => void, concurrency?: number): Promise<PrepareResult>;
 export declare function runPrepare(opts: PrepareOptions): Promise<void>;
+export declare function verifyPrepareArtifacts(opts: PrepareOptions, log?: (msg: string) => void, err?: (msg: string) => void): Promise<{
+    ok: boolean;
+    result: PrepareResult;
+    changed: string[];
+}>;
 export {};