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

package/src/lib/base-url-advisory.ts

@@ -0,0 +1,173 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { relPosix } from "./rel-posix.js";
+
+/**
+ * F52 — a provider mounted with no `baseUrl` on a project whose `apiPrefix` is not empty.
+ *
+ * 1.0 moved `$apiPrefix` out of the entity descriptor: a browser's base URL is a
+ * DEPLOYMENT fact, so the provider supplies it at runtime. The migration note argues the
+ * rename is safe because `<EntityFetcherProvider value={…}>` no longer typechecks — and
+ * that is true for the adopter who leaves `value` alone. It says nothing about the
+ * adopter who reads the note, renames `value` → `fetcher`, and stops: `baseUrl` is
+ * OPTIONAL with default `""`, so that tree compiles clean and every generated hook has
+ * quietly lost its `/api` segment. Nothing at the type level can see it, and on the
+ * estate where this was found nothing else could either — `vite build` transpiles without
+ * typechecking, so `build`, 150 tests and every `meta verify` gate were green over a
+ * storefront and an admin app whose entire generated CRUD surface would have 404'd.
+ *
+ * So this is the only gate that can catch it, and it is a WARNING: `baseUrl` is genuinely
+ * optional, a project may serve its API at the origin root, and a prefix can legitimately
+ * come from somewhere this scan cannot read. It never touches an exit code.
+ *
+ * It fires ONLY when `apiPrefix` is non-empty — the `meta init` scaffold sets `""`, which
+ * is exactly why the trap is easy to ship: the default-configured project is the one the
+ * design was reasoned about.
+ */
+export interface BaseUrlFinding {
+  file: string;
+  line: number;
+  /** The provider construct found without a base. */
+  construct: string;
+  message: string;
+}
+
+const IGNORE_SEGMENTS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", ".turbo", ".output",
+  "coverage", ".metaobjects", ".wrangler",
+]);
+const SCAN_EXT = /\.(?:ts|tsx|js|jsx|mjs)$/;
+const SKIP_FILE = /(?:\.d\.ts$|\.test\.|\.spec\.)/;
+
+/**
+ * The two ways a base is supplied, one per client tier.
+ *
+ * Matched across the WHOLE opening construct rather than a single line, because a JSX
+ * provider is nearly always written multi-line — a per-line rule (which is what the
+ * anti-pattern scan uses) would miss the formatting every real codebase has.
+ */
+const PROVIDERS: readonly { construct: string; open: RegExp; kind: "jsx" | "call" }[] = [
+  { construct: "<EntityFetcherProvider>", open: /<EntityFetcherProvider\b/g, kind: "jsx" },
+  { construct: "provideEntityFetcher()", open: /provideEntityFetcher\s*\(/g, kind: "call" },
+];
+
+/**
+ * The text of the opening construct that begins at `start`.
+ *
+ * JSX: up to the `>` that closes the opening TAG. Call this a one-file tokenizer rather
+ * than a bracket count, because a bracket count is what the first version was and it was
+ * wrong in both directions:
+ *
+ *   <EntityFetcherProvider title="a > b" fetcher={f} baseUrl="/api">
+ *       → the `>` inside the STRING ended the tag before `baseUrl`, warning about a
+ *         correct provider.
+ *   <EntityFetcherProvider fetcher={mk(")")}>
+ *       → the unbalanced `)` inside a string meant depth never returned to 0, so the
+ *         4000-char cap swallowed an unrelated `baseUrl` later in the file and SUPPRESSED
+ *         a real finding.
+ *
+ * So string literals (all three quote styles, with escapes), line comments and block
+ * comments are skipped rather than counted. A regex literal is deliberately NOT handled —
+ * telling `/` division from a regex needs real parsing, and a regex inside a JSX opening
+ * tag is vanishingly rare next to the cost of getting it wrong.
+ *
+ * Call: to the `)` balancing the argument list, so a nested object or arrow does not end
+ * it early.
+ *
+ * Both bail after a generous cap rather than scanning a whole minified file when a
+ * construct is unterminated.
+ */
+function constructText(src: string, start: number, kind: "jsx" | "call"): string {
+  const limit = Math.min(src.length, start + 4000);
+  let depth = 0;
+  for (let i = start; i < limit; i++) {
+    const c = src[i]!;
+
+    // --- skip what is not code -------------------------------------------------
+    if (c === '"' || c === "'" || c === "`") {
+      i++;
+      while (i < limit && src[i] !== c) { if (src[i] === "\\") i++; i++; }
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "/") {
+      while (i < limit && src[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "*") {
+      i += 2;
+      while (i < limit && !(src[i] === "*" && src[i + 1] === "/")) i++;
+      i++;
+      continue;
+    }
+
+    // --- code ------------------------------------------------------------------
+    if (kind === "jsx" && c === ">" && depth === 0) return src.slice(start, i + 1);
+    if (c === "{" || c === "(" || c === "[") depth++;
+    else if (c === "}" || c === ")" || c === "]") {
+      if (kind === "call" && depth === 1 && c === ")") return src.slice(start, i + 1);
+      depth--;
+    }
+  }
+  return src.slice(start, limit);
+}
+
+function scanFile(rel: string, src: string, apiPrefix: string): BaseUrlFinding[] {
+  const out: BaseUrlFinding[] = [];
+  for (const { construct, open, kind } of PROVIDERS) {
+    open.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = open.exec(src)) !== null) {
+      const text = constructText(src, m.index, kind);
+      if (/\bbaseUrl\b/.test(text)) continue;
+      const line = src.slice(0, m.index).split("\n").length;
+      out.push({
+        file: rel, line, construct,
+        message:
+          `${rel}:${line} — ${construct} is mounted with no baseUrl, but this project's ` +
+          `apiPrefix is "${apiPrefix}". Every generated hook fetches a path RELATIVE to ` +
+          `baseUrl, which defaults to "", so those requests go to the origin root and miss ` +
+          `"${apiPrefix}". Pass baseUrl (a literal, or your build's env var). If the API ` +
+          `really is served at the root here, this is a false positive — ignore it.`,
+      });
+    }
+  }
+  return out;
+}
+
+function walk(dir: string, root: string, acc: BaseUrlFinding[], apiPrefix: string): void {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (IGNORE_SEGMENTS.has(e.name)) continue;
+    const abs = join(dir, e.name);
+    // Symlinked directories are NOT followed — same as the anti-pattern scan beside it.
+    //
+    // The first version did follow them, with a comment claiming it "never re-enters
+    // one". There was no visited set, so `src/loop -> <root>` produced 41 findings for a
+    // single file (`src/loop/src/loop/…`), terminating only because Linux's 40-symlink
+    // ELOOP limit made readdirSync throw into the catch below. It also meant a link
+    // pointing outside the project — a monorepo sibling, a linked package — got walked on
+    // every `meta verify`. A provider reachable only through a symlink is reachable
+    // through its real path too, so following them buys nothing and the duplicates
+    // inflate the count the header prints.
+    if (e.isDirectory()) { walk(abs, root, acc, apiPrefix); continue; }
+    if (!SCAN_EXT.test(e.name) || SKIP_FILE.test(e.name)) continue;
+    let src: string;
+    try { src = readFileSync(abs, "utf8"); } catch { continue; }
+    if (!src.includes("EntityFetcher")) continue;
+    acc.push(...scanFile(relPosix(root, abs), src, apiPrefix));
+  }
+}
+
+/**
+ * Scan a project tree for providers mounted without a base.
+ *
+ * Returns [] when `apiPrefix` is empty — there is nothing to lose then, and warning would
+ * fire on every scaffolded project.
+ */
+export function scanForMissingBaseUrl(root: string, apiPrefix: string): BaseUrlFinding[] {
+  if (apiPrefix === "") return [];
+  const acc: BaseUrlFinding[] = [];
+  walk(root, root, acc, apiPrefix);
+  return acc;
+}

