@onreza/sqlx-js 0.4.0 → 0.6.0

package/dist/bin/sqlx-js.js

@@ -2,13 +2,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { runPrepare } from "../src/commands/prepare.js";
-import { runWatch } from "../src/commands/watch.js";
-import { migrateArchiveList, migrateArchiveRestore, migrateCheck, migrateDev, migrateRun, migrateInfo, migrateRevert, migrateAdd, migrateSquash, migrateVerify, } from "../src/commands/migrate.js";
-import { applyShadowMigrations, runSchemaCheck, runSchemaDump } from "../src/commands/schema.js";
-import { runInit } from "../src/commands/init.js";
-import { runPgschemaCommand, runPgschemaInstall } from "../src/commands/pgschema.js";
-import { loadConfig } from "../src/config.js";
+import { parseArgs } from "node:util";
+import { assertSupportedRuntime, loadConfig, loadRootEnv } from "../src/config.js";
 function packageVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
     for (const path of [join(here, "../package.json"), join(here, "../../package.json")]) {
@@ -21,16 +16,20 @@ function packageVersion() {
     throw new Error("sqlx-js: cannot locate package.json for version");
 }
 const VERSION = packageVersion();
-function help() {
-    console.error(`sqlx-js — compile-time-checked SQL for TypeScript + Postgres (v${VERSION})
+const HELP = {
+    root: `sqlx-js — compile-time-checked SQL for TypeScript + Postgres (v${VERSION})
 
 usage:
   sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]
-  sqlx-js db install | check | plan | apply [--root <dir>] [-- <pgschema args>]
-  sqlx-js prepare [--check | --watch] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
-  sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | verify [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] [--pg-dump <path>] [--lock-timeout <ms>] | archive list | archive restore <name> [--force]
-  sqlx-js schema dump | check [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
+  sqlx-js doctor [--root <dir>] [--dts <path>] [--json]
+  sqlx-js db install | check [--root <dir>]
+  sqlx-js db plan | apply [--root <dir>] [-- <pgschema args>]
+  sqlx-js prepare [--check | --verify | --watch] [--json] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
+  sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | verify [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] [--pg-dump <path>] [--lock-timeout <ms>] | archive list | archive restore <name> [--force]
+  sqlx-js schema dump [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
+  sqlx-js schema check [--schema <path>] [--shadow-url <url>]
   sqlx-js --version
+  sqlx-js-diagnostics github|unix < prepare-diagnostics.json
 
 env:
   DATABASE_URL=postgres://...  (supports sslmode, cert paths, application_name, connect_timeout, statement_timeout)
@@ -41,11 +40,13 @@ flags:
   --root <dir>             scan root (default: cwd)
   --dts <path>             declarations output (default: <root>/sqlx-js-env.d.ts)
   --check                  offline mode: verify scanned queries exist in cache, no DB
+  --verify                 prepare against DB/shadow and compare committed generated artifacts
   --watch                  re-prepare on file change (persistent PG connection)
   --no-prune               keep orphaned cache entries (default: remove)
   --migrations <dir>       migrations directory (default: <root>/migrations)
   --dry-run                validate and print migrate run/revert plan without applying migrations
-  --json                   machine-readable output for migrate info/check and migrate run/revert --dry-run
+  --json                   machine-readable output for prepare and migration inspection/dry-run commands
+  --strict-inference       fail when query inference degrades or emits unknown types
   --force                  allow archive restore to overwrite existing migration files
   --lock-timeout <ms>      advisory-lock acquisition timeout for migrate run/revert/dev/verify/squash
   --shadow-url <url>       use an existing disposable shadow DB instead of auto-creating one
@@ -56,52 +57,250 @@ flags:
   --manifest <path>        LLM schema manifest path (default: <root>/.sqlx-js/schema/schema.md)
   --no-manifest            skip writing the LLM schema manifest during schema dump
   --schema-provider <name> init schema workflow: builtin (default) or pgschema
-`);
-    process.exit(2);
+`,
+    init: `usage: sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]`,
+    doctor: `usage: sqlx-js doctor [--root <dir>] [--dts <path>] [--json]`,
+    db: `usage: sqlx-js db install | check [--root <dir>] | plan | apply [--root <dir>] [-- <pgschema args>]`,
+    prepare: `usage: sqlx-js prepare [--check | --verify | --watch] [--json] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]`,
+    migrate: `usage: sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | verify [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] [--pg-dump <path>] [--lock-timeout <ms>] | archive list | archive restore <name> [--force]`,
+    schema: `usage: sqlx-js schema dump [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>] | check [--schema <path>] [--shadow-url <url>]`,
+};
+function printHelp(scope, error = false) {
+    (error ? console.error : console.log)(HELP[scope]);
 }
-const passthroughIndex = process.argv.indexOf("--");
-const cliArgv = passthroughIndex >= 0 ? process.argv.slice(0, passthroughIndex) : process.argv;
-const passthroughArgs = passthroughIndex >= 0 ? process.argv.slice(passthroughIndex + 1) : [];
-function arg(name, def) {
-    const eq = `${name}=`;
-    for (let i = 0; i < cliArgv.length; i++) {
-        const a = cliArgv[i];
-        if (a === name)
-            return cliArgv[i + 1] ?? def;
-        if (a.startsWith(eq))
-            return a.slice(eq.length);
-    }
-    return def;
+function exitHelp(scope) {
+    printHelp(scope);
+    process.exit(0);
 }
-function flag(name) {
-    for (const a of cliArgv) {
-        if (a === name)
-            return true;
-    }
-    return false;
+function usageError(message, scope = "root") {
+    console.error(`sqlx-js: ${message}`);
+    printHelp(scope, true);
+    process.exit(2);
 }
-const cmd = process.argv[2];
+const rawArgv = process.argv.slice(2);
+const passthroughIndex = rawArgv.indexOf("--");
+const cliArgv = passthroughIndex >= 0 ? rawArgv.slice(0, passthroughIndex) : rawArgv;
+const passthroughArgs = passthroughIndex >= 0 ? rawArgv.slice(passthroughIndex + 1) : [];
+const cmd = cliArgv[0];
+const scopes = new Set(["init", "doctor", "db", "prepare", "migrate", "schema"]);
 if (cmd === "--version" || cmd === "-v") {
     console.log(VERSION);
     process.exit(0);
 }
-if (cmd === "--help" || cmd === "-h" || !cmd) {
-    help();
+if (!cmd || cmd === "--help" || cmd === "-h")
+    exitHelp("root");
+if (!scopes.has(cmd))
+    usageError(`unknown command ${JSON.stringify(cmd)}`);
+const scope = cmd;
+if (cliArgv.includes("--help") || cliArgv.includes("-h"))
+    exitHelp(scope);
+if (passthroughIndex >= 0 && cmd !== "db")
+    usageError("arguments after -- are only supported by sqlx-js db", scope);
+const ROOT_OPTIONS = {
+    root: { type: "string" },
+    help: { type: "boolean", short: "h" },
+};
+function optionsFor(command, subcommand) {
+    if (command === "init")
+        return { ...ROOT_OPTIONS, "schema-provider": { type: "string" } };
+    if (command === "doctor")
+        return { ...ROOT_OPTIONS, dts: { type: "string" }, json: { type: "boolean" } };
+    if (command === "db")
+        return ROOT_OPTIONS;
+    if (command === "prepare") {
+        return {
+            ...ROOT_OPTIONS,
+            dts: { type: "string" },
+            check: { type: "boolean" },
+            verify: { type: "boolean" },
+            watch: { type: "boolean" },
+            json: { type: "boolean" },
+            "no-prune": { type: "boolean" },
+            "shadow-url": { type: "string" },
+            migrations: { type: "string" },
+            "strict-inference": { type: "boolean" },
+        };
+    }
+    if (command === "schema") {
+        const common = {
+            ...ROOT_OPTIONS,
+            schema: { type: "string" },
+            "shadow-url": { type: "string" },
+            migrations: { type: "string" },
+        };
+        return subcommand === "dump"
+            ? { ...common, manifest: { type: "string" }, "no-manifest": { type: "boolean" } }
+            : common;
+    }
+    const common = { ...ROOT_OPTIONS, migrations: { type: "string" } };
+    if (subcommand === "run") {
+        return { ...common, "dry-run": { type: "boolean" }, json: { type: "boolean" }, "lock-timeout": { type: "string" } };
+    }
+    if (subcommand === "info" || subcommand === "check")
+        return { ...common, json: { type: "boolean" } };
+    if (subcommand === "dev") {
+        return {
+            ...common,
+            "shadow-admin-url": { type: "string" },
+            "shadow-url": { type: "string" },
+            "lock-timeout": { type: "string" },
+            "no-prune": { type: "boolean" },
+            "strict-inference": { type: "boolean" },
+        };
+    }
+    if (subcommand === "verify") {
+        return {
+            ...common,
+            "shadow-admin-url": { type: "string" },
+            "shadow-url": { type: "string" },
+            "lock-timeout": { type: "string" },
+            "strict-inference": { type: "boolean" },
+        };
+    }
+    if (subcommand === "revert") {
+        return {
+            ...common,
+            "dry-run": { type: "boolean" },
+            json: { type: "boolean" },
+            "shadow-admin-url": { type: "string" },
+            "shadow-url": { type: "string" },
+            "lock-timeout": { type: "string" },
+        };
+    }
+    if (subcommand === "squash") {
+        return {
+            ...common,
+            "shadow-admin-url": { type: "string" },
+            "shadow-url": { type: "string" },
+            "lock-timeout": { type: "string" },
+            replace: { type: "boolean" },
+            "pg-dump": { type: "string" },
+        };
+    }
+    if (subcommand === "archive")
+        return { ...common, force: { type: "boolean" } };
+    return common;
+}
+const commandArgv = cliArgv.slice(1);
+const subcommand = commandArgv[0]?.startsWith("-") ? undefined : commandArgv[0];
+let parsed;
+try {
+    parsed = parseArgs({
+        args: commandArgv,
+        options: optionsFor(cmd, subcommand),
+        strict: true,
+        allowPositionals: true,
+    });
 }
+catch (error) {
+    usageError(error.message, scope);
+}
+const values = parsed.values;
+const positionals = parsed.positionals;
+function arg(name, def) {
+    const value = values[name.replace(/^--/, "")];
+    return typeof value === "string" ? value : def;
+}
+function flag(name) {
+    return values[name.replace(/^--/, "")] === true;
+}
+function requirePositionals(min, max, label) {
+    if (positionals.length < min || positionals.length > max) {
+        usageError(`${label}: expected ${min === max ? min : `${min} to ${max}`} positional argument(s)`, scope);
+    }
+}
+function validateInvocation() {
+    if (cmd === "init" || cmd === "doctor" || cmd === "prepare") {
+        requirePositionals(0, 0, cmd);
+        return;
+    }
+    if (cmd === "db") {
+        requirePositionals(1, 1, "db");
+        const sub = positionals[0];
+        if (sub !== "install" && sub !== "check" && sub !== "plan" && sub !== "apply") {
+            usageError(`unknown db command ${JSON.stringify(sub)}`, "db");
+        }
+        if (passthroughArgs.length > 0 && sub !== "plan" && sub !== "apply") {
+            usageError(`db ${sub} does not accept arguments after --`, "db");
+        }
+        return;
+    }
+    if (cmd === "schema") {
+        requirePositionals(1, 1, "schema");
+        const sub = positionals[0];
+        if (sub !== "dump" && sub !== "check")
+            usageError(`unknown schema command ${JSON.stringify(sub)}`, "schema");
+        return;
+    }
+    const sub = positionals[0];
+    if (!sub)
+        usageError("migrate command is required", "migrate");
+    if (["dev", "verify", "run", "info", "check", "revert"].includes(sub)) {
+        requirePositionals(1, 1, `migrate ${sub}`);
+        return;
+    }
+    if (sub === "add" || sub === "squash") {
+        requirePositionals(2, 2, `migrate ${sub}`);
+        return;
+    }
+    if (sub === "archive") {
+        const action = positionals[1];
+        if (action === "list") {
+            requirePositionals(2, 2, "migrate archive list");
+            if (flag("--force"))
+                usageError("--force is only supported by migrate archive restore", "migrate");
+        }
+        else if (action === "restore")
+            requirePositionals(3, 3, "migrate archive restore");
+        else
+            usageError(`unknown migrate archive command ${JSON.stringify(action)}`, "migrate");
+        return;
+    }
+    usageError(`unknown migrate command ${JSON.stringify(sub)}`, "migrate");
+}
+validateInvocation();
 const root = resolve(arg("--root", process.cwd()));
+if (cmd !== "doctor") {
+    try {
+        assertSupportedRuntime();
+    }
+    catch (e) {
+        console.error(e.message);
+        process.exit(2);
+    }
+}
+let envError;
+const needsEnvironment = cmd === "doctor" ||
+    cmd === "schema" ||
+    (cmd === "db" && (positionals[0] === "plan" || positionals[0] === "apply")) ||
+    (cmd === "prepare" && !flag("--check")) ||
+    (cmd === "migrate" && !["add", "check", "archive"].includes(positionals[0]));
+if (needsEnvironment) {
+    try {
+        loadRootEnv(root);
+    }
+    catch (e) {
+        envError = e.message;
+        if (cmd !== "doctor") {
+            console.error(envError);
+            process.exit(2);
+        }
+    }
+}
 const databaseUrl = process.env.DATABASE_URL ?? "";
 const shadowUrlArg = arg("--shadow-url");
 const shadowUrl = shadowUrlArg ?? process.env.SHADOW_DATABASE_URL;
 const shadowAdminUrl = arg("--shadow-admin-url") ?? process.env.SHADOW_ADMIN_DATABASE_URL;
 const cacheDir = join(root, ".sqlx-js");
 const dtsArg = arg("--dts");
-const dtsPath = dtsArg ? resolve(dtsArg) : join(root, "sqlx-js-env.d.ts");
+const dtsPath = dtsArg ? resolve(root, dtsArg) : join(root, "sqlx-js-env.d.ts");
 const migrationsDir = join(root, arg("--migrations", "migrations"));
 const schemaArg = arg("--schema");
-const schemaPath = schemaArg ? resolve(schemaArg) : join(root, ".sqlx-js/schema/schema.json");
+const schemaPath = schemaArg ? resolve(root, schemaArg) : join(root, ".sqlx-js/schema/schema.json");
 const manifestArg = arg("--manifest");
-const manifestPath = manifestArg ? resolve(manifestArg) : join(root, ".sqlx-js/schema/schema.md");
+const manifestPath = manifestArg ? resolve(root, manifestArg) : join(root, ".sqlx-js/schema/schema.md");
 if (cmd === "init") {
+    const { runInit } = await import("../src/commands/init.js");
     const provider = arg("--schema-provider", "builtin");
     if (provider !== "builtin" && provider !== "pgschema") {
         console.error("--schema-provider must be builtin or pgschema");
@@ -109,8 +308,13 @@ if (cmd === "init") {
     }
     runInit({ root, schemaProvider: provider });
 }
+else if (cmd === "doctor") {
+    const { runDoctor } = await import("../src/commands/doctor.js");
+    await runDoctor({ root, databaseUrl, cacheDir, dtsPath, json: flag("--json"), envError });
+}
 else if (cmd === "db") {
-    const sub = process.argv[3];
+    const { runPgschemaCommand, runPgschemaInstall } = await import("../src/commands/pgschema.js");
+    const sub = positionals[0];
     if (sub === "install") {
         try {
             await runPgschemaInstall({ root });
@@ -121,8 +325,6 @@ else if (cmd === "db") {
         }
     }
     else {
-        if (sub !== "check" && sub !== "plan" && sub !== "apply")
-            help();
         try {
             runPgschemaCommand({
                 root,
@@ -139,29 +341,64 @@ else if (cmd === "db") {
     }
 }
 else if (cmd === "prepare") {
-    if (flag("--check") && shadowUrlArg) {
-        console.error("--shadow-url cannot be used with prepare --check; use live prepare or schema check --shadow-url");
-        process.exit(2);
+    const { PrepareFatalError, runPrepare } = await import("../src/commands/prepare.js");
+    const prepareCheck = flag("--check");
+    const prepareVerify = flag("--verify");
+    const prepareWatch = flag("--watch");
+    const prepareJson = flag("--json");
+    const prepareMode = prepareVerify ? "verify" : prepareCheck ? "check" : "prepare";
+    const failPrepare = (message, phase, exitCode = 2, location = {}) => {
+        if (prepareJson) {
+            console.log(JSON.stringify({
+                formatVersion: 1,
+                ok: false,
+                mode: prepareMode,
+                sites: 0,
+                entries: 0,
+                failures: 1,
+                pruned: 0,
+                functions: 0,
+                diagnostics: [{ severity: "error", phase, message, ...location }],
+            }, null, 2));
+        }
+        else {
+            console.error(message);
+        }
+        process.exit(exitCode);
+    };
+    if ([prepareCheck, prepareVerify, prepareWatch].filter(Boolean).length > 1) {
+        failPrepare("--check, --verify, and --watch are mutually exclusive", "config");
+    }
+    if (prepareCheck && shadowUrlArg) {
+        failPrepare("--shadow-url cannot be used with prepare --check; use live prepare or schema check --shadow-url", "config");
+    }
+    if (prepareWatch && prepareJson) {
+        failPrepare("--watch and --json are mutually exclusive", "config");
+    }
+    if ((prepareCheck || prepareVerify) && flag("--no-prune")) {
+        failPrepare("--no-prune is only supported by prepare and prepare --watch", "config");
     }
-    const prepareShadowUrl = flag("--check") ? undefined : shadowUrl;
+    const prepareShadowUrl = prepareCheck ? undefined : shadowUrl;
     const prepareDatabaseUrl = prepareShadowUrl ?? databaseUrl;
-    if (!flag("--check") && !prepareDatabaseUrl) {
-        console.error("DATABASE_URL is required for prepare (use --check for offline)");
-        process.exit(2);
+    if (!prepareCheck && !prepareDatabaseUrl) {
+        failPrepare("DATABASE_URL is required for prepare (use --check for offline)", "connect");
     }
     const opts = {
         root,
         databaseUrl: prepareDatabaseUrl,
         cacheDir,
         dtsPath,
-        check: flag("--check"),
+        check: prepareCheck,
+        verify: prepareVerify,
+        json: prepareJson,
         prune: !flag("--no-prune"),
+        strictInference: flag("--strict-inference"),
     };
-    if (flag("--watch")) {
-        if (flag("--check")) {
-            console.error("--watch and --check are mutually exclusive");
-            process.exit(2);
-        }
+    const applyShadowMigrations = prepareShadowUrl
+        ? (await import("../src/commands/schema.js")).applyShadowMigrations
+        : undefined;
+    if (prepareWatch) {
+        const { runWatch } = await import("../src/commands/watch.js");
         await runWatch({
             ...opts,
             ...(prepareShadowUrl
@@ -175,13 +412,33 @@ else if (cmd === "prepare") {
         });
     }
     else {
-        if (prepareShadowUrl)
-            await applyShadowMigrations(prepareShadowUrl, migrationsDir);
-        await runPrepare(opts);
+        if (prepareShadowUrl) {
+            try {
+                await applyShadowMigrations(prepareShadowUrl, migrationsDir, prepareJson ? () => { } : console.log);
+            }
+            catch (e) {
+                failPrepare(e.message, "shadow", 1);
+            }
+        }
+        try {
+            await runPrepare(opts);
+        }
+        catch (e) {
+            const message = e.message;
+            const phase = e instanceof PrepareFatalError
+                ? e.phase
+                : prepareVerify
+                    ? "verify"
+                    : "scan";
+            failPrepare(message, phase, 1, e instanceof PrepareFatalError
+                ? { file: e.file, line: e.line, column: e.column }
+                : {});
+        }
     }
 }
 else if (cmd === "schema") {
-    const sub = process.argv[3];
+    const { runSchemaCheck, runSchemaDump } = await import("../src/commands/schema.js");
+    const sub = positionals[0];
     const schemaDatabaseUrl = shadowUrl ?? databaseUrl;
     if (!schemaDatabaseUrl) {
         console.error("DATABASE_URL is required for schema commands (or pass --shadow-url)");
@@ -199,19 +456,21 @@ else if (cmd === "schema") {
         await runSchemaDump(opts);
     else if (sub === "check")
         await runSchemaCheck(opts);
-    else
-        help();
 }
 else if (cmd === "migrate") {
-    const sub = process.argv[3];
+    const { migrateArchiveList, migrateArchiveRestore, migrateCheck, migrateDev, migrateRun, migrateInfo, migrateRevert, migrateAdd, migrateSquash, migrateVerify, } = await import("../src/commands/migrate.js");
+    const sub = positionals[0];
     const revertDryRun = sub === "revert" && flag("--dry-run");
     const workflowShadowOnly = ((sub === "dev" || sub === "verify" || sub === "squash") && !!shadowUrl) || (revertDryRun && !!shadowUrl);
-    if (!databaseUrl && sub !== "add" && sub !== "check" && sub !== "squash" && sub !== "archive" && !workflowShadowOnly) {
+    if (!databaseUrl && sub !== "add" && sub !== "check" && sub !== "archive" && !workflowShadowOnly) {
         console.error("DATABASE_URL is required");
         process.exit(2);
     }
     const tRaw = arg("--lock-timeout");
     const lockTimeoutMs = tRaw ? Number(tRaw) : undefined;
+    if (lockTimeoutMs !== undefined && !Number.isFinite(lockTimeoutMs)) {
+        usageError("--lock-timeout must be a finite number of milliseconds", "migrate");
+    }
     if (sub === "dev") {
         await migrateDev({
             root,
@@ -223,6 +482,7 @@ else if (cmd === "migrate") {
             shadowUrl,
             shadowAdminUrl,
             lockTimeoutMs,
+            strictInference: flag("--strict-inference"),
         });
     }
     else if (sub === "verify") {
@@ -235,15 +495,18 @@ else if (cmd === "migrate") {
             shadowUrl,
             shadowAdminUrl,
             lockTimeoutMs,
+            strictInference: flag("--strict-inference"),
         });
     }
     else if (sub === "run") {
         await migrateRun({ databaseUrl, migrationsDir, lockTimeoutMs, dryRun: flag("--dry-run"), json: flag("--json") });
     }
-    else if (sub === "info")
+    else if (sub === "info") {
         await migrateInfo({ databaseUrl, migrationsDir, json: flag("--json") });
-    else if (sub === "check")
+    }
+    else if (sub === "check") {
         migrateCheck({ migrationsDir, json: flag("--json") });
+    }
     else if (sub === "revert") {
         await migrateRevert({
             databaseUrl,
@@ -256,19 +519,11 @@ else if (cmd === "migrate") {
         });
     }
     else if (sub === "add") {
-        const name = process.argv[4];
-        if (!name) {
-            console.error("migrate add: name required");
-            process.exit(2);
-        }
+        const name = positionals[1];
         migrateAdd({ databaseUrl, migrationsDir, name });
     }
     else if (sub === "squash") {
-        const name = process.argv[4];
-        if (!name) {
-            console.error("migrate squash: name required");
-            process.exit(2);
-        }
+        const name = positionals[1];
         await migrateSquash({
             databaseUrl,
             migrationsDir,
@@ -281,23 +536,16 @@ else if (cmd === "migrate") {
         });
     }
     else if (sub === "archive") {
-        const action = process.argv[4];
-        if (action === "list")
+        const action = positionals[1];
+        if (action === "list") {
             migrateArchiveList({ migrationsDir });
+        }
         else if (action === "restore") {
-            const name = process.argv[5];
-            if (!name) {
-                console.error("migrate archive restore: name required");
-                process.exit(2);
-            }
+            const name = positionals[2];
             migrateArchiveRestore({ migrationsDir, name, force: flag("--force") });
         }
-        else
-            help();
     }
-    else
-        help();
 }
 else {
-    help();
+    usageError(`unknown command ${JSON.stringify(cmd)}`);
 }

package/dist/src/artifacts.d.ts

@@ -0,0 +1,9 @@
+export type ArtifactSet = {
+    cacheDir: string;
+    dtsPath: string;
+};
+export type ArtifactComparison = {
+    ok: boolean;
+    changed: string[];
+};
+export declare function compareArtifacts(expected: ArtifactSet, actual: ArtifactSet): ArtifactComparison;

package/dist/src/artifacts.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { CACHE_MANIFEST_FILE } from "./cache.js";
+function readGeneratedFiles(set) {
+    const files = new Map();
+    if (existsSync(set.cacheDir)) {
+        for (const name of readdirSync(set.cacheDir).sort()) {
+            if (name !== CACHE_MANIFEST_FILE && !/^[0-9a-f]{16}\.json$/.test(name))
+                continue;
+            files.set(`cache/${name}`, readFileSync(join(set.cacheDir, name), "utf8"));
+        }
+        const functions = join(set.cacheDir, "functions/functions.json");
+        if (existsSync(functions))
+            files.set("cache/functions/functions.json", readFileSync(functions, "utf8"));
+    }
+    if (existsSync(set.dtsPath))
+        files.set("sqlx-js-env.d.ts", readFileSync(set.dtsPath, "utf8"));
+    return files;
+}
+export function compareArtifacts(expected, actual) {
+    const left = readGeneratedFiles(expected);
+    const right = readGeneratedFiles(actual);
+    const names = new Set([...left.keys(), ...right.keys()]);
+    const changed = [...names].filter((name) => left.get(name) !== right.get(name)).sort();
+    return { ok: changed.length === 0, changed };
+}

package/dist/src/cache.d.ts

@@ -1,3 +1,11 @@
+export declare const CACHE_FORMAT_VERSION = 2;
+export declare const GENERATOR_REVISION = 3;
+export declare const CACHE_MANIFEST_FILE = "cache-manifest.json";
+export type CacheManifest = {
+    cacheFormat: typeof CACHE_FORMAT_VERSION;
+    generatorRevision: typeof GENERATOR_REVISION;
+    configHash: string;
+};
 export type CacheColumn = {
     name: string;
     typeOid: number;
@@ -19,6 +27,7 @@ export type CacheEntry = {
         reason: string;
     };
 };
+export declare function portableCacheOid(oid: number): number;
 export declare function fingerprint(query: string): string;
 export declare function effectiveNullable(c: CacheColumn): boolean;
 export declare class Cache {
@@ -28,6 +37,10 @@ export declare class Cache {
     has(fp: string): boolean;
     read(fp: string): CacheEntry | null;
     write(fp: string, entry: CacheEntry): void;
+    replaceAll(entries: Iterable<{
+        fp: string;
+        entry: CacheEntry;
+    }>, prune?: boolean): string[];
     list(): {
         fp: string;
         entry: CacheEntry;
@@ -35,3 +48,7 @@ export declare class Cache {
     remove(fp: string): void;
     prune(keep: Iterable<string>): string[];
 }
+export declare function cacheManifestPath(cacheDir: string): string;
+export declare function writeCacheManifest(cacheDir: string, configHash: string): void;
+export declare function readCacheManifest(cacheDir: string): CacheManifest | null;
+export declare function assertCacheManifest(cacheDir: string, configHash: string): CacheManifest;