@apso/cli 0.43.4 → 0.45.0

package/dist/lib/verify/review.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Review a TypeORM-generated migration for statements that lose data or fail
+ * on a populated database. TypeORM changes a column type by DROP + ADD, casts
+ * enums without remapping removed values, and adds NOT NULL columns as if the
+ * table were empty. The generated file is kept; each finding names a
+ * statement to rewrite.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reviewMigration = void 0;
+/** The SQL of each queryRunner.query call in a method body. */
+const queries = (body) => [...body.matchAll(/queryRunner\.query\(\s*`([\S\s]*?)`/g)].map((m) => m[1]);
+const enumValues = (sql) => {
+    var _a, _b;
+    return new Set([...((_b = (_a = sql === null || sql === void 0 ? void 0 : sql.match(/ENUM\(([^)]*)\)/)) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : "").matchAll(/'([^']*)'/g)].map((v) => v[1]));
+};
+const typeSql = (sqls, type) => sqls.find((s) => s.startsWith(`CREATE TYPE "public"."${type}" AS ENUM`));
+const list = (values) => values.map((v) => `"${v}"`).join(", ");
+function reviewMigration(source) {
+    var _a, _b, _c, _d, _e;
+    const [upBody, downBody = ""] = source.split(/public\s+async\s+down\s*\(/);
+    const up = queries(upBody);
+    const down = queries(downBody);
+    const findings = [];
+    const add = (code, table, column, message) => findings.push({ code, table, column, message });
+    // Statements on tables this migration creates touch no existing rows.
+    const created = new Set(up.map((q) => { var _a; return (_a = q.match(/^CREATE TABLE "([^"]+)"/)) === null || _a === void 0 ? void 0 : _a[1]; }).filter(Boolean));
+    const existing = (table) => !created.has(table);
+    // An UPDATE or INSERT before a statement that names the column means the
+    // migration already moves or backfills its data.
+    const handled = (i, col) => up.slice(0, i).some((q) => /^(UPDATE|INSERT)\b/.test(q) && q.includes(`"${col}"`));
+    const dropped = new Map();
+    const added = new Map();
+    for (const [i, q] of up.entries()) {
+        const d = q.match(/^ALTER TABLE "([^"]+)" DROP COLUMN "([^"]+)"/);
+        if (d && !handled(i, d[2]))
+            dropped.set(d[1], [...((_a = dropped.get(d[1])) !== null && _a !== void 0 ? _a : []), d[2]]);
+        const a = q.match(/^ALTER TABLE "([^"]+)" ADD "([^"]+)"/);
+        if (a)
+            added.set(a[1], [...((_b = added.get(a[1])) !== null && _b !== void 0 ? _b : []), a[2]]);
+    }
+    for (const [table, cols] of dropped) {
+        const adds = (_c = added.get(table)) !== null && _c !== void 0 ? _c : [];
+        const newCols = adds.filter((a) => !cols.includes(a));
+        for (const col of cols) {
+            if (adds.includes(col))
+                add("TYPE_CHANGE_DROPS_DATA", table, col, `${table}.${col}: TypeORM drops and re-adds the column to change its type, deleting every value. Replace the DROP and ADD with ALTER COLUMN "${col}" TYPE ... USING a cast that converts the existing values.`);
+            else if (newCols.length > 0)
+                add("POSSIBLE_RENAME", table, col, `${table}.${col} is dropped while ${list(newCols)} is added. If that is a rename, replace the DROP and ADD with RENAME COLUMN to keep the data; otherwise every value in "${col}" is deleted.`);
+            else
+                add("DROPS_COLUMN", table, col, created.size > 0
+                    ? `${table}.${col} is dropped with all its values while this migration creates ${list([...created])}. If the data moves there, copy it with INSERT ... SELECT before the DROP; otherwise confirm the loss.`
+                    : `${table}.${col} is dropped with all its values. Confirm the loss, or copy the data first.`);
+        }
+    }
+    for (const [i, q] of up.entries()) {
+        let m = q.match(/^DROP TABLE "([^"]+)"/);
+        if (m)
+            add("DROPS_TABLE", m[1], undefined, `Table ${m[1]} is dropped with all its rows. Confirm the loss, or rename the table if an entity was renamed.`);
+        m = q.match(/^ALTER TABLE "([^"]+)" ADD "([^"]+)" [^,]*\bNOT NULL\b(.*)$/);
+        if (m && existing(m[1])) {
+            const def = (_d = m[3].match(/DEFAULT (.+)$/)) === null || _d === void 0 ? void 0 : _d[1].trim();
+            if (def)
+                add("DEFAULT_BACKFILLS_ROWS", m[1], m[2], `${m[1]}.${m[2]} is added NOT NULL DEFAULT ${def}, so every existing row gets ${def}. Confirm that is right for existing rows, or add the column nullable, backfill it, then SET NOT NULL.`);
+            else
+                add("NOT_NULL_WITHOUT_BACKFILL", m[1], m[2], `${m[1]}.${m[2]} is added NOT NULL with no default, which fails if ${m[1]} has any rows. Add it nullable, backfill it, then SET NOT NULL.`);
+        }
+        m = q.match(/^ALTER TABLE "([^"]+)" ALTER COLUMN "([^"]+)" SET NOT NULL/);
+        if (m && existing(m[1]) && !handled(i, m[2]))
+            add("SET_NOT_NULL", m[1], m[2], `${m[1]}.${m[2]} becomes NOT NULL, which fails on any row where it is null. Backfill those rows first.`);
+        m = q.match(/^ALTER TABLE "([^"]+)" ALTER COLUMN "([^"]+)" TYPE (?!"public"\."[^"]+_enum")/);
+        if (m && existing(m[1]))
+            add("TYPE_CAST", m[1], m[2], `${m[1]}.${m[2]} changes type in place; a value the cast cannot convert fails the migration. Check the USING clause handles every existing value.`);
+        m =
+            (_e = q.match(/^CREATE UNIQUE INDEX "[^"]+" ON "([^"]+)" \(([^)]+)\)/)) !== null && _e !== void 0 ? _e : q.match(/^ALTER TABLE "([^"]+)" ADD CONSTRAINT "[^"]+" UNIQUE \(([^)]+)\)/);
+        if (m && existing(m[1]))
+            add("UNIQUE_ON_EXISTING_ROWS", m[1], m[2].replace(/"/g, ""), `A unique constraint on ${m[1]} (${m[2].replace(/"/g, "")}) fails if existing rows hold duplicates. Check for duplicates first and decide which row wins.`);
+        m = q.match(/^ALTER TABLE "([^"]+)" ADD CONSTRAINT "[^"]+" FOREIGN KEY \("([^"]+)"\) REFERENCES "([^"]+)"/);
+        if (m && existing(m[1]) && created.has(m[3]))
+            add("FOREIGN_KEY_TO_NEW_TABLE", m[1], m[2], `Existing ${m[1]} rows must point at ${m[3]}, which this migration creates empty, so the foreign key fails on any row with ${m[2]} set. If ${m[3]} replaces an existing entity, replace the CREATE TABLE with ALTER TABLE "<old table>" RENAME TO "${m[3]}" and ALTER SEQUENCE "<old table>_id_seq" RENAME TO "${m[3]}_id_seq"; TypeORM leaves the old table in place.`);
+    }
+    // TypeORM swaps an enum by renaming the old type to *_old, creating the new
+    // one and casting through text; down() recreates *_old with the old values.
+    for (const q of up) {
+        const m = q.match(/^ALTER TYPE "public"\."([^"]+)" RENAME TO "([^"]+_old)"/);
+        if (!m)
+            continue;
+        const now = enumValues(typeSql(up, m[1]));
+        const cast = up.find((s) => s.includes(`TYPE "public"."${m[1]}" USING`));
+        // A USING clause that names a removed value maps it; the rest still fail.
+        const removed = [...enumValues(typeSql(down, m[2]))].filter((v) => !now.has(v) && !(cast === null || cast === void 0 ? void 0 : cast.includes(`'${v}'`)));
+        const col = cast === null || cast === void 0 ? void 0 : cast.match(/^ALTER TABLE "([^"]+)" ALTER COLUMN "([^"]+)"/);
+        if (removed.length > 0 && col)
+            add("ENUM_VALUES_REMOVED", col[1], col[2], `${col[1]}.${col[2]} drops enum value ${removed.map((v) => `'${v}'`).join(", ")}; the cast fails on any row that still holds it. Map those rows to a remaining value in the USING clause, e.g. CASE "${col[2]}"::text WHEN '${removed[0]}' THEN '...' ELSE "${col[2]}"::text END.`);
+    }
+    return findings;
+}
+exports.reviewMigration = reviewMigration;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@apso/cli",
-  "version": "0.43.4",
+  "version": "0.45.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@apso/cli",
-      "version": "0.43.4",
+      "version": "0.45.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@apso/schema-tools": "^0.2.0",

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.43.4",
+  "version": "0.45.0",
   "commands": {
     "config": {
       "id": "config",
@@ -379,7 +379,7 @@
     },
     "migrate": {
       "id": "migrate",
-      "description": "Detect schema changes, generate migration SQL, and test against a local PGlite sandbox",
+      "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.",
       "strict": true,
       "pluginName": "@apso/cli",
       "pluginAlias": "@apso/cli",
@@ -388,27 +388,65 @@
       "hiddenAliases": [],
       "examples": [
         "$ apso migrate",
-        "$ apso migrate --apply",
-        "$ apso migrate --reset",
-        "$ apso migrate --sql"
+        "$ apso migrate --answer field:Contact.phone=rename:mobilePhone",
+        "$ apso migrate --seed seed.sql --check checks.sql"
       ],
       "flags": {
-        "apply": {
-          "name": "apply",
+        "baseline": {
+          "name": "baseline",
+          "type": "option",
+          "description": "The deployed .apsorc, the first time only. Later runs find it from the last migration",
+          "multiple": false
+        },
+        "answer": {
+          "name": "answer",
+          "type": "option",
+          "description": "Answer a question: <question id>=<option>. Repeatable.",
+          "multiple": true,
+          "default": []
+        },
+        "seed": {
+          "name": "seed",
+          "type": "option",
+          "description": "SQL file of rows to load first; the test then fails if the migration loses any",
+          "multiple": false
+        },
+        "check": {
+          "name": "check",
+          "type": "option",
+          "description": "SQL file of SELECTs with a boolean ok column, run after the migration",
+          "multiple": false
+        },
+        "accept-loss": {
+          "name": "accept-loss",
+          "type": "option",
+          "description": "A table or table.column whose seeded data may be dropped on purpose (repeatable)",
+          "multiple": true,
+          "default": []
+        },
+        "name": {
+          "name": "name",
+          "type": "option",
+          "description": "Migration name",
+          "multiple": false,
+          "default": "SchemaUpdate"
+        },
+        "skip-generate": {
+          "name": "skip-generate",
           "type": "boolean",
-          "description": "Apply the migration: update the local snapshot after a successful test",
+          "description": "Don't regenerate code from .apsorc first",
           "allowNo": false
         },
-        "reset": {
-          "name": "reset",
+        "skip-verify": {
+          "name": "skip-verify",
           "type": "boolean",
-          "description": "Reset the sandbox (clear snapshot and PGlite data)",
+          "description": "Write the migration without testing it",
           "allowNo": false
         },
-        "sql": {
-          "name": "sql",
+        "json": {
+          "name": "json",
           "type": "boolean",
-          "description": "Output raw SQL only (for piping to files)",
+          "description": "Print the result as JSON (the default when output is not a terminal)",
           "allowNo": false
         }
       },
@@ -771,7 +809,7 @@
     },
     "migrate:generate": {
       "id": "migrate:generate",
-      "description": "Generate a TypeORM migration from the deployed schema to this project's entities, using a local PGlite database (TypeScript services)",
+      "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).",
       "strict": true,
       "pluginName": "@apso/cli",
       "pluginAlias": "@apso/cli",
@@ -779,14 +817,15 @@
       "aliases": [],
       "hiddenAliases": [],
       "examples": [
-        "$ apso migrate generate --baseline deployed.apsorc"
+        "$ apso migrate plan --answer entity:Company=rename:Organization",
+        "$ apso migrate generate",
+        "$ apso migrate generate --typeorm"
       ],
       "flags": {
         "baseline": {
           "name": "baseline",
           "type": "option",
-          "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",
           "multiple": false
         },
         "name": {
@@ -796,6 +835,19 @@
           "multiple": false,
           "default": "SchemaUpdate"
         },
+        "plan": {
+          "name": "plan",
+          "type": "option",
+          "description": "Migration plan with the answers",
+          "multiple": false,
+          "default": ".apso/migration-plan.json"
+        },
+        "typeorm": {
+          "name": "typeorm",
+          "type": "boolean",
+          "description": "Use TypeORM's migration:generate instead of Apso's plan (no data moves)",
+          "allowNo": false
+        },
         "json": {
           "name": "json",
           "type": "boolean",
@@ -805,9 +857,90 @@
       },
       "args": {}
     },
+    "migrate:plan": {
+      "id": "migrate:plan",
+      "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.",
+      "strict": true,
+      "pluginName": "@apso/cli",
+      "pluginAlias": "@apso/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "examples": [
+        "$ apso migrate plan",
+        "$ apso migrate plan --answer field:Contact.phone=rename:mobilePhone",
+        "$ apso migrate plan --baseline deployed.apsorc"
+      ],
+      "flags": {
+        "baseline": {
+          "name": "baseline",
+          "type": "option",
+          "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",
+          "multiple": false
+        },
+        "plan": {
+          "name": "plan",
+          "type": "option",
+          "description": "Plan file to read answers from and write",
+          "multiple": false,
+          "default": ".apso/migration-plan.json"
+        },
+        "answer": {
+          "name": "answer",
+          "type": "option",
+          "description": "Answer a question: <question id>=<option>. Repeatable.",
+          "multiple": true,
+          "default": []
+        },
+        "json": {
+          "name": "json",
+          "type": "boolean",
+          "description": "Print the open questions as JSON (the default when output is not a terminal)",
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
+    "migrate:sandbox": {
+      "id": "migrate:sandbox",
+      "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)",
+      "strict": true,
+      "pluginName": "@apso/cli",
+      "pluginAlias": "@apso/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "examples": [
+        "$ apso migrate sandbox",
+        "$ apso migrate sandbox --apply",
+        "$ apso migrate sandbox --reset",
+        "$ apso migrate sandbox --sql"
+      ],
+      "flags": {
+        "apply": {
+          "name": "apply",
+          "type": "boolean",
+          "description": "Apply the migration: update the local snapshot after a successful test",
+          "allowNo": false
+        },
+        "reset": {
+          "name": "reset",
+          "type": "boolean",
+          "description": "Reset the sandbox (clear snapshot and PGlite data)",
+          "allowNo": false
+        },
+        "sql": {
+          "name": "sql",
+          "type": "boolean",
+          "description": "Output raw SQL only (for piping to files)",
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
     "migrate:verify": {
       "id": "migrate:verify",
-      "description": "Run a migration on a local PGlite copy of the deployed schema, then check the database matches this project's entities (TypeScript services)",
+      "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)",
       "strict": true,
       "pluginName": "@apso/cli",
       "pluginAlias": "@apso/cli",
@@ -815,23 +948,43 @@
       "aliases": [],
       "hiddenAliases": [],
       "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"
       ],
       "flags": {
         "baseline": {
           "name": "baseline",
           "type": "option",
-          "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",
           "multiple": false
         },
         "migration": {
           "name": "migration",
           "type": "option",
-          "description": "The migration file to run",
-          "required": true,
+          "description": "The migration file to run. Defaults to the newest planned migration",
           "multiple": false
         },
+        "seed": {
+          "name": "seed",
+          "type": "option",
+          "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",
+          "multiple": false
+        },
+        "check": {
+          "name": "check",
+          "type": "option",
+          "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",
+          "multiple": false
+        },
+        "accept-loss": {
+          "name": "accept-loss",
+          "type": "option",
+          "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": {
           "name": "skip-build",
           "type": "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apso/cli",
-  "version": "0.43.4",
+  "version": "0.45.0",
   "mcpName": "io.github.apsoai/apso",
   "description": "Apso CLI",
   "author": "Apso by Mavric - @mavric",