@onreza/sqlx-js 0.3.0 → 0.5.0

package/dist/bin/sqlx-js.js

@@ -2,11 +2,14 @@
 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 { 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 { 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")]) {
@@ -23,8 +26,10 @@ function help() {
     console.error(`sqlx-js — compile-time-checked SQL for TypeScript + Postgres (v${VERSION})
 
 usage:
-  sqlx-js init [--root <dir>]
-  sqlx-js prepare [--check | --watch] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
+  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 --version
@@ -38,11 +43,12 @@ 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
   --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
@@ -52,23 +58,26 @@ flags:
   --schema <path>          schema snapshot path (default: <root>/.sqlx-js/schema/schema.json)
   --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);
 }
+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 argv = process.argv;
     const eq = `${name}=`;
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
+    for (let i = 0; i < cliArgv.length; i++) {
+        const a = cliArgv[i];
         if (a === name)
-            return argv[i + 1] ?? def;
+            return cliArgv[i + 1] ?? def;
         if (a.startsWith(eq))
             return a.slice(eq.length);
     }
     return def;
 }
 function flag(name) {
-    for (const a of process.argv) {
+    for (const a of cliArgv) {
         if (a === name)
             return true;
     }
@@ -83,6 +92,26 @@ if (cmd === "--help" || cmd === "-h" || !cmd) {
     help();
 }
 const root = resolve(arg("--root", process.cwd()));
+if (cmd !== "doctor") {
+    try {
+        assertSupportedRuntime();
+    }
+    catch (e) {
+        console.error(e.message);
+        process.exit(2);
+    }
+}
+let envError;
+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;
@@ -96,32 +125,95 @@ const schemaPath = schemaArg ? resolve(schemaArg) : join(root, ".sqlx-js/schema/
 const manifestArg = arg("--manifest");
 const manifestPath = manifestArg ? resolve(manifestArg) : join(root, ".sqlx-js/schema/schema.md");
 if (cmd === "init") {
-    runInit({ root });
+    const provider = arg("--schema-provider", "builtin");
+    if (provider !== "builtin" && provider !== "pgschema") {
+        console.error("--schema-provider must be builtin or pgschema");
+        process.exit(2);
+    }
+    runInit({ root, schemaProvider: provider });
+}
+else if (cmd === "doctor") {
+    await runDoctor({ root, databaseUrl, cacheDir, dtsPath, json: flag("--json"), envError });
+}
+else if (cmd === "db") {
+    const sub = process.argv[3];
+    if (sub === "install") {
+        try {
+            await runPgschemaInstall({ root });
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(2);
+        }
+    }
+    else {
+        if (sub !== "check" && sub !== "plan" && sub !== "apply")
+            help();
+        try {
+            runPgschemaCommand({
+                root,
+                databaseUrl,
+                config: await loadConfig(root),
+                subcommand: sub,
+                passthrough: passthroughArgs,
+            });
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(2);
+        }
+    }
 }
 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 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");
     }
-    const prepareShadowUrl = flag("--check") ? undefined : shadowUrl;
+    if (prepareWatch && prepareJson) {
+        failPrepare("--watch and --json are mutually exclusive", "config");
+    }
+    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"),
     };
-    if (flag("--watch")) {
-        if (flag("--check")) {
-            console.error("--watch and --check are mutually exclusive");
-            process.exit(2);
-        }
+    if (prepareWatch) {
         await runWatch({
             ...opts,
             ...(prepareShadowUrl
@@ -135,9 +227,28 @@ 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") {

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;

package/dist/src/cache.js

@@ -1,6 +1,13 @@
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, renameSync } from "node:fs";
 import { join } from "node:path";
+import { isBuiltinOid } from "./pg/oids.js";
+export const CACHE_FORMAT_VERSION = 2;
+export const GENERATOR_REVISION = 3;
+export const CACHE_MANIFEST_FILE = "cache-manifest.json";
+export function portableCacheOid(oid) {
+    return isBuiltinOid(oid) ? oid : 0;
+}
 export function fingerprint(query) {
     const norm = normalizeForFingerprint(query);
     return createHash("sha256").update(norm).digest("hex").slice(0, 16);
@@ -202,11 +209,35 @@ export class Cache {
             throw err;
         }
     }
+    replaceAll(entries, prune = true) {
+        this.ensure();
+        const staged = [];
+        try {
+            for (const { fp, entry } of entries) {
+                const final = join(this.dir, `${fp}.json`);
+                const tmp = `${final}.tmp-${randomBytes(4).toString("hex")}`;
+                writeFileSync(tmp, JSON.stringify(entry, null, 2));
+                staged.push({ fp, tmp, final });
+            }
+            for (const item of staged)
+                renameSync(item.tmp, item.final);
+        }
+        catch (err) {
+            for (const item of staged) {
+                try {
+                    unlinkSync(item.tmp);
+                }
+                catch { }
+            }
+            throw err;
+        }
+        return prune ? this.prune(staged.map((item) => item.fp)) : [];
+    }
     list() {
         if (!existsSync(this.dir))
             return [];
         return readdirSync(this.dir)
-            .filter((f) => f.endsWith(".json") && !f.includes(".tmp-"))
+            .filter((f) => f !== CACHE_MANIFEST_FILE && f.endsWith(".json") && !f.includes(".tmp-"))
             .map((f) => {
             const fp = f.replace(/\.json$/, "");
             return { fp, entry: assertEntryShape(fp, parseEntryJson(join(this.dir, f))) };
@@ -229,3 +260,54 @@ export class Cache {
         return removed;
     }
 }
+export function cacheManifestPath(cacheDir) {
+    return join(cacheDir, CACHE_MANIFEST_FILE);
+}
+export function writeCacheManifest(cacheDir, configHash) {
+    if (!existsSync(cacheDir))
+        mkdirSync(cacheDir, { recursive: true });
+    const path = cacheManifestPath(cacheDir);
+    const tmp = `${path}.tmp-${randomBytes(4).toString("hex")}`;
+    const manifest = {
+        cacheFormat: CACHE_FORMAT_VERSION,
+        generatorRevision: GENERATOR_REVISION,
+        configHash,
+    };
+    writeFileSync(tmp, JSON.stringify(manifest, null, 2) + "\n");
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
+}
+export function readCacheManifest(cacheDir) {
+    const path = cacheManifestPath(cacheDir);
+    if (!existsSync(path))
+        return null;
+    const raw = parseEntryJson(path);
+    if (!raw || typeof raw !== "object") {
+        throw new Error(`sqlx-js: cache manifest is malformed: ${path}`);
+    }
+    const value = raw;
+    if (value.cacheFormat !== CACHE_FORMAT_VERSION ||
+        value.generatorRevision !== GENERATOR_REVISION ||
+        typeof value.configHash !== "string") {
+        throw new Error(`sqlx-js: cache manifest is stale: ${path}. Run \`sqlx-js prepare\`.`);
+    }
+    return value;
+}
+export function assertCacheManifest(cacheDir, configHash) {
+    const manifest = readCacheManifest(cacheDir);
+    if (!manifest) {
+        throw new Error(`sqlx-js: cache manifest is missing. Run \`sqlx-js prepare\` to regenerate the cache.`);
+    }
+    if (manifest.configHash !== configHash) {
+        throw new Error("sqlx-js: cache was generated with a different jsonbTypes/customTypes config. Run `sqlx-js prepare`.");
+    }
+    return manifest;
+}

package/dist/src/codegen.d.ts

@@ -1,2 +1,3 @@
 import { type CacheEntry } from "./cache.js";
-export declare function emitDts(outPath: string, entries: CacheEntry[]): void;
+import type { FunctionEntry } from "./function-cache.js";
+export declare function emitDts(outPath: string, entries: CacheEntry[], functions?: FunctionEntry[]): void;

package/dist/src/codegen.js

@@ -1,4 +1,5 @@
-import { writeFileSync, mkdirSync } from "node:fs";
+import { writeFileSync, mkdirSync, renameSync, unlinkSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { dirname } from "node:path";
 import { effectiveNullable } from "./cache.js";
 function entrySignature(e) {
@@ -16,18 +17,29 @@ function entrySignature(e) {
     });
     return { params, row: `{ ${cols.join("; ")} }` };
 }
-export function emitDts(outPath, entries) {
+export function emitDts(outPath, entries, functions = []) {
     mkdirSync(dirname(outPath), { recursive: true });
     const lines = [];
     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);
+    emitModule(lines, "@onreza/sqlx-js", entries, functions);
     lines.push("");
     lines.push("export {};");
-    writeFileSync(outPath, lines.join("\n") + "\n");
+    const tmp = `${outPath}.tmp-${randomBytes(4).toString("hex")}`;
+    writeFileSync(tmp, lines.join("\n") + "\n");
+    try {
+        renameSync(tmp, outPath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
 }
-function emitModule(lines, moduleName, entries) {
+function emitModule(lines, moduleName, entries, functions) {
     lines.push(`declare module ${JSON.stringify(moduleName)} {`);
     lines.push("  interface KnownQueries {");
     const inlineSeen = new Set();
@@ -70,5 +82,22 @@ function emitModule(lines, moduleName, entries) {
         lines.push(`    ${JSON.stringify(path)}: { params: ${params}; row: ${row} };`);
     }
     lines.push("  }");
+    lines.push("");
+    lines.push("  interface KnownFunctions {");
+    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("  }");
     lines.push("}");
 }
+function inputParams(fn) {
+    const params = fn.params
+        .filter((p) => p.mode === "in" || p.mode === "inout" || p.mode === "variadic")
+        .map((p) => p.tsType);
+    return params.length === 0 ? "[]" : `[${params.join(", ")}]`;
+}

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

@@ -0,0 +1,16 @@
+export type DoctorCheck = {
+    name: string;
+    status: "ok" | "warning" | "error";
+    message: string;
+    details?: Record<string, unknown>;
+};
+export type DoctorOptions = {
+    root: string;
+    databaseUrl: string;
+    cacheDir: string;
+    dtsPath: string;
+    json?: boolean;
+    envError?: string;
+};
+export declare function inspectDoctor(opts: DoctorOptions): Promise<DoctorCheck[]>;
+export declare function runDoctor(opts: DoctorOptions): Promise<void>;