@apso/cli 0.43.3 → 0.44.0

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.43.3",
+  "version": "0.44.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.3",
+  "version": "0.44.0",
   "mcpName": "io.github.apsoai/apso",
   "description": "Apso CLI",
   "author": "Apso by Mavric - @mavric",