@apso/cli 0.43.4 → 0.45.0

package/README.md

@@ -185,22 +185,18 @@ Requires Docker and Docker Compose. Looks for `docker-compose.yml` in the curren
 
 ### `apso migrate`
 
-Detect schema changes, generate migration SQL, and test against a local PGlite sandbox. No Docker or external database required.
+Write the migration for a schema change without losing data. `apso migrate` regenerates the code, compares `.apsorc` with the deployed schema, and asks about every change whose intent the schema can't show: was a missing field renamed or dropped, how does a field split, what replaces a removed enum value, what do existing rows get for a new required field. It then writes the migration from your answers (a TypeORM migration for TypeScript, an Alembic revision for Python, a goose file for Go), saves the answered plan beside it, and tests it on a local PGlite copy of the deployed schema.
 
 ```bash
-apso migrate              # Detect changes, generate and test SQL
-apso migrate --apply      # Update snapshot after successful test
-apso migrate --reset      # Clear sandbox and start fresh
-apso migrate --sql        # Output raw SQL only (for piping)
+apso migrate --baseline deployed.apsorc     # first time: the .apsorc that is deployed
+apso migrate                                # later runs find the baseline from the last migration
+apso migrate --answer field:Contact.phone=rename:mobilePhone
+apso migrate --seed seed.sql --check checks.sql
 ```
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--apply` | Update local schema snapshot after verified migration | `false` |
-| `--reset` | Reset the sandbox (clear snapshot and PGlite data) | `false` |
-| `--sql` | Output raw SQL statements only | `false` |
+In a terminal it asks each question. Without one (or with `--json`) it prints the open questions as JSON and exits 2, so a coding agent can answer them with `--answer` or in `.apso/migration-plan.json` and run it again. The same answers always produce the same SQL.
 
-The sandbox works by comparing your current `.apsorc` against the last-known snapshot, generating the migration SQL, and executing it against an in-process Postgres instance (PGlite). If the migration fails locally, you know before it reaches any real database.
+The steps are also separate commands: `apso migrate plan`, `apso migrate generate` and `apso migrate verify`. `apso migrate sandbox` is the older snapshot preview on an empty database (`--apply`, `--reset`, `--sql`).
 
 ### `apso deploy`
 

package/dist/commands/deploy.js

@@ -50,7 +50,7 @@ class Deploy extends base_command_1.default {
                         this.log(`Error: ${result.error}`);
                     }
                     this.log("Fix the schema issue before deploying.");
-                    this.log("Run 'apso migrate' for details.");
+                    this.log("Run 'apso migrate sandbox' for details.");
                     this.exit(1);
                 }
                 migrationCount = result.upSql.length;

package/dist/commands/generate.js

@@ -2,9 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const core_1 = require("@oclif/core");
+const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
 const inquirer_1 = tslib_1.__importDefault(require("inquirer"));
 const lib_1 = require("../lib");
+const types_1 = require("../lib/types");
 const base_command_1 = tslib_1.__importDefault(require("../lib/base-command"));
 const interactive_1 = require("../lib/utils/interactive");
 const perf_hooks_1 = require("perf_hooks");
@@ -173,6 +175,7 @@ class Generate extends base_command_1.default {
                     allEntities: entities,
                     apiType: lowerCaseApiType,
                     relationshipMap,
+                    auth,
                 }));
             }
             // eslint-disable-next-line no-await-in-loop
@@ -202,7 +205,7 @@ class Generate extends base_command_1.default {
             await writeGenerated(file.path, file.content);
         }
         // Generate index module
-        const indexFiles = await generator.generateIndexModule(entities, lowerCaseApiType, { emitEvents, http });
+        const indexFiles = await generator.generateIndexModule(entities, lowerCaseApiType, { emitEvents, http, auth });
         for (const file of indexFiles) {
             // eslint-disable-next-line no-await-in-loop
             await writeGenerated(file.path, file.content);
@@ -265,6 +268,23 @@ class Generate extends base_command_1.default {
                 console.log("[apso] Updated src/orm.config.ts so `apso migrate verify` and `apso test smoke` can run on a local PGlite database. Run npm install before building.");
             }
         }
+        // The generated auth code imports a JWT library; declare it.
+        if (auth && (0, types_1.isJwtAuth)(auth)) {
+            if (language === "typescript" &&
+                (0, crud_deps_1.addMissingDeps)(process.cwd(), crud_deps_1.JOSE_DEP).length > 0)
+                console.log("[apso] Added jose to package.json (the generated auth guard imports it). Run npm install before building.");
+            if (language === "python" &&
+                (0, crud_deps_1.addMissingPythonDep)(process.cwd(), crud_deps_1.PYJWT_DEP))
+                console.log(`[apso] Added ${crud_deps_1.PYJWT_DEP} to pyproject.toml (the generated auth module imports it). Reinstall the project's dependencies.`);
+            if (language === "go")
+                console.log("[apso] The generated auth middleware imports github.com/golang-jwt/jwt/v5 and github.com/MicahParks/keyfunc/v3. Run go mod tidy before building.");
+        }
+        if (language === "python") {
+            const main = path.join(process.cwd(), "app", "main.py");
+            if (fs.existsSync(main) &&
+                !fs.readFileSync(main, "utf8").includes("autogen_router"))
+                console.warn("[apso] app/main.py does not include autogen_router, so the generated routes are not served. Add: from app.autogen import autogen_router; app.include_router(autogen_router)");
+        }
         const totalBuildTime = perf_hooks_1.performance.now() - totalBuildStart;
         console.log(`[apso] Finished building all entities in ${totalBuildTime.toFixed(2)} ms`);
         // Best-effort: install the commit co-author hook so commits that include

