@metaobjectsdev/cli 1.0.0-rc.5 → 1.0.0-rc.7

package/src/lib/load-metaobjects-config.ts

@@ -141,10 +141,14 @@ function resolveCliPkg(specifier: string): string {
  * the supported home of the generators with no ownable copy), so nothing upstream of here
  * can tell a correct import from a removed one.
  *
- * It reads the config SOURCE rather than catching the throw because the throw happens inside
- * a generator factory call with no reference back to the import that produced it, and only a
- * config declaring one of these in `generators: [...]` throws at all — a stale type-only
- * import would fail silently at typecheck-time instead.
+ * It reads the config SOURCE because that is the arm that can name the FILE and the exact
+ * import. `removedGeneratorRuntimeError` below is the second arm, and an adopter estate is
+ * why there are two: the import does not have to be in the config. This project's config
+ * imported an OWNED generator — `./codegen/generators/entityFileTyped`, the shape `meta
+ * eject` itself produces — and THAT file carried the stale
+ * `import { entityFile } from "@metaobjectsdev/codegen-ts/generators"`. The source scan saw
+ * a clean config and the adopter got exactly the bare TypeError this check exists to
+ * prevent: `(0 , _generators.entityFile) is not a function`, exit 2, no file, no remedy.
  */
 const REMOVED_GENERATOR_EXPORTS = ["entityFile", "queriesFile", "routesFile", "barrel"] as const;
 const GENERATORS_SUBPATH = "@metaobjectsdev/codegen-ts/generators";
@@ -180,6 +184,39 @@ export function removedGeneratorImportError(source: string): string | undefined
   );
 }
 