package/src/lib/codegen-drift.ts

@@ -44,6 +44,7 @@ import {
   contentHash,
   readGeneratedHash,
   listGeneratedPaths,
+  NAMES_FILE_SUFFIX,
 } from "@metaobjectsdev/codegen-ts";
 import type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 import type { MetaData } from "@metaobjectsdev/metadata";
@@ -59,6 +60,14 @@ export interface CodegenDriftResult {
   driftedFiles: string[];
   /** Human-readable, one-line-per-file drift summary. */
   lines: string[];
+  /**
+   * The subset of `driftedFiles` convicted for being a HAND-EDITED names artifact,
+   * sorted. Reported rather than left to the caller to re-derive, because the remedy
+   * differs in kind: `meta gen` MERGES a hand edit and exits 0, so prescribing it for
+   * one of these is an unbreakable loop — the same loop the hand-edit exemption exists
+   * to end. Two doors asking one question must not answer it twice.
+   */
+  handEditedNames: string[];
   /** Set when the gate could not run (e.g. no outDir to compare against). */
   error?: string;
 }
@@ -128,6 +137,7 @@ export async function computeCodegenDrift(
       clean: false,
       driftedFiles: [],
       lines: [],
+      handEditedNames: [],
       error:
         "verify --codegen: no outDir configured — cannot locate the committed " +
         "generated output to diff against. Set 'outDir' (and/or per-target " +
@@ -196,6 +206,7 @@ export async function computeCodegenDrift(
     // Diff each committed outDir against its temp mirror.
     const driftedFiles = new Set<string>();
     const lines: string[] = [];
+    const handEditedNames = new Set<string>();
 
     // Whether we have any record of what we wrote here. With records, the orphan
     // branch below can scope itself to our own output; with none, it cannot tell
@@ -232,21 +243,53 @@ export async function computeCodegenDrift(
         } else {
           const a = readFileSync(join(committed, rel), "utf8");
           const b = readFileSync(join(fresh, rel), "utf8");
-          // Not `a !== b` alone: that convicts the hand edit `meta gen` preserved.
-          // The question this gate can honestly answer is "is the GENERATED
-          // contribution current?", and the recorded hash answers exactly it.
-          // FAILS CLOSED, matching `isPristineGenerated`: with no recorded hash
-          // nothing is proven, so the old byte verdict stands.
-          if (a !== b && readGeneratedHash(projectGenStateDir, relKey) !== contentHash(b)) {
-            driftedFiles.add(relKey);
-            lines.push(`~ ${relKey} (committed content differs from a fresh regen)`);
+          if (a !== b) {
+            // A `<Entity>Names` artifact is the ONE generated file where a hand edit is
+            // itself the defect, so the exemption below does not reach it. RULED: if you
+            // want a constant of your own, put it in a file of your own.
+            //
+            // The exemption exists because `meta gen` MERGES a hand edit and reports
+            // "merged", so convicting it printed a remedy that could not work — gen
+            // merges again and the next verify fails identically. A names artifact is not
+            // that shape. It is a module of physical database names, every value a string:
+            // no compiler can see a wrong one, no test reads it, and the whole point of
+            // the artifact is that a name is spelled ONCE per run and referenced. So an
+            // edited one silently renames a column for every consumer of it, while the
+            // gate reports "generated output is in sync with the metadata" — the exact
+            // failure the artifact was added to prevent, committed inside the artifact.
+            //
+            // Keyed on the suffix the emitter and the reference template both spell from
+            // one constant. An adopter who owns the generator and RENAMES the artifact
+            // opts out of this — stated rather than hidden; the gate cannot recognise a
+            // file shape it was never told about.
+            if (rel.endsWith(NAMES_FILE_SUFFIX)) {
+              driftedFiles.add(relKey);
+              handEditedNames.add(relKey);
+              lines.push(
+                `~ ${relKey} (hand-edited; a names artifact must match a fresh regen exactly — ` +
+                  `put constants of your own in a file of your own)`,
+              );
+            } else if (readGeneratedHash(projectGenStateDir, relKey) !== contentHash(b)) {
+              // Not `a !== b` alone: that convicts the hand edit `meta gen` preserved.
+              // The question this gate can honestly answer is "is the GENERATED
+              // contribution current?", and the recorded hash answers exactly it.
+              // FAILS CLOSED, matching `isPristineGenerated`: with no recorded hash
+              // nothing is proven, so the old byte verdict stands.
+              driftedFiles.add(relKey);
+              lines.push(`~ ${relKey} (committed content differs from a fresh regen)`);
+            }
           }
         }
       }
     }
 
     const sorted = [...driftedFiles].sort();
-    return { clean: sorted.length === 0, driftedFiles: sorted, lines };
+    return {
+      clean: sorted.length === 0,
+      driftedFiles: sorted,
+      lines,
+      handEditedNames: [...handEditedNames].sort(),
+    };
   } finally {
     rmSync(tempRoot, { recursive: true, force: true });
   }