package/dist/commands/mcp/serve.js

@@ -382,6 +382,7 @@ class McpServe extends base_command_1.default {
                             allEntities: entities,
                             apiType: lowerCaseApiType,
                             relationshipMap,
+                            auth,
                         }),
                         generator.generateModule({
                             entity,
@@ -408,7 +409,7 @@ class McpServe extends base_command_1.default {
                     filesGenerated.push(file.path);
                 }
                 // Generate index module
-                const indexFiles = await generator.generateIndexModule(entities, lowerCaseApiType);
+                const indexFiles = await generator.generateIndexModule(entities, lowerCaseApiType, { auth });
                 for (const file of indexFiles) {
                     const fullPath = path.join(autogenPath, file.path);
                     // eslint-disable-next-line no-await-in-loop
@@ -450,6 +451,7 @@ class McpServe extends base_command_1.default {
                 "auth0",
                 "clerk",
                 "cognito",
+                "jwt",
                 "api-key",
                 "custom-db-session",
             ])
@@ -518,11 +520,12 @@ class McpServe extends base_command_1.default {
                             issuer: "https://YOUR_TENANT.auth0.com/",
                             audience: "https://api.yourapp.com",
                         },
+                        // Auth0 custom claims must be namespaced URLs, added by a post-login Action.
                         claims: {
                             userId: "sub",
                             email: "email",
-                            roles: "roles",
-                            organizationId: "org_id",
+                            roles: "https://yourapp.com/roles",
+                            workspaceId: "https://yourapp.com/org_id",
                         },
                     },
                     entities: [],
@@ -531,15 +534,14 @@ class McpServe extends base_command_1.default {
                 clerk: {
                     auth: {
                         provider: "clerk",
+                        // Clerk session tokens carry no aud; the active organization is o.id / o.rol.
                         jwt: {
                             issuer: "https://YOUR_CLERK_FRONTEND_API",
-                            audience: "",
                         },
                         claims: {
                             userId: "sub",
-                            email: "email",
-                            roles: "roles",
-                            organizationId: "org_id",
+                            workspaceId: "o.id",
+                            roles: "o.rol",
                         },
                     },
                     entities: [],
@@ -556,7 +558,26 @@ class McpServe extends base_command_1.default {
                             userId: "sub",
                             email: "email",
                             roles: "cognito:groups",
-                            organizationId: "custom:org_id",
+                            workspaceId: "custom:org_id",
+                        },
+                    },
+                    entities: [],
+                    relationships: [],
+                },
+                jwt: {
+                    // Any issuer that publishes a JWKS (Supabase Auth, Firebase, WorkOS, Okta, Better Auth's JWT plugin).
+                    auth: {
+                        provider: "jwt",
+                        jwt: {
+                            issuer: "https://YOUR_ISSUER",
+                            audience: "YOUR_AUDIENCE",
+                            jwksUri: "https://YOUR_ISSUER/.well-known/jwks.json",
+                        },
+                        claims: {
+                            userId: "sub",
+                            email: "email",
+                            workspaceId: "org_id",
+                            roles: "roles",
                         },
                     },
                     entities: [],
@@ -601,7 +622,7 @@ class McpServe extends base_command_1.default {
                 content: [
                     {
                         type: "text",
-                        text: `# Auth Setup: ${authProvider}\n\nMerge the following into your .apsorc file:\n\n\`\`\`json\n${JSON.stringify(config, null, 2)}\n\`\`\`\n\nAfter updating .apsorc:\n1. Run \`apso generate\` (or use the scaffold_api tool) to regenerate code\n2. Run \`npm install\` if new dependencies are needed\n3. Run \`apso dev\` to start the server and create auth tables\n\n${authProvider === "better-auth" ? "**Important:** BetterAuth stores passwords in the `account` table (not User). The `providerId` field must be set to \"credential\" for email/password login to work. Use `@apso/better-auth-adapter@latest` in your frontend." : "Configure the JWT issuer and audience values for your " + authProvider + " tenant."}`,
+                        text: `# Auth Setup: ${authProvider}\n\nMerge the following into your .apsorc file:\n\n\`\`\`json\n${JSON.stringify(config, null, 2)}\n\`\`\`\n\nAfter updating .apsorc:\n1. Run \`apso generate\` (or use the scaffold_api tool) to regenerate code\n2. Run \`npm install\` if new dependencies are needed\n3. Run \`apso dev\` to start the server and create auth tables\n\n${authProvider === "better-auth" ? "**Important:** BetterAuth stores passwords in the `account` table (not User). The `providerId` field must be set to \"credential\" for email/password login to work. Use `@apso/better-auth-adapter@latest` in your frontend." : authProvider === "api-key" ? "Store each key's hex SHA-256 in ApiKey.keyHash, never the key itself; callers send the key in the x-api-key header." : "Replace the issuer, audience and claim names with your " + authProvider + " tenant's values. The service checks each token's signature against the issuer's JWKS. See https://docs.apso.ai/develop/auth/byoa."}`,
                     },
                 ],
             };

package/dist/commands/migrate/generate.d.ts

@@ -3,8 +3,10 @@ export default class MigrateGenerate extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
-        baseline: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        baseline: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         name: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        plan: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        typeorm: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;

package/dist/commands/migrate/generate.js

@@ -5,14 +5,37 @@ const path = tslib_1.__importStar(require("path"));
 const core_1 = require("@oclif/core");
 const base_command_1 = tslib_1.__importDefault(require("../../lib/base-command"));
 const apsorc_parser_1 = require("../../lib/apsorc-parser");
+const migration_file_1 = require("../../lib/ddl/migration-file");
+const baseline_1 = require("../../lib/plan/baseline");
 const verify_1 = require("../../lib/verify");
 class MigrateGenerate extends base_command_1.default {
     async run() {
+        var _a, _b;
         const { flags } = await this.parse(MigrateGenerate);
-        const unsupported = (0, verify_1.migrateUnsupported)((0, apsorc_parser_1.parseApsorc)().language);
-        if (unsupported)
-            this.error(unsupported);
-        const result = await (0, verify_1.generateMigration)(process.cwd(), path.resolve(flags.baseline), flags.name, (0, verify_1.cliBinPath)(this.config.root));
+        const { apsorc } = (0, apsorc_parser_1.readApsorcFile)();
+        if (flags.typeorm && ((_a = apsorc.language) !== null && _a !== void 0 ? _a : "typescript") !== "typescript")
+            this.error("--typeorm works on TypeScript services only.");
+        let baseline;
+        try {
+            baseline = (0, baseline_1.resolveBaseline)(process.cwd(), apsorc, flags.baseline, path.resolve(flags.plan));
+        }
+        catch (error) {
+            this.error(error.message, { exit: 1 });
+        }
+        const result = flags.typeorm
+            ? await (0, verify_1.generateMigration)(process.cwd(), (0, baseline_1.baselineFile)(baseline), flags.name, (0, verify_1.cliBinPath)(this.config.root))
+            : (0, migration_file_1.writePlannedMigration)(process.cwd(), baseline.schema, flags.name, path.resolve(flags.plan));
+        const { open } = result;
+        if (open && open.length > 0) {
+            if (flags.json)
+                this.log(JSON.stringify(result));
+            else {
+                this.log((_b = result.steps[0].output) !== null && _b !== void 0 ? _b : "");
+                for (const q of open)
+                    this.log(`\n${q.id}\n  ${q.subject}\n  options: ${q.options.join(" | ")}${q.suggested ? ` (suggested: ${q.suggested})` : ""}`);
+            }
+            this.exit(2);
+        }
         const summary = result.needed
             ? `Created ${result.file}`
             : "The database already matches; no migration needed.";
@@ -21,17 +44,28 @@ class MigrateGenerate extends base_command_1.default {
             this.exit(1);
     }
 }
-MigrateGenerate.description = "Generate a TypeORM migration from the deployed schema to this project's entities, using a local PGlite database (TypeScript services)";
-MigrateGenerate.examples = [`$ apso migrate generate --baseline deployed.apsorc`];
+MigrateGenerate.description = "Write a migration from the deployed schema to this project's .apsorc. Apso renders the SQL from the answered migration plan (apso migrate plan), including data moves and a down() that reverses them. Exits 2 while plan questions are open. The migration is a TypeORM class, an Alembic revision or a goose SQL file, by the service's language. --typeorm uses TypeORM's generator on a local PGlite database instead (TypeScript services).";
+MigrateGenerate.examples = [
+    `$ apso migrate plan --answer entity:Company=rename:Organization`,
+    `$ apso migrate generate`,
+    `$ apso migrate generate --typeorm`,
+];
 MigrateGenerate.flags = {
     baseline: core_1.Flags.string({
-        description: "The deployed .apsorc to migrate from",
-        required: true,
+        description: "The deployed .apsorc to migrate from. Defaults to the schema after the newest planned migration, or the .apsorc from the last commit that changed the migrations folder",
     }),
     name: core_1.Flags.string({
         description: "Migration name",
         default: "SchemaUpdate",
     }),
+    plan: core_1.Flags.string({
+        description: "Migration plan with the answers",
+        default: ".apso/migration-plan.json",
+    }),
+    typeorm: core_1.Flags.boolean({
+        description: "Use TypeORM's migration:generate instead of Apso's plan (no data moves)",
+        default: false,
+    }),
     json: core_1.Flags.boolean({
         description: "Print the result as JSON",
         default: false,

package/dist/commands/migrate/plan.d.ts

@@ -0,0 +1,12 @@
+import BaseCommand from "../../lib/base-command";
+export default class MigratePlan extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        baseline: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        plan: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        answer: import("@oclif/core/lib/interfaces").OptionFlag<string[], import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/migrate/plan.js

@@ -0,0 +1,88 @@
+"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 base_command_1 = tslib_1.__importDefault(require("../../lib/base-command"));
+const apsorc_parser_1 = require("../../lib/apsorc-parser");
+const plan_1 = require("../../lib/plan");
+const baseline_1 = require("../../lib/plan/baseline");
+const prompts_1 = require("../../lib/plan/prompts");
+class MigratePlan extends base_command_1.default {
+    async run() {
+        const { flags } = await this.parse(MigratePlan);
+        const planPath = path.resolve(flags.plan);
+        const { apsorc: after } = (0, apsorc_parser_1.readApsorcFile)();
+        let baseline;
+        try {
+            baseline = (0, baseline_1.resolveBaseline)(process.cwd(), after, flags.baseline, planPath);
+        }
+        catch (error) {
+            this.error(error.message, { exit: 1 });
+        }
+        const before = baseline.schema;
+        // Agents read the output from a pipe; people at a terminal get text.
+        const json = flags.json || !process.stdout.isTTY;
+        // Keep stdout pure JSON for agents: parser notices go to stderr.
+        if (json)
+            console.info = (...m) => process.stderr.write(m.join(" ") + "\n");
+        const previous = fs.existsSync(planPath)
+            ? JSON.parse(fs.readFileSync(planPath).toString())
+            : undefined;
+        let plan;
+        try {
+            plan = (0, plan_1.planWithAnswers)(before, after, previous, flags.answer);
+        }
+        catch (error) {
+            this.error(error.message, { exit: 1 });
+        }
+        fs.mkdirSync(path.dirname(planPath), { recursive: true });
+        fs.writeFileSync(planPath, JSON.stringify({ ...plan, before }, null, 2) + "\n");
+        const open = (0, plan_1.openQuestions)(plan);
+        if (json) {
+            this.log(JSON.stringify({ plan: flags.plan, baseline: baseline.source, open: open.map((q) => (0, prompts_1.describeQuestion)(q)) }, null, 2));
+        }
+        else if (open.length === 0) {
+            this.log(`Compared with ${baseline.source}.`);
+            this.log(`${flags.plan}: all ${plan.questions.length} question(s) answered.`);
+        }
+        else {
+            this.log(`Compared with ${baseline.source}.`);
+            this.log(`${flags.plan}: ${open.length} of ${plan.questions.length} question(s) open.`);
+            for (const q of open) {
+                const hint = q.suggested ? ` (suggested: ${q.suggested})` : "";
+                this.log(`\n${q.id}\n  ${q.subject}\n  options: ${q.options.join(" | ")}${hint}`);
+            }
+            this.log(`\nAnswer with --answer <id>=<option>, or edit ${flags.plan}. ` +
+                `"sql" and "split:" answers also need a "sql" value in the file.`);
+        }
+        if (open.length > 0)
+            this.exit(2);
+    }
+}
+MigratePlan.description = "Compare the deployed .apsorc with this one and write a migration plan. Changes whose intent is ambiguous (rename or drop, how a field splits, which value replaces a removed enum value) become questions; answer them in the plan file or with --answer. Exits 2 while questions are open.";
+MigratePlan.examples = [
+    "$ apso migrate plan",
+    "$ apso migrate plan --answer field:Contact.phone=rename:mobilePhone",
+    "$ apso migrate plan --baseline deployed.apsorc",
+];
+MigratePlan.flags = {
+    baseline: core_1.Flags.string({
+        description: "The deployed .apsorc to migrate from. Defaults to the schema after the newest planned migration, or the .apsorc from the last commit that changed the migrations folder",
+    }),
+    plan: core_1.Flags.string({
+        description: "Plan file to read answers from and write",
+        default: ".apso/migration-plan.json",
+    }),
+    answer: core_1.Flags.string({
+        description: "Answer a question: <question id>=<option>. Repeatable.",
+        multiple: true,
+        default: [],
+    }),
+    json: core_1.Flags.boolean({
+        description: "Print the open questions as JSON (the default when output is not a terminal)",
+        default: false,
+    }),
+};
+exports.default = MigratePlan;

package/dist/commands/migrate/sandbox.d.ts

@@ -0,0 +1,11 @@
+import BaseCommand from "../../lib/base-command";
+export default class MigrateSandbox extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        apply: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        reset: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        sql: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/migrate/sandbox.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const core_1 = require("@oclif/core");
+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");
+class MigrateSandbox extends base_command_1.default {
+    async run() {
+        const { flags } = await this.parse(MigrateSandbox);
+        // Handle reset
+        if (flags.reset) {
+            (0, sandbox_1.resetSandbox)();
+            this.log("Sandbox reset. Snapshot and PGlite data cleared.");
+            return;
+        }
+        // Parse .apsorc
+        let parsed;
+        try {
+            parsed = (0, apsorc_parser_1.parseApsorc)();
+        }
+        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...");
+        }
+        // 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;
+        }
+        // Output results
+        if (flags.sql) {
+            // Raw SQL output mode
+            for (const sql of result.upSql) {
+                this.log(sql + ";");
+            }
+            return;
+        }
+        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}`);
+                }
+            }
+            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.");
+            }
+        }
+        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};`);
+                }
+            }
+            this.exit(1);
+        }
+    }
+}
+MigrateSandbox.description = "Test schema changes against a local PGlite sandbox that keeps its own snapshot of the last schema (the older flow; apso migrate is the guided one)";
+MigrateSandbox.examples = [
+    `$ apso migrate sandbox`,
+    `$ apso migrate sandbox --apply`,
+    `$ apso migrate sandbox --reset`,
+    `$ apso migrate sandbox --sql`,
+];
+MigrateSandbox.flags = {
+    apply: core_1.Flags.boolean({
+        description: "Apply the migration: update the local snapshot after a successful test",
+        default: false,
+    }),
+    reset: core_1.Flags.boolean({
+        description: "Reset the sandbox (clear snapshot and PGlite data)",
+        default: false,
+    }),
+    sql: core_1.Flags.boolean({
+        description: "Output raw SQL only (for piping to files)",
+        default: false,
+    }),
+};
+exports.default = MigrateSandbox;

