@metaobjectsdev/cli 1.0.9-rc.1 → 1.0.9-rc.3

package/src/lib/allow.ts

@@ -79,11 +79,19 @@ export function describeChange(c: Change): string {
     case "drop-index": return `${c.table} idx ${c.index}`;
     case "add-fk": return `${c.table} fk ${c.fk.name}`;
     case "drop-fk": return `${c.table} fk ${c.fk}`;
+    case "add-check": return `${c.table} check ${c.check.name} (${c.check.expression})`;
+    case "drop-check":
+      return c.restore !== undefined
+        ? `${c.table} check ${c.check} (${c.restore.expression})`
+        : `${c.table} check ${c.check}`;
     case "create-view": return c.view.name;
     case "replace-view": return c.view.name;
     case "drop-view": return c.view;
-    default: return JSON.stringify(c);
   }
+  // Exhaustive: a new Change kind fails to compile here rather than printing a JSON dump
+  // of the change object to a person (which is what a blocked drop-check used to do).
+  const unhandled: never = c;
+  return unhandled;
 }
 
 /** The `--allow` token that unblocks `c`. migrate-ts picks the permission by what blocked the

package/src/lib/catalog-listing.ts

@@ -77,6 +77,9 @@ export interface GeneratorCatalogRow {
     wouldEmit: number | null;
     /** Why `wouldEmit` is null despite --probe. Absent when it is a number. */
     probeError?: string;
+    /** Config keys this project leaves unset that the generator needs before `meta gen`
+     *  can run it. `wouldEmit` was counted with a placeholder for each. Absent when none. */
+    needsConfig?: string[];
   };
 }
 
@@ -180,21 +183,44 @@ async function probeOne(
   project: CatalogProject,
   metadata: MetaData,
   scope: ((fqn: string) => boolean) | undefined,
-): Promise<{ count: number } | { error: string }> {
-  try {
+): Promise<{ count: number; needsConfig?: string[] } | { error: string }> {
+  const count = async (config: MetaobjectsGenConfig): Promise<number> => {
     const result = await runGen({
-      config: { ...project.config, generators: [entry.factory()] },
+      config: { ...config, generators: [entry.factory()] },
       metadata,
       projectRoot: project.projectRoot,
       dryRun: true,
       ...(scope !== undefined ? { scope } : {}),
     });
-    return { count: result.files.length };
+    return result.files.length;
+  };
+  try {
+    return { count: await count(project.config) };
   } catch (err) {
+    // A generator that emits `import { db } from …` (the Fastify `routes`, `queries`)
+    // refuses to run while `dbImport` is unset — which it is in a freshly initialised
+    // project, exactly when `--probe` is being asked "what would this emit?". The path
+    // changes one import line, never the file count, so count with a placeholder and
+    // report the key as needed rather than dropping the count: the listing used to show
+    // `routes … [fastify]` beside `routes-hono … [hono, would emit 3]` with no reason.
+    // Only a retry that SUCCEEDS with the key supplied attributes the failure to it.
+    if (project.config.dbImport === undefined) {
+      try {
+        return {
+          count: await count({ ...project.config, dbImport: PROBE_DB_IMPORT_PLACEHOLDER }),
+          needsConfig: ["dbImport"],
+        };
+      } catch {
+        // Fall through: the original error is the one worth reporting.
+      }
+    }
     return { error: (err as Error).message };
   }
 }
 
+/** Stand-in `dbImport` for a probe. Never written anywhere — `dryRun` touches no file. */
+const PROBE_DB_IMPORT_PLACEHOLDER = "./db";
+
 // ---------------------------------------------------------------------------
 // the listing
 // ---------------------------------------------------------------------------
@@ -241,10 +267,13 @@ export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promis
 
       let wouldEmit: number | null = null;
       let probeError: string | undefined;
+      let needsConfig: string[] | undefined;
       if (opts.probe !== undefined) {
         const outcome = await probeOne(entry, project, opts.probe.metadata, opts.probe.scope);
-        if ("count" in outcome) wouldEmit = outcome.count;
-        else probeError = outcome.error;
+        if ("count" in outcome) {
+          wouldEmit = outcome.count;
+          needsConfig = outcome.needsConfig;
+        } else probeError = outcome.error;
       }
 
       row.project = {
@@ -252,6 +281,7 @@ export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promis
         frameworkDetected,
         wouldEmit,
         ...(probeError !== undefined ? { probeError } : {}),
+        ...(needsConfig !== undefined ? { needsConfig } : {}),
       };
     }
 
