@onreza/sqlx-js 0.5.0 → 0.6.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,17 +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 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 | --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)
@@ -49,6 +46,7 @@ flags:
   --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
+  --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 +57,208 @@ 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 {
@@ -102,14 +270,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")) ||
+    (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 +293,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 +309,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 +325,6 @@ else if (cmd === "db") {
         }
     }
     else {
-        if (sub !== "check" && sub !== "plan" && sub !== "apply")
-            help();
         try {
             runPgschemaCommand({
                 root,
@@ -165,6 +341,7 @@ else if (cmd === "db") {
     }
 }
 else if (cmd === "prepare") {
+    const { PrepareFatalError, runPrepare } = await import("../src/commands/prepare.js");
     const prepareCheck = flag("--check");
     const prepareVerify = flag("--verify");
     const prepareWatch = flag("--watch");
@@ -198,6 +375,9 @@ else if (cmd === "prepare") {
     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 = prepareCheck ? undefined : shadowUrl;
     const prepareDatabaseUrl = prepareShadowUrl ?? databaseUrl;
     if (!prepareCheck && !prepareDatabaseUrl) {
@@ -212,8 +392,13 @@ else if (cmd === "prepare") {
         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,
             ...(prepareShadowUrl
@@ -252,7 +437,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 +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,
@@ -294,6 +482,7 @@ else if (cmd === "migrate") {
             shadowUrl,
             shadowAdminUrl,
             lockTimeoutMs,
+            strictInference: flag("--strict-inference"),
         });
     }
     else if (sub === "verify") {
@@ -306,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,
@@ -327,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,
@@ -352,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/commands/init.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 const CONFIG_TEMPLATE = `import { defineConfig } from "@onreza/sqlx-js";
 
@@ -33,10 +33,23 @@ const PGSCHEMA_TEMPLATE = `-- Desired PostgreSQL schema managed by pgschema.
 --   sqlx-js db plan -- --output-json plan.json
 --   sqlx-js db apply -- --auto-approve
 `;
+const DTS_TEMPLATE = `// AUTO-GENERATED by sqlx-js. Do not edit.
+// Run \`sqlx-js prepare\` to regenerate.
+
+declare module "@onreza/sqlx-js" {
+  interface KnownQueries {}
+  interface KnownFileQueries {}
+  interface KnownFunctions {}
+}
+
+export {};
+`;
 export function runInit(opts) {
     const log = opts.log ?? console.log;
     const created = [];
+    const updated = [];
     const skipped = [];
+    const notes = [];
     const ensureFile = (rel, content) => {
         const full = join(opts.root, rel);
         if (existsSync(full)) {
@@ -63,10 +76,81 @@ export function runInit(opts) {
     else
         ensureDir("migrations");
     ensureFile(".env.example", ENV_TEMPLATE);
+    ensureFile("sqlx-js-env.d.ts", DTS_TEMPLATE);
+    const updateJson = (rel, mutate) => {
+        const full = join(opts.root, rel);
+        if (!existsSync(full))
+            return;
+        const source = readFileSync(full, "utf8");
+        let value;
+        try {
+            value = JSON.parse(source);
+        }
+        catch {
+            notes.push(`${rel}: manual update required because the file is not strict JSON`);
+            return;
+        }
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return;
+        if (!mutate(value))
+            return;
+        const indent = source.match(/\n([ \t]+)"/)?.[1] ?? "  ";
+        writeFileSync(full, JSON.stringify(value, null, indent) + "\n");
+        updated.push(rel);
+    };
+    updateJson("tsconfig.json", (value) => {
+        const files = value.files;
+        if (files !== undefined && (!Array.isArray(files) || !files.every((item) => typeof item === "string"))) {
+            notes.push("tsconfig.json: manual update required because files is not an array of strings");
+            return false;
+        }
+        if (Array.isArray(files)) {
+            if (files.includes("sqlx-js-env.d.ts"))
+                return false;
+            files.push("sqlx-js-env.d.ts");
+            return true;
+        }
+        const include = value.include;
+        if (include !== undefined && (!Array.isArray(include) || !include.every((item) => typeof item === "string"))) {
+            notes.push("tsconfig.json: manual update required because include is not an array of strings");
+            return false;
+        }
+        if (Array.isArray(include)) {
+            if (include.includes("sqlx-js-env.d.ts"))
+                return false;
+            include.push("sqlx-js-env.d.ts");
+            return true;
+        }
+        return false;
+    });
+    updateJson("package.json", (value) => {
+        if (value.scripts !== undefined && (!value.scripts || typeof value.scripts !== "object" || Array.isArray(value.scripts))) {
+            notes.push("package.json: manual script update required because scripts is not an object");
+            return false;
+        }
+        const scripts = (value.scripts ??= {});
+        const defaults = {
+            "sqlx:prepare": "sqlx-js prepare",
+            "sqlx:check": "sqlx-js prepare --check",
+            "sqlx:verify": "sqlx-js prepare --verify --strict-inference",
+        };
+        let changed = false;
+        for (const [name, command] of Object.entries(defaults)) {
+            if (scripts[name] !== undefined)
+                continue;
+            scripts[name] = command;
+            changed = true;
+        }
+        return changed;
+    });
     for (const f of created)
         log(`created ${f}`);
+    for (const f of updated)
+        log(`updated ${f}`);
     for (const f of skipped)
         log(`exists  ${f} (left unchanged)`);
+    for (const note of notes)
+        log(`manual  ${note}`);
     log("");
     log("Next steps:");
     log("  1. Set DATABASE_URL (see .env.example).");
@@ -78,7 +162,7 @@ export function runInit(opts) {
     }
     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");
+        log("  3. Check the project setup:  sqlx-js doctor");
+        log("  4. Develop locally:  sqlx-js migrate dev --strict-inference");
     }
 }