@metaobjectsdev/cli 0.23.2 → 0.24.1

package/src/commands/docs.ts

@@ -1,4 +1,4 @@
-// `meta docs <metadata> --out <dir>` — STANDALONE neutral metadata docs.
+// `meta docs [<project-root>] --out <dir>` — STANDALONE neutral metadata docs.
 //
 // Emits one neutral page per entity (`<Entity>.md`) and one per
 // `template.output` (`<Template>.md`) from metadata ALONE — no gen config, no
@@ -14,8 +14,8 @@
 import { resolve as resolvePath, basename } from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
 import { log } from "../lib/log.js";
-import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
-import { loadMemory, DEFAULT_METADATA_DIR } from "@metaobjectsdev/sdk";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { loadMemory, resolveCollection, resolveConfigDir, type Collection } from "@metaobjectsdev/sdk";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import {
@@ -31,7 +31,7 @@ import type {
   ResolvedDocsConfig,
   DocsSurface,
 } from "@metaobjectsdev/codegen-ts";
-import { docsFile, apiDocsFile } from "@metaobjectsdev/codegen-ts/generators";
+import { docsFile, apiDocsFile, requirementsFile } from "@metaobjectsdev/codegen-ts/generators";
 import { composeRegistry, coreProviders, renderCoreMetamodelDocs } from "@metaobjectsdev/metadata";
 import type { MetaDataTypeProvider } from "@metaobjectsdev/metadata";
 import { generateSite, SITE_TEMPLATE_NAMES, SITE_ASSET_NAMES, readSiteFile } from "@metaobjectsdev/docs-site";
@@ -39,8 +39,12 @@ import { generateSite, SITE_TEMPLATE_NAMES, SITE_ASSET_NAMES, readSiteFile } fro
 type DocsLayout = "flat" | "package";
 
 interface DocsFlags {
-  /** Project root holding `metaobjects/` (the metadata to document). */
-  metadata: string;
+  /** The PROJECT ROOT to resolve metadata from — the directory that CONTAINS
+   *  the metadata, never the metadata directory itself (#344). Named for what
+   *  it is: while it was called `metadata` the help text spelled the positional
+   *  `<metadata>`, which is what the Python and C# `docs` positionals actually
+   *  mean, and pointing this one at `metaobjects/` fails. */
+  projectRoot: string;
   /** Output directory for the rendered pages. */
   out: string;
   /** Page-placement layout. `flat` (default) writes `<Name>.md` at the out
@@ -48,7 +52,7 @@ interface DocsFlags {
    *  for multi-package models with repeated short names). */
   layout: DocsLayout;
   /** Optional override for the project root used to resolve adopter
-   *  `templates/` overrides. Defaults to the metadata root. */
+   *  `templates/` overrides. Defaults to the project root. */
   templates?: string;
   /** Optional directory holding the prompt `.mustache` sources, for a project
    *  whose templates live outside the conventional `metaobjects/` or `templates/`
@@ -66,6 +70,12 @@ interface DocsFlags {
   outProvided: boolean;
   /** Whether `--layout` was explicitly passed (same override semantics). */
   layoutProvided: boolean;
+  /** Whether the `<project-root>` positional was explicitly passed. An explicit path
+   *  DEFINES the source set (`resolveCollection`'s `explicitDir` pin); the default
+   *  cwd discovers one by walking up. Without this distinction the two are
+   *  indistinguishable at the call site, which is how an explicitly-scoped run came
+   *  to have an ancestor config's sources unioned into it (#327). */
+  projectRootProvided: boolean;
   /** FR-033 S3 — document the METAMODEL ITSELF (the built-in type/subtype/attr
    *  vocabulary) instead of a user's entities. Needs NO metadata + NO config. */
   metamodel: boolean;
@@ -87,7 +97,7 @@ function parseLayout(v: string | undefined, flag: string): DocsLayout {
 }
 
 function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
-  let metadata: string | undefined;
+  let projectRoot: string | undefined;
   let out: string | undefined;
   let templates: string | undefined;
   let prompts: string | undefined;
@@ -95,6 +105,7 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   let baseUrl: string | undefined;
   let wantModel = false;
   let wantApi = false;
+  let wantRequirements = false;
   let wantMetamodel = false;
   let wantSite = false;
   let wantScaffoldSite = false;
@@ -120,6 +131,8 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
       wantModel = true;
     } else if (a === "--api") {
       wantApi = true;
+    } else if (a === "--requirements") {
+      wantRequirements = true;
     } else if (a === "--metamodel") {
       wantMetamodel = true;
     } else if (a === "--site") {
@@ -146,8 +159,8 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
       prompts = a.slice("--prompts=".length);
     } else if (a.startsWith("-")) {
       throw new Error(`unknown flag: ${a}`);
-    } else if (metadata === undefined) {
-      metadata = a;
+    } else if (projectRoot === undefined) {
+      projectRoot = a;
     } else {
       throw new Error(`unexpected argument: ${a}`);
     }
@@ -161,11 +174,13 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   const surfaces: DocsSurface[] = [];
   if (wantModel) surfaces.push("model");
   if (wantApi) surfaces.push("api");
+  if (wantRequirements) surfaces.push("requirements");
   return {
-    // `<metadata>` is the project root that contains metaobjects/; default cwd
-    // (mirrors how migrate/gen treat the working directory as the root).
-    metadata: metadata ?? cwd,
-    // Default out dir, resolved against the metadata root below. In --metamodel
+    // `<project-root>` is the project root that CONTAINS the metadata; default
+    // cwd (mirrors how migrate/gen treat the working directory as the root).
+    projectRoot: projectRoot ?? cwd,
+    projectRootProvided: projectRoot !== undefined,
+    // Default out dir, resolved against the project root below. In --metamodel
     // mode the renderer writes under <out>/metamodel/, default ./docs/metamodel.
     out: out ?? (wantMetamodel ? "./docs/metamodel" : "./docs"),
     // Default flat preserves today's single-package output (+ existing goldens).
@@ -199,23 +214,75 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
     return metamodelDocsCommand(cwd, flags.out);
   }
 
-  const metaRoot = resolvePath(cwd, flags.metadata);
+  const metaRoot = resolvePath(cwd, flags.projectRoot);
   // Absolute prompt-source dir for the site (--prompts), for a project whose
   // templates live outside metaobjects/ or templates/ (e.g. data/templates/).
   const promptsDir = flags.prompts !== undefined ? resolvePath(cwd, flags.prompts) : undefined;
 
   // `--scaffold-site`: copy the docs-site templates + assets into codegen/docs-site/
   // so the consumer owns them (ADR-0034 scaffold-and-own). Scaffold and return —
-  // it does not also generate.
+  // it does not also generate. `resolveConfigDir` rather than `resolveCollection`:
+  // scaffolding needs no metadata, but it must write where `emitSite` will READ
+  // (below, under the resolved project root), and that is the same walk.
   if (flags.scaffoldSite) {
-    return scaffoldSiteCommand(metaRoot);
+    // `resolveGenConfigDir` over the bare walk: `emitSite` reads the owned theme
+    // from the directory holding `metaobjects.config.ts`, so scaffolding must write
+    // to the same one or the theme is scaffolded where nothing will ever read it.
+    return scaffoldSiteCommand(resolveGenConfigDir(metaRoot, await resolveConfigDir(metaRoot)));
   }
 
+  // Discovery and load are two separate failure modes, kept in separate try
+  // blocks deliberately — same reasoning as `meta gen` (gen.ts): a broad
+  // catch around both would swallow a genuine ParseError as "no metaobjects/
+  // found", masking the real failure.
+  //
+  // Discovery runs BEFORE the config read, deliberately, and `meta gen` calls
+  // out the same ordering as the thing it fixed: the project root is whichever
+  // directory `resolveCollection` decided the metadata belongs to, so
+  // everything project-relative — `metaobjects.config.ts` and its providers,
+  // the `docs.outDir` it names, the adopter `templates/` overrides, the owned
+  // `codegen/docs-site/` theme — has to come from that same directory. Reading
+  // the config from the ambient `<project-root>` argument while the metadata came
+  // from an ancestor renders the ancestor's model with the subdirectory's
+  // (absent) providers. For a run at the project root the two are the same path.
+  //
+  // An EXPLICIT `<project-root>` positional pins the collection rather than seeding a
+  // walk (#327). The argument has always meant "document this": before sources were
+  // resolvable it read `<path>/metaobjects/` and nothing else, and passing it to
+  // discovery turned it into a starting point, so the nearest ancestor
+  // `.metaobjects/config.json` was found and ITS sources were unioned in — a command
+  // whose entire purpose is documenting one subset silently documenting the whole
+  // repo, at exit 0. Pinned, `<path>` governs: its own config if it has one, the
+  // default `<path>/metaobjects` if not. A bare `meta docs` still discovers, which is
+  // the right default for "document the project I am standing in".
+  let collection: Awaited<ReturnType<typeof resolveCollection>>;
+  try {
+    collection = await resolveCollection(
+      metaRoot,
+      flags.projectRootProvided ? { explicitDir: metaRoot } : undefined,
+    );
+  } catch (err) {
+    log.error(`docs: ${(err as Error).message}`);
+    return 2;
+  }
+
+  // Which directory's `metaobjects.config.ts` governs is its OWN nearest-ancestor
+  // walk, not the collection's: the two files answer different questions (design
+  // §4.6), and in a Maven- or pip-rooted monorepo the collection is declared at the
+  // repo root while the TS config sits in the app. Reading the second from the
+  // first made docs silently drop that app's providers and skip its api surface
+  // entirely (#326). Everything that config names follows it — the `docs.outDir` it
+  // carries, the adopter `templates/` overrides and the owned `codegen/docs-site/`
+  // theme beside it. Same directory whenever the two files sit together, which is
+  // every `meta init` project.
+  const genConfigDir = resolveGenConfigDir(metaRoot, collection.configDir);
+
   // The project root used to resolve adopter `templates/` overrides; the
-  // framework defaults sit underneath via projectProvider's chain.
+  // framework defaults sit underneath via projectProvider's chain. `--templates`
+  // is the one explicit override.
   const projectRoot = flags.templates !== undefined
     ? resolvePath(cwd, flags.templates)
-    : metaRoot;
+    : genConfigDir;
 
   // Best-effort load of metaobjects.config.ts to pick up consumer-supplied
   // providers (e.g. a project's custom field/object subtypes). Unlike `gen`,
@@ -225,12 +292,14 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // if the metadata genuinely uses an unregistered type.
   let loadedConfig: Awaited<ReturnType<typeof loadMetaobjectsConfig>> | undefined;
   let configProviders: NonNullable<Awaited<ReturnType<typeof loadMetaobjectsConfig>>["providers"]> | undefined;
+  // The same config's contributions to the metadata LOAD — providers plus the shipped
+  // `libraries` a project opts into (#333). `configProviders` stays separate because the
+  // site surface has its own loader and takes providers alone.
+  let configLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   // hasConfig gates the api surface: api docs describe the GENERATED REST
   // surface, which only exists when there is a (loadable) gen config. A config
   // that EXISTS but fails to load degrades to model-only with a warning.
-  const hasConfig = existsSync(join(metaRoot, "metaobjects.config.ts"));
-  // The config lives alongside metaobjects/ at the metadata root (metaRoot);
-  // projectRoot only diverges when --templates overrides the template lookup.
+  const hasConfig = existsSync(join(genConfigDir, "metaobjects.config.ts"));
   // Only attempt the load when the file is actually present: absence is the
   // expected config-less case (stay silent), but a config that EXISTS yet fails
   // to load is surfaced as a warning rather than silently degrading to
@@ -238,8 +307,9 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // cryptic unknown-subtype error instead of the real config error.
   if (hasConfig) {
     try {
-      loadedConfig = await loadMetaobjectsConfig(metaRoot);
+      loadedConfig = await loadMetaobjectsConfig(genConfigDir);
       configProviders = loadedConfig.providers;
+      configLoadOptions = loadMemoryOptionsFrom(loadedConfig);
     } catch (err) {
       log.warn(
         `docs: metaobjects.config.ts failed to load (${(err as Error).message}); ` +
@@ -247,6 +317,7 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
       );
       loadedConfig = undefined;
       configProviders = undefined;
+      configLoadOptions = {};
     }
   }
 
@@ -269,7 +340,11 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
     cliOverrides,
     loadedConfig?.outputLayout ?? "flat",
   );