@@ -361,7 +391,16 @@ export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
     if (r.project?.wired) marks.push("WIRED");
     if (r.source.owned) marks.push("owned");
     if (probed && r.project?.wouldEmit !== null && r.project?.wouldEmit !== undefined) {
-      marks.push(`would emit ${r.project.wouldEmit}`);
+      const needs = r.project.needsConfig;
+      marks.push(
+        needs !== undefined && needs.length > 0
+          ? `would emit ${r.project.wouldEmit} once ${needs.join(", ")} is set`
+          : `would emit ${r.project.wouldEmit}`,
+      );
+    } else if (probed && r.project?.probeError !== undefined) {
+      // Say that the probe could not count it, not nothing: a missing count read as
+      // "emits nothing" beside a sibling that showed one.
+      marks.push("probe failed — see --format json");
     }
     const suffix = marks.length > 0 ? `  [${marks.join(", ")}]` : "";
     lines.push(`  ${r.name.padEnd(width)}  —  ${r.description}${suffix}`);

package/src/lib/config.ts

@@ -82,6 +82,20 @@ async function tryLoadConfig(metaRoot: string): Promise<Config | undefined> {
 // Public resolvers
 // ---------------------------------------------------------------------------
 
+/**
+ * The migrations directory and dialect `meta migrate` would use with no flags — what
+ * `meta gen` needs to word its "now migrate" next step and find the committed snapshot.
+ */
+export async function resolveMigrateDefaults(
+  metaRoot: string,
+): Promise<{ outDir: string; dialect: Dialect | undefined }> {
+  const config = await tryLoadConfig(metaRoot);
+  return {
+    outDir: config?.migrate?.outDir ?? MIGRATE_DEFAULTS.outDir,
+    dialect: config?.migrate?.dialect ?? MIGRATE_DEFAULTS.dialect,
+  };
+}
+
 export function resolveGenConfig(flags: GenFlags): ResolvedGenConfig {
   return { dryRun: flags.dryRun, entities: flags.entities };
 }

package/src/lib/gen-migrate-advice.ts

@@ -0,0 +1,129 @@
+// The "now migrate" next step `meta gen` prints — WHEN a schema change is plausible,
+// and in the project's own dialect.
+//
+// It used to be one hardcoded line on every run that wrote a file:
+// `meta migrate --from-db --db <url> --dialect <sqlite|postgres> --slug init --apply`.
+// That was wrong twice over for a D1 project (whose migrate takes `--dialect d1 --d1
+// <binding>` and applies through wrangler), and it was noise after any change that
+// cannot reach the database — a value object or a prompt payload has no table.
+//
+// The decision, most precise evidence first:
+//   1. No table-backed object in the model → no advice (nothing to migrate, ever).
+//   2. Nothing written this run → no advice.
+//   3. A committed schema snapshot exists → advise exactly when the expected schema's
+//      TABLES differ from it (the same diff `meta migrate` runs offline).
+//   4. No snapshot (a D1 project, or before the first migrate) → advise when a file
+//      generated for a table-backed object, or the shared enums module (enum members
+//      are CHECK constraints), changed this run. Files of value objects, prompts and
+//      other sourceless declarations do not count.
+import { existsSync } from "node:fs";
+import { basename, resolve as resolvePath } from "node:path";
+import type { MetaRoot } from "@metaobjectsdev/metadata";
+import {
+  buildExpectedSchemaWithProvenance,
+  diff,
+  findWranglerConfig,
+  parseWranglerConfig,
+  readSnapshot,
+  snapshotPath,
+  type Change,
+  type D1Binding,
+} from "@metaobjectsdev/migrate-ts";
+
+/** The FQN separator; an object's short name is the segment after the last one. */
+const FQN_SEPARATOR = "::";
+/** The shared enums module `entityFile()` emits (its members back CHECK constraints). */
+const SHARED_ENUMS_BASENAME = "enums.ts";
+
+const VIEW_CHANGE_KINDS: ReadonlySet<Change["kind"]> = new Set(["create-view", "drop-view", "replace-view"]);
+
+export interface GenMigrateAdviceInput {
+  metadata: MetaRoot;
+  /** `metaobjects.config.ts` `dialect` — undefined when no DB code is generated. */
+  dialect: "sqlite" | "postgres" | undefined;
+  /** `.metaobjects/config.json` `migrate.dialect`, when set (may say `d1`). */
+  migrateDialect: "sqlite" | "postgres" | "d1" | undefined;
+  columnNamingStrategy: "snake_case" | "literal" | "kebab-case" | undefined;
+  projectRoot: string;
+  /** The migrations directory `meta migrate` uses (holds the committed snapshot). */
+  migrateOutDir: string;
+  /** Paths (any form) of the files this run wrote, merged or removed. */
+  changedFiles: readonly string[];
+}
+
+/** The next-step line, or undefined when this run cannot have changed the schema. */
+export async function genMigrateAdvice(input: GenMigrateAdviceInput): Promise<string | undefined> {
+  if (input.dialect === undefined || input.changedFiles.length === 0) return undefined;
+
+  const d1 = d1BindingFor(input);
+  const schemaDialect = d1 !== undefined ? "d1" : input.dialect;
+  let built;
+  try {
+    built = buildExpectedSchemaWithProvenance(input.metadata, {
+      dialect: schemaDialect,
+      ...(input.columnNamingStrategy !== undefined ? { columnNamingStrategy: input.columnNamingStrategy } : {}),
+    });
+  } catch {
+    // A model `meta migrate` would refuse (it says why); gen is not the place to report it.
+    return undefined;
+  }
+  const expected = { tables: built.snapshot.tables, views: [] };
+  if (expected.tables.length === 0) return undefined;
+
+  const snapPath = snapshotPath(resolvePath(input.projectRoot, input.migrateOutDir), schemaDialect);
+  const snapshot = existsSync(snapPath) ? await readSnapshot(snapPath) : null;
+  if (snapshot !== null) {
+    const actual = { ...snapshot, views: [] };
+    try {
+      const d = await diff({ expected, actual, dialect: schemaDialect });
+      if (d.changes.every((c) => VIEW_CHANGE_KINDS.has(c.kind))) return undefined;
+    } catch {
+      // A diff the engine refuses (a primary-key move, say) is still a schema change.
+    }
+  } else if (!touchesTableBackedObject(input.changedFiles, built.provenance)) {
+    return undefined;
+  }
+
+  if (d1 !== undefined) {
+    const db = d1.database_name.length > 0 ? d1.database_name : "<database>";
+    return `write the schema change as a D1 migration with \`meta migrate --dialect d1 --d1 ${d1.binding} ` +
+      `--slug <name>\`, then apply it with \`wrangler d1 migrations apply ${db} --local\``;
+  }
+  return snapshot === null
+    ? `create your database tables with \`meta migrate --from-db --db <url> --dialect ${input.dialect} --slug init --apply\``
+    : `migrate the schema change with \`meta migrate --db <url> --dialect ${input.dialect} --slug <name> --apply\``;
+}
+
+/** The project's D1 binding when it migrates through D1, else undefined. */
+function d1BindingFor(input: GenMigrateAdviceInput): D1Binding | undefined {
+  if (input.dialect !== "sqlite" && input.migrateDialect !== "d1") return undefined;
+  const path = findWranglerConfig(input.projectRoot);
+  if (path === undefined) return undefined;
+  try {
+    return parseWranglerConfig(path).d1Bindings[0];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether a changed file was generated for a table-backed object: its basename starts
+ * with that object's short name followed by a `.` (`Pet.ts`, `Pet.queries.ts`), or it
+ * is the shared enums module.
+ */
+function touchesTableBackedObject(
+  changedFiles: readonly string[],
+  provenance: ReadonlyMap<string, string>,
+): boolean {
+  const shortName = (fqn: string): string => {
+    const at = fqn.lastIndexOf(FQN_SEPARATOR);
+    return at === -1 ? fqn : fqn.slice(at + FQN_SEPARATOR.length);
+  };
+  const names = new Set([...provenance.values()].map(shortName));
+  return changedFiles.some((f) => {
+    const base = basename(f);
+    if (base === SHARED_ENUMS_BASENAME) return true;
+    const dot = base.indexOf(".");
+    return dot > 0 && names.has(base.slice(0, dot));
+  });
+}

package/src/lib/install-set.ts

@@ -108,7 +108,13 @@ function specs(from: Map<string, string | undefined>): string[] {
  * `@metaobjectsdev/codegen-ts-tanstack` ONCE, and an adopter handed the same package
  * twice reasonably wonders which one to run.
  */
-export function installSetFor(entries: readonly GeneratorRegistryEntry[]): InstallSet {
+export function installSetFor(
+  entries: readonly GeneratorRegistryEntry[],
+  /** `@metaobjectsdev/*` packages an ejected generator FILE imports at gen time (the
+   *  catalog does not know them). Build-time, so dev — unless the runtime set already
+   *  installs the package, which satisfies the build too. */
+  templatePackages: readonly string[] = [],
+): InstallSet {
   const version = cliVersion();
   const dev = new Map<string, string | undefined>();
   const runtime = new Map<string, string | undefined>();
@@ -131,6 +137,10 @@ export function installSetFor(entries: readonly GeneratorRegistryEntry[]): Insta
     }
   }
 
+  for (const p of templatePackages) {
+    if (!runtime.has(p)) addPackage(dev, p, `^${version}`);
+  }
+
   const devList = specs(dev);
   const runtimeList = specs(runtime);
   const parts: string[] = [];

package/src/lib/output.ts

@@ -70,6 +70,11 @@ export interface GenResultShape {
    * already correct. The output's own first line (`gen: []`) already knew.
    */
   generatorCount: number;
+  /**
+   * The "now migrate" next step, worded for this project's dialect — or absent when
+   * this run cannot have changed the database schema (see gen-migrate-advice.ts).
+   */
+  migrateAdvice?: string;
 }
 
 const GEN_GLYPHS: Record<GenFileStatus, string> = {
@@ -283,7 +288,7 @@ export function genResultToData(result: GenResultShape): {
       ? "no generators are wired in metaobjects.config.ts, so nothing was generated"
       : `no entities to generate in ${result.outDir}`;
   const help = result.files.length !== 0
-    ? ["typecheck the generated code with `npx tsc`", "create your database tables with `meta migrate --from-db --db <url> --dialect <sqlite|postgres> --slug init --apply`"]
+    ? ["typecheck the generated code with `npx tsc`", ...(result.migrateAdvice !== undefined ? [result.migrateAdvice] : [])]
     : noGenerators
       ? ["add generators to the `generators: []` array in metaobjects.config.ts — `meta eject --list` names every generator you can own, and `meta init` scaffolds the usual set"]
       : ["author entities in this project's metadata sources then re-run `meta gen`"];

package/src/lib/referential-action-advisory.ts

@@ -0,0 +1,58 @@
+// Two relationships over one foreign key that disagree on its referential action.
+//
+// A 1:N may be declared on either side — the parent (`Author` composition `books`) or the
+// FK-owning child (`Book` association `author`) — and each side's subtype implies an
+// ON DELETE default (composition → cascade, association → restrict). When BOTH are
+// declared and disagree, the documented precedence (ADR-0047) lets the FK-owning side
+// govern, so the parent's relationship has no effect on the constraint. That is a
+// defensible rule and a silent one: an adopter declared a composition, read "cascade" in
+// the docs, and got ON DELETE RESTRICT and a 409 with nothing saying why.
+//
+// Advisory, never a gate: changing the precedence would change the DDL of every model
+// that relies on it. This names each such key, the action that governs, and the two
+// one-line ways to say which one the author means. Read off the SAME walk that emits the
+// FK (`buildExpectedSchema`'s `onReferentialActionConflict`), so it can only ever name a
+// constraint migrate actually writes. `meta verify` lists them; `meta migrate` warns.
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+import {
+  buildExpectedSchema,
+  describeReferentialActionConflict,
+  type ReferentialActionConflict,
+} from "@metaobjectsdev/migrate-ts";
+
+export interface ReferentialActionConflictFinding {
+  /** The metadata file declaring the FK-owning entity ("" when the loader recorded none). */
+  file: string;
+  /** `<entity FQN>.<reference name>` — the FK, which is where the fix is declared. */
+  construct: string;
+  message: string;
+}
+
+export interface ReferentialActionConflictOptions {
+  /** Skip an entity by FQN — imported (dependency) metadata is not the adopter's to fix. */
+  skip?: (fqn: string) => boolean;
+}
+
+export function scanForReferentialActionConflicts(
+  root: MetaData,
+  opts: ReferentialActionConflictOptions = {},
+): ReferentialActionConflictFinding[] {
+  const conflicts: ReferentialActionConflict[] = [];
+  buildExpectedSchema(root, { onReferentialActionConflict: (c) => conflicts.push(c) });
+
+  const out: ReferentialActionConflictFinding[] = [];
+  const seen = new Set<string>();
+  for (const c of conflicts) {
+    const fqn = c.entity.resolutionKey();
+    if (opts.skip?.(fqn) === true) continue;
+    const construct = `${fqn}.${c.ref.name}`;
+    if (seen.has(construct)) continue;
+    seen.add(construct);
+    const files = "files" in c.entity.source ? c.entity.source.files : [];
+    // A node a shipped library contributed is the library's design, not the adopter's.
+    if (files.some((f) => f.startsWith("library:"))) continue;
+    out.push({ file: files[0] ?? "", construct, message: describeReferentialActionConflict(c) });
+  }
+  return out;
+}