@metaobjectsdev/cli 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/cli",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "CLI for MetaObjects: scaffold, codegen, migrate, and drift-detection commands.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -51,15 +51,15 @@
     "@biomejs/js-api": "^0.7.0",
     "@biomejs/wasm-nodejs": "^1.9.4",
     "@libsql/kysely-libsql": "^0.4.0",
-    "@metaobjectsdev/codegen-ts": "1.0.5",
-    "@metaobjectsdev/codegen-ts-react": "1.0.5",
-    "@metaobjectsdev/codegen-ts-tanstack": "1.0.5",
-    "@metaobjectsdev/docs-site": "1.0.5",
-    "@metaobjectsdev/metadata": "1.0.5",
-    "@metaobjectsdev/migrate-ts": "1.0.5",
-    "@metaobjectsdev/render": "1.0.5",
-    "@metaobjectsdev/runtime-ts": "1.0.5",
-    "@metaobjectsdev/sdk": "1.0.5",
+    "@metaobjectsdev/codegen-ts": "1.0.7",
+    "@metaobjectsdev/codegen-ts-react": "1.0.7",
+    "@metaobjectsdev/codegen-ts-tanstack": "1.0.7",
+    "@metaobjectsdev/docs-site": "1.0.7",
+    "@metaobjectsdev/metadata": "1.0.7",
+    "@metaobjectsdev/migrate-ts": "1.0.7",
+    "@metaobjectsdev/render": "1.0.7",
+    "@metaobjectsdev/runtime-ts": "1.0.7",
+    "@metaobjectsdev/sdk": "1.0.7",
     "@toon-format/toon": "^2.3.0",
     "jiti": "^2.4.0"
   },

package/src/commands/migrate.ts

