@metaobjectsdev/cli 0.23.2 → 0.24.0

package/src/index.ts

@@ -2,6 +2,7 @@ import { resolve } from "node:path";
 import { log } from "./lib/log.js";
 import { cliVersion } from "./lib/version.js";
 import { resolveFormat, isValidFormat, VALID_FORMATS } from "./lib/format.js";
+import { resolveCollection } from "@metaobjectsdev/sdk";
 export { defineConfig } from "@metaobjectsdev/codegen-ts";
 export type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 
@@ -13,14 +14,16 @@ USAGE:
   meta <command> [flags]
 
 COMMANDS:
-  init                  Scaffold metaobjects/ + .metaobjects/ in the current repo
+  init                  Scaffold a MetaObjects project in the current repo
   init --refresh-docs   Refresh .metaobjects/AGENTS.md + CLAUDE.md after CLI upgrades
+  init --config-only    Write only .metaobjects/config.json — for a Maven- or pip-rooted project
   agent-docs            Scaffold only the agent-context (.metaobjects/ + .claude/skills/) — canonical redirect target for all language ports
-  gen [<entity>...]     Codegen TS targets from metaobjects/ entities
+  gen [<entity>...]     Codegen TS targets from your declared metadata
   types [query]         Search the metadata vocabulary (types, subtypes, @attrs) by name or description
   export                Flatten loaded metadata to one canonical JSON artifact
   docs <metadata> --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
   verify                Drift gate — subverbs: --templates / --db / --codegen (bare = --templates)
+  upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
   --version, -v         Print version
@@ -39,7 +42,7 @@ EXPORT FLAGS:
   --out <file>          Write output to a file (default: stdout)
 
 DOCS FLAGS:
-  <metadata>            Project root holding metaobjects/ (default: current directory)
+  <metadata>            Project root to resolve metadata from; passing it SCOPES the run (default: cwd)
   --out <dir>, -o       Output directory for the pages (default: ./docs)
   --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
   --prompts <dir>       Extra dir holding prompt .mustache sources for --site (e.g. data/templates/)