package/src/lib/detect-stack.ts

@@ -48,14 +48,85 @@ async function probe(cwd: string): Promise<ProjectProbe> {
   };
 }
 
+/**
+ * Spellings accepted for a stack value that is not the canonical one.
+ *
+ * `node` is here because the CLI's OWN `--help` gives it as an example of `--server`, and it
+ * is the more natural word for a Fastify backend run by the Node CLI. It used to be filtered
+ * out silently — see `assertKnownStackValues` for what that silence cost.
+ */
+const SERVER_ALIASES: Readonly<Record<string, ServerLang>> = {
+  node: "typescript",
+  nodejs: "typescript",
+  ts: "typescript",
+  "c#": "csharp",
+  dotnet: "csharp",
+  py: "python",
+};
+
+const CLIENT_ALIASES: Readonly<Record<string, ClientFramework>> = {
+  reactjs: "react",
+  "react-query": "tanstack",
+};
+
+/** Canonicalize one value, or `undefined` when it names nothing we know. */
+function canonical<T extends string>(
+  raw: string,
+  valid: readonly string[],
+  aliases: Readonly<Record<string, T>>,
+): T | undefined {
+  const v = raw.trim().toLowerCase();
+  if (valid.includes(v)) return v as T;
+  return aliases[v];
+}
+
+/**
+ * Refuse an unknown `--server` / `--client` value instead of dropping it.
+ *
+ * `--server node` — the CLI's own help example — used to exit 0 with no warning and record
+ * `"servers": []`. Worse than the missing four reference fragments: a non-empty override
+ * array suppresses BOTH the prior manifest's stack and detection, so the emitted context then
+ * declared "Stack: no server, no client" and told the agent that this project has no
+ * `metaobjects.config.ts` — about a project with a Fastify server, a React client, and the
+ * very config file the same CLI had just read. One silently-dropped flag value made three
+ * statements false in the artifact whose whole job is to orient an agent correctly.
+ *
+ * Either accept the value or say so; never neither.
+ */
+export function assertKnownStackValues(overrides: { servers: string[]; clients: string[] }): void {
+  const bad: string[] = [];
+  for (const s of overrides.servers) {
+    if (canonical(s, SERVER_LANGS as readonly string[], SERVER_ALIASES) === undefined) {
+      bad.push(`--server ${s} (known: ${SERVER_LANGS.join(", ")})`);
+    }
+  }
+  for (const c of overrides.clients) {
+    if (canonical(c, CLIENT_FRAMEWORKS as readonly string[], CLIENT_ALIASES) === undefined) {
+      bad.push(`--client ${c} (known: ${CLIENT_FRAMEWORKS.join(", ")})`);
+    }
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      `unknown stack value(s): ${bad.join("; ")}. A value that names nothing is refused rather ` +
+        "than dropped: an empty stack suppresses both the prior manifest and detection, and the " +
+        "generated agent context then states the project has no server, no client and no " +
+        "metaobjects.config.ts.",
+    );
+  }
+}
+
 /** Resolve the stack: explicit --server/--client overrides take precedence; otherwise detect.
  * Concern tokens (e.g. requirements) are always OBSERVED from project state, independent of
  * any --server/--client override — a concern is not a stack axis. */
 export async function resolveStack(cwd: string, overrides: { servers: string[]; clients: string[] }): Promise<Stack> {
   const validServers = SERVER_LANGS as readonly string[];
   const validClients = CLIENT_FRAMEWORKS as readonly string[];
-  const oServers = overrides.servers.filter((s): s is ServerLang => validServers.includes(s));
-  const oClients = overrides.clients.filter((c): c is ClientFramework => validClients.includes(c));
+  const oServers = overrides.servers
+    .map((s) => canonical<ServerLang>(s, validServers, SERVER_ALIASES))
+    .filter((s): s is ServerLang => s !== undefined);
+  const oClients = overrides.clients
+    .map((c) => canonical<ClientFramework>(c, validClients, CLIENT_ALIASES))
+    .filter((c): c is ClientFramework => c !== undefined);
   const p = await probe(cwd);
   const concerns = detectConcerns(p);
   if (oServers.length > 0 || oClients.length > 0) return makeStack(oServers, oClients, concerns);

package/src/lib/docs-drift.ts

@@ -19,9 +19,11 @@
 //      `.gen-state/.hashes.json` to tell a preserved hand edit from stale output; here
 //      there is no such offer to honour.
 //
-//   2. IT REPORTS A FILE AS EXTRA ONLY WHERE IT OWNS THE DIRECTORY. `docs.outDir`
-//      defaults to `./docs`, which in a real repository is full of hand-written
-//      documentation — this repository's own `docs/` holds a hundred such files. Its
+//   2. IT REPORTS A FILE AS EXTRA ONLY WHERE IT OWNS THE DIRECTORY. `docs.outDir` is a
+//      directory an adopter chooses, and it may well be one full of hand-written
+//      documentation — this repository's own `docs/` holds a hundred such files. (The
+//      default moved to `./docs/generated` for exactly that reason: defaulting into the
+//      most-owned directory name in the ecosystem contradicted this paragraph.) Its
 //      `api/` subtree is not ours either: on a multi-port project those pages are written
 //      by the OTHER port's docs command (`mvn metaobjects:docs`, `metaobjects docs`,
 //      `dotnet meta docs`), which this gate never runs, so a fresh run here legitimately
@@ -47,9 +49,10 @@
 
 import { mkdtempSync, rmSync, existsSync, readFileSync, readdirSync, lstatSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, relative, resolve, isAbsolute, sep } from "node:path";
+import { join, relative, resolve, isAbsolute } from "node:path";
 import { docsCommand } from "../commands/docs.js";
 import { gitIgnored } from "./git-ignore.js";
+import { toPosix } from "./rel-posix.js";
 
 export interface DocsDriftResult {
   /** True when every page a fresh `meta docs` would write is committed and identical. */
@@ -123,7 +126,7 @@ const GENERATED_MARKER = "@generated";
  * hand-written note inside `agent/` out of it.
  */
 function isOurs(docsDir: string, rel: string): boolean {
-  const normalized = rel.split(sep).join("/");
+  const normalized = toPosix(rel);
   if (!OWNED_PREFIXES.some((p) => normalized.startsWith(p))) return false;
   try {
     return readFileSync(join(docsDir, rel), "utf8")
@@ -237,11 +240,18 @@ export async function computeDocsDrift(args: ComputeDocsDriftArgs): Promise<Docs
       "ignored" in ignoreLookup ? ignoreLookup.ignored : new Set<string>();
     const ignoreReason: string | undefined =
       "unavailable" in ignoreLookup ? ignoreLookup.unavailable : undefined;
-    const isIgnored = (rel: string): boolean => ignored.has(rel.split(sep).join("/"));
+    const isIgnored = (rel: string): boolean => ignored.has(toPosix(rel));
 
     const toCheck = fresh.filter((rel) => !isIgnored(rel));
     const orphans = ownedOrphans.filter((rel) => !isIgnored(rel));
-    const ignoredCount = fresh.length - toCheck.length;
+    // BOTH halves. `ignoreCandidates` above tests fresh pages AND owned orphans, so an
+    // ignored orphan is dropped from the check exactly like an ignored fresh page — but
+    // counting only the fresh half reported a number SMALLER than the work actually
+    // skipped. That is the `verify --templates` denominator mistake in miniature (a line
+    // describing work the command did not do), which is the very thing the orphan loop
+    // below is written to avoid; the two must be consistent about the same set.
+    const ignoredCount =
+      fresh.length - toCheck.length + (ownedOrphans.length - orphans.length);
 
     // A gate asked to check pages that could check NONE must not answer "no drift".
     if (toCheck.length === 0 && orphans.length === 0) {

package/src/lib/git-ignore.ts

@@ -16,7 +16,7 @@
 // where those files are present and on a CI runner where they are not.
 
 import { spawnSync } from "node:child_process";
-import { sep } from "node:path";
+import { toPosix } from "./rel-posix.js";
 
 /** Ignored paths, or the reason the question could not be asked. */
 export type GitIgnoreResult =
@@ -69,7 +69,7 @@ export function gitIgnored(
 
   // Forward slashes: git speaks them on every platform, and `listFiles` hands us
   // platform separators.
-  const input = rels.map((r) => r.split(sep).join("/")).join("\0");
+  const input = rels.map(toPosix).join("\0");
 
   let res;
   try {
@@ -111,5 +111,49 @@ export function isGitIgnored(
 ): boolean | undefined {
   const res = gitIgnored(dir, [rel], opts);
   if ("unavailable" in res) return undefined;
-  return res.ignored.has(rel.split(sep).join("/"));
+  return res.ignored.has(toPosix(rel));
+}
+
+/**
+ * WHICH rule ignores `rel` — the `.gitignore` file, its line, and the pattern.
+ *
+ * Advisories that tell an adopter to fix an ignore rule have to name the rule that is
+ * actually in force, not a conventional location. The exclusion can live in ANY
+ * `.gitignore` up the tree, in `.git/info/exclude`, or in a per-user excludes file, and an
+ * advisory that assumes one of them sends the reader to edit a file that does not hold the
+ * rule — after which the same advisory prints again, unchanged. `git check-ignore -v`
+ * answers it exactly, so nothing has to be assumed.
+ *
+ * `undefined` when git cannot say or nothing matches. The verdict itself still comes from
+ * `isGitIgnored`; this is only for the message, so a failure here degrades the wording
+ * rather than the check.
+ */
+export function gitIgnoreSource(
+  dir: string,
+  rel: string,
+  opts: GitIgnoreOptions,
+): { file: string; line: string; pattern: string } | undefined {
+  const gitBin = process.env.META_GEN_GIT ?? "git";
+  const args: string[] = [];
+  if (!opts.honourGlobalExcludes) {
+    args.push("-c", `core.excludesFile=${NO_SUCH_EXCLUDES_FILE}`);
+  }
+  args.push("-C", dir, "check-ignore", "-v", "--", toPosix(rel));
+
+  let res;
+  try {
+    res = spawnSync(gitBin, args, { encoding: "utf-8" });
+  } catch {
+    return undefined;
+  }
+  if (res.error !== undefined || res.status !== 0) return undefined;
+  // `<source>:<line>:<pattern>\t<path>` — the source may itself contain a colon on
+  // Windows, so split from the RIGHT of the first tab-delimited field.
+  const first = (res.stdout ?? "").split("\n")[0];
+  if (first === undefined || first === "") return undefined;
+  const lhs = first.split("\t")[0];
+  if (lhs === undefined) return undefined;
+  const m = /^(.*):(\d+):(.*)$/.exec(lhs);
+  if (m === null) return undefined;
+  return { file: m[1]!, line: m[2]!, pattern: m[3]! };
 }

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

@@ -0,0 +1,78 @@
+// Advisory: did the scaffold land in a directory this repository ignores?
+//
+// `meta init` reports "(11 files)". Eight of them go under `.claude/skills/`, and many
+// projects git-ignore `.claude/` — commonly under a comment about credentials, which is a
+// defensible convention, not a mistake. Ignored, those files exist only on the machine that
+// ran the command: never committed, absent from CI and from a fresh clone, invisible to a
+// teammate — while `.metaobjects/.agent-context.json`, which IS committed, records every one
+// of them. The count says eleven; the repository gets three.
+//
+// The failure is INVISIBLE, which is why it is worth a check rather than a doc: nothing
+// errors, nothing looks wrong, and the whole downstream agent-context design is simply void
+// for that repo.
+//
+// Deliberately ADVISORY. Ignoring `.claude/` may be exactly what the project wants — it is a
+// per-repo policy call, and a scaffolder has no standing to fail a build over it.
+
+import { isAbsolute, relative } from "node:path";
+import { log } from "./log.js";
+import { gitIgnored } from "./git-ignore.js";
+import { toPosix } from "./rel-posix.js";
+
+/**
+ * `meta init` records what it created as paths RELATIVE TO THE PROJECT, and one of them
+ * carries a display decoration ("CLAUDE.md (created with MetaObjects @import)") because the
+ * same array is printed back to the user. Normalize both into a plain project-relative,
+ * POSIX-separated path, and drop anything outside the project.
+ *
+ * The relative case is why this exists at all: `relative(cwd, p)` resolves BOTH arguments
+ * against the ambient `process.cwd()`, so handing it an already-relative path under `--cwd`
+ * produced a "../"-prefixed result for every entry, the filter dropped them all, and the
+ * advisory returned before consulting git. It fired only when the process happened to be
+ * running in the project directory — silent on the path the check exists for.
+ */
+function toProjectRelative(cwd: string, p: string): string | undefined {
+  // Strip a trailing display decoration; handed to git verbatim it is not a path, so a
+  // repository ignoring that file was never told about it.
+  const bare = p.replace(/\s+\(.*\)$/, "");
+  const rel = toPosix(isAbsolute(bare) ? relative(cwd, bare) : bare);
+  if (rel.length === 0 || rel === ".." || rel.startsWith("../")) return undefined;
+  return rel;
+}
+
+/**
+ * Warn when some of the scaffolded paths are git-ignored, naming how many and where.
+ *
+ * Silent when: nothing is ignored, the project is not a git repository, or git cannot be
+ * consulted — "cannot say" must never be reported as "there is a problem".
+ *
+ * `honourGlobalExcludes: false` for the same reason the docs-drift gate uses it: this is a
+ * property of the REPOSITORY, and a personal `~/.gitignore` is not something a teammate
+ * shares. A warning that fires for one developer and not another is worse than none.
+ */
+export function reportIgnoredScaffold(cwd: string, created: readonly string[]): void {
+  const rels = created
+    .map((p) => toProjectRelative(cwd, p))
+    .filter((p): p is string => p !== undefined);
+  if (rels.length === 0) return;
+
+  const res = gitIgnored(cwd, rels, { honourGlobalExcludes: false });
+  if ("unavailable" in res) return;   // not a git repo, or git could not answer
+  const ignored = rels.filter((p) => res.ignored.has(p));
+  if (ignored.length === 0) return;
+
+  // Report the DIRECTORIES rather than every path: an adopter fixes this by editing one
+  // `.gitignore` line, and a wall of forty filenames buries that.
+  const dirs = [...new Set(ignored.map((p) => {
+    const i = p.indexOf("/");
+    return i < 0 ? p : p.slice(0, i) + "/";
+  }))].sort();
+
+  log.warn(
+    `${ignored.length} of ${rels.length} scaffolded file(s) are git-ignored (${dirs.join(", ")}), ` +
+      "so they exist only on this machine — not committed, absent from CI and from a fresh " +
+      "clone, invisible to a teammate — while .metaobjects/.agent-context.json is committed " +
+      "and records them. If the agent context is meant to be shared, un-ignore those paths; " +
+      "if it is deliberately local, nothing to do.",
+  );
+}

package/src/lib/load-error.ts

@@ -0,0 +1,89 @@
+import type { LoaderError } from "@metaobjectsdev/metadata";
+
+/**
+ * One rendering of a metadata LOAD failure, for every command that can hit one.
+ *
+ * The loader builds a full ADR-0009 envelope — a stable `code`, the `files` the node came
+ * from, the `jsonPath` inside the document, and often `suggestions[]` naming the next step.
+ * Five commands then printed `` `failed to load metadata: ${err.message}` `` and threw all
+ * of it away. So `ERR_ABSTRACT_SUBTYPE_AUTHORED` reached an adopter as a paragraph with no
+ * file, no line, no node name and no code — and `--format json` carried the same bare
+ * string, so a CI job could not key on the code ADR-0009 promises and the docs name. Five
+ * metadata files made that a `grep`; two hundred would not.
+ *
+ * This does not invent provenance. It reports exactly what the error carries and stays
+ * silent about what it does not, so a caller can never read more precision into the line
+ * than the loader actually had.
+ */
+export interface LoadErrorReport {
+  /** The message plus whatever provenance the envelope carried, for a human. */
+  readonly text: string;
+  /** ADR-0009 stable code, when the loader attached one. */
+  readonly code?: string;
+  /** The file(s) the failing node was read from. */
+  readonly files?: readonly string[];
+  /** JSON path of the failing node within its document. */
+  readonly jsonPath?: string;
+  /** The loader's own next steps. Printed verbatim; never paraphrased. */
+  readonly suggestions?: readonly string[];
+}
+
+/** True for a thrown value carrying the loader's ADR-0009 envelope. */
+function isLoaderError(err: unknown): err is LoaderError {
+  return (
+    typeof err === "object" && err !== null
+    && typeof (err as { code?: unknown }).code === "string"
+    && typeof (err as { source?: unknown }).source === "object"
+  );
+}
+
+export function describeLoadError(err: unknown): LoadErrorReport {
+  const message = err instanceof Error ? err.message : String(err);
+  if (!isLoaderError(err)) return { text: message };
+
+  const source = err.source as { files?: readonly string[]; jsonPath?: string };
+  const files = source.files?.filter((f) => f.length > 0);
+  const jsonPath = source.jsonPath;
+  const suggestions = err.suggestions?.filter((s) => s.length > 0);
+
+  // `code` first: it is the one part a machine keys on, and a human scanning a terminal
+  // finds it fastest at the front of the line. Then WHERE, which is the question the
+  // message itself can never answer.
+  const where = [
+    files !== undefined && files.length > 0 ? files.join(", ") : undefined,
+    jsonPath !== undefined && jsonPath.length > 0 ? `at ${jsonPath}` : undefined,
+  ].filter((p): p is string => p !== undefined).join(" ");
+
+  const head = `${err.code}: ${message}`;
+  return {
+    text: where.length > 0 ? `${head}\n  in ${where}` : head,
+    code: err.code,
+    ...(files !== undefined && files.length > 0 ? { files } : {}),
+    ...(jsonPath !== undefined && jsonPath.length > 0 ? { jsonPath } : {}),
+    ...(suggestions !== undefined && suggestions.length > 0 ? { suggestions } : {}),
+  };
+}
+
+/**
+ * Print a load failure the one way every command prints it: the described line, then the
+ * loader's own `suggestions[]` indented beneath it, verbatim.
+ *
+ * This lived as a byte-identical private copy in `docs.ts`, `gen.ts` and `migrate.ts`. It
+ * belongs beside `describeLoadError` for the same reason that function exists: the rendering
+ * of a load failure is ONE decision, and three copies of it are three places for the next
+ * improvement to reach two of. `verify.ts`'s variant is deliberately NOT this — it chooses
+ * between the loader's suggestions and its own strict-attr hint (ADR-0023), which is a
+ * different decision, not a different spelling of this one.
+ *
+ * `log` is a parameter rather than an import so a test can capture what was printed without
+ * reaching into module state.
+ */
+export function reportLoadError(
+  log: { error: (msg: string) => void },
+  prefix: string,
+  err: unknown,
+): void {
+  const report = describeLoadError(err);
+  log.error(`${prefix}: ${report.text}`);
+  for (const s of report.suggestions ?? []) log.error(`  ${s}`);
+}