@@ -17,6 +17,9 @@ import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { exclusionNotes, importedOption, migrateScopeMismatch } from "../lib/migrate-scope.js";
 import {
   allowOptionFor,
+  isBlockedChangesError,
+  isPrimaryKeyChangeError,
+  isDeclaredRenameError,
   buildExpectedSchemaWithProvenance,
   scopeExpectedSchema,
   scopedDiffInputs,
@@ -32,8 +35,7 @@ import {
   readSnapshot,
   writeSnapshot,
   qualifiedDbName,
-  BlockedChangesError,
-  PrimaryKeyChangeError,
+  type BlockedChangesError,
   renderD1,
   writeMigrationD1,
   writeMigrationFlyway,
@@ -46,6 +48,7 @@ import {
   type AmbiguousChange,
   type AmbiguousResolution,
   type Change,
+  type DataHazard,
   type D1Binding,
   type EmitResult,
   type D1Runner,
@@ -112,6 +115,15 @@ MIGRATE FLAGS:
                        never existed.
   --on-ambiguous abort|rename|drop-add
                        How to handle ambiguous renames (default: abort)
+  --rename-table [schema.]old=new
+                       Declare a table rename (repeatable). Resolves the drop+create
+                       as ALTER TABLE ... RENAME TO whatever the rename heuristic
+                       makes of the names; refused if no such pair is pending.
+  --rename-column [schema.]table.old=new
+                       Declare a column rename (repeatable); keeps the column's data.
+                       'table' is the name in the metadata (the NEW name when the
+                       table is renamed in the same run). The column's type,
+                       nullability and default must not change in the same run.
   --from-db            Introspect live DB instead of using the committed snapshot
   --apply              Run pending migration files against the DB after writing
   --rollback <target>  Roll back applied migrations newer than <target>
@@ -269,6 +281,47 @@ function mapOnAmbiguous(v: "abort" | "rename" | "drop-add"): AmbiguousResolution
   return v === "drop-add" ? "drop+add" : v;
 }
 
+/**
+ * The report-and-exit for an engine refusal whose message the engine already made
+ * actionable — the sibling of `refuseScopeMismatch` above, which is the same decision
+ * for scope. The engine's guards (`isPrimaryKeyChangeError` et al.) narrow at the catch
+ * site; only the hint varies by refusal, so each hint is written once.
+ */
+function refuseEngineError(err: Error, hint: string, fmt: OutputFormat): number {
+  log.error(`migrate: ${err.message}`);
+  emitStructuredError(`migrate: ${err.message}`, hint, fmt);
+  return 1;
+}
+
+const PK_CHANGE_HINT =
+  "align the primary key manually, or reconcile the metadata identity to match the live table";
+const DECLARED_RENAME_HINT =
+  "fix or remove the --rename-table / --rename-column flag; a table's name is its name in the metadata (the new name when it is renamed too)";
+
+/**
+ * Warn about changes that apply to an empty table and fail on a populated one. Warn, not
+ * refuse: the diff cannot see rows, and a new required column on an empty table is fine.
+ * The Postgres migration file carries the same warning, with the preparation step, above
+ * the statement.
+ */
+function warnDataHazards(hazards: readonly DataHazard[]): string[] {
+  const warnings = hazards.map((h) => {
+    const t = h.schema !== undefined ? `${h.schema}.${h.table}` : h.table;
+    switch (h.kind) {
+      case "add-required-column":
+        return `${t}.${h.column} is added NOT NULL with no default — fails if ${t} has rows. `
+          + `Give the field a @default, or add it optional, backfill, then make it required.`;
+      case "set-not-null":
+        return `${t}.${h.column} becomes NOT NULL — fails if any row holds NULL. Backfill it first.`;
+      case "add-check":
+        return `CHECK ${h.check} is added to ${t} — fails if any existing row violates `
+          + `(${h.expression}). Fix those rows first.`;
+    }
+  });
+  for (const w of warnings) log.warn(`migrate: ${w}`);
+  return warnings;
+}
+
 /**
  * The command that actually creates tables in a fresh/empty database. This is the
  * correct first step for a brand-new project — it introspects the (empty) DB, diffs
@@ -657,6 +710,7 @@ export async function migrateCommand(
   let applyFailed = false;
   let blocked: BlockedEntry[] = [];
   let ambiguous: AmbiguousEntry[] = [];
+  let hazardWarnings: string[] = [];
   let changeCounts: Record<string, number> = {};
 
   try {
@@ -712,6 +766,7 @@ export async function migrateCommand(
         actual,
         dialect: kysely.dialect,
         allow: tokensToAllowOptions(config.allow),
+        renames: config.renames,
         // #258 — adopting a live DB whose PRIMARY KEY differs from the metadata identity
         // has no expressible migration; refuse loudly instead of emitting SQL that drops
         // the constraint and breaks referencing FKs at apply.
@@ -723,11 +778,14 @@ export async function migrateCommand(
       });
     } catch (err) {
       // #258 — a primary-key move has no expressible migration; refuse loudly.
-      if (err instanceof PrimaryKeyChangeError) {
-        log.error(`migrate: ${err.message}`);
-        emitStructuredError(`migrate: ${err.message}`, "align the primary key manually, or reconcile the metadata identity to match the live table", fmt);
+      if (isPrimaryKeyChangeError(err)) {
+        const rc = refuseEngineError(err, PK_CHANGE_HINT, fmt);
         await kysely.close();
-        return 1;
+        return rc;
+      }
+      if (isDeclaredRenameError(err)) {
+        await kysely.close();
+        return refuseEngineError(err, DECLARED_RENAME_HINT, fmt);
       }
       // diff() throws when onAmbiguous returns "abort" — surface as exit 1
       // with the collected ambiguity list.
@@ -756,6 +814,7 @@ export async function migrateCommand(
     }
 
     changeCounts = summarizeChanges(diffResult.changes);
+    hazardWarnings = warnDataHazards(diffResult.hazards);
 
     // #313 — refuse to AUTHOR a drop for an object the committed snapshot never
     // contained. This path diffs metadata against introspection and never reads the
@@ -813,7 +872,7 @@ export async function migrateCommand(
           ...(actual.meta !== undefined ? { actualMeta: actual.meta } : {}),
         });
       } catch (err) {
-        if (err instanceof BlockedChangesError) {
+        if (isBlockedChangesError(err)) {
           blocked = blockedToEntries(err);
           exitCode = 1;
         } else {
@@ -944,6 +1003,7 @@ export async function migrateCommand(
     format: config.format,
     applied: appliedNames,
     applyFailed,
+    warnings: hazardWarnings,
   };
   const output =
     fmt === "toon" ? formatMigrateResultToon(migrateResult)
@@ -1267,6 +1327,7 @@ export async function runOfflineGenerate(
       // the default `meta migrate` — performing no import exclusion at all.
       ...importedOption(collection),
       allow: tokensToAllowOptions(config.allow),
+      renames: config.renames,
       onAmbiguous: async (a) => {
         collectedAmbiguous.push(a);
         return onAmbiguousResolution;
@@ -1274,11 +1335,8 @@ export async function runOfflineGenerate(
     });
   } catch (err) {
     // #258 — a primary-key move has no expressible migration; refuse loudly.
-    if (err instanceof PrimaryKeyChangeError) {
-      log.error(`migrate: ${err.message}`);
-      emitStructuredError(`migrate: ${err.message}`, "align the primary key manually, or reconcile the metadata identity to match the live table", fmt);
-      return 1;
-    }
+    if (isPrimaryKeyChangeError(err)) return refuseEngineError(err, PK_CHANGE_HINT, fmt);
+    if (isDeclaredRenameError(err)) return refuseEngineError(err, DECLARED_RENAME_HINT, fmt);
     if ((err as Error).message.includes("aborted by onAmbiguous")) {
       log.error(`migrate: ambiguous rename/drop detected; re-run with --on-ambiguous rename|drop-add`);
       return 1;
@@ -1304,6 +1362,7 @@ export async function runOfflineGenerate(
     log.error(`migrate: --slug <name> required when there are changes (e.g., --slug add-user-shipping)`);
     return 2;
   }
+  warnDataHazards(diffResult.hazards);
 
   const emitResult = emit(diffResult.changes, {
     dialect: config.dialect,
@@ -1523,6 +1582,7 @@ async function runD1Migrate(
       // @constraintName models churning and enum @values changes silent on D1.
       dialect: "d1",
       allow: tokensToAllowOptions(config.allow),
+      renames: config.renames,
       // #258 — adopting a live D1 DB whose PRIMARY KEY differs from the metadata identity
       // has no expressible migration; refuse loudly instead of emitting SQL that drops
       // the constraint and breaks referencing FKs at apply (same failure as the online path).
@@ -1534,11 +1594,8 @@ async function runD1Migrate(
     });
   } catch (err) {
     // #258 — a primary-key move has no expressible migration; refuse loudly.
-    if (err instanceof PrimaryKeyChangeError) {
-      log.error(`migrate: ${err.message}`);
-      emitStructuredError(`migrate: ${err.message}`, "align the primary key manually, or reconcile the metadata identity to match the live table", fmt);
-      return 1;
-    }
+    if (isPrimaryKeyChangeError(err)) return refuseEngineError(err, PK_CHANGE_HINT, fmt);
+    if (isDeclaredRenameError(err)) return refuseEngineError(err, DECLARED_RENAME_HINT, fmt);
     if ((err as Error).message.includes("aborted by onAmbiguous")) {
       const entries = ambiguousToEntries(collectedAmbiguous);
       for (const e of entries) {
@@ -1551,6 +1608,7 @@ async function runD1Migrate(
   }
 
   const changeCounts = summarizeChanges(diffResult.changes);
+  warnDataHazards(diffResult.hazards);
 
   // Views are emitted by the one schema-diff path: renderD1 = renderSqlite (which
   // renders view DDL) + the D1 safety pass (applied inside renderD1, stripping the
@@ -1572,7 +1630,7 @@ async function runD1Migrate(
   try {
     emitResult = renderD1(diffResult.changes, expected, actual.meta, actual);
   } catch (err) {
-    if (err instanceof BlockedChangesError) {
+    if (isBlockedChangesError(err)) {
       const entries = blockedToEntries(err);
       for (const e of entries) {
         log.error(`migrate: blocked '${e.kind}' on ${e.description} (allow with --allow ${e.allowFlag})`);

package/src/commands/verify.ts

@@ -122,7 +122,7 @@ const ERR_UNKNOWN_ATTR = "ERR_UNKNOWN_ATTR";
  */
 const EMPTY_MIGRATE_FLAGS = {
   db: undefined, dialect: undefined, format: undefined, outDir: undefined, slug: undefined,
-  allow: [], onAmbiguous: undefined, dryRun: false, d1Binding: undefined, remote: false,
+  allow: [], onAmbiguous: undefined, renames: [], dryRun: false, d1Binding: undefined, remote: false,
   apply: false, rollback: undefined, yes: false, fromDb: false, baseline: false,
   applyPending: false,
 } as const satisfies MigrateFlags;

package/src/index.ts

@@ -143,6 +143,8 @@ MIGRATE FLAGS:
                         drop-check,drop-view,drop-view-cascade,
                         adopt-view,nullable-to-not-null,drop-identity-default
   --on-ambiguous abort|rename|drop-add   Default abort
+  --rename-table [schema.]old=new         Declare a table rename (repeatable)
+  --rename-column [schema.]table.old=new  Declare a column rename; keeps its data (repeatable)
   --d1 <binding>        D1 binding name from wrangler.toml (only with --dialect d1)
   --remote              Target remote D1 instead of local (only with --dialect d1)
   --apply               Run 'wrangler d1 migrations apply' after writing files

package/src/lib/args.ts

@@ -1,4 +1,5 @@
 import { parseArgs } from "node:util";
+import type { DeclaredRename } from "@metaobjectsdev/migrate-ts";
 import { parseAdvisoryLimit } from "./advisory.js";
 
 // ---------------------------------------------------------------------------
@@ -510,6 +511,8 @@ export interface MigrateFlags {
   slug: string | undefined;
   allow: AllowToken[];
   onAmbiguous: OnAmbiguous | undefined;
+  /** `--rename-table` / `--rename-column`: renames the author declares (see `DeclaredRename`). */
+  renames: DeclaredRename[];
   dryRun: boolean;
   // D1-specific:
   d1Binding: string | undefined;
@@ -539,6 +542,8 @@ export const MIGRATE_OPTIONS = {
   "slug": { type: "string" },
   "allow": { type: "string", multiple: true },
   "on-ambiguous": { type: "string" },
+  "rename-table": { type: "string", multiple: true },
+  "rename-column": { type: "string", multiple: true },
   "dry-run": { type: "boolean", default: false },
   "from-db": { type: "boolean", default: false },
   "d1": { type: "string" },
@@ -593,6 +598,10 @@ export function parseMigrateArgs(argv: string[]): MigrateFlags {
     slug: values.slug as string | undefined,
     allow: allowTokens as AllowToken[],
     onAmbiguous: onAmb as OnAmbiguous | undefined,
+    renames: [
+      ...((values["rename-table"] as string[] | undefined) ?? []).map(parseTableRename),
+      ...((values["rename-column"] as string[] | undefined) ?? []).map(parseColumnRename),
+    ],
     dryRun: !!values["dry-run"],
     d1Binding: values.d1 as string | undefined,
     remote: !!values.remote,
@@ -605,6 +614,40 @@ export function parseMigrateArgs(argv: string[]): MigrateFlags {
   };
 }
 
+/** `--rename-table [schema.]old=new` — the new name is bare: a rename never moves schemas. */
+function parseTableRename(v: string): DeclaredRename {
+  const { path, to } = splitRename(v, "--rename-table", "[schema.]old=new", 1, 2);
+  const from = path[path.length - 1]!;
+  return path.length === 2 ? { kind: "table", schema: path[0]!, from, to } : { kind: "table", from, to };
+}
+
+/** `--rename-column [schema.]table.old=new` — `table` is the table's name in the metadata. */
+function parseColumnRename(v: string): DeclaredRename {
+  const { path, to } = splitRename(v, "--rename-column", "[schema.]table.old=new", 2, 3);
+  const [from, table] = [path[path.length - 1]!, path[path.length - 2]!];
+  return path.length === 3
+    ? { kind: "column", schema: path[0]!, table, from, to }
+    : { kind: "column", table, from, to };
+}
+
+/**
+ * Split `<path>=<new>` into the dotted path and the new name, refusing anything the
+ * flag's grammar cannot hold — including a path of [minPath, maxPath] segments, so the
+ * `invalid <flag>` message has the one construction site its callers also use.
+ */
+function splitRename(
+  v: string, flag: string, shape: string, minPath: number, maxPath: number,
+): { path: string[]; to: string } {
+  const eq = v.indexOf("=");
+  const path = eq < 0 ? [] : v.slice(0, eq).split(".");
+  const to = eq < 0 ? "" : v.slice(eq + 1);
+  if (to === "" || to.includes(".") || to.includes("=") || path.some((p) => p === "")
+      || path.length < minPath || path.length > maxPath) {
+    throw new Error(`invalid ${flag} '${v}'; expected ${shape}`);
+  }
+  return { path, to };
+}
+
 // ---------------------------------------------------------------------------
 // eject flags — FR-040 §4.2(a)
 // ---------------------------------------------------------------------------

package/src/lib/config.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { ConfigSchema, type Config, DEFAULT_METAOBJECTS_DIR } from "@metaobjectsdev/sdk";
 import type { GenFlags, MigrateFlags, MigrateFormat } from "./args.js";
 import type { Dialect } from "./kysely.js";
+import type { DeclaredRename } from "@metaobjectsdev/migrate-ts";
 
 // ---------------------------------------------------------------------------
 // Built-in defaults
@@ -42,6 +43,8 @@ export interface ResolvedMigrateConfig {
   /** Output-format adapter (#192): "default" homegrown layout, or "flyway" V__/U__. */
   format: MigrateFormat;
   onAmbiguous: "abort" | "rename" | "drop-add";
+  /** Declared renames — CLI-only, never config: a rename is a one-time migration event. */
+  renames: DeclaredRename[];
   allow: string[];
   slug: string | undefined;
   dryRun: boolean;
@@ -121,6 +124,7 @@ export async function resolveMigrateConfig(
     dialect: flags.dialect ?? cfgBlock.dialect ?? MIGRATE_DEFAULTS.dialect,
     format: flags.format ?? cfgBlock.format ?? MIGRATE_DEFAULTS.format,
     onAmbiguous: flags.onAmbiguous ?? cfgBlock.onAmbiguous ?? MIGRATE_DEFAULTS.onAmbiguous,
+    renames: flags.renames,
     allow: flags.allow.length > 0
       ? flags.allow
       : (cfgBlock.allow ?? MIGRATE_DEFAULTS.allow),

package/src/lib/output.ts

@@ -181,6 +181,12 @@ export interface MigrateResultShape {
    * that cannot work.
    */
   format?: "default" | "flyway";
+  /**
+   * Data-hazard warnings: changes that apply to an empty table and fail on a populated one.
+   * Text output already carries them on stderr; JSON/toon carry them here so a programmatic
+   * caller sees the risk before applying.
+   */
+  warnings?: string[];
 }
 
 export function formatMigrateResult(result: MigrateResultShape, _opts: FormatOptions): string {
@@ -298,6 +304,7 @@ export function migrateResultToData(result: MigrateResultShape): {
   written: string[];
   summary: string;
   help: string[];
+  warnings?: string[];
 } {
   const changeEntries = Object.entries(result.changeCounts).filter(([, v]) => v > 0);
   const changes = changeEntries.map(([kind, count]) => ({ kind, count }));
@@ -352,7 +359,12 @@ export function migrateResultToData(result: MigrateResultShape): {
     help = ["re-run with --slug <name> to write the migration"];
   }
 
-  return { changes, written: result.writtenPaths, summary, help };
+  const warnings = result.warnings ?? [];
+  return {
+    changes, written: result.writtenPaths, summary, help,
+    // Only when present, so a run with no hazard keeps its existing shape.
+    ...(warnings.length > 0 ? { warnings } : {}),
+  };
 }
 
 export function formatMigrateResultToon(result: MigrateResultShape): string {