@metaobjectsdev/codegen-ts 1.0.3 → 1.0.4-rc.1

package/dist/catalog-gates.d.ts

@@ -0,0 +1,52 @@
+import type { Generator } from "./generator.js";
+import type { GeneratorRegistryEntry } from "./generator-registry.js";
+export declare function stableNameIndex(catalog: Record<string, GeneratorRegistryEntry>): ReadonlyMap<string, string>;
+/**
+ * Warn for each wired generator whose `requires` are not also wired.
+ *
+ * A generator whose name resolves to no catalog entry is an owned or third-party one
+ * with nothing declared, and is skipped in silence — there is no declaration to check
+ * it against.
+ */
+export declare function warnUnsatisfiedRequires(generators: readonly Generator[], catalog: Record<string, GeneratorRegistryEntry>, warn: (message: string) => void): void;
+/**
+ * Warn when two wired `api`-layer generators declare DIFFERENT frameworks.
+ *
+ * Verified before it was written: `routes` emits `<Entity>.routes.ts` and `routes-hono`
+ * emits `<Entity>.routes.hono.ts`. Different paths — so wiring both does not trip the
+ * runner's conflicting-output-path error, does not fail `tsc`, and silently produces two
+ * complete HTTP surfaces over the same entities. Worth saying; not worth refusing.
+ *
+ * **`api` only, and there is deliberately no general per-layer rule.** The `client`
+ * layer disproves one: `@metaobjectsdev/tanstack` declares `react` as a peer, so
+ * `form` (react) + `hooks`/`grid` (tanstack) is the documented, normal composition. An
+ * earlier draft of the design carried "at most one framework per api and per client
+ * layer"; that rule would have forbidden the single most common client selection.
+ */
+export declare function warnMixedApiFrameworks(generators: readonly Generator[], catalog: Record<string, GeneratorRegistryEntry>, warn: (message: string) => void): void;
+/**
+ * Warn on the two halves of a library/generator selection that do not agree.
+ *
+ * A library ships metadata; a generator that keys on that metadata is a separate
+ * choice, and FR-043 §6 deliberately wires neither for you. What it does instead is
+ * refuse to let either half be silently half-done:
+ *
+ *   - **opted in, not wired** — the design is in your model and the code it implies is
+ *     not being generated.
+ *   - **wired, not opted in** — the generator's anchor is a node only that library
+ *     declares, so it will match nothing and emit zero files. Without this line that is
+ *     indistinguishable from "my model has no trace entities yet".
+ *
+ * Both self-extinguish: wire it, or opt in, or remove one. Neither ever fails a build —
+ * an adopter who ejected the library and owns the metadata is in a legitimate state
+ * this cannot see, and a gate that cries wolf gets switched off.
+ *
+ * `optedIn` is the project's selection TOKENS (`["ai", "ai/db"]`); a layer token names
+ * the same library as its bare form.
+ */
+export declare function warnLibrarySelectionMismatch(generators: readonly Generator[], catalog: Record<string, GeneratorRegistryEntry>, manifests: Readonly<Record<string, {
+    generators?: ReadonlyArray<{
+        name: string;
+    }>;
+}>>, optedIn: readonly string[], warn: (message: string) => void): void;
+//# sourceMappingURL=catalog-gates.d.ts.map

package/dist/catalog-gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-gates.d.ts","sourceRoot":"","sources":["../src/catalog-gates.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAqBtE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAC9C,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAuB7B;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC/C,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,IAAI,CAsBN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC/C,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,IAAI,CAyBN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC/C,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;IAAE,UAAU,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAAC,EACrF,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,IAAI,CAwCN"}

package/dist/catalog-gates.js

@@ -0,0 +1,183 @@
+// The post-selection audits `meta gen` runs over the wired suite.
+//
+// Codegen is opt-in, so the selection is the adopter's (increasingly their agent's).
+// That makes `meta gen` the place the selection is CHECKED — not by refusing it, but by
+// naming the ways a legal selection still surprises you:
+//
+//   1. a generator whose output imports a module nothing in the run emits;
+//   2. two `api`-layer generators bringing two different HTTP frameworks;
+//   3. (FR-043) a library opted into whose implied generator is not wired, or a
+//      generator wired whose library is not opted into — the two halves of one choice.
+//
+// Both are WARNINGS, self-extinguishing, never a build failure. An adopter may
+// legitimately have hand-written the other half, and serving Node and edge from one
+// model is a real thing people do. Following the house rule: a gate that cries wolf
+// gets deleted, and a gate nobody can satisfy is worse than no gate.
+/**
+ * Map a CONSTRUCTED generator back to its catalog stable name.
+ *
+ * These are two different names and conflating them is the trap here: the catalog key
+ * is `routes` / `grid-hook`, while the object a factory returns calls itself
+ * `routes-file` / `tanstack-grid-hook`. A gate keyed on `g.name` therefore matches
+ * nothing at all — silently, since a name the catalog does not know is legitimately
+ * skipped as somebody's own generator.
+ *
+ * DERIVED by constructing every catalog factory and reading the name back, not kept as
+ * a table: a table would be a third spelling to maintain, and the failure mode of it
+ * going stale is exactly the silent no-op above. The factories are trivial (that is a
+ * registry invariant `--list` already depends on), and the result is memoized per
+ * catalog object.
+ *
+ * An implementation name produced by two entries is dropped rather than guessed at.
+ */
+const STABLE_NAME_CACHE = new WeakMap();
+export function stableNameIndex(catalog) {
+    const cached = STABLE_NAME_CACHE.get(catalog);
+    if (cached !== undefined)
+        return cached;
+    const index = new Map();
+    const ambiguous = new Set();
+    for (const [stable, entry] of Object.entries(catalog)) {
+        let implName;
+        try {
+            implName = entry.factory().name;
+        }
+        catch {
+            continue; // a factory that cannot construct contributes nothing
+        }
+        if (index.has(implName) && index.get(implName) !== stable)
+            ambiguous.add(implName);
+        index.set(implName, stable);
+        // The stable name maps to itself too, so a generator that already calls itself by
+        // its stable name (and an ejected copy that renamed itself to one) still resolves.
+        if (!index.has(stable))
+            index.set(stable, stable);
+    }
+    for (const name of ambiguous)
+        index.delete(name);
+    STABLE_NAME_CACHE.set(catalog, index);
+    return index;
+}
+/**
+ * Warn for each wired generator whose `requires` are not also wired.
+ *
+ * A generator whose name resolves to no catalog entry is an owned or third-party one
+ * with nothing declared, and is skipped in silence — there is no declaration to check
+ * it against.
+ */
+export function warnUnsatisfiedRequires(generators, catalog, warn) {
+    const index = stableNameIndex(catalog);
+    const stableOf = (g) => index.get(g.name);
+    const wired = new Set(generators.map(stableOf).filter((n) => n !== undefined));
+    for (const g of generators) {
+        const stable = stableOf(g);
+        if (stable === undefined)
+            continue;
+        const entry = catalog[stable];
+        if (entry?.requires === undefined)
+            continue;
+        const missing = entry.requires.filter((dep) => !wired.has(dep));
+        if (missing.length === 0)
+            continue;
+        const list = missing.map((m) => `"${m}"`).join(", ");
+        warn(`"${stable}" is wired but ${list} ${missing.length === 1 ? "is" : "are"} not. ` +
+            `The code "${stable}" emits imports modules ${list} would have emitted, so ` +
+            `tsc will report an unresolved import. Wire ${missing.length === 1 ? "it" : "them"} ` +
+            `(\`meta eject ${missing.join(" ")}\` copies the reference generator${missing.length === 1 ? "" : "s"}), ` +
+            `or keep your own hand-written module${missing.length === 1 ? "" : "s"} at ${missing.length === 1 ? "that path" : "those paths"}.`);
+    }
+}
+/**
+ * Warn when two wired `api`-layer generators declare DIFFERENT frameworks.
+ *
+ * Verified before it was written: `routes` emits `<Entity>.routes.ts` and `routes-hono`
+ * emits `<Entity>.routes.hono.ts`. Different paths — so wiring both does not trip the
+ * runner's conflicting-output-path error, does not fail `tsc`, and silently produces two
+ * complete HTTP surfaces over the same entities. Worth saying; not worth refusing.
+ *
+ * **`api` only, and there is deliberately no general per-layer rule.** The `client`
+ * layer disproves one: `@metaobjectsdev/tanstack` declares `react` as a peer, so
+ * `form` (react) + `hooks`/`grid` (tanstack) is the documented, normal composition. An
+ * earlier draft of the design carried "at most one framework per api and per client
+ * layer"; that rule would have forbidden the single most common client selection.
+ */
+export function warnMixedApiFrameworks(generators, catalog, warn) {
+    const index = stableNameIndex(catalog);
+    const byFramework = new Map();
+    for (const g of generators) {
+        const stable = index.get(g.name);
+        if (stable === undefined)
+            continue;
+        const entry = catalog[stable];
+        if (entry?.layer !== "api" || entry.framework === undefined)
+            continue;
+        const names = byFramework.get(entry.framework) ?? [];
+        names.push(stable);
+        byFramework.set(entry.framework, names);
+    }
+    if (byFramework.size < 2)
+        return;
+    const described = [...byFramework.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([fw, names]) => `${names.sort().map((n) => `"${n}"`).join(" + ")} (${fw})`)
+        .join(" and ");
+    warn(`two api-layer frameworks are wired — ${described}. They emit to DIFFERENT paths, ` +
+        "so nothing conflicts and nothing fails; this run produces two complete HTTP " +
+        "surfaces over the same entities. That is legitimate when you are migrating " +
+        "between them or serving Node and edge from one model — otherwise wire one.");
+}
+/**
+ * Warn on the two halves of a library/generator selection that do not agree.
+ *
+ * A library ships metadata; a generator that keys on that metadata is a separate
+ * choice, and FR-043 §6 deliberately wires neither for you. What it does instead is
+ * refuse to let either half be silently half-done:
+ *
+ *   - **opted in, not wired** — the design is in your model and the code it implies is
+ *     not being generated.
+ *   - **wired, not opted in** — the generator's anchor is a node only that library
+ *     declares, so it will match nothing and emit zero files. Without this line that is
+ *     indistinguishable from "my model has no trace entities yet".
+ *
+ * Both self-extinguish: wire it, or opt in, or remove one. Neither ever fails a build —
+ * an adopter who ejected the library and owns the metadata is in a legitimate state
+ * this cannot see, and a gate that cries wolf gets switched off.
+ *
+ * `optedIn` is the project's selection TOKENS (`["ai", "ai/db"]`); a layer token names
+ * the same library as its bare form.
+ */
+export function warnLibrarySelectionMismatch(generators, catalog, manifests, optedIn, warn) {
+    const index = stableNameIndex(catalog);
+    const wired = new Set(generators.map((g) => index.get(g.name)).filter((n) => n !== undefined));
+    const selected = new Set(optedIn.map((t) => t.split("/")[0]));
+    for (const [library, manifest] of Object.entries(manifests)) {
+        const implied = (manifest.generators ?? []).map((g) => g.name);
+        if (implied.length === 0)
+            continue;
+        if (selected.has(library)) {
+            const notWired = implied.filter((n) => !wired.has(n));
+            if (notWired.length > 0) {
+                warn(`library "${library}" is opted in and implies ${notWired.map((n) => `"${n}"`).join(", ")}, ` +
+                    `which ${notWired.length === 1 ? "is" : "are"} not wired. The design is in your model; ` +
+                    `the code it implies is not being generated. Wire it, or ignore this if you are ` +
+                    `taking the metadata alone.`);
+            }
+            continue;
+        }
+        // Not opted in: name any of its generators that ARE wired. Checked per library
+        // rather than per generator so a name two libraries imply is not reported twice
+        // when one of them is selected.
+        const orphaned = implied.filter((n) => wired.has(n) && !impliedByAnySelected(n, manifests, selected));
+        if (orphaned.length > 0) {
+            warn(`${orphaned.map((n) => `"${n}"`).join(", ")} ${orphaned.length === 1 ? "is" : "are"} wired, ` +
+                `but library "${library}" — which declares the node ${orphaned.length === 1 ? "it keys" : "they key"} ` +
+                `on — is not opted in, so ${orphaned.length === 1 ? "it will" : "they will"} match nothing and emit ` +
+                `no files. Add "${library}" to \`libraries\` in .metaobjects/config.json, or unwire ` +
+                `${orphaned.length === 1 ? "it" : "them"}.`);
+        }
+    }
+}
+function impliedByAnySelected(generator, manifests, selected) {
+    return [...selected].some((lib) => (manifests[lib]?.generators ?? []).some((g) => g.name === generator));
+}
+//# sourceMappingURL=catalog-gates.js.map

package/dist/catalog-gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-gates.js","sourceRoot":"","sources":["../src/catalog-gates.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -24,6 +24,30 @@ export declare const GENERATED_HEADER = "@generated by @metaobjectsdev/codegen-t
  * finding the artifact it exists to protect, silently.
  */
 export declare const NAMES_FILE_SUFFIX = ".names.ts";
+/**
+ * Line 3 of every generated file's header — where an adopter's own code goes.
+ *
+ * It used to read `Customize via <Name>.extra.ts in this directory`, and on the routes
+ * emitters `(e.g., auth, additional handlers)`. Both asserted a plugin point this engine
+ * does not have — the same claim `EXTRA_SUFFIX` was deleted above for implying. The
+ * convention is real and documented (`docs/features/own-your-codegen.md`): a sibling file
+ * is safe because `meta gen` writes only the paths it records, and the barrel is built
+ * from the model so it never re-exports one. What is NOT real is anything importing it
+ * for you, and "Customize via" is exactly the verb that promises otherwise.
+ *
+ * #367 is the measured cost: an agent building a real API read `(e.g., auth)` on a routes
+ * file, went looking for the seam, found none, and deleted `routesFile()` from its config
+ * rather than mount five unauthenticated endpoints over a password-hash table. The auth
+ * seam it needed exists — a parent plugin scope's `preHandler` (Fastify) or `app.use`
+ * (Hono) — and the routes emitters now say so in the handler's own JSDoc, gated by
+ * `runtime-ts/test/route-auth-seam.test.ts`.
+ *
+ * Spelled once because the literal had been copy-pasted to ten TypeScript emitters plus
+ * Python's `generated_header`, which is how one wrong sentence reached every generated
+ * file in the estate. `sidecarName` is the emitted module name, extension included
+ * (`Order.extra.ts`, `OrderForm.extra.tsx`).
+ */
+export declare function sidecarLine(sidecarName: string): string;
 /** Default outDir used by tests + as a sane default for generate(). */
 export declare const DEFAULT_OUT_DIR = "./src/db/entities";
 /** One retired codegen-control attribute, paired with what an adopter does instead. */

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,6CAA6C,CAAC;AAE3E;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAU7C,uEAAuE;AACvE,eAAO,MAAM,eAAe,sBAAsB,CAAC;AA8BnD,uFAAuF;AACvF,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAmCrD,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,6CAA6C,CAAC;AAE3E;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAU7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,uEAAuE;AACvE,eAAO,MAAM,eAAe,sBAAsB,CAAC;AA8BnD,uFAAuF;AACvF,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAmCrD,CAAC"}

package/dist/constants.js

@@ -32,6 +32,32 @@ export const NAMES_FILE_SUFFIX = ".names.ts";
 // records in `.gen-state/.hashes.json` — not because of its name — and the generated
 // barrel is built from the model, so it does not re-export it. Say that in prose;
 // do not re-add a constant that suggests the engine knows the name.
+/**
+ * Line 3 of every generated file's header — where an adopter's own code goes.
+ *
+ * It used to read `Customize via <Name>.extra.ts in this directory`, and on the routes
+ * emitters `(e.g., auth, additional handlers)`. Both asserted a plugin point this engine
+ * does not have — the same claim `EXTRA_SUFFIX` was deleted above for implying. The
+ * convention is real and documented (`docs/features/own-your-codegen.md`): a sibling file
+ * is safe because `meta gen` writes only the paths it records, and the barrel is built
+ * from the model so it never re-exports one. What is NOT real is anything importing it
+ * for you, and "Customize via" is exactly the verb that promises otherwise.
+ *
+ * #367 is the measured cost: an agent building a real API read `(e.g., auth)` on a routes
+ * file, went looking for the seam, found none, and deleted `routesFile()` from its config
+ * rather than mount five unauthenticated endpoints over a password-hash table. The auth
+ * seam it needed exists — a parent plugin scope's `preHandler` (Fastify) or `app.use`
+ * (Hono) — and the routes emitters now say so in the handler's own JSDoc, gated by
+ * `runtime-ts/test/route-auth-seam.test.ts`.
+ *
+ * Spelled once because the literal had been copy-pasted to ten TypeScript emitters plus
+ * Python's `generated_header`, which is how one wrong sentence reached every generated
+ * file in the estate. `sidecarName` is the emitted module name, extension included
+ * (`Order.extra.ts`, `OrderForm.extra.tsx`).
+ */
+export function sidecarLine(sidecarName) {
+    return `// Extend in your own module (e.g. ${sidecarName}) — nothing imports it for you.\n`;
+}
 /** Default outDir used by tests + as a sane default for generate(). */
 export const DEFAULT_OUT_DIR = "./src/db/entities";
 /** Every retired codegen-control attribute. Read ONLY by the `meta gen` warning. */

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAElC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,0CAA0C,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAE7C,qFAAqF;AACrF,kFAAkF;AAClF,uFAAuF;AACvF,iFAAiF;AACjF,qFAAqF;AACrF,kFAAkF;AAClF,oEAAoE;AAEpE,uEAAuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAsCnD,oFAAoF;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAAkC;IAClE;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EACT,qFAAqF;YACrF,mGAAmG;KACtG;IACD;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,kFAAkF;YAClF,4EAA4E;YAC5E,8DAA8D;KACjE;IACD;QACE,IAAI,EAAE,UAAU;QAChB,WAAW,EACT,mFAAmF;YACnF,yFAAyF;KAC5F;IACD;QACE,IAAI,EAAE,UAAU;QAChB,WAAW,EACT,wFAAwF;YACxF,qFAAqF;YACrF,yFAAyF;YACzF,kFAAkF;KACrF;IACD;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EACT,yFAAyF;YACzF,8EAA8E;YAC9E,mEAAmE;KACtE;CACO,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAElC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,0CAA0C,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAE7C,qFAAqF;AACrF,kFAAkF;AAClF,uFAAuF;AACvF,iFAAiF;AACjF,qFAAqF;AACrF,kFAAkF;AAClF,oEAAoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,WAAW,CAAC,WAAmB;IAC7C,OAAO,sCAAsC,WAAW,mCAAmC,CAAC;AAC9F,CAAC;AAED,uEAAuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAsCnD,oFAAoF;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAAkC;IAClE;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EACT,qFAAqF;YACrF,mGAAmG;KACtG;IACD;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,kFAAkF;YAClF,4EAA4E;YAC5E,8DAA8D;KACjE;IACD;QACE,IAAI,EAAE,UAAU;QAChB,WAAW,EACT,mFAAmF;YACnF,yFAAyF;KAC5F;IACD;QACE,IAAI,EAAE,UAAU;QAChB,WAAW,EACT,wFAAwF;YACxF,qFAAqF;YACrF,yFAAyF;YACzF,kFAAkF;KACrF;IACD;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EACT,yFAAyF;YACzF,8EAA8E;YAC9E,mEAAmE;KACtE;CACO,CAAC"}

package/dist/generator-registry.d.ts

@@ -1,8 +1,41 @@
 import type { Generator } from "./generator.js";
+import type { MetaobjectsGenConfig } from "./metaobjects-config.js";
 export type GeneratorTier = "native" | "neutral";
+/**
+ * The six layers a generator can belong to — the axis an adopter SELECTS BY.
+ *
+ * Cross-port: `layer` is gated by every port's registry-conformance test against
+ * `fixtures/generator-registry-conformance/registry.json`, exactly as `tier` is, so a
+ * polyglot agent groups the catalog by the same words everywhere.
+ *
+ * Six, not ten. The first four are app-shape decisions a builder makes; `docs` is on by
+ * default (`meta docs`); `capability` holds the ones the MODEL has already made — nobody
+ * picks `prompt-render` by browsing a taxonomy, they pick it because they declared a
+ * `template.prompt`, which `meta gen --list --probe` reports with a real file count. A
+ * layer with one member does no grouping work, so do not split `capability` to tidy it.
+ */
+export declare const GENERATOR_LAYERS: readonly ["model", "persistence", "api", "client", "docs", "capability"];
+export type Layer = (typeof GENERATOR_LAYERS)[number];
+/**
+ * The framework a generator's OUTPUT targets. Absent = framework-neutral.
+ *
+ * Exclusivity is an ADVISORY and only on the `api` layer (spec §8a): `routes` and
+ * `routes-hono` emit to different paths, so wiring both is legal and silently produces
+ * two HTTP surfaces — worth a warning, never an error, because migrating between them is
+ * legitimate. There is NO general per-layer rule: `@metaobjectsdev/tanstack` peers on
+ * `react`, so `form` (react) + `hooks`/`grid` (tanstack) is the intended composition.
+ */
+export type GeneratorFramework = "fastify" | "hono" | "react" | "tanstack";
 export interface GeneratorRegistryEntry {
     /** Stable, cross-port-consistent id. Equals the registry map key. */
     name: string;
+    /**
+     * Catalog discriminator. Today every entry is a generator; FR-043 adds
+     * `kind: "library"` rows to the same table rather than building a parallel one.
+     */
+    kind: "generator";
+    /** The selection axis — see {@link GENERATOR_LAYERS}. Gated cross-port. */
+    layer: Layer;
     /** One-line (no newline) human description for `--list`. */
     description: string;
     /** "native" = recommended `meta gen` suite; "neutral" = `meta docs`-owned. */
@@ -11,6 +44,46 @@ export interface GeneratorRegistryEntry {
     factory: () => Generator;
     /** Optional one-line options summary for `--list`. */
     options?: string;
+    /** The framework this generator's OUTPUT targets. Absent = framework-neutral. */
+    framework?: GeneratorFramework;
+    /**
+     * Stable names whose emitted output THIS generator's output imports.
+     *
+     * Resolved, not trusted: a gate dry-runs every generator, resolves each emitted
+     * RELATIVE import back to whichever generator emits that path, and asserts the result
+     * is a subset of this list — so a generator that quietly starts depending on `entity`
+     * cannot ship claiming it depends on nothing.
+     */
+    requires?: readonly string[];
+    /**
+     * The `@metaobjectsdev` runtime packages the EMITTED code imports.
+     *
+     * PLURAL, against the design's first sketch, because the emitted code is: an
+     * `output-parser` module imports `@metaobjectsdev/metadata`, `/render` AND
+     * `/runtime-ts`, and a `hooks` module imports `/runtime-web` and `/tanstack`. A
+     * singular field would have forced two of the three to go undeclared, which is the
+     * exact under-declaration the gate exists to catch. Resolved, not trusted — the
+     * emitted files are read back and every `@metaobjectsdev` import must appear here.
+     */
+    runtimePackages?: readonly string[];
+    /**
+     * Third-party packages the EMITTED code imports.
+     *
+     * Per generator rather than derived from {@link runtimePackages}, because
+     * `@metaobjectsdev/runtime-ts`'s peers are a union (drizzle-orm, fastify, hono, kysely,
+     * zod) — deriving per package would tell someone ejecting `entity` to install both
+     * Fastify and Hono. Version RANGES are read from the runtime package's own
+     * `peerDependencies`, never written here. Gated the same way `requires` is.
+     */
+    runtimePeers?: readonly string[];
+    /**
+     * Config keys this generator reads. Typed against the real config so a renamed key
+     * breaks the build instead of going quietly stale — the same "resolved, not trusted"
+     * doctrine as `requires`, obtained here for free from the type system.
+     */
+    configKeys?: readonly (keyof MetaobjectsGenConfig)[];
+    /** True iff this package ships a `src/reference/<name>.ts` for `meta eject`. */
+    ejectable: boolean;
     /** Optional note — used to point neutral entries at their canonical door. */
     note?: string;
 }

package/dist/generator-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator-registry.d.ts","sourceRoot":"","sources":["../src/generator-registry.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAyBhD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjD,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,IAAI,EAAE,aAAa,CAAC;IACpB,kFAAkF;IAClF,OAAO,EAAE,MAAM,SAAS,CAAC;IACzB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAeD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAuIpE,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,cAAc,IAAI,sBAAsB,EAAE,CAQzD;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAE3E"}
+{"version":3,"file":"generator-registry.d.ts","sourceRoot":"","sources":["../src/generator-registry.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AA2BpE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,0EAOnB,CAAC;AACX,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAE3E,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,EAAE,WAAW,CAAC;IAClB,2EAA2E;IAC3E,KAAK,EAAE,KAAK,CAAC;IACb,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,IAAI,EAAE,aAAa,CAAC;IACpB,kFAAkF;IAClF,OAAO,EAAE,MAAM,SAAS,CAAC;IACzB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC,MAAM,oBAAoB,CAAC,EAAE,CAAC;IACrD,gFAAgF;IAChF,SAAS,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAoBD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAgPpE,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,cAAc,IAAI,sBAAsB,EAAE,CAQzD;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAE3E"}