package/dist/commands/migrate/verify.d.ts

@@ -3,8 +3,11 @@ export default class MigrateVerify extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
-        baseline: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
-        migration: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        baseline: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        migration: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        seed: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        check: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        "accept-loss": import("@oclif/core/lib/interfaces").OptionFlag<string[], import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         "skip-build": import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };

package/dist/commands/migrate/verify.js

@@ -5,31 +5,66 @@ const path = tslib_1.__importStar(require("path"));
 const core_1 = require("@oclif/core");
 const base_command_1 = tslib_1.__importDefault(require("../../lib/base-command"));
 const apsorc_parser_1 = require("../../lib/apsorc-parser");
+const baseline_1 = require("../../lib/plan/baseline");
 const verify_1 = require("../../lib/verify");
 class MigrateVerify extends base_command_1.default {
     async run() {
+        var _a;
         const { flags } = await this.parse(MigrateVerify);
-        const unsupported = (0, verify_1.migrateUnsupported)((0, apsorc_parser_1.parseApsorc)().language);
-        if (unsupported)
-            this.error(unsupported);
-        const result = await (0, verify_1.verifyMigration)(process.cwd(), path.resolve(flags.baseline), flags.migration, (0, verify_1.cliBinPath)(this.config.root), flags["skip-build"]);
+        const { apsorc } = (0, apsorc_parser_1.readApsorcFile)();
+        const latest = (0, baseline_1.latestPlannedMigration)(process.cwd(), apsorc);
+        const migration = (_a = flags.migration) !== null && _a !== void 0 ? _a : latest === null || latest === void 0 ? void 0 : latest.file;
+        if (!migration)
+            this.error("No planned migration found. Run apso migrate generate, or pass --migration.", { exit: 1 });
+        // The migration's own plan says which schema it starts from.
+        const saved = latest && path.resolve(latest.file) === path.resolve(migration)
+            ? latest.saved
+            : undefined;
+        let baseline;
+        if (flags.baseline)
+            baseline = path.resolve(flags.baseline);
+        else if (saved)
+            baseline = (0, baseline_1.baselineFile)({
+                schema: saved.before,
+                source: latest.planFile,
+            });
+        else
+            this.error(`No saved plan for ${migration}; pass the deployed .apsorc with --baseline.`, { exit: 1 });
+        const result = await (0, verify_1.verifyMigration)(process.cwd(), baseline, migration, (0, verify_1.cliBinPath)(this.config.root), {
+            skipBuild: flags["skip-build"],
+            seedFile: flags.seed,
+            checkFile: flags.check,
+            acceptLoss: flags["accept-loss"],
+        });
         (0, verify_1.report)((s) => this.log(s), result, flags.json, result.ok ? "Migration verified." : undefined);
         if (!result.ok)
             this.exit(1);
     }
 }
