@onreza/sqlx-js 0.5.0 → 0.7.0

package/dist/bin/sqlx-js.js

@@ -2,13 +2,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { PrepareFatalError, 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 { runDoctor } from "../src/commands/doctor.js";
+import { parseArgs } from "node:util";
 import { assertSupportedRuntime, loadConfig, loadRootEnv } from "../src/config.js";
 function packageVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -22,33 +16,39 @@ 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 doctor [--root <dir>] [--json]
-  sqlx-js db install | check | plan | apply [--root <dir>] [-- <pgschema args>]
-  sqlx-js prepare [--check | --verify | --watch] [--json] [--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 | --offline | --verify | --watch] [--json | --jsonl] [--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)
+  DATABASE_URL=postgres://...  (supports sslmode, cert paths, application_name, options, connect_timeout, statement_timeout)
   SHADOW_DATABASE_URL=postgres://...  (optional pre-created disposable shadow DB)
   SHADOW_ADMIN_DATABASE_URL=postgres://...  (optional admin URL for auto-created shadow DBs)
 
 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
+  --check                  read-only offline verification of cache and declarations
+  --offline                regenerate declarations from committed 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 prepare and migration inspection/dry-run commands
+  --jsonl                  streaming machine-readable output for prepare --watch
+  --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
@@ -59,38 +59,210 @@ 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 | --offline | --verify | --watch] [--json | --jsonl] [--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" },
+            offline: { type: "boolean" },
+            verify: { type: "boolean" },
+            watch: { type: "boolean" },
+            json: { type: "boolean" },
+            jsonl: { 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 {
@@ -102,14 +274,21 @@ if (cmd !== "doctor") {
     }
 }
 let envError;
-try {
-    loadRootEnv(root);
-}
-catch (e) {
-    envError = e.message;
-    if (cmd !== "doctor") {
-        console.error(envError);
-        process.exit(2);
+const needsEnvironment = cmd === "doctor" ||
+    cmd === "schema" ||
+    (cmd === "db" && (positionals[0] === "plan" || positionals[0] === "apply")) ||
+    (cmd === "prepare" && !flag("--check") && !flag("--offline")) ||
+    (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 ?? "";
@@ -118,13 +297,14 @@ 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");
@@ -133,10 +313,12 @@ 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 });
@@ -147,8 +329,6 @@ else if (cmd === "db") {
         }
     }
     else {
-        if (sub !== "check" && sub !== "plan" && sub !== "apply")
-            help();
         try {
             runPgschemaCommand({
                 root,
@@ -165,13 +345,24 @@ else if (cmd === "db") {
     }
 }
 else if (cmd === "prepare") {
+    const { PrepareFatalError, runPrepare } = await import("../src/commands/prepare.js");
     const prepareCheck = flag("--check");
+    const prepareOffline = flag("--offline");
     const prepareVerify = flag("--verify");
     const prepareWatch = flag("--watch");
     const prepareJson = flag("--json");
-    const prepareMode = prepareVerify ? "verify" : prepareCheck ? "check" : "prepare";
+    const prepareJsonl = flag("--jsonl");
+    const prepareMode = prepareVerify ? "verify" : prepareCheck ? "check" : prepareOffline ? "offline" : "prepare";
     const failPrepare = (message, phase, exitCode = 2, location = {}) => {
-        if (prepareJson) {
+        if (prepareJsonl) {
+            console.log(JSON.stringify({
+                formatVersion: 1,
+                event: "error",
+                timestamp: new Date().toISOString(),
+                diagnostic: { severity: "error", phase, message, ...location },
+            }));
+        }
+        else if (prepareJson) {
             console.log(JSON.stringify({
                 formatVersion: 1,
                 ok: false,
@@ -189,19 +380,28 @@ else if (cmd === "prepare") {
         }
         process.exit(exitCode);
     };
-    if ([prepareCheck, prepareVerify, prepareWatch].filter(Boolean).length > 1) {
-        failPrepare("--check, --verify, and --watch are mutually exclusive", "config");
+    if ([prepareCheck, prepareOffline, prepareVerify, prepareWatch].filter(Boolean).length > 1) {
+        failPrepare("--check, --offline, --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 ((prepareCheck || prepareOffline) && shadowUrlArg) {
+        failPrepare("--shadow-url cannot be used with offline prepare modes; use live prepare or schema check --shadow-url", "config");
     }
     if (prepareWatch && prepareJson) {
         failPrepare("--watch and --json are mutually exclusive", "config");
     }
-    const prepareShadowUrl = prepareCheck ? undefined : shadowUrl;
+    if (prepareJson && prepareJsonl) {
+        failPrepare("--json and --jsonl are mutually exclusive", "config");
+    }
+    if (prepareJsonl && !prepareWatch) {
+        failPrepare("--jsonl is only supported by prepare --watch", "config");
+    }
+    if ((prepareCheck || prepareOffline || prepareVerify) && flag("--no-prune")) {
+        failPrepare("--no-prune is only supported by live prepare and prepare --watch", "config");
+    }
+    const prepareShadowUrl = prepareCheck || prepareOffline ? undefined : shadowUrl;
     const prepareDatabaseUrl = prepareShadowUrl ?? databaseUrl;
-    if (!prepareCheck && !prepareDatabaseUrl) {
-        failPrepare("DATABASE_URL is required for prepare (use --check for offline)", "connect");
+    if (!prepareCheck && !prepareOffline && !prepareDatabaseUrl) {
+        failPrepare("DATABASE_URL is required for prepare (use --check or --offline without a database)", "connect");
     }
     const opts = {
         root,
@@ -209,13 +409,20 @@ else if (cmd === "prepare") {
         cacheDir,
         dtsPath,
         check: prepareCheck,
+        offline: prepareOffline,
         verify: prepareVerify,
         json: prepareJson,
         prune: !flag("--no-prune"),
+        strictInference: flag("--strict-inference"),
     };
+    const applyShadowMigrations = prepareShadowUrl
+        ? (await import("../src/commands/schema.js")).applyShadowMigrations
+        : undefined;
     if (prepareWatch) {
+        const { runWatch } = await import("../src/commands/watch.js");
         await runWatch({
             ...opts,
+            jsonl: prepareJsonl,
             ...(prepareShadowUrl
                 ? {
                     beforePrepare: async () => {
@@ -252,7 +459,8 @@ else if (cmd === "prepare") {
     }
 }
 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)");
@@ -270,19 +478,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,
@@ -294,6 +504,7 @@ else if (cmd === "migrate") {
             shadowUrl,
             shadowAdminUrl,
             lockTimeoutMs,
+            strictInference: flag("--strict-inference"),
         });
     }
     else if (sub === "verify") {
@@ -306,15 +517,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,
@@ -327,19 +541,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,
@@ -352,23 +558,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/cache.d.ts

@@ -1,5 +1,5 @@
 export declare const CACHE_FORMAT_VERSION = 2;
-export declare const GENERATOR_REVISION = 3;
+export declare const GENERATOR_REVISION = 4;
 export declare const CACHE_MANIFEST_FILE = "cache-manifest.json";
 export type CacheManifest = {
     cacheFormat: typeof CACHE_FORMAT_VERSION;

package/dist/src/cache.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlink
 import { join } from "node:path";
 import { isBuiltinOid } from "./pg/oids.js";
 export const CACHE_FORMAT_VERSION = 2;
-export const GENERATOR_REVISION = 3;
+export const GENERATOR_REVISION = 4;
 export const CACHE_MANIFEST_FILE = "cache-manifest.json";
 export function portableCacheOid(oid) {
     return isBuiltinOid(oid) ? oid : 0;

package/dist/src/codegen.js

@@ -23,7 +23,9 @@ export function emitDts(outPath, entries, functions = []) {
     lines.push("// AUTO-GENERATED by sqlx-js. Do not edit.");
     lines.push("// Run `sqlx-js prepare` to regenerate.");
     lines.push("");
-    emitModule(lines, "@onreza/sqlx-js", entries, functions);
+    emitRegistry(lines, entries, functions);
+    lines.push("");
+    emitModuleAugmentation(lines, "@onreza/sqlx-js");
     lines.push("");
     lines.push("export {};");
     const tmp = `${outPath}.tmp-${randomBytes(4).toString("hex")}`;
@@ -39,9 +41,8 @@ export function emitDts(outPath, entries, functions = []) {
         throw err;
     }
 }
-function emitModule(lines, moduleName, entries, functions) {
-    lines.push(`declare module ${JSON.stringify(moduleName)} {`);
-    lines.push("  interface KnownQueries {");
+function emitRegistry(lines, entries, functions) {
+    lines.push("export interface SqlxJsGeneratedQueries {");
     const inlineSeen = new Set();
     const inlinePairs = [];
     for (const e of entries) {
@@ -58,12 +59,12 @@ function emitModule(lines, moduleName, entries, functions) {
         inlineSeen.add(query);
         const { params, row } = entrySignature(entry);
         if (entry.degraded)
-            lines.push(`    /** Nullability inference degraded: ${entry.degraded.reason}. All result columns conservatively typed as nullable. */`);
-        lines.push(`    ${JSON.stringify(query)}: { params: ${params}; row: ${row} };`);
+            lines.push(`  /** Nullability inference degraded: ${entry.degraded.reason}. All result columns conservatively typed as nullable. */`);
+        lines.push(`  ${JSON.stringify(query)}: { params: ${params}; row: ${row} };`);
     }
-    lines.push("  }");
+    lines.push("}");
     lines.push("");
-    lines.push("  interface KnownFileQueries {");
+    lines.push("export interface SqlxJsGeneratedFileQueries {");
     const filePairs = [];
     for (const e of entries) {
         if (!e.filePaths || e.filePaths.length === 0)
@@ -78,21 +79,33 @@ function emitModule(lines, moduleName, entries, functions) {
         filePathsSeen.add(path);
         const { params, row } = entrySignature(entry);
         if (entry.degraded)
-            lines.push(`    /** Nullability inference degraded: ${entry.degraded.reason}. */`);
-        lines.push(`    ${JSON.stringify(path)}: { params: ${params}; row: ${row} };`);
+            lines.push(`  /** Nullability inference degraded: ${entry.degraded.reason}. */`);
+        lines.push(`  ${JSON.stringify(path)}: { params: ${params}; row: ${row} };`);
     }
-    lines.push("  }");
+    lines.push("}");
     lines.push("");
-    lines.push("  interface KnownFunctions {");
+    lines.push("export interface SqlxJsGeneratedFunctions {");
     const functionSeen = new Set();
     for (const fn of functions.slice().sort((a, b) => a.signature.localeCompare(b.signature))) {
         if (functionSeen.has(fn.signature))
             continue;
         functionSeen.add(fn.signature);
         const params = inputParams(fn);
-        lines.push(`    ${JSON.stringify(fn.signature)}: { kind: ${JSON.stringify(fn.kind)}; params: ${params}; returns: ${fn.returns}; returnsSet: ${fn.returnsSet} };`);
+        lines.push(`  ${JSON.stringify(fn.signature)}: { kind: ${JSON.stringify(fn.kind)}; params: ${params}; returns: ${fn.returns}; returnsSet: ${fn.returnsSet} };`);
     }
-    lines.push("  }");
+    lines.push("}");
+    lines.push("");
+    lines.push("export interface SqlxJsGeneratedRegistry {");
+    lines.push("  queries: SqlxJsGeneratedQueries;");
+    lines.push("  fileQueries: SqlxJsGeneratedFileQueries;");
+    lines.push("  functions: SqlxJsGeneratedFunctions;");
+    lines.push("}");
+}
+function emitModuleAugmentation(lines, moduleName) {
+    lines.push(`declare module ${JSON.stringify(moduleName)} {`);
+    lines.push("  interface KnownQueries extends SqlxJsGeneratedQueries {}");
+    lines.push("  interface KnownFileQueries extends SqlxJsGeneratedFileQueries {}");
+    lines.push("  interface KnownFunctions extends SqlxJsGeneratedFunctions {}");
     lines.push("}");
 }
 function inputParams(fn) {