@@ -90,7 +93,7 @@ ship in later sub-projects. See https://metaobjects.com for docs.
 
 /** Focused per-subcommand usage slices shown by `<cmd> --help`. */
 const COMMAND_HELP: Record<string, string> = {
-  gen: `meta gen — codegen TS targets from metaobjects/ entities
+  gen: `meta gen — codegen TS targets from your declared metadata
 
 USAGE:
   meta gen [<entity>...] [flags]
@@ -109,7 +112,7 @@ or META_NO_ANTIPATTERNS=1.
 
 NOTE: outDir, dialect, dbImport, extStyle are read from metaobjects.config.ts
 `,
-  verify: `meta verify — drift gate (templates / DB schema / codegen)
+  verify: `meta verify — drift gate (templates / DB schema / codegen / migration replay)
 
 USAGE:
   meta verify [flags]
@@ -121,6 +124,17 @@ FLAGS:
   --db <url>            Schema drift — live DB URL enables the schema-drift gate.
                         Supports: file:, libsql:, postgres:, postgresql:
                         D1 has no URL — use --dialect d1 / --d1 <binding> instead.
+  --replay              Migration-chain drift — replay the committed chain into an
+                        EMPTY throwaway database and assert it applies. Needs no --db:
+                        the engine is in-process (PGlite for postgres, a temp file for
+                        sqlite) and provisions nothing. Dialect comes from --dialect,
+                        else migrate.dialect. flyway and d1 are refused.
+                        Postgres needs the optional peer '@electric-sql/pglite'.
+  --replay-snapshot     ...and assert the replayed schema EQUALS the committed
+                        snapshot — catches a hand-edited up.sql that still applies but
+                        no longer builds the recorded schema. Does NOT apply to a
+                        project adopted with 'migrate baseline --from-db' (its chain
+                        does not build the schema); use --replay there.
   --prompts <dir>       Directory of provider-resolved template text (default: prompts)
   --dialect sqlite|postgres|d1   Optional override (auto-detected from --db URL scheme)
   --allow <csv>         Accepted for parity with 'migrate'; does NOT affect the drift gate
@@ -152,19 +166,23 @@ USAGE:
   meta docs [<metadata>] [flags]
 
 FLAGS:
-  <metadata>            Project root holding metaobjects/ (default: current directory)
+  <metadata>            Project root to resolve metadata from. Passing it SCOPES the run to
+                        that directory's own sources; no ancestor .metaobjects/config.json is
+                        consulted. Omitted (default), the project is discovered by walking up.
   --out <dir>, -o       Output directory for the pages (default: ./docs)
   --model               Emit the markdown model surface (entity + template pages)
   --api                 Emit the markdown api surface (generated SDK reference)
+  --requirements        Emit the declared requirement ledger (requirements.md + .toon).
+                        Emits nothing when the project declares no requirement.* node.
   --metamodel           Document the built-in metamodel vocabulary (no metadata needed)
   --site                Generate the browsable HTML documentation site (<out>/site/)
   --scaffold-site       Copy the site's templates + assets into codegen/docs-site/ to own (theme) them
   --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
   --prompts <dir>       Extra dir holding prompt .mustache sources (for --site) when they
-                        live outside metaobjects/ or templates/ (e.g. data/templates/)
+                        live outside the metadata sources or templates/ (e.g. data/templates/)
   --help, -h            Print this help
 `,
-  init: `meta init — scaffold metaobjects/ + .metaobjects/ in the current repo
+  init: `meta init — scaffold a MetaObjects project in the current repo
 
 USAGE:
   meta init [flags]
@@ -176,6 +194,8 @@ FLAGS:
   --print-only          Print what would be written, don't write
   --d1                  Include D1 (Cloudflare) migration config
   --no-wire-root        Skip wiring root metaobjects.config.ts
+  --config-only         Write only .metaobjects/config.json (no TS scaffold) — declares
+                        metadata sources for the Node CLI from a Maven- or pip-rooted project
   --help, -h            Print this help
 `,
   "agent-docs": `meta agent-docs — scaffold the agent-context (.metaobjects/ always-on files + .claude/skills/)
@@ -271,12 +291,19 @@ export async function run(argv: string[]): Promise<number> {
     case undefined: {
       // Content-first no-args view: concise status + next-step help[] rather than
       // dumping the full manual (full manual is still available via `meta --help`).
-      const metaobjectsExists = await import("node:fs/promises")
-        .then(({ stat }) => stat(resolve(cwd, "metaobjects")).then(() => true).catch(() => false));
-      const statusLine = metaobjectsExists
-        ? `meta — MetaObjects CLI (v${VERSION})  ·  metaobjects/ found`
-        : `meta — MetaObjects CLI (v${VERSION})  ·  no metaobjects/ here`;
-      const nextSteps = metaobjectsExists
+      // "Is this a MetaObjects project?" routes through resolveCollection — the
+      // single authority on where metadata lives — rather than assuming the
+      // default `metaobjects/` directory name. The status line must not assert
+      // it either: a project whose config points `sources` at
+      // `../shared-model/metadata` would be told "metaobjects/ found", which is
+      // false, and one that resolves nothing would be told there is no
+      // `metaobjects/` here when the real problem may be a declared source that
+      // failed to resolve.
+      const metadataResolves = await resolveCollection(cwd).then(() => true).catch(() => false);
+      const statusLine = metadataResolves
+        ? `meta — MetaObjects CLI (v${VERSION})  ·  metadata found`
+        : `meta — MetaObjects CLI (v${VERSION})  ·  no MetaObjects project here`;
+      const nextSteps = metadataResolves
         ? [
             "  meta gen              Run codegen",
             "  meta verify           Check for drift",
@@ -284,7 +311,7 @@ export async function run(argv: string[]): Promise<number> {
             "  meta --help           Full command reference",
           ]
         : [
-            "  meta init             Scaffold metaobjects/ in this directory",
+            "  meta init             Scaffold a MetaObjects project in this directory",
             "  meta --help           Full command reference",
           ];
       log.info(`${statusLine}\n\n${nextSteps.join("\n")}\n`);
@@ -351,6 +378,10 @@ export async function run(argv: string[]): Promise<number> {
       const { verifyCommand } = await import("./commands/verify.js");
       return verifyCommand(rest, cwd);
     }
+    case "upgrade": {
+      const { upgradeCommand } = await import("./commands/upgrade.js");
+      return upgradeCommand(rest, cwd);
+    }
     case "prompt-snapshot": {
       const { promptSnapshotCommand } = await import("./commands/prompt-snapshot.js");
       return promptSnapshotCommand(rest, cwd);

package/src/lib/allow.ts

@@ -33,6 +33,10 @@ export const ALLOW_TOKEN_MAP: Record<string, keyof AllowOptions> = {
   // @generation at all — ambiguous between "never declared it" and
   // "deliberately removing auto-increment", so migrate refuses without it.
   "drop-identity-default": "dropIdentityDefault",
+  // Gates dropping an object the committed snapshot never contained (#313). Read by
+  // migrate's generation-time provenance guard, not by diff()'s status pass — see
+  // AllowOptions.dropUnmanaged for why it still belongs in that shape.
+  "drop-unmanaged": "dropUnmanaged",
 };
 
 /** Translate parsed `--allow` tokens into the migrate-ts `AllowOptions` shape. */

package/src/lib/args.ts

@@ -15,6 +15,7 @@ export interface InitFlags {
   noSkills: boolean;
   wireRoot: boolean;
   docsOnly: boolean;
+  configOnly: boolean;
 }
 
 export function parseInitArgs(argv: string[]): InitFlags {
@@ -31,6 +32,7 @@ export function parseInitArgs(argv: string[]): InitFlags {
       "no-skills": { type: "boolean", default: false },
       "no-wire-root": { type: "boolean", default: false },
       "docs-only": { type: "boolean", default: false },
+      "config-only": { type: "boolean", default: false },
     },
     strict: true,
     allowPositionals: false,
@@ -46,6 +48,7 @@ export function parseInitArgs(argv: string[]): InitFlags {
     noSkills: !!values["no-skills"],
     wireRoot: !values["no-wire-root"],
     docsOnly: !!values["docs-only"],
+    configOnly: !!values["config-only"],
   };
 }
 
@@ -197,6 +200,13 @@ export const ALLOW_TOKENS = [
   // metadata declares no @generation at all — ambiguous between "never
   // declared it" and "deliberately removing auto-increment".
   "drop-identity-default",
+  // drop-unmanaged permits dropping an object the COMMITTED SNAPSHOT never
+  // contained — i.e. one this toolchain never managed, typically a table another
+  // tool owns. Without it such a drop is refused at generation time, because the
+  // migration it writes cannot replay against a database where that object never
+  // existed (#313). Unlike its neighbours this one is enforced by `migrate` itself
+  // rather than by `diff()`'s status pass; see AllowOptions.dropUnmanaged.
+  "drop-unmanaged",
 ] as const;
 type AllowToken = (typeof ALLOW_TOKENS)[number];
 
@@ -232,7 +242,20 @@ export interface VerifyFlags {
   templates: boolean;
   /** Run the codegen-drift gate (regenerate-to-temp and diff committed output). */
   codegen: boolean;
-  /** Whether ANY explicit subverb flag (--templates/--db/--codegen) was passed. */
+  /**
+   * Replay the committed migration chain into an empty throwaway database and assert
+   * it applies (#313). Needs no `--db`: the engine is local and disposable (PGlite
+   * for postgres, a temp sqlite file), so the gate provisions nothing.
+   */
+  replay: boolean;
+  /**
+   * `--replay` plus: assert the replayed schema EQUALS the committed snapshot. A
+   * separate subverb rather than a `--strict` modifier, because `--lax` below is a
+   * different axis (ADR-0023 attribute strictness) and `--strict` beside it would
+   * read as that flag's opposite rather than as a replay depth.
+   */
+  replaySnapshot: boolean;
+  /** Whether ANY explicit subverb flag (--templates/--db/--codegen/--replay*) was passed. */
   anyExplicit: boolean;
   /** Suppress the advisory anti-pattern (verify-as-teacher) pass. */
   noAntipatterns: boolean;
@@ -255,6 +278,8 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
       "skip-schema": { type: "boolean", default: false },
       templates: { type: "boolean", default: false },
       codegen: { type: "boolean", default: false },
+      replay: { type: "boolean", default: false },
+      "replay-snapshot": { type: "boolean", default: false },
       "no-antipatterns": { type: "boolean", default: false },
       lax: { type: "boolean", default: false },
       "d1": { type: "string" },
@@ -283,11 +308,15 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
 
   const templates = !!values.templates;
   const codegen = !!values.codegen;
+  const replay = !!values.replay;
+  const replaySnapshot = !!values["replay-snapshot"];
   // --db is itself an explicit subverb selector: passing a connection URL means
   // "run the schema-drift mode". So is `--dialect d1` (D1 has no --db connection
-  // URL — see the `d1` field doc above). So "any explicit subverb" is
-  // templates|codegen|db|dialect==d1.
-  const anyExplicit = templates || codegen || values.db !== undefined || dialect === "d1";
+  // URL — see the `d1` field doc above). The replay flags are subverbs too, and
+  // must be listed here or `meta verify --replay` would ALSO run the template gate
+  // as the bare-verify default.
+  const anyExplicit =
+    templates || codegen || values.db !== undefined || dialect === "d1" || replay || replaySnapshot;
 
   return {
     prompts: values.prompts,
@@ -297,6 +326,8 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     skipSchema: !!values["skip-schema"],
     templates,
     codegen,
+    replay,
+    replaySnapshot,
     anyExplicit,
     noAntipatterns: !!values["no-antipatterns"],
     lax: !!values.lax,

package/src/lib/codegen-drift.ts

@@ -81,11 +81,19 @@ function listFiles(dir: string): string[] {
  * @param config   the loaded metaobjects config (provides outDir/targets).
  * @param metadata the loaded MetaRoot (same object `meta gen` would use).
  * @param projectRoot absolute project root (committed outDirs are keyed off it).
+ * @param scope    the SAME output-scope predicate `meta gen` used to produce the
+ *   committed output (Task 12b / design §7 open question 3). A `verify --codegen`
+ *   that regenerates unscoped while the committed output was scoped would read
+ *   every out-of-scope entity as drift — regen would try to emit it, but it was
+ *   never committed because the `meta gen` that produced the committed tree
+ *   never emitted it either. Undefined ⇒ everything is in scope (byte-identical
+ *   to a project with no `scope` declared).
  */
 export async function computeCodegenDrift(
   config: MetaobjectsGenConfig,
   metadata: MetaData,
   projectRoot: string,
+  scope?: (fqn: string) => boolean,
 ): Promise<CodegenDriftResult> {
   const root = isAbsolute(projectRoot) ? projectRoot : resolve(projectRoot);
 
@@ -157,6 +165,7 @@ export async function computeCodegenDrift(
       genStateDir: join(tempRoot, ".gen-state"),
       mergeStrategy: "overwrite",
       baseline: "fresh",
+      ...(scope !== undefined ? { scope } : {}),
     });
 
     // Diff each committed outDir against its temp mirror.

package/src/lib/detect-stack.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import type { Dirent } from "node:fs";
 import { join } from "node:path";
+import { resolveCollection } from "@metaobjectsdev/sdk";
 import {
   detectStack, detectConcerns, makeStack,
   type ServerLang, type ClientFramework, type Stack, type ProjectProbe,
@@ -21,62 +21,49 @@ function depNames(cwd: string): Set<string> {
   return out;
 }
 
-const METADATA_DIR = "metaobjects";
-const METADATA_FILE_PATTERN = /\.(json|ya?ml)$/i;
 // Cheap substring probe, not a metamodel load: matches both canonical JSON's
 // quoted `"requirement.functional"` key and sigil-free YAML's bare
 // `requirement.functional:` authoring form.
 const REQUIREMENT_NODE_MARKER = "requirement.";
 
-/** Recursively scans `metaobjects/` for any `.json`/`.yaml`/`.yml` file containing a
- * `requirement.*` node marker. Defensive throughout: a missing/unreadable directory
- * or file is treated as "not found", never thrown — this is a cheap heuristic, not
- * a metamodel load. */
-function hasRequirementNodes(cwd: string): boolean {
-  const root = join(cwd, METADATA_DIR);
-  if (!existsSync(root)) return false;
-  const pending: string[] = [root];
-  while (pending.length > 0) {
-    const dir = pending.pop()!;
-    let entries: Dirent[];
-    try {
-      entries = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue; // unreadable directory — skip it, keep scanning siblings
-    }
-    for (const entry of entries) {
-      const full = join(dir, entry.name);
-      if (entry.isDirectory()) {
-        pending.push(full);
-      } else if (METADATA_FILE_PATTERN.test(entry.name)) {
-        try {
-          if (readFileSync(full, "utf8").includes(REQUIREMENT_NODE_MARKER)) return true;
-        } catch { /* unreadable file — treat as no match */ }
-      }
+/** Scans the project's resolved metadata collection (`resolveCollection` — the
+ * single authority on where metadata lives, honouring declared `sources` rather
+ * than assuming `metaobjects/`) for any file containing a `requirement.*` node
+ * marker. Defensive throughout: no declared sources and no default directory, an
+ * unresolvable source, or an unreadable file are all treated as "not found",
+ * never thrown — this is a cheap heuristic, not a metamodel load. */
+async function hasRequirementNodes(cwd: string): Promise<boolean> {
+  try {
+    const { files } = await resolveCollection(cwd);
+    for (const file of files) {
+      if (readFileSync(file, "utf8").includes(REQUIREMENT_NODE_MARKER)) return true;
     }
+    return false;
+  } catch {
+    return false;
   }
-  return false;
 }
 
-function probe(cwd: string): ProjectProbe {
+async function probe(cwd: string): Promise<ProjectProbe> {
   const deps = depNames(cwd);
   const names = existsSync(cwd) ? readdirSync(cwd) : [];
+  const requirementNodes = await hasRequirementNodes(cwd);
   return {
     hasDep: (name) => deps.has(name),
     hasFileMatching: (re) => names.some((n) => re.test(n)),
-    hasRequirementNodes: () => hasRequirementNodes(cwd),
+    hasRequirementNodes: () => requirementNodes,
   };
 }
 
 /** 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 function resolveStack(cwd: string, overrides: { servers: string[]; clients: string[] }): Stack {
+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 p = probe(cwd);
+  const p = await probe(cwd);
   const concerns = detectConcerns(p);
   if (oServers.length > 0 || oClients.length > 0) return makeStack(oServers, oClients, concerns);
   const detected = detectStack(p);

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

@@ -1,11 +1,11 @@
 import { existsSync, readdirSync, unlinkSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 import { createJiti } from "jiti";
-import type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
+import type { MetaDataTypeProvider, MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 
 const CONFIG_FILE = "metaobjects.config.ts";
 
@@ -149,6 +149,69 @@ function rewriteImportSpecifiers(source: string, aliasMap: Record<string, string
   return result;
 }
 
+/**
+ * The `loadMemory` options a project's gen config contributes.
+ *
+ * One helper rather than a spread pair repeated at each of the eight load sites,
+ * because threading one of these and forgetting the other is exactly how #333
+ * happened: `providers` reached every command while `libraries` reached none, so a
+ * generator was registered FOR the CLI with its input unreachable THROUGH it. Adding a
+ * third contribution later should not mean finding eight call sites again.
+ *
+ * Conditional spreads honour `exactOptionalPropertyTypes` — a key is omitted rather
+ * than set to `undefined`, which is what lets `loadMemory` apply its own defaults.
+ */
+export function loadMemoryOptionsFrom(
+  cfg: Pick<MetaobjectsGenConfig, "providers" | "libraries"> | undefined,
+): { providers?: readonly MetaDataTypeProvider[]; libraries?: readonly string[] } {
+  return {
+    ...(cfg?.providers !== undefined ? { providers: cfg.providers } : {}),
+    ...(cfg?.libraries !== undefined ? { libraries: cfg.libraries } : {}),
+  };
+}
+
+/**
+ * The directory whose `metaobjects.config.ts` governs a run started in `startDir` —
+ * the nearest ancestor carrying that file, `fallback` when there is none.
+ *
+ * This is a SECOND walk, deliberately separate from `resolveCollection`'s. The two
+ * files answer different questions and design §4.6 already says so: `.metaobjects/
+ * config.json` declares where metadata comes from — port-neutral, read by all five
+ * CLIs, and reasonably repo-global in a polyglot monorepo — while
+ * `metaobjects.config.ts` declares how THIS TypeScript package generates code. Reading
+ * the second from the directory that carried the first (#326) meant a Maven- or
+ * pip-rooted repo with a JS app underneath could not run `meta gen` at all: the
+ * collection resolved to the repo root, and the app's config, sitting in the very
+ * directory the command was invoked from, was never looked at.
+ *
+ * Nearest wins, which is what keeps the opposite arm — the divergence commit
+ * 0c8fd136e fixed — closed: a run from a subdirectory that declares NO config of its
+ * own walks up to the project root's, exactly as before, rather than silently
+ * defaulting `columnNamingStrategy` and emitting a migration that renames every
+ * column. When the two files sit together, as they do in every `meta init` project,
+ * this walk and the collection walk return the same directory by construction.
+ *
+ * The `fallback` is the collection's directory, so a project with no
+ * `metaobjects.config.ts` anywhere keeps today's diagnostics unchanged: this walk can
+ * only ever move the answer CLOSER to the invocation, never further away.
+ *
+ * Boundaries mirror `discoverCollectionRoot` (sdk `discovery.ts`): the marker is
+ * checked before `.git`, so a repo-root project sharing its directory with `.git` is
+ * still reachable from any subdirectory, and the walk stops there so a monorepo can
+ * never adopt a parent checkout's codegen config.
+ */
+export function resolveGenConfigDir(startDir: string, fallback: string): string {
+  let dir = resolve(startDir);
+  for (;;) {
+    if (existsSync(join(dir, CONFIG_FILE))) return dir;
+    if (existsSync(join(dir, ".git"))) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return fallback;
+}
+
 export async function loadMetaobjectsConfig(projectRoot: string): Promise<MetaobjectsGenConfig> {
   const fullPath = resolve(projectRoot, CONFIG_FILE);
   if (!existsSync(fullPath)) {
@@ -254,6 +317,25 @@ export async function loadMetaobjectsConfig(projectRoot: string): Promise<Metaob
     if (!cfg || typeof cfg !== "object" || !Array.isArray(cfg.generators)) {
       throw new Error(`metaobjects.config.ts at ${fullPath} did not export a valid MetaobjectsGenConfig (missing 'generators' array).`);
     }
+    // An unknown `libraries` name is a hard config error naming the valid ones, while
+    // `librarySources` keeps skipping one silently for a programmatic caller. The two
+    // are deliberately different: an API caller asking for a package this version does
+    // not ship should still be able to load its own metadata, but a name a human typed
+    // into a config file is a mistake worth failing on — skipped, it resurfaces later as
+    // ERR_UNRESOLVED_SUPER pointing at the adopter's own metadata, which is the wrong
+    // place to send someone looking. Python's `project_config` draws the same line in
+    // the same place, and the two ports agreeing here is the point.
+    if (cfg.libraries !== undefined && cfg.libraries.length > 0) {
+      const { knownLibraryPackages } = await import("@metaobjectsdev/metadata/library");
+      const available = knownLibraryPackages();
+      const unknown = cfg.libraries.filter((n) => !available.includes(n));
+      if (unknown.length > 0) {
+        throw new Error(
+          `metaobjects.config.ts at ${fullPath}: 'libraries' names unknown package(s) ` +
+            `${JSON.stringify(unknown)}; available: ${JSON.stringify(available)}.`,
+        );
+      }
+    }
     return cfg;
   } finally {
     // Restoring is safe: Babel's installer self-neuters after the first call, so

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

@@ -0,0 +1,75 @@
+// Advisory: is the codegen hash manifest git-ignored?
+//
+// `.gen-state/.hashes.json` is what lets `meta gen` tell "this file is exactly what
+// I wrote" from "somebody edited this" on a machine that did not generate it. If it
+// is ignored, that knowledge never leaves the generating machine, and on every other
+// machine a hand-edited generated file cannot be recognised as such.
+//
+// The reason this check exists rather than only a migration doc: the failure is
+// INVISIBLE. A project with the manifest ignored looks completely normal — `meta gen`
+// succeeds, output is correct — right up until a fresh clone refuses a wall of files
+// or (before the fix) silently ate an edit. This repo's own 0.23.1 lesson was that a
+// fix ships with the check that would have caught it, or it survives as folklore.
+//
+// Deliberately advisory. It cannot be an error: a project that genuinely does not
+// commit generated output has no use for the manifest, and failing its build over an
+// unused artifact would be wrong.
+
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { log } from "./log.js";
+
+/** Project-relative path of the manifest — the one artifact of `.gen-state/` that is
+ *  meant to be committed. */
+export const HASH_MANIFEST_REL = join(".metaobjects", ".gen-state", ".hashes.json");
+
+/**
+ * Ask git whether `relPath` is ignored, or undefined when the question cannot be
+ * answered (not a repository, git missing).
+ *
+ * `check-ignore` is the only reliable answer: parsing `.gitignore` by hand would have
+ * to reimplement precedence, negation and nested ignore files — and the specific trap
+ * this check exists to catch (`.gen-state/` excluding a directory so a `!` negation
+ * inside it can never apply) is exactly the rule a hand-rolled parser gets wrong.
+ */
+function isGitIgnored(cwd: string, relPath: string): boolean | undefined {
+  const gitBin = process.env.META_GEN_GIT ?? "git";
+  let res;
+  try {
+    res = spawnSync(gitBin, ["-C", cwd, "check-ignore", "-q", "--", relPath], {
+      encoding: "utf-8",
+    });
+  } catch {
+    return undefined;
+  }
+  if (res.error !== undefined) return undefined;
+  // 0 = ignored, 1 = not ignored, 128 = not a git repo / other git error.
+  if (res.status === 0) return true;
+  if (res.status === 1) return false;
+  return undefined;
+}
+
+/**
+ * Warn once when the hash manifest is git-ignored, naming the fix.
+ *
+ * Silent when: it is tracked correctly, the project is not a git repository, git is
+ * unavailable, or no generated output has ever been produced (nothing to protect yet).
+ * Never throws, never blocks.
+ */
+export function warnIfManifestIgnored(cwd: string): void {
+  // Nothing generated yet ⇒ nothing at risk ⇒ nothing worth saying.
+  if (!existsSync(join(cwd, HASH_MANIFEST_REL))) return;
+
+  if (isGitIgnored(cwd, HASH_MANIFEST_REL) !== true) return;
+
+  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.`,
+  );
+}