-MigrateVerify.description = "Run a migration on a local PGlite copy of the deployed schema, then check the database matches this project's entities (TypeScript services)";
+MigrateVerify.description = "Run a migration on a local PGlite copy of the deployed schema, then check the database matches this project's entities (TypeScript), or a fresh build of its .apsorc (Python and Go, which also run down and check it gives back the deployed schema)";
 MigrateVerify.examples = [
+    `$ apso migrate verify`,
+    `$ apso migrate verify --seed seed.sql --check checks.sql`,
+    `$ apso migrate verify --seed seed.sql --check checks.sql --accept-loss contact.fullName`,
     `$ apso migrate verify --baseline deployed.apsorc --migration src/migrations/1700000000000-SchemaUpdate-migration.ts`,
 ];
 MigrateVerify.flags = {
     baseline: core_1.Flags.string({
-        description: "The deployed .apsorc the migration starts from",
-        required: true,
+        description: "The deployed .apsorc the migration starts from. Defaults to the schema saved with the migration's plan",
     }),
     migration: core_1.Flags.string({
-        description: "The migration file to run",
-        required: true,
+        description: "The migration file to run. Defaults to the newest planned migration",
+    }),
+    seed: core_1.Flags.string({
+        description: "SQL file of rows to insert into the deployed schema before the migration runs; the check then fails if the migration loses any of them",
+    }),
+    check: core_1.Flags.string({
+        description: "SQL file of SELECTs run after the migration; each row must have a boolean ok (and a label naming the check), e.g. SELECT bool_and(\"firstName\" <> '') AS ok, 'every contact has a first name' AS label FROM contact",
+    }),
+    "accept-loss": core_1.Flags.string({
+        description: "A table or table.column whose seeded data the migration may drop on purpose (repeatable); pair it with --check to prove where the data went",
+        multiple: true,
+        default: [],
     }),
     "skip-build": core_1.Flags.boolean({
         description: "Use the existing dist/ build instead of building first",