+/**
+ * The same diagnostic, recovered from the THROW instead of the source — for the case the
+ * source scan structurally cannot see: a removed export imported by a module the config
+ * imports, rather than by the config itself.
+ *
+ * It cannot name the file (the TypeError carries no reference back to the import that
+ * produced it — that limitation is real, it is just not a reason to say nothing), so it
+ * names what it does know: the symbol, the removal, and the one-command remedy. Matching is
+ * on the SYMBOL, not the message shape, because the shape is the transpiler's: Bun says
+ * `(0 , _generators.entityFile) is not a function` and Node ESM says
+ * `entityFile is not a function`.
+ */
+export function removedGeneratorRuntimeError(err: unknown): string | undefined {
+  const message = err instanceof Error ? err.message : String(err ?? "");
+  if (!/is not a function/.test(message)) return undefined;
+  const hit = REMOVED_GENERATOR_EXPORTS.find((n) => new RegExp(`\\b${n}\\b`).test(message));
+  if (hit === undefined) return undefined;
+  const template = hit.replace(/File$/, "");
+  return (
+    `${hit}() is not a function — 1.0 REMOVED it from "${GENERATORS_SUBPATH}" ` +
+    `(ADR-0034 scaffold-and-own): these generators are yours to own, so the package no ` +
+    `longer ships them as an import. Your metaobjects.config.ts does not import it, so ` +
+    `the import is in a module the config imports — most often an OWNED generator under ` +
+    `codegen/generators/, which is exactly what 'meta eject' writes.\n` +
+    `  Fix — copy it into your repo:\n    meta eject ${template}\n` +
+    `  then change that module's import to: ` +
+    `import { ${hit} } from "./codegen/generators/${template}";\n` +
+    `  The subpath itself is fine — promptRender, outputParser, routesFileHono and the ` +
+    `rest still live there.\n` +
+    `  Guide: docs/features/migrations/0.x-to-1.0.md §11`
+  );
+}
+
 function rewriteImportSpecifiers(source: string, aliasMap: Record<string, string>): string {
   let result = source;
   for (const [specifier, resolvedPath] of Object.entries(aliasMap)) {
@@ -461,7 +498,18 @@ export async function loadMetaobjectsConfig(projectRoot: string): Promise<Metaob
   const prepareStackTraceBefore = Error.prepareStackTrace;
   const stackTraceLimitBefore = Error.stackTraceLimit;
   try {
-    const raw = (await jiti.import(loadPath)) as MetaobjectsGenConfig | { default: MetaobjectsGenConfig };
+    let raw: MetaobjectsGenConfig | { default: MetaobjectsGenConfig };
+    try {
+      raw = (await jiti.import(loadPath)) as MetaobjectsGenConfig | { default: MetaobjectsGenConfig };
+    } catch (err) {
+      // The second arm of the ADR-0034 diagnostic: a removed export imported by a module the
+      // config imports rather than by the config itself. Rethrown as the migration message,
+      // because what reaches the adopter otherwise is `(0 , _generators.entityFile) is not a
+      // function` — the exact unactionable failure the source scan above exists to prevent.
+      const runtime = removedGeneratorRuntimeError(err);
+      if (runtime !== undefined) throw new Error(runtime);
+      throw err;
+    }
     // jiti's interopDefault doesn't always unwrap the default export when accessed
     // across module boundaries — explicitly unwrap if present.
     const cfg = (raw && typeof raw === "object" && "default" in raw && raw.default

package/src/lib/manifest-ignored-check.ts

@@ -18,7 +18,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { log } from "./log.js";
-import { isGitIgnored } from "./git-ignore.js";
+import { gitIgnoreSource, isGitIgnored } from "./git-ignore.js";
 
 /** Project-relative path of the manifest — the one artifact of `.gen-state/` that is
  *  meant to be committed. */
@@ -40,13 +40,28 @@ export function warnIfManifestIgnored(cwd: string): void {
   // per-user ignore file answers it just as truly as a committed .gitignore does.
   if (isGitIgnored(cwd, HASH_MANIFEST_REL, { honourGlobalExcludes: true }) !== true) return;
 
+  // WHERE the rule actually lives, asked of git rather than assumed. This used to name
+  // `.metaobjects/.gitignore` and the literal pattern `.gen-state/`, which is only one of
+  // the places the exclusion can sit: an adopter estate had it in the ROOT `.gitignore` as
+  // `.metaobjects/.gen-state/`, so following this advisory to the letter edited a file that
+  // did not hold the rule, changed nothing, and printed this same line again — the loop
+  // shape. `git check-ignore -v` knows the answer, so nothing is guessed. When git cannot
+  // say, the wording degrades to the generic form rather than asserting a location.
+  const src = gitIgnoreSource(cwd, HASH_MANIFEST_REL, { honourGlobalExcludes: true });
+  const where =
+    src !== undefined
+      ? `The rule is '${src.pattern}' at ${src.file}:${src.line} — replace it there with ` +
+        `a '/*' form plus a '!' negation for the manifest ` +
+        `(e.g. '${src.pattern.replace(/\/$/, "")}/*' and '!${src.pattern.replace(/\/$/, "")}/.hashes.json')`
+      : `Find the rule with 'git check-ignore -v ${HASH_MANIFEST_REL}' and replace it with ` +
+        `a '/*' form plus a '!' negation for the manifest`;
+
   log.warn(
     `${HASH_MANIFEST_REL} is git-ignored, so it never reaches another machine — ` +
       `on a fresh clone or CI runner 'meta gen' cannot tell your hand edits from its ` +
-      `own stale output, and will refuse to overwrite rather than guess. Fix it in ` +
-      `.metaobjects/.gitignore by replacing '.gen-state/' with '.gen-state/*' plus ` +
-      `'!.gen-state/.hashes.json' (the glob matters — git will not descend into an ` +
-      `excluded directory, so a negation under '.gen-state/' can never apply), then ` +
-      `commit the manifest. If you deliberately do not commit generated output, ignore this.`,
+      `own stale output, and will refuse to overwrite rather than guess. ${where} ` +
+      `(the glob matters — git will not descend into an excluded directory, so a negation ` +
+      `INSIDE an excluded directory can never apply), then commit the manifest. ` +
+      `If you deliberately do not commit generated output, ignore this.`,
   );
 }

package/src/lib/output.ts

@@ -31,6 +31,10 @@ export type GenFileStatus =
   | "conflict"
   | "unchanged"
   | "refused"
+  /** `--baseline=adopt`: the file's existing content became the merge base and
+   *  nothing was written. Never folded into "unchanged" — the run's product is the
+   *  manifest, and a summary that showed these as unchanged would hide it. */
+  | "adopted"
   | "removed";
 
 export interface GenFileEntry {
@@ -57,6 +61,14 @@ export interface GenResultShape {
    * structured payload carries every finding.
    */
   antiPatterns?: AdvisorySection<AdvisoryFindingRow>;
+  /**
+   * How many generators the config wired. Required, because the alternative is a
+   * message that GUESSES: with no generators wired, a run over a project with five
+   * entities emitted nothing and reported "no entities to generate … author entities
+   * in this project's metadata sources", sending the reader to edit a file that was
+   * already correct. The output's own first line (`gen: []`) already knew.
+   */
+  generatorCount: number;
 }
 
 const GEN_GLYPHS: Record<GenFileStatus, string> = {
@@ -66,6 +78,7 @@ const GEN_GLYPHS: Record<GenFileStatus, string> = {
   conflict: "✗",
   unchanged: "=",
   refused: "⚠",
+  adopted: "⊕",
   removed: "−",
 };
 
@@ -76,6 +89,7 @@ const GEN_WORDS: Record<GenFileStatus, string> = {
   conflict: "CONFLICT",
   unchanged: "UNCHANGED",
   refused: "REFUSED",
+  adopted: "ADOPTED",
   removed: "REMOVED",
 };
 
@@ -106,7 +120,7 @@ export function formatGenResult(result: GenResultShape, opts: FormatOptions): st
       acc[f.status] = (acc[f.status] ?? 0) + 1;
       return acc;
     },
-    { new: 0, overwrite: 0, merged: 0, conflict: 0, unchanged: 0, refused: 0, removed: 0 },
+    { new: 0, overwrite: 0, merged: 0, conflict: 0, unchanged: 0, refused: 0, adopted: 0, removed: 0 },
   );
   const parts: string[] = [];
   // "written" stays the sum of new + overwrite: that number was always correct and
@@ -118,6 +132,10 @@ export function formatGenResult(result: GenResultShape, opts: FormatOptions): st
   if (counts.conflict > 0) parts.push(`${counts.conflict} conflict`);
   if (counts.unchanged > 0) parts.push(`${counts.unchanged} unchanged`);
   if (counts.refused > 0) parts.push(`${counts.refused} refused`);
+  // `--baseline=adopt`: recorded as the merge base, nothing written. Counted separately
+  // from `unchanged` because the run's product is the manifest, and an adopter who cannot
+  // see how many files it now covers has no way to review what they are about to commit.
+  if (counts.adopted > 0) parts.push(`${counts.adopted} adopted`);
   if (counts.removed > 0) parts.push(`${counts.removed} removed`);
   lines.push("", `  ${parts.join(", ")}`, "");
 
@@ -220,7 +238,7 @@ export function genResultToData(result: GenResultShape): {
 } {
   const counts = result.files.reduce<Record<GenFileStatus, number>>(
     (a, f) => ((a[f.status] = (a[f.status] ?? 0) + 1), a),
-    { new: 0, overwrite: 0, merged: 0, conflict: 0, unchanged: 0, refused: 0, removed: 0 },
+    { new: 0, overwrite: 0, merged: 0, conflict: 0, unchanged: 0, refused: 0, adopted: 0, removed: 0 },
   );
   const parts: string[] = [];
   // Same split as the text formatter: `written` is new + overwrite, and the
@@ -231,13 +249,23 @@ export function genResultToData(result: GenResultShape): {
   if (counts.conflict) parts.push(`${counts.conflict} conflict`);
   if (counts.unchanged) parts.push(`${counts.unchanged} unchanged`);
   if (counts.refused) parts.push(`${counts.refused} refused`);
+  if (counts.adopted) parts.push(`${counts.adopted} adopted`);
   if (counts.removed) parts.push(`${counts.removed} removed`);
-  const summary = result.files.length === 0
-    ? `no entities to generate in ${result.outDir}`
-    : parts.join(", ");
-  const help = result.files.length === 0
-    ? ["author entities in this project's metadata sources then re-run `meta gen`"]
-    : ["typecheck the generated code with `npx tsc`", "create your database tables with `meta migrate --from-db --db <url> --dialect <sqlite|postgres> --slug init --apply`"];
+  // Two ways to emit nothing, and they send the reader to different files. Name the
+  // one that is actually true: a config wiring no generators cannot produce output
+  // however good the metadata is, and telling its author to go write entities is a
+  // false statement about a project that already has them.
+  const noGenerators = result.generatorCount === 0;
+  const summary = result.files.length !== 0
+    ? parts.join(", ")
+    : noGenerators
+      ? "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`"]
+    : 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`"];
   // An absent section is STATED, never omitted: a reader must be able to tell
   // "the scan found nothing" from "the scan never ran".
   const antiPatterns = result.antiPatterns

package/src/lib/rel-posix.ts

@@ -0,0 +1,25 @@
+// One spelling of "a path, with forward slashes".
+//
+// Six modules under lib/ carried this rule inline — `git-ignore`, `docs-drift` (twice),
+// `anti-patterns`, `base-url-advisory` and `ignored-scaffold-check` — and one of the six
+// was spelled differently: `.split("\\").join("/")` rather than `.split(sep).join("/")`.
+// On Windows those agree, because `sep` IS a backslash. On POSIX they do not: `sep` is
+// already "/" so the correct form is a no-op, while splitting on a literal backslash
+// rewrites a filename that legitimately CONTAINS one. That is the drift six copies of a
+// one-line rule invite, and it had already happened.
+//
+// Comparisons against git's output are the reason the rule exists at all: `git check-ignore`
+// and `git ls-files` speak forward slashes on every platform, so a Windows path has to be
+// normalized before it can be looked up in a set built from git's answer.
+
+import { relative, sep } from "node:path";
+
+/** A path with the platform separator replaced by "/" — a no-op on POSIX. */
+export function toPosix(p: string): string {
+  return p.split(sep).join("/");
+}
+
+/** `abs` relative to `root`, forward-slashed. */
+export function relPosix(root: string, abs: string): string {
+  return toPosix(relative(root, abs));
+}

package/src/lib/replay-remedy.ts

@@ -0,0 +1,78 @@
+import { MigrationApplyError } from "@metaobjectsdev/migrate-ts";
+
+/**
+ * What to tell someone whose committed chain will not apply to an empty database.
+ *
+ * The message this replaces prescribed ONE fix — *"fix this with a NEW migration that
+ * creates the missing object"* — and it cannot work, in any case. Migrations apply in
+ * timestamp order, so anything authored now sorts AFTER the migration that failed; the
+ * object is still missing when that file runs. Two estates found it from opposite
+ * directions and it is the same defect both times:
+ *
+ * - a chain whose FIRST migration needs a schema an out-of-band script creates (the third
+ *   migration emits `CREATE SCHEMA IF NOT EXISTS`, the first predates it). A new migration
+ *   sorts last, after the one that needs the schema.
+ * - a project where **another tool owns schema creation** — drizzle-kit's chain builds the
+ *   tables, `.metaobjects/migrations/` holds later incremental patches. Following the
+ *   printed remedy literally means hand-authoring every `CREATE TABLE` into the MetaObjects
+ *   chain, i.e. duplicating a schema this project does not own, which is the opposite of
+ *   what the agent context teaches two paragraphs into its own Principles.
+ *
+ * The old message assumed MetaObjects is the only schema authority and offered no third
+ * possibility. These name the fixes that exist, and the head-of-chain case gets the extra
+ * sentence that is only true there: nothing in this chain could have created what the
+ * first migration needs, so the base schema comes from outside it.
+ *
+ * "Applied migrations are immutable" is kept, because it is true and it is the reason the
+ * obvious fix is not offered first — but it is stated as the CONDITION it actually is
+ * (a checksum guard on databases that already ran the file), not as a blanket ban, because
+ * a migration no database has applied yet is edited in place every day.
+ */
+/**
+ * Is this the migrate engine's own apply failure?
+ *
+ * By NAME, not `instanceof`. Two physical copies of `@metaobjectsdev/migrate-ts` in one
+ * process — a globally-installed or linked `meta` alongside a project-local dependency —
+ * give the class object and the instance different identities, so `instanceof` returns
+ * false for a real error and the remedy silently degrades to its un-positioned form. That
+ * is the same class-identity defect that split ts-poet's `Code` in 0.21.6 and drove the
+ * exported node guards in `metadata`. Unreachable through today's single import; costs one
+ * line to make unreachable by construction.
+ */
+function isApplyError(err: unknown): err is MigrationApplyError {
+  return err instanceof MigrationApplyError
+    || (err instanceof Error && err.name === "MigrationApplyError"
+        && typeof (err as MigrationApplyError).migration === "string"
+        && typeof (err as MigrationApplyError).index === "number");
+}
+
+export function replayRemedy(err: unknown): string[] {
+  const applyErr = isApplyError(err) ? err : undefined;
+  const head = applyErr !== undefined && applyErr.index === 0;
+  const which =
+    applyErr === undefined
+      ? "the committed chain does not apply to an empty database."
+      : `'${applyErr.migration}' (migration ${applyErr.index + 1} of ${applyErr.pendingCount}) ` +
+        `does not apply to an empty database.`;
+
+  const out = [which];
+  if (head) {
+    out.push(
+      "It is the FIRST migration in the chain, so nothing here could have created what it " +
+        "needs — this chain has never built a database from empty, and its base schema comes " +
+        "from outside it.",
+    );
+  }
+  out.push(
+    "A NEW migration cannot fix this: migrations apply in timestamp order, so anything you " +
+      "author now sorts after the file that failed.",
+  );
+  out.push(
+    "The fixes that do work: if another tool or an out-of-band script owns schema creation " +
+      "for this project, --replay asserts a property this chain does not have — don't wire " +
+      "it. Otherwise correct the migration in place if no database has applied it yet " +
+      "(the ledger's checksum guard is what stops you once one has), or re-baseline from a " +
+      "live database with `meta migrate baseline --from-db --db <url>`.",
+  );
+  return out;
+}

package/src/lib/wrangler.ts

@@ -24,8 +24,56 @@ export function buildWranglerExecuteArgs(opts: WranglerExecuteOptions): string[]
 }
 
 /**
- * Run wrangler with the given args; return stdout. Stderr is included in the
- * error message when wrangler exits non-zero. `cwd` is the directory wrangler
+ * The reason to report when wrangler exits non-zero.
+ *
+ * **`--json` puts wrangler's error on STDOUT, and warnings on stderr.** This function
+ * exists because the runner used to report stderr alone, so a live D1 gate failing for
+ * want of a `CLOUDFLARE_API_TOKEN` told the adopter its cause was
+ * `▲ [WARNING] … "unsafe" fields are experimental` — a warning, named as the reason a
+ * schema gate failed, with the real cause discarded. Found by running an estate's own
+ * `verify:prod-schema` against production for the first time.
+ *
+ * Order: the structured error wrangler wrote, then stderr, then raw stdout, then the
+ * process's own message. Stderr is still consulted — a genuine wrangler failure that
+ * never reaches stdout must not be swallowed to fix the opposite mistake.
+ */
+export function wranglerFailureReason(
+  stdout: string,
+  stderr: string,
+  fallback: string,
+): string {
+  const structured = structuredWranglerError(stdout);
+  if (structured !== undefined) return structured;
+  const err = stderr.trim();
+  if (err.length > 0) return err;
+  const out = stdout.trim();
+  if (out.length > 0) return out;
+  return fallback;
+}
+
+/** wrangler's two `--json` error shapes: `{error:{text}}` / `{error}` and the
+ *  `[{success:false,error}]` execute envelope. Anything else reads as absent. */
+function structuredWranglerError(stdout: string): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  const node = Array.isArray(parsed) ? parsed[0] : parsed;
+  if (node === null || typeof node !== "object") return undefined;
+  const { error } = node as { error?: unknown };
+  if (typeof error === "string" && error.trim().length > 0) return error.trim();
+  if (error !== null && typeof error === "object") {
+    const { text } = error as { text?: unknown };
+    if (typeof text === "string" && text.trim().length > 0) return text.trim();
+  }
+  return undefined;
+}
+
+/**
+ * Run wrangler with the given args; return stdout. The failure REASON is chosen by
+ * `wranglerFailureReason` when wrangler exits non-zero. `cwd` is the directory wrangler
  * runs in (defaults to process.cwd() — caller should pass the project root).
  */
 export type WranglerRunner = (args: string[], cwd: string) => Promise<{ stdout: string; stderr: string }>;
@@ -39,8 +87,8 @@ export const defaultWranglerRunner: WranglerRunner = async (args, cwd) => {
     if (e.code === "ENOENT") {
       throw new Error(`wrangler not found on PATH; install it: 'npm i -D wrangler'`);
     }
-    const stderr = e.stderr ?? "";
-    throw new Error(`wrangler ${args.join(" ")} failed: ${stderr || e.message}`);
+    const reason = wranglerFailureReason(e.stdout ?? "", e.stderr ?? "", e.message);
+    throw new Error(`wrangler ${args.join(" ")} failed: ${reason}`);
   }
 };