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

package/src/index.ts

@@ -55,6 +55,12 @@ GLOBAL OPTIONS:
 
 GEN FLAGS:
   --dry-run             Compute and print, don't write
+  --list                Print the generator registry (name, tier, options) and exit —
+                        no config or metadata required
+  --baseline <default|fresh>
+                        First-time-on-existing-file behavior. Default: write-if-different,
+                        adopting existing content as the canonical baseline. "fresh"
+                        overwrites and re-baselines.
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --limit <n|all>       How many advisory lines TEXT output prints before it truncates
                         (default 20). Never applies to --format toon/json, which
@@ -127,7 +133,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> = {
+export const COMMAND_HELP: Record<string, string> = {
   gen: `meta gen — codegen TS targets from your declared metadata
 
 USAGE:
@@ -135,6 +141,12 @@ USAGE:
 
 FLAGS:
   --dry-run             Compute and print, don't write
+  --list                Print the generator registry (name, tier, options) and exit —
+                        no config or metadata required
+  --baseline <default|fresh>
+                        First-time-on-existing-file behavior. Default: write-if-different,
+                        adopting existing content as the canonical baseline. "fresh"
+                        overwrites and re-baselines.
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --limit <n|all>       Advisory lines TEXT output prints before truncating (default 20)
   --format <toon|json|text>   Output format (global flag; default toon off-TTY)
@@ -182,7 +194,11 @@ FLAGS:
   --codegen             Codegen drift — regenerate to temp dir and diff committed output
                         Needs metaobjects.config.ts; exit 2 if absent.
   --docs                Docs drift — run 'meta docs' to a temp dir and diff docs.outDir
-                        Needs metaobjects.config.ts; exit 2 if absent.
+                        Needs metaobjects.config.ts; exit 2 if absent. A page the
+                        project GIT-IGNORES is exempt (docs.outDir is a directory, not
+                        a namespace MetaObjects owns); the count of exempt pages is
+                        reported either way, and a run where every page is ignored is
+                        refused rather than reported clean.
   --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.
@@ -204,6 +220,10 @@ FLAGS:
   --d1 <binding>        D1 binding name from wrangler.toml (only with --dialect d1)
   --remote              Target remote D1 instead of local (only with --dialect d1) —
                         the ONLY way to verify the actual deployed D1 database
+  --lax                 Load with the legacy OPEN attribute set instead of strict
+                        (ADR-0023). Strict is the default: an undeclared or typo'd own
+                        @attr fails verify with ERR_UNKNOWN_ATTR. Use only while
+                        migrating a model onto a registered provider.
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
   --limit <n|all>       Advisory lines TEXT output prints PER SECTION before truncating
@@ -274,6 +294,14 @@ USAGE:
 
 FLAGS:
   --refresh-docs        Refresh .metaobjects/AGENTS.md + CLAUDE.md after CLI upgrades
+  --docs-only           Write only the agent-context files — no metadata sources, no
+                        codegen scaffold, no config. Pair with --refresh-docs to update
+                        an existing project after upgrading.
+  --server <lang>       Declare a server language for the agent context (repeatable;
+                        e.g. csharp, kotlin, python, node)
+  --client <fw>         Declare a client framework for the agent context (repeatable;
+                        e.g. react, vue)
+  --no-skills           Skip the .claude/skills/ scaffold
   --force               Overwrite existing files
   --quiet               Suppress output
   --print-only          Print what would be written, don't write

package/src/lib/args.ts

@@ -19,22 +19,25 @@ export interface InitFlags {
   configOnly: boolean;
 }
 
+/** The flag table `parseInitArgs` parses. Exported so the help text can be gated against it. */
+export const INIT_OPTIONS = {
+  force: { type: "boolean", default: false },
+  quiet: { type: "boolean", default: false },
+  "print-only": { type: "boolean", default: false },
+  "refresh-docs": { type: "boolean", default: false },
+  d1: { type: "boolean", default: false },
+  server: { type: "string", multiple: true },
+  client: { type: "string", multiple: true },
+  "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 },
+} as const;
+
 export function parseInitArgs(argv: string[]): InitFlags {
   const { values } = parseArgs({
     args: argv,
-    options: {
-      force: { type: "boolean", default: false },
-      quiet: { type: "boolean", default: false },
-      "print-only": { type: "boolean", default: false },
-      "refresh-docs": { type: "boolean", default: false },
-      d1: { type: "boolean", default: false },
-      server: { type: "string", multiple: true },
-      client: { type: "string", multiple: true },
-      "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 },
-    },
+    options: INIT_OPTIONS,
     strict: true,
     allowPositionals: false,
   });
@@ -65,16 +68,19 @@ export interface AgentDocsFlags {
   wireRoot: boolean;
 }
 
+/** The flag table `parseAgentDocsArgs` parses. Exported so the help text can be gated against it. */
+export const AGENT_DOCS_OPTIONS = {
+  server: { type: "string", multiple: true },
+  client: { type: "string", multiple: true },
+  out: { type: "string" },
+  "no-skills": { type: "boolean", default: false },
+  "no-wire-root": { type: "boolean", default: false },
+} as const;
+
 export function parseAgentDocsArgs(argv: string[]): AgentDocsFlags {
   const { values } = parseArgs({
     args: argv,
-    options: {
-      server: { type: "string", multiple: true },
-      client: { type: "string", multiple: true },
-      out: { type: "string" },
-      "no-skills": { type: "boolean", default: false },
-      "no-wire-root": { type: "boolean", default: false },
-    },
+    options: AGENT_DOCS_OPTIONS,
     strict: true,
     allowPositionals: false,
   });
@@ -111,16 +117,19 @@ export interface GenFlags {
   limit: number;
 }
 
+/** The flag table `parseGenArgs` parses. Exported so the help text can be gated against it. */
+export const GEN_OPTIONS = {
+  "dry-run": { type: "boolean", default: false },
+  "baseline": { type: "string" },
+  "list": { type: "boolean", default: false },
+  "no-antipatterns": { type: "boolean", default: false },
+  "limit": { type: "string" },
+} as const;
+
 export function parseGenArgs(argv: string[]): GenFlags {
   const { values, positionals } = parseArgs({
     args: argv,
-    options: {
-      "dry-run": { type: "boolean", default: false },
-      "baseline": { type: "string" },
-      "list": { type: "boolean", default: false },
-      "no-antipatterns": { type: "boolean", default: false },
-      "limit": { type: "string" },
-    },
+    options: GEN_OPTIONS,
     strict: true,
     allowPositionals: true,
   });
@@ -150,12 +159,15 @@ export interface ExportFlags {
   out: string | undefined;
 }
 
+/** The flag table `parseExportArgs` parses. Exported so the help text can be gated against it. */
+export const EXPORT_OPTIONS = {
+  out: { type: "string" },
+} as const;
+
 export function parseExportArgs(argv: string[]): ExportFlags {
   const { values } = parseArgs({
     args: argv,
-    options: {
-      out: { type: "string" },
-    },
+    options: EXPORT_OPTIONS,
     strict: true,
     allowPositionals: false,
   });
@@ -306,27 +318,30 @@ export interface VerifyFlags {
   limit: number;
 }
 
+/** The flag table `parseVerifyArgs` parses. Exported so the help text can be gated against it. */
+export const VERIFY_OPTIONS = {
+  prompts: { type: "string" },
+  db: { type: "string" },
+  dialect: { type: "string" },
+  allow: { type: "string" },
+  "skip-schema": { type: "boolean", default: false },
+  templates: { type: "boolean", default: false },
+  codegen: { type: "boolean", default: false },
+  docs: { type: "boolean", default: false },
+  replay: { type: "boolean", default: false },
+  "replay-snapshot": { type: "boolean", default: false },
+  "no-antipatterns": { type: "boolean", default: false },
+  "no-requirement-lint": { type: "boolean", default: false },
+  lax: { type: "boolean", default: false },
+  "d1": { type: "string" },
+  "remote": { type: "boolean", default: false },
+  "limit": { type: "string" },
+} as const;
+
 export function parseVerifyArgs(argv: string[]): VerifyFlags {
   const { values } = parseArgs({
     args: argv,
-    options: {
-      prompts: { type: "string" },
-      db: { type: "string" },
-      dialect: { type: "string" },
-      allow: { type: "string" },
-      "skip-schema": { type: "boolean", default: false },
-      templates: { type: "boolean", default: false },
-      codegen: { type: "boolean", default: false },
-      docs: { type: "boolean", default: false },
-      replay: { type: "boolean", default: false },
-      "replay-snapshot": { type: "boolean", default: false },
-      "no-antipatterns": { type: "boolean", default: false },
-      "no-requirement-lint": { type: "boolean", default: false },
-      lax: { type: "boolean", default: false },
-      "d1": { type: "string" },
-      "remote": { type: "boolean", default: false },
-      "limit": { type: "string" },
-    },
+    options: VERIFY_OPTIONS,
     strict: true,
     allowPositionals: false,
   });
@@ -395,13 +410,16 @@ export interface PromptSnapshotFlags {
   prompts: string | undefined;
 }
 
+/** The flag table `parsePromptSnapshotArgs` parses. Exported so the help text can be gated against it. */
+export const PROMPT_SNAPSHOT_OPTIONS = {
+  check: { type: "boolean", default: false },
+  prompts: { type: "string" },
+} as const;
+
 export function parsePromptSnapshotArgs(argv: string[]): PromptSnapshotFlags {
   const { values } = parseArgs({
     args: argv,
-    options: {
-      check: { type: "boolean", default: false },
-      prompts: { type: "string" },
-    },
+    options: PROMPT_SNAPSHOT_OPTIONS,
     strict: true,
     allowPositionals: false,
   });
@@ -447,25 +465,28 @@ export interface MigrateFlags {
   applyPending: boolean;
 }
 
+/** The flag table `parseMigrateArgs` parses. Exported so the help text can be gated against it. */
+export const MIGRATE_OPTIONS = {
+  "db": { type: "string" },
+  "dialect": { type: "string" },
+  "migration-format": { type: "string" },
+  "out-dir": { type: "string" },
+  "slug": { type: "string" },
+  "allow": { type: "string" },
+  "on-ambiguous": { type: "string" },
+  "dry-run": { type: "boolean", default: false },
+  "from-db": { type: "boolean", default: false },
+  "d1": { type: "string" },
+  "remote": { type: "boolean", default: false },
+  "apply": { type: "boolean", default: false },
+  "rollback": { type: "string" },
+  "yes": { type: "boolean", default: false },
+} as const;
+
 export function parseMigrateArgs(argv: string[]): MigrateFlags {
   const { values, positionals } = parseArgs({
     args: argv,
-    options: {
-      "db": { type: "string" },
-      "dialect": { type: "string" },
-      "migration-format": { type: "string" },
-      "out-dir": { type: "string" },
-      "slug": { type: "string" },
-      "allow": { type: "string" },
-      "on-ambiguous": { type: "string" },
-      "dry-run": { type: "boolean", default: false },
-      "from-db": { type: "boolean", default: false },
-      "d1": { type: "string" },
-      "remote": { type: "boolean", default: false },
-      "apply": { type: "boolean", default: false },
-      "rollback": { type: "string" },
-      "yes": { type: "boolean", default: false },
-    },
+    options: MIGRATE_OPTIONS,
     strict: true,
     allowPositionals: true,
   });
@@ -541,13 +562,16 @@ export interface EjectFlags {
   force: boolean;
 }
 
+/** The flag table `parseEjectArgs` parses. Exported so the help text can be gated against it. */
+export const EJECT_OPTIONS = {
+  "list": { type: "boolean", default: false },
+  "force": { type: "boolean", default: false },
+} as const;
+
 export function parseEjectArgs(argv: string[]): EjectFlags {
   const { values, positionals } = parseArgs({
     args: argv,
-    options: {
-      "list": { type: "boolean", default: false },
-      "force": { type: "boolean", default: false },
-    },
+    options: EJECT_OPTIONS,
     strict: true,
     allowPositionals: true,
   });

package/src/lib/docs-drift.ts

@@ -49,6 +49,7 @@ import { mkdtempSync, rmSync, existsSync, readFileSync, readdirSync, lstatSync }
 import { tmpdir } from "node:os";
 import { join, relative, resolve, isAbsolute, sep } from "node:path";
 import { docsCommand } from "../commands/docs.js";
+import { gitIgnored } from "./git-ignore.js";
 
 export interface DocsDriftResult {
   /** True when every page a fresh `meta docs` would write is committed and identical. */
@@ -59,8 +60,19 @@ export interface DocsDriftResult {
   /** Human-readable, one line per file. */
   lines: string[];
   /** The denominator both the passing and the failing report divide by: the pages a fresh
-   *  run produced, plus any committed page under `agent/` it no longer emits. */
+   *  run produced, plus any committed page under `agent/` it no longer emits, MINUS the
+   *  git-ignored ones. A pure function of (fresh set, repository ignore rules) — never of
+   *  which files happen to be on this machine's disk. */
   checked: number;
+  /** How many pages a fresh run emits that the project git-ignores, so did not check.
+   *  Reported on BOTH the passing and the failing line: a gate that quietly checked two
+   *  of 589 pages and said "no drift" would be indistinguishable from one that checked
+   *  everything. */
+  ignored: number;
+  /** Why the ignore rules could not be consulted, when they could not be. Undefined means
+   *  they were. The gate then falls back to checking EVERY page a fresh run emits — the
+   *  pre-existing behaviour — and says so rather than degrading silently. */
+  ignoreReason?: string | undefined;
   /** Set when the gate could not run at all. */
   error?: string;
 }
@@ -163,6 +175,7 @@ export async function computeDocsDrift(args: ComputeDocsDriftArgs): Promise<Docs
         driftedFiles: [],
         lines: [],
         checked: 0,
+        ignored: 0,
         error:
           `verify --docs: 'meta docs' exited ${exit}, so the committed pages could not be ` +
           `compared against a fresh run. Fix that first — the error is above.`,
@@ -176,19 +189,89 @@ export async function computeDocsDrift(args: ComputeDocsDriftArgs): Promise<Docs
         driftedFiles: [],
         lines: [],
         checked: 0,
+        ignored: 0,
         error:
           "verify --docs: a fresh 'meta docs' produced no pages, so there is nothing to " +
           "compare. Check that this project declares metadata the docs surfaces cover.",
       };
     }
 
+    // Committed-but-not-regenerated, inside the directories this command owns.
+    const freshSet = new Set(fresh);
+    const ownedOrphans = listFiles(docsDir)
+      .filter((rel) => !freshSet.has(rel) && isOurs(docsDir, rel))
+      .sort();
+
+    // A page the project deliberately does not commit is not drift.
+    //
+    // `docs.outDir` is a directory, not a namespace MetaObjects owns — the same
+    // jurisdiction ruling 0.24.3 made for `verify --codegen`. But `--codegen` could key
+    // on `.gen-state/.hashes.json`, a record of what the generator WROTE, and `meta
+    // docs` keeps no such manifest. What it can ask instead is what the PROJECT says:
+    // a page under `docs.outDir` that git reports ignored is one the project has
+    // declared it does not commit.
+    //
+    // This is not a guess about intent, it is the project's own statement of it. And it
+    // cannot be used to hide a file the project actually tracks: git never reports a
+    // TRACKED path as ignored, whatever pattern matches it, so a committed page is
+    // always compared.
+    //
+    // The exemption is computed over the FRESH set by NAME, present on disk or not.
+    // That is what makes the verdict machine-independent: a developer box that has run
+    // `meta docs` locally has all 589 pages on disk and a CI runner has two, and both
+    // must report the same denominator. Deciding per-file-existence would have made
+    // `checked` a property of the machine.
+    //
+    // Without it: an estate generating three surfaces and committing 2 files of 589 —
+    // gitignoring the rest with a comment explaining they are a derived view of
+    // metadata that is already the source of truth — was told it had 588 drifted pages,
+    // of which exactly ONE was real.
+    const ignoreCandidates = [...fresh, ...ownedOrphans];
+    // honourGlobalExcludes: false — this verdict must be a property of the repository.
+    // A gate that passes for the author and fails in CI because of a personal ignore
+    // file is worse than no gate.
+    const ignoreLookup = gitIgnored(docsDir, ignoreCandidates, {
+      honourGlobalExcludes: false,
+    });
+    const ignored: ReadonlySet<string> =
+      "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 toCheck = fresh.filter((rel) => !isIgnored(rel));
+    const orphans = ownedOrphans.filter((rel) => !isIgnored(rel));
+    const ignoredCount = fresh.length - toCheck.length;
+
+    // A gate asked to check pages that could check NONE must not answer "no drift".
+    if (toCheck.length === 0 && orphans.length === 0) {
+      return {
+        clean: false,
+        driftedFiles: [],
+        lines: [],
+        checked: 0,
+        ignored: ignoredCount,
+        ignoreReason,
+        error:
+          `verify --docs: a fresh 'meta docs' produced ${fresh.length} page(s) and every ` +
+          `one of them is git-ignored, so there is nothing to compare. Commit the pages ` +
+          `you want checked, or run without --docs.`,
+      };
+    }
+
     const driftedFiles: string[] = [];
     const lines: string[] = [];
-    for (const rel of fresh) {
+    for (const rel of toCheck) {
       const committedPath = join(docsDir, rel);
       if (!existsSync(committedPath)) {
         driftedFiles.push(rel);
-        lines.push(`+ ${rel} (a fresh 'meta docs' emits it; not committed)`);
+        // When the rules could not be consulted the last clause would be a claim we
+        // have not checked, so it is dropped rather than asserted.
+        lines.push(
+          ignoreReason === undefined
+            ? `+ ${rel} (a fresh 'meta docs' emits it; not committed, not git-ignored)`
+            : `+ ${rel} (a fresh 'meta docs' emits it; not committed)`,
+        );
         continue;
       }
       const a = readFileSync(committedPath, "utf8");
@@ -198,14 +281,9 @@ export async function computeDocsDrift(args: ComputeDocsDriftArgs): Promise<Docs
         lines.push(`~ ${rel} (committed content differs from a fresh 'meta docs')`);
       }
     }
-    // Committed-but-not-regenerated, inside the directories this command owns. Counted
-    // into `checked` as well as `driftedFiles` so the failing line and the passing line
-    // keep dividing by the same set — the `verify --templates` mistake, where a red run
-    // and a green run reported different denominators for the same project.
-    const freshSet = new Set(fresh);
-    const orphans = listFiles(docsDir)
-      .filter((rel) => !freshSet.has(rel) && isOurs(docsDir, rel))
-      .sort();
+    // Counted into `checked` as well as `driftedFiles` so the failing line and the
+    // passing line keep dividing by the same set — the `verify --templates` mistake,
+    // where a red run and a green run reported different denominators for one project.
     for (const rel of orphans) {
       driftedFiles.push(rel);
       lines.push(`- ${rel} (committed; a fresh 'meta docs' no longer emits it)`);
@@ -214,7 +292,9 @@ export async function computeDocsDrift(args: ComputeDocsDriftArgs): Promise<Docs
       clean: driftedFiles.length === 0,
       driftedFiles: driftedFiles.sort(),
       lines,
-      checked: fresh.length + orphans.length,
+      checked: toCheck.length + orphans.length,
+      ignored: ignoredCount,
+      ignoreReason,
     };
   } finally {
     rmSync(tempRoot, { recursive: true, force: true });

package/src/lib/git-ignore.ts

@@ -0,0 +1,115 @@
+// "Does this project deliberately not commit these files?" — asked of git, once.
+//
+// `check-ignore` is the only reliable answer. Parsing `.gitignore` by hand would have
+// to reimplement precedence, negation and nested ignore files, and the traps are
+// exactly the rules a hand-rolled parser gets wrong: a directory pattern (`docs/`)
+// makes a `!` negation inside it unreachable, and a TRACKED file is never reported
+// ignored no matter what pattern matches it.
+//
+// That last property is what makes this usable as an exemption: a page the project
+// has committed is always compared, whatever its `.gitignore` says. So a rule built
+// on this cannot be used to hide a file the project actually tracks.
+//
+// Paths are evaluated BY NAME — a path need not exist on disk for git to answer. That
+// is deliberate and load-bearing for the docs gate: the exemption is computed over
+// the set a fresh run WOULD emit, so the verdict is identical on a developer box
+// 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";
+
+/** Ignored paths, or the reason the question could not be asked. */
+export type GitIgnoreResult =
+  | { readonly ignored: ReadonlySet<string> }
+  | { readonly unavailable: string };
+
+export interface GitIgnoreOptions {
+  /**
+   * Whether a per-user ignore file (`core.excludesFile`) may contribute to the
+   * verdict.
+   *
+   * `false` for anything whose answer must be a property of the REPOSITORY — a gate
+   * that passes on the author's machine and fails in CI because of a personal ignore
+   * file is worse than no gate. Implemented by pointing `core.excludesFile` at a path
+   * that does not exist, which is the only way to neutralise it.
+   *
+   * `true` where the question is genuinely about this machine — "will this file reach
+   * anyone else?" is answered by every rule that applies here, personal ones included.
+   *
+   * Note `.git/info/exclude` is per-clone and CANNOT be neutralised; it is reported
+   * like any other rule, and the caller's count line is what exposes it.
+   */
+  readonly honourGlobalExcludes: boolean;
+}
+
+/** A path that cannot exist, used to neutralise a per-user excludes file. */
+const NO_SUCH_EXCLUDES_FILE = "/dev/null/metaobjects-no-global-excludes";
+
+/**
+ * Ask git which of `rels` are ignored, relative to `dir`.
+ *
+ * Returns `unavailable` — never throws, never guesses — when git is not on PATH or
+ * `dir` is not inside a repository. A caller must decide what that means for it;
+ * silently treating "cannot say" as "nothing is ignored" is a fallback that lies, and
+ * the callers here say so out loud instead.
+ */
+export function gitIgnored(
+  dir: string,
+  rels: readonly string[],
+  opts: GitIgnoreOptions,
+): GitIgnoreResult {
+  if (rels.length === 0) return { ignored: new Set() };
+
+  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", "--stdin", "-z");
+
+  // 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");
+
+  let res;
+  try {
+    res = spawnSync(gitBin, args, { encoding: "utf-8", input });
+  } catch (err) {
+    return { unavailable: `git could not be run (${(err as Error).message})` };
+  }
+  if (res.error !== undefined) {
+    return { unavailable: "git is not on PATH" };
+  }
+  // 0 = at least one ignored, 1 = none ignored, anything else = not a repository
+  // (or a git error), which is a different fact from "nothing is ignored".
+  if (res.status === 1) return { ignored: new Set() };
+  if (res.status !== 0) {
+    const stderr = (res.stderr ?? "").split("\n")[0]?.trim();
+    return {
+      unavailable:
+        stderr !== undefined && stderr !== ""
+          ? stderr
+          : `'${dir}' is not inside a git repository`,
+    };
+  }
+
+  const ignored = new Set(
+    (res.stdout ?? "").split("\0").map((p) => p.trim()).filter((p) => p !== ""),
+  );
+  return { ignored };
+}
+
+/**
+ * Single-path convenience: true / false / undefined when git cannot say.
+ *
+ * `honourGlobalExcludes` is the caller's decision — see the option's doc.
+ */
+export function isGitIgnored(
+  dir: string,
+  rel: string,
+  opts: GitIgnoreOptions,
+): boolean | undefined {
+  const res = gitIgnored(dir, [rel], opts);
+  if ("unavailable" in res) return undefined;
+  return res.ignored.has(rel.split(sep).join("/"));
+}

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

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
@@ -351,6 +351,63 @@ export async function loadMetaobjectsConfig(projectRoot: string): Promise<Metaob
     } catch { /* no ts-poet adjacent to codegen-ts — leave project resolution in place */ }
   }
 
+  // EVERY DECLARED SUBPATH EXPORT NEEDS ITS OWN ENTRY, because jiti's `alias` matches by
+  // PREFIX and then concatenates the remainder onto the mapped value. The mapped value is
+  // a FILE, so `@metaobjectsdev/codegen-ts/templates/inferred-types` became
+  // `…/codegen-ts/dist/index.js/templates/inferred-types` — a path that has never existed,
+  // named in an error message that mentions neither jiti nor the alias map:
+  //
+  //     Cannot find module '…/@metaobjectsdev/codegen-ts/dist/index.js/templates/inferred-types'
+  //
+  // So every subpath the package deliberately exports was unloadable from an owned
+  // generator, and the documented escape (a dynamic `import()`, which this file's own
+  // comment offers) failed identically, because it falls back to the same broken matcher.
+  // A cold adoption probe hit this retargeting the entity tier off Drizzle and got past it
+  // only by reading this file's compiled output — the subpath holds `fieldTsTypeString`,
+  // the one neutral MetaField→TypeScript mapper, which anyone replacing `renderDrizzleSchema`
+  // needs. `rewriteImportSpecifiers` above was always correct here (it anchors on the
+  // closing quote, so a subpath is left alone); only the alias fallback was wrong, and the
+  // fallback is what an OWNED GENERATOR gets, since only the config file is pre-processed.
+  //
+  // DERIVED from each package's own `exports` map rather than listed. A hand-kept list of
+  // subpaths is the same defect one level up: the package adds an export, nobody edits this
+  // file, and it is unloadable again with the same unrecognisable error. Resolution goes
+  // through `createRequire().resolve`, so the exports map — including its conditions — is
+  // the authority, and a subpath that does not resolve is skipped rather than guessed at.
+  for (const [specifier, resolvedPath] of [...Object.entries(aliasMap)]) {
+    if (!specifier.startsWith("@metaobjectsdev/")) continue;
+    // The package root is the specifier itself; a specifier that is already a subpath
+    // (e.g. ".../generators") contributes nothing further.
+    if (specifier.slice("@metaobjectsdev/".length).includes("/")) continue;
+    // Read the manifest off the FILE SYSTEM by walking up from the resolved entry, not by
+    // requiring `<specifier>/package.json` — these packages do not list `./package.json` in
+    // their own exports map, so requiring it throws ERR_PACKAGE_PATH_NOT_EXPORTED and the
+    // derivation silently produces nothing. (Which it did, on the first cut of this fix:
+    // the gate in test/owned-generator-subpath-import.test.ts stayed red and named the
+    // same impossible path, which is exactly what that assertion is for.)
+    let manifest: { exports?: Record<string, unknown> } | undefined;
+    for (let dir = dirname(resolvedPath); ; dir = dirname(dir)) {
+      try {
+        const parsed = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf8")) as {
+          name?: string;
+          exports?: Record<string, unknown>;
+        };
+        if (parsed.name === specifier) { manifest = parsed; break; }
+      } catch { /* not this directory — keep walking */ }
+      const parent = dirname(dir);
+      if (parent === dir) break;   // filesystem root
+    }
+    if (manifest === undefined) continue;   // no readable manifest — leave normal resolution
+    for (const key of Object.keys(manifest?.exports ?? {})) {
+      if (!key.startsWith("./") || key.includes("*")) continue;
+      const sub = `${specifier}/${key.slice(2)}`;
+      if (aliasMap[sub] !== undefined) continue;   // an explicit CLI_PKG_PATHS entry wins
+      try {
+        aliasMap[sub] = createRequire(resolvedPath).resolve(sub);
+      } catch { /* not resolvable under these conditions — skip rather than invent a path */ }
+    }
+  }
+
   // Pre-process the config file content to rewrite @metaobjectsdev/* import
   // specifiers to resolved absolute paths. This is the primary mechanism that
   // ensures the CLI's own copies are used: jiti's `alias` map is kept below as