-  const outDir = resolvePath(metaRoot, docsCfg.outDir);
+  // Against `genConfigDir`, not the collection's: `docs.outDir` is declared in
+  // `metaobjects.config.ts`, so it resolves against the directory that config lives
+  // in — the same rule `meta gen` applies to its own `outDir`. Identical whenever
+  // the two files sit together.
+  const outDir = resolvePath(genConfigDir, docsCfg.outDir);
 
   // SITE surface has its OWN model loader (docs-site's loadModel — NOT the sdk
   // loadMemory below) and needs no gen config. When the site is the ONLY
@@ -277,23 +352,19 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // WITHOUT building the markdown GenContext — decoupled and one fewer failure
   // surface. Combined with --model/--api it is emitted after them (below).
   if (flags.site && docsCfg.surfaces.length === 0) {
-    return emitSite(metaRoot, outDir, configProviders, promptsDir);
+    return emitSite(collection, projectRoot, genConfigDir, outDir, configProviders, promptsDir);
   }
 
   // Load metadata standalone — same loader path as migrate/gen. Threads any
   // consumer providers from the config so custom types resolve.
   let root;
   try {
-    root = await loadMemory(metaRoot, {
-      ...(configProviders !== undefined ? { providers: configProviders } : {}),
+    root = await loadMemory(collection.configDir, {
+      files: collection.files,
+      ...configLoadOptions,
     });
   } catch (err) {
-    const msg = (err as Error).message;
-    if (!existsSync(join(metaRoot, DEFAULT_METADATA_DIR))) {
-      log.error(`docs: no metaobjects/ found in ${metaRoot}; run 'meta init' to scaffold`);
-    } else {
-      log.error(`docs: failed to load metadata: ${msg}`);
-    }
+    log.error(`docs: failed to load metadata: ${(err as Error).message}`);
     return 2;
   }
 
@@ -385,6 +456,16 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
     emit.push(...modelFiles);
   }
 
+  // REQUIREMENTS surface — the declared ledger as documentation (requirements.md +
+  // requirements.toon). Metadata-alone like the model surface: it reads ctx.loadedRoot
+  // and nothing else, so it is NOT gated on a loadable gen config the way `api` is.
+  //
+  // Emits ZERO files when the project declares no `requirement.*` node, which is what
+  // makes this surface safe to default ON — a project without a ledger sees no change.
+  if (docsCfg.surfaces.includes("requirements")) {
+    emit.push(...(await requirementsFile().generate(ctx)));
+  }
+
   // API surface — the SDK reference for the GENERATED REST surface, side by side
   // under each surface's subDir. THIS command only OWNS the surfaces it can
   // generate — i.e. its own port (lang "ts"). Surfaces owned by other ports are
@@ -444,7 +525,7 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
 
   // SITE surface (additive) — emit after the markdown surfaces so both coexist.
   if (flags.site) {
-    const siteRc = await emitSite(metaRoot, outDir, configProviders, promptsDir);
+    const siteRc = await emitSite(collection, projectRoot, genConfigDir, outDir, configProviders, promptsDir);
     if (siteRc !== 0) return siteRc;
   }
 
@@ -462,7 +543,12 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   const apiSummary = apiFiles.length > 0
     ? `${apiFiles.length} api page(s)`
     : "no api pages";
-  log.info(`meta docs — wrote ${modelSummary}; ${apiSummary} → ${outDir}`);
+  // Reported only when it actually wrote something. A project with no ledger emits no
+  // requirements file, and saying "0 requirement pages" would advertise a surface that
+  // did not run — the opposite of the silence the empty-ledger guard exists to produce.
+  const requirementFiles = emit.filter((f) => f.path.startsWith("requirements.")).length;
+  const reqSummary = requirementFiles > 0 ? `; ${requirementFiles} requirement file(s)` : "";
+  log.info(`meta docs — wrote ${modelSummary}; ${apiSummary}${reqSummary} → ${outDir}`);
   return 0;
 }
 
@@ -471,9 +557,9 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
  * into `<root>/codegen/docs-site/{templates,assets}`, writing each file ONLY if
  * absent so a re-run never clobbers a hand-edited file.
  */
-async function scaffoldSiteCommand(metaRoot: string): Promise<number> {
-  const tplDir = join(metaRoot, "codegen/docs-site/templates");
-  const astDir = join(metaRoot, "codegen/docs-site/assets");
+async function scaffoldSiteCommand(projectRoot: string): Promise<number> {
+  const tplDir = join(projectRoot, "codegen/docs-site/templates");
+  const astDir = join(projectRoot, "codegen/docs-site/assets");
   const created: string[] = [];
   const preserved: string[] = [];
   try {
@@ -499,53 +585,80 @@ async function scaffoldSiteCommand(metaRoot: string): Promise<number> {
   }
   log.info(
     `meta docs --scaffold-site — ${created.length} created, ${preserved.length} preserved ` +
-      `→ ${join(metaRoot, "codegen/docs-site")} (edit these to own your theme)`,
+      `→ ${join(projectRoot, "codegen/docs-site")} (edit these to own your theme)`,
   );
   return 0;
 }
 
 /**
  * Emit the browsable HTML documentation site via `@metaobjectsdev/docs-site`.
- * The site loads the model with its OWN loader from the metadata source dir
- * (`<metaRoot>/metaobjects`), so this is independent of the sdk loadMemory path
- * used for the markdown surfaces. Writes under `<outDir>/site` so it can coexist
- * with the markdown output. Scaffold-and-own: when the consumer has copied
- * templates/assets into `<metaRoot>/codegen/docs-site/` (via `--scaffold-site`),
- * those win over the bundled defaults.
+ * The site loads the model with its OWN loader from the collection's declared
+ * source ROOTS (whole directories, one page group each) rather than from the
+ * per-file list the sdk `loadMemory` path takes, so this is independent of the
+ * markdown surfaces. Writes under `<outDir>/site` so it can coexist with the markdown
+ * output. Scaffold-and-own: when the consumer has copied templates/assets
+ * into `<projectRoot>/codegen/docs-site/` (via `--scaffold-site`), those win
+ * over the bundled defaults.
+ *
+ * Takes the ALREADY-RESOLVED collection: `docsCommand` resolved it to read the
+ * config from the right directory, and resolving a second time here made the
+ * combined `--model --site` path do the whole discovery-and-config walk twice.
  */
 async function emitSite(
-  metaRoot: string,
+  collection: Collection,
+  projectRoot: string,
+  /** Directory holding `metaobjects.config.ts` — where `--scaffold-site` writes the
+   *  owned theme, so where this must read it from. Distinct from `collection.configDir`
+   *  since #326: in a polyglot monorepo the collection is declared at the repo root
+   *  while the TS package (and its owned theme) sits in the app. */
+  genConfigDir: string,
   outDir: string,
   configProviders?: readonly MetaDataTypeProvider[],
   promptsDir?: string,
 ): Promise<number> {
   const siteOutDir = resolvePath(outDir, "site");
-  // metaobjects/ is REQUIRED (the site loads the model from it) and always first.
-  // Prompt `.mustache` source is additionally searched in the conventional
-  // <root>/templates/ and any explicit --prompts dir (for a project whose templates
-  // live elsewhere, e.g. data/templates/) — else the site can't show the prompt TEXT
-  // and prints a "source missing" note. Only existing dirs are added, and dirs are
-  // deduped by BASENAME (the site keys source groups by basename, and rejects a dup).
-  const sourceDirs = [join(metaRoot, DEFAULT_METADATA_DIR)];
-  const seenBasenames = new Set([basename(join(metaRoot, DEFAULT_METADATA_DIR))]);
+  // The resolved metadata source dir(s) are REQUIRED (the site loads the
+  // model from them) and always first. Prompt `.mustache` source is
+  // additionally searched in the conventional <root>/templates/ and any
+  // explicit --prompts dir (for a project whose templates live elsewhere,
+  // e.g. data/templates/) — else the site can't show the prompt TEXT and
+  // prints a "source missing" note. Only existing dirs are added.
+  //
+  // Deduped by resolved PATH, not by basename. Two DIFFERENT directories that
+  // happen to share a basename are a legitimate multi-source project (`metaobjects`
+  // plus `../shared-model/metaobjects`); `loadModel` disambiguates their site
+  // group names, so refusing the pair here — which a basename key did, by
+  // dropping the second — would break the feature this branch exists to ship.
+  // The same directory named twice is the real hazard: it would be symlinked
+  // and loaded twice.
+  // The DECLARED source roots, not directories re-derived from the resolved
+  // files: a declared source directory holding no metadata yet would otherwise
+  // vanish from the site's group list entirely, and `sourceDirs` could come back
+  // empty where the pre-branch code always passed `<root>/metaobjects`.
+  const sourceDirs = [...collection.sourceRoots];
+  const seenDirs = new Set(sourceDirs);
   if (promptsDir !== undefined && !existsSync(promptsDir)) {
     log.warn(`docs: --prompts dir does not exist: ${promptsDir}`);
   }
-  for (const d of [join(metaRoot, "templates"), ...(promptsDir !== undefined ? [promptsDir] : [])]) {
-    if (existsSync(d) && !seenBasenames.has(basename(d))) {
-      sourceDirs.push(d);
-      seenBasenames.add(basename(d));
+  for (const d of [join(projectRoot, "templates"), ...(promptsDir !== undefined ? [promptsDir] : [])]) {
+    const abs = resolvePath(d);
+    if (existsSync(abs) && !seenDirs.has(abs)) {
+      sourceDirs.push(abs);
+      seenDirs.add(abs);
     }
   }
   // Scaffold-and-own: when the consumer has copied templates/assets into
   // codegen/docs-site/ (via --scaffold-site), use those; else the bundled defaults.
-  const ownedTemplates = join(metaRoot, "codegen/docs-site/templates");
-  const ownedAssets = join(metaRoot, "codegen/docs-site/assets");
+  // Keyed on `genConfigDir`, NOT `projectRoot`: `--templates` redirects the adopter
+  // RENDER template chain (the `templates/` above), and letting it also move the
+  // docs-site theme would read it from somewhere `--scaffold-site` never writes.
+  const ownedTemplates = join(genConfigDir, "codegen/docs-site/templates");
+  const ownedAssets = join(genConfigDir, "codegen/docs-site/assets");
   try {
     const r = await generateSite({
       sourceDirs,
       outDir: siteOutDir,
-      title: basename(metaRoot) || "Metadata",
+      title: basename(collection.configDir) || "Metadata",
       stamp: new Date().toISOString().slice(0, 10),
       commit: "",
       core: { n: 15 },

package/src/commands/export.ts

@@ -1,10 +1,10 @@
-import { resolve, join } from "node:path";
+import { resolve } from "node:path";
 import { writeFile } from "node:fs/promises";
 import { parseExportArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
-import { loadAndExportJson } from "@metaobjectsdev/metadata/core";
-import { TypeRegistry, registerCoreTypes } from "@metaobjectsdev/metadata";
-import { DEFAULT_METADATA_DIR, registerForgeTypes } from "@metaobjectsdev/sdk";
+import { FileSource } from "@metaobjectsdev/metadata/core";
+import { TypeRegistry, registerCoreTypes, MetaDataLoader, canonicalSerialize } from "@metaobjectsdev/metadata";
+import { registerForgeTypes, resolveCollection } from "@metaobjectsdev/sdk";
 
 export async function exportCommand(args: string[], cwd: string): Promise<number> {
   let flags;
@@ -16,7 +16,6 @@ export async function exportCommand(args: string[], cwd: string): Promise<number
   }
 
   const projectRoot = cwd;
-  const metadataDir = join(projectRoot, DEFAULT_METADATA_DIR);
 
   // Build a registry with core + forge types so metadata that includes
   // descriptive types (decision, principle, etc.) loads without errors.
@@ -24,7 +23,32 @@ export async function exportCommand(args: string[], cwd: string): Promise<number
   registerCoreTypes(registry);
   registerForgeTypes(registry);
 
-  const result = await loadAndExportJson(metadataDir, { registry });
+  // `export` has never used exit 2 for a metadata problem — only for a bad CLI
+  // flag (see parseExportArgs above). Previously any directory-load failure
+  // surfaced through loadAndExportJson's collected result.errors (exit 1); a
+  // resolveCollection failure (no declared sources, no default metaobjects/,
+  // or a malformed config.json) is the same class of problem and is reported
+  // the same way, to keep that contract exactly as it was.
+  let files: readonly string[];
+  try {
+    files = (await resolveCollection(projectRoot)).files;
+  } catch (err) {
+    log.error((err as Error).message);
+    return 1;
+  }
+
+  // `loadAndExportJson` only accepts a scanned directory (`MetaDataLoader.fromDirectory`);
+  // `resolveCollection` already resolved the file SET (declared `sources`, or the
+  // `metaobjects/` default), so load that list directly via the same loader +
+  // serializer `loadAndExportJson` composes, rather than re-deriving a directory.
+  const loadResult = await new MetaDataLoader({ registry }).load(
+    files.map((f) => new FileSource(f)),
+  );
+  const result = {
+    json: canonicalSerialize(loadResult.root),
+    errors: loadResult.errors,
+    warnings: loadResult.warnings.map((w) => w.message),
+  };
 
   for (const w of result.warnings) {
     log.warn(w);

package/src/commands/gen.ts

@@ -1,15 +1,15 @@
-import { relative, join } from "node:path";
-import { existsSync } from "node:fs";
+import { relative } from "node:path";
 import { parseGenArgs } from "../lib/args.js";
 import { resolveGenConfig } from "../lib/config.js";
-import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { formatGenResult, formatGenResultToon, type GenFileEntry, type GenFileStatus } from "../lib/output.js";
 import { formatGenResultJson } from "../lib/output-json.js";
 import type { OutputFormat } from "../lib/format.js";
 import { log } from "../lib/log.js";
 import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
+import { warnIfManifestIgnored } from "../lib/manifest-ignored-check.js";
 import { scanSourceForAntiPatterns } from "../lib/anti-patterns.js";
-import { loadMemory, DEFAULT_METADATA_DIR } from "@metaobjectsdev/sdk";
+import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
 import { runGen, listGenerators } from "@metaobjectsdev/codegen-ts";
 import type { WriteStatus } from "@metaobjectsdev/codegen-ts";
 
@@ -22,6 +22,10 @@ function mapStatus(s: WriteStatus): GenFileStatus {
     case "unchanged":
     case "skipped":   return "unchanged";
     case "refused":   return "refused";
+    // FR-038 §8 — a generated file deleted because it is no longer generated.
+    // Shown as its own outcome, not folded into "unchanged": a run summary that
+    // lists writes but hides deletions is how a silent deletion happens.
+    case "removed":   return "removed";
   }
 }
 
@@ -36,12 +40,59 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     return listGeneratorsCommand();
   }
 
-  // Advisory: nudge to refresh the .claude/skills docs if they predate this CLI.
-  warnIfAgentContextStale(cwd);
-
-  const projectRoot = cwd;
   const cliConfig = resolveGenConfig(flags);
 
+  // Discovery and load are two separate failure modes, kept in separate try
+  // blocks deliberately: a broad catch around both previously swallowed
+  // genuine ParseErrors (e.g. `origin.@via "X.y" ...: no such relationship
+  // "y" on X`) as "no metaobjects/ found", masking the real failure.
+  // `resolveCollection` raises `ERR_COLLECTION_NOT_FOUND` with its own
+  // message when nothing is discovered and no default directory exists.
+  //
+  // Discovery runs BEFORE the config read, deliberately: everything named BY the
+  // metadata resolves against the directory `resolveCollection` decided the
+  // metadata belongs to. Reading THAT from ambient cwd while the metadata came
+  // from an ancestor is the divergence this design exists to remove (design
+  // §4.6.1).
+  let collection;
+  try {
+    collection = await resolveCollection(cwd);
+  } catch (err) {
+    log.error((err as Error).message);
+    return 2;
+  }
+  // ...but `metaobjects.config.ts` is not named by the metadata: it is this
+  // package's own answer to a different question (design §4.6 — "how is code
+  // generated here?", per-port, versus the port-neutral "where does metadata come
+  // from?"). It gets its own nearest-ancestor walk, so a JS app under a Maven- or
+  // pip-rooted repo generates with the config sitting beside it rather than
+  // demanding one at the repo root that no such repo has (#326). Everything the
+  // TS config names follows it — `outDir`, `targets`, and the
+  // `.metaobjects/.gen-state/` merge base that mirrors that output, which must be
+  // per-package or two apps sharing one collection would clobber each other's.
+  // Nearest wins, so a subdirectory declaring nothing still walks up to the
+  // project root's config exactly as before.
+  const projectRoot = resolveGenConfigDir(cwd, collection.configDir);
+
+  // ...and a package that declares its own sources GENERATES from them (#340). An
+  // ancestor collection is the default for a package that declares none, never an
+  // addition to one that does — otherwise a sub-project's output silently absorbs
+  // metadata from unrelated trees. Identical object when the two configs sit together.
+  const genCollection = await resolveGenCollection(collection, projectRoot);
+
+  // Advisory: nudge to refresh the .claude/skills docs if they predate this CLI.
+  // Rooted at `projectRoot`, not ambient cwd — the scaffolded agent context sits
+  // with the project that declares the metadata, so a run from a subdirectory
+  // would find no manifest there and silently skip the nudge. `meta verify` makes
+  // the same call for the same reason; the two commands describe this and the
+  // anti-pattern scan below as one advisory pass, so they must scan one tree.
+  warnIfAgentContextStale(projectRoot);
+  // Advisory: the committed hash manifest is what makes hand-edit detection work on a
+  // machine that did not generate the output. Silent unless it is ignored. Keyed on
+  // projectRoot, not cwd, for the same reason its neighbour is — the manifest belongs to
+  // whichever directory `resolveCollection` decided the metadata lives in.
+  warnIfManifestIgnored(projectRoot);
+
   let forgeConfig;
   try {
     forgeConfig = await loadMetaobjectsConfig(projectRoot);
@@ -52,22 +103,12 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
 
   let metadata;
   try {
-    metadata = await loadMemory(projectRoot, {
-      ...(forgeConfig.providers !== undefined ? { providers: forgeConfig.providers } : {}),
+    metadata = await loadMemory(genCollection.configDir, {
+      files: genCollection.files,
+      ...loadMemoryOptionsFrom(forgeConfig),
     });
   } catch (err) {
-    const msg = (err as Error).message;
-    // Only emit the scaffold hint for the ACTUAL missing-metadata-dir
-    // condition — checked explicitly here. A broad substring match on
-    // "no such" / "cannot read" wrongly swallowed genuine ParseErrors (e.g.
-    // `origin.@via "X.y" ...: no such relationship "y" on X`) as "no
-    // metaobjects/ found", masking the real failure. Real parse/validation
-    // errors propagate with their actual message.
-    if (!existsSync(join(projectRoot, DEFAULT_METADATA_DIR))) {
-      log.error(`no metaobjects/ found in ${projectRoot}; run 'meta init' to scaffold`);
-    } else {
-      log.error(`failed to load metadata: ${msg}`);
-    }
+    log.error(`failed to load metadata: ${(err as Error).message}`);
     return 2;
   }
 
@@ -81,6 +122,11 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
       // --dry-run must actually preview. This was previously passed only to the
       // display object below, so a "preview" run wrote every file.
       dryRun: cliConfig.dryRun,
+      // Collection-level `scope` (Task 12b) — the output filter over
+      // GENERATED entities, never over what the collection loads. Always
+      // passed: an unconfigured project's predicate admits everything, so this
+      // is a no-op for the common case, not a behavior change.
+      scope: genCollection.inScope,
       ...(cliConfig.entities.length > 0 ? { entityFilter: cliConfig.entities } : {}),
     });
   } catch (err) {