@apso/cli 0.43.4 → 0.44.0

package/dist/commands/migrate.js

@@ -1,131 +1,206 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
 const core_1 = require("@oclif/core");
+const inquirer = tslib_1.__importStar(require("inquirer"));
 const base_command_1 = tslib_1.__importDefault(require("../lib/base-command"));
 const apsorc_parser_1 = require("../lib/apsorc-parser");
-const sandbox_1 = require("../lib/migrate/sandbox");
-const lib_1 = require("../lib");
-const file_system_1 = require("../lib/utils/file-system");
+const migration_file_1 = require("../lib/ddl/migration-file");
+const plan_1 = require("../lib/plan");
+const baseline_1 = require("../lib/plan/baseline");
+const prompts_1 = require("../lib/plan/prompts");
+const verify_1 = require("../lib/verify");
+const required = (v) => v.trim() !== "" || "Enter an expression";
 class Migrate extends base_command_1.default {
+    constructor() {
+        super(...arguments);
+        this.json = false;
+    }
+    /** Progress for people; agents get only the final JSON. */
+    say(s) {
+        if (!this.json)
+            this.log(s);
+    }
+    /** Print the outcome: one JSON object for agents, nothing extra for people. */
+    out(status, extra) {
+        if (this.json)
+            this.log(JSON.stringify({ status, ...extra }, null, 2));
+    }
+    fail(message, extra = {}) {
+        if (this.json) {
+            this.out("failed", { error: message, ...extra });
+            this.exit(1);
+        }
+        this.error(message, { exit: 1 });
+    }
     async run() {
+        var _a, _b, _c;
         const { flags } = await this.parse(Migrate);
-        // Handle reset
-        if (flags.reset) {
-            (0, sandbox_1.resetSandbox)();
-            this.log("Sandbox reset. Snapshot and PGlite data cleared.");
-            return;
+        const cwd = process.cwd();
+        this.json = flags.json || !process.stdout.isTTY;
+        const interactive = !this.json && Boolean(process.stdin.isTTY);
+        // Keep stdout pure JSON for agents: parser notices go to stderr.
+        if (this.json)
+            console.info = (...m) => process.stderr.write(m.join(" ") + "\n");
+        const { apsorc } = (0, apsorc_parser_1.readApsorcFile)();
+        const cliBin = (0, verify_1.cliBinPath)(this.config.root);
+        if (!flags["skip-generate"]) {
+            this.say("Generating code from .apsorc...");
+            // Agents run without a terminal, where generate needs the language spelled out.
+            const language = (_a = apsorc.language) !== null && _a !== void 0 ? _a : "typescript";
+            const gen = await (0, verify_1.run)(process.execPath, [cliBin, "generate", "--language", language], cwd);
+            if (!gen.ok)
+                this.fail(`apso generate failed:\n${gen.output.trim().split("\n").slice(-15).join("\n")}`);
         }
-        // Parse .apsorc
-        let parsed;
+        const planPath = path.resolve(".apso/migration-plan.json");
+        let baseline;
         try {
-            parsed = (0, apsorc_parser_1.parseApsorc)();
+            baseline = (0, baseline_1.resolveBaseline)(cwd, apsorc, flags.baseline, planPath);
         }
         catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            this.error(`Failed to parse .apsorc: ${msg}`);
-        }
-        if (!flags.sql) {
-            this.log("Schema changes detected. Running migration sandbox...");
+            this.fail(error.message);
         }
-        // Run the sandbox
-        const result = await (0, sandbox_1.runMigrationSandbox)({ entities: parsed.entities, relationshipMap: parsed.relationshipMap });
-        if (!result.needed) {
-            if (!flags.sql) {
-                this.log("No database-level changes detected.");
-            }
-            return;
+        this.say(`Comparing with ${baseline.source}.`);
+        const previous = fs.existsSync(planPath)
+            ? JSON.parse(fs.readFileSync(planPath).toString())
+            : undefined;
+        let plan;
+        try {
+            plan = (0, plan_1.planWithAnswers)(baseline.schema, apsorc, previous, flags.answer);
         }
-        // Output results
-        if (flags.sql) {
-            // Raw SQL output mode
-            for (const sql of result.upSql) {
-                this.log(sql + ";");
-            }
-            return;
+        catch (error) {
+            this.fail(error.message);
         }
-        if (result.success) {
-            this.log("");
-            this.log("Migration SQL (up):");
-            this.log("---");
-            for (const sql of result.upSql) {
-                this.log(`  ${sql};`);
-            }
-            this.log("---");
-            this.log("");
-            this.log(`${result.upSql.length} statement(s) generated and tested.`);
-            this.log("Migration validated against local PGlite.");
-            // Generate language-native migration files for Python and Go
-            const language = parsed.language || "typescript";
-            if (language !== "typescript") {
-                const generatorConfig = {
-                    language,
-                    rootFolder: parsed.rootFolder || "src",
-                    apiType: parsed.apiType || "rest",
-                    entities: parsed.entities,
-                    relationshipMap: parsed.relationshipMap,
-                };
-                const generator = (0, lib_1.createGenerator)(generatorConfig);
-                const migrationFiles = await generator.generateMigration({
-                    entities: parsed.entities,
-                    relationshipMap: parsed.relationshipMap,
-                    upSql: result.upSql,
-                    downSql: result.downSql,
-                });
-                for (const file of migrationFiles) {
-                    const fullPath = path.join(process.cwd(), file.path);
-                    // eslint-disable-next-line no-await-in-loop
-                    await (0, file_system_1.createFile)(fullPath, file.content);
-                    this.log(`Generated migration file: ${file.path}`);
+        const save = () => {
+            fs.mkdirSync(path.dirname(planPath), { recursive: true });
+            fs.writeFileSync(planPath, JSON.stringify({ ...plan, before: baseline.schema }, null, 2) + "\n");
+        };
+        // Ask until nothing is open. Answers can raise new questions (dropping a
+        // field leaves a required one to backfill), so re-plan after each round.
+        for (let open = (0, plan_1.openQuestions)(plan); open.length > 0; open = (0, plan_1.openQuestions)(plan)) {
+            save();
+            if (!interactive) {
+                const next = 'Rerun apso migrate --answer <id>=<option> for each. For "sql" and "split:" answers, also set the question\'s "sql" in the plan file: a string, or one expression per split field.';
+                if (this.json) {
+                    this.out("questions", { plan: path.relative(cwd, planPath), baseline: baseline.source, open: open.map((q) => (0, prompts_1.describeQuestion)(q)), next });
                 }
+                else {
+                    for (const q of open)
+                        this.log(`\n${q.id}\n  ${q.subject}\n  options: ${q.options.join(" | ")}`);
+                    this.log(`\n${next}`);
+                }
+                this.exit(2);
             }
-            if (flags.apply) {
-                (0, sandbox_1.applyMigration)({
-                    entities: parsed.entities,
-                    relationshipMap: parsed.relationshipMap,
-                });
-                this.log("Snapshot updated.");
-            }
-            else {
-                this.log("Run with --apply to update the snapshot.");
+            for (const q of open) {
+                // eslint-disable-next-line no-await-in-loop
+                await this.ask(q);
             }
+            plan = (0, plan_1.planWithAnswers)(baseline.schema, apsorc, plan, []);
         }
-        else {
-            this.log("");
-            this.log("Migration FAILED.");
-            if (result.error) {
-                this.log(`Error: ${result.error}`);
-            }
-            if (result.upSql.length > 0) {
-                this.log("");
-                this.log("Attempted SQL:");
-                for (const sql of result.upSql) {
-                    this.log(`  ${sql};`);
-                }
+        save();
+        const written = (0, migration_file_1.writePlannedMigration)(cwd, baseline.schema, flags.name, planPath);
+        if (!written.ok)
+            this.fail(written.steps.map((s) => s.output).filter(Boolean).join("\n"));
+        if (!written.needed) {
+            this.say("The database already matches .apsorc. Nothing to migrate.");
+            this.out("up-to-date", {});
+            return;
+        }
+        this.say(`Wrote ${written.file}`);
+        for (const f of (_b = written.findings) !== null && _b !== void 0 ? _b : [])
+            this.say(`  warning ${f.code}: ${f.message}`);
+        let verified = "skipped";
+        // Python and Go verify without the project's own database driver.
+        const canVerify = ((_c = apsorc.language) !== null && _c !== void 0 ? _c : "typescript") !== "typescript" || (0, verify_1.supportsPglite)(cwd);
+        if (!flags["skip-verify"] && canVerify) {
+            this.say("Testing the migration on a local copy of the deployed schema...");
+            const result = await (0, verify_1.verifyMigration)(cwd, (0, baseline_1.baselineFile)(baseline), written.file, cliBin, {
+                seedFile: flags.seed,
+                checkFile: flags.check,
+                acceptLoss: flags["accept-loss"],
+            });
+            verified = result.ok;
+            if (!this.json)
+                (0, verify_1.report)((s) => this.log(s), { ...result, findings: [] }, false);
+            if (!result.ok)
+                this.fail(`The migration in ${written.file} failed its test. Fix the answers in ${written.planFile} or the .apsorc, then run apso migrate again.`, { file: written.file, planFile: written.planFile, steps: result.steps });
+        }
+        this.say(`\nReview and commit ${written.file} and ${written.planFile}, then deploy.`);
+        if (verified === true && !flags.seed)
+            this.say("Tip: --seed <rows.sql> also checks that existing rows survive the migration.");
+        this.out("written", { file: written.file, planFile: written.planFile, verified });
+    }
+    async ask(q) {
+        const { choice } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "choice",
+                message: q.subject,
+                choices: q.options.map((o) => ({ name: (0, prompts_1.optionLabel)(q, o), value: o })),
+                default: q.suggested,
+            },
+        ]);
+        q.answer = choice;
+        if (choice === "sql") {
+            const { sql } = await inquirer.prompt([
+                { type: "input", name: "sql", message: (0, prompts_1.sqlHint)(q), validate: required },
+            ]);
+            q.sql = sql;
+        }
+        if (choice.startsWith("split:")) {
+            const targets = choice.slice("split:".length).split(",");
+            const defaults = (0, prompts_1.splitDefaults)(q, targets);
+            const sql = {};
+            for (const t of targets) {
+                // eslint-disable-next-line no-await-in-loop
+                const { expr } = await inquirer.prompt([
+                    { type: "input", name: "expr", message: `SQL for ${t}`, default: defaults[t], validate: required },
+                ]);
+                sql[t] = expr;
             }
-            this.exit(1);
+            q.sql = sql;
         }
     }
 }
-Migrate.description = "Detect schema changes, generate migration SQL, and test against a local PGlite sandbox";
+Migrate.description = "Migrate the database to this .apsorc in one step: regenerate the code, compare with the deployed schema, ask about anything ambiguous (a rename or a drop, how a field splits, what replaces a removed value), write the migration, and test it on a local copy. In a terminal it asks; for an agent it prints the open questions as JSON and exits 2, and the agent reruns it with --answer. The steps are also separate commands: apso migrate plan, generate and verify.";
 Migrate.examples = [
-    `$ apso migrate`,
-    `$ apso migrate --apply`,
-    `$ apso migrate --reset`,
-    `$ apso migrate --sql`,
+    "$ apso migrate",
+    "$ apso migrate --answer field:Contact.phone=rename:mobilePhone",
+    "$ apso migrate --seed seed.sql --check checks.sql",
 ];
 Migrate.flags = {
-    apply: core_1.Flags.boolean({
-        description: "Apply the migration: update the local snapshot after a successful test",
+    baseline: core_1.Flags.string({
+        description: "The deployed .apsorc, the first time only. Later runs find it from the last migration",
+    }),
+    answer: core_1.Flags.string({
+        description: "Answer a question: <question id>=<option>. Repeatable.",
+        multiple: true,
+        default: [],
+    }),
+    seed: core_1.Flags.string({
+        description: "SQL file of rows to load first; the test then fails if the migration loses any",
+    }),
+    check: core_1.Flags.string({
+        description: "SQL file of SELECTs with a boolean ok column, run after the migration",
+    }),
+    "accept-loss": core_1.Flags.string({
+        description: "A table or table.column whose seeded data may be dropped on purpose (repeatable)",
+        multiple: true,
+        default: [],
+    }),
+    name: core_1.Flags.string({ description: "Migration name", default: "SchemaUpdate" }),
+    "skip-generate": core_1.Flags.boolean({
+        description: "Don't regenerate code from .apsorc first",
         default: false,
     }),
-    reset: core_1.Flags.boolean({
-        description: "Reset the sandbox (clear snapshot and PGlite data)",
+    "skip-verify": core_1.Flags.boolean({
+        description: "Write the migration without testing it",
         default: false,
     }),
-    sql: core_1.Flags.boolean({
-        description: "Output raw SQL only (for piping to files)",
+    json: core_1.Flags.boolean({
+        description: "Print the result as JSON (the default when output is not a terminal)",
         default: false,
     }),
 };

package/dist/lib/ddl/catalog.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Read a database's schema back out of Postgres's own catalog, in a form two
+ * databases can be compared by. Postgres normalizes what it stores (types,
+ * defaults, constraint definitions), so two databases built by different SQL
+ * compare equal when they ended up the same.
+ */
+export interface Catalog {
+    columns: string[];
+    constraints: string[];
+    indexes: string[];
+    enums: string[];
+}
+interface Queryable {
+    query<T>(sql: string): Promise<{
+        rows: T[];
+    }>;
+}
+export declare function readCatalog(db: Queryable): Promise<Catalog>;
+/** Lines present in one catalog and not the other, prefixed - or +. */
+export declare function catalogDiff(a: Catalog, b: Catalog): string[];
+export {};

package/dist/lib/ddl/catalog.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Read a database's schema back out of Postgres's own catalog, in a form two
+ * databases can be compared by. Postgres normalizes what it stores (types,
+ * defaults, constraint definitions), so two databases built by different SQL
+ * compare equal when they ended up the same.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.catalogDiff = exports.readCatalog = void 0;
+const COLUMNS = `
+SELECT table_name || '.' || column_name || ' ' || format_type(a.atttypid, a.atttypmod)
+       || CASE WHEN c.is_nullable = 'NO' THEN ' NOT NULL' ELSE '' END
+       || COALESCE(' DEFAULT ' || c.column_default, '') AS line
+FROM information_schema.columns c
+JOIN pg_attribute a ON a.attrelid = ('"' || c.table_name || '"')::regclass AND a.attname = c.column_name
+WHERE c.table_schema = 'public'`;
+const CONSTRAINTS = `
+SELECT conrelid::regclass::text || ' ' || conname || ' ' || pg_get_constraintdef(oid) AS line
+FROM pg_constraint
+WHERE connamespace = 'public'::regnamespace AND contype IN ('p', 'u', 'f', 'c')`;
+const INDEXES = `
+SELECT indexdef AS line FROM pg_indexes
+WHERE schemaname = 'public'
+  AND indexname NOT IN (SELECT conname FROM pg_constraint WHERE connamespace = 'public'::regnamespace)`;
+const ENUMS = `
+SELECT t.typname || ' ' || string_agg(e.enumlabel, ',' ORDER BY e.enumsortorder) AS line
+FROM pg_type t JOIN pg_enum e ON e.enumtypid = t.oid
+WHERE t.typnamespace = 'public'::regnamespace
+GROUP BY t.typname`;
+const lines = async (db, sql) => {
+    const result = await db.query(sql);
+    return result.rows.map((r) => r.line).sort();
+};
+async function readCatalog(db) {
+    return {
+        columns: await lines(db, COLUMNS),
+        constraints: await lines(db, CONSTRAINTS),
+        indexes: await lines(db, INDEXES),
+        enums: await lines(db, ENUMS),
+    };
+}
+exports.readCatalog = readCatalog;
+/** Lines present in one catalog and not the other, prefixed - or +. */
+function catalogDiff(a, b) {
+    const out = [];
+    for (const key of Object.keys(a)) {
+        const left = new Set(a[key]);
+        const right = new Set(b[key]);
+        for (const l of a[key])
+            if (!right.has(l))
+                out.push(`- ${key}: ${l}`);
+        for (const l of b[key])
+            if (!left.has(l))
+                out.push(`+ ${key}: ${l}`);
+    }
+    return out;
+}
+exports.catalogDiff = catalogDiff;

package/dist/lib/ddl/change.d.ts

@@ -0,0 +1,19 @@
+import { ApsorcType } from "../apsorc-parser";
+import { Plan } from "../plan";
+export interface ChangeDdl {
+    up: string[];
+}
+export declare function changeDdl(before: ApsorcType, after: ApsorcType, plan: Plan): ChangeDdl;
+export type DownDdl = {
+    down: string[];
+} | {
+    irreversible: string[];
+};
+/**
+ * The reverse migration: the plan from the new schema back to the deployed
+ * one, answered from the forward answers. Renames invert, added fields drop,
+ * removed enum values map back, a split rejoins, and data that moved (to a
+ * new table, or into many-to-many links) is copied back. Anything left
+ * unanswered is reported instead of guessed.
+ */
+export declare function downDdl(before: ApsorcType, after: ApsorcType, plan: Plan): DownDdl;