@metaobjectsdev/codegen-ts 0.12.5-rc.1 → 0.13.0-rc.1

package/dist/template-codegen/template-data.js

@@ -0,0 +1,60 @@
+import { FIELD_ATTR_VALUES, FIELD_SUBTYPE_ENUM } from "@metaobjectsdev/metadata";
+import { effectivePackage } from "../docs-paths.js";
+/** The effective package of an object — its own package OR the file-default
+ *  folded into `resolutionKey()`. `entity.package` alone is usually undefined
+ *  (object fqn() stays bare), so all package reads go through here. */
+export function packageOf(entity) {
+    return effectivePackage(entity) ?? "";
+}
+function fieldData(field) {
+    const d = {
+        name: field.name,
+        type: field.subType,
+        required: field.isRequired,
+        isArray: field.isArray === true,
+    };
+    if (typeof field.maxLength === "number")
+        d.maxLength = field.maxLength;
+    if (field.subType === FIELD_SUBTYPE_ENUM) {
+        const vals = field.attr(FIELD_ATTR_VALUES);
+        if (Array.isArray(vals))
+            d.enumValues = vals.map((v) => String(v));
+    }
+    return d;
+}
+export function buildEntityTemplateData(entity) {
+    return {
+        name: entity.name,
+        package: packageOf(entity),
+        fields: entity.fields().map(fieldData),
+        identities: entity.identities().map((i) => ({ kind: i.subType, fields: [...i.fields] })),
+        relationships: entity.relationships().map((r) => ({
+            name: r.name,
+            cardinality: r.cardinality ?? "",
+            targetRef: r.objectRef ?? "",
+        })),
+    };
+}
+export function buildPackageTemplateData(pkg, entities) {
+    return { package: pkg, entities: entities.map(buildEntityTemplateData) };
+}
+/** Groups concrete (non-abstract) objects by package — packages ascending,
+ *  entities in `root.objects()` order. Abstract objects never emit instance
+ *  artifacts, so they are excluded. */
+export function buildModelTemplateData(root) {
+    const concrete = root.objects().filter((o) => o.isAbstract !== true);
+    const byPkg = new Map();
+    for (const o of concrete) {
+        const pkg = packageOf(o);
+        let bucket = byPkg.get(pkg);
+        if (bucket === undefined) {
+            bucket = [];
+            byPkg.set(pkg, bucket);
+        }
+        bucket.push(o);
+    }
+    return {
+        packages: [...byPkg.keys()].sort().map((pkg) => buildPackageTemplateData(pkg, byPkg.get(pkg))),
+    };
+}
+//# sourceMappingURL=template-data.js.map

package/dist/template-codegen/template-data.js.map

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

package/dist/template-codegen/template-spec.d.ts

@@ -0,0 +1,20 @@
+import { type RenderFormat } from "@metaobjectsdev/render";
+import type { Generator } from "../generator.js";
+import { type TemplateScope } from "../generators/template-generator.js";
+export interface TemplateSpecEntry {
+    name: string;
+    template: string;
+    scope: TemplateScope;
+    outputPattern: string;
+    format?: RenderFormat;
+    target?: string;
+}
+export interface TemplateSpecFile {
+    generators: TemplateSpecEntry[];
+}
+/** Validate + narrow an untyped JSON value into a TemplateSpecFile. Throws on
+ *  any shape violation (missing/empty required string, bad scope, non-object). */
+export declare function parseTemplateSpec(json: unknown): TemplateSpecFile;
+/** Map a parsed spec into runnable Generators (one templateGenerator per entry). */
+export declare function templateSpecToGenerators(spec: TemplateSpecFile): Generator[];
+//# sourceMappingURL=template-spec.d.ts.map

package/dist/template-codegen/template-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-spec.d.ts","sourceRoot":"","sources":["../../src/template-codegen/template-spec.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAK5F,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,gBAAgB;IAAG,UAAU,EAAE,iBAAiB,EAAE,CAAC;CAAE;AAMtE;kFACkF;AAClF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CAkCjE;AAED,oFAAoF;AACpF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAAE,CAW5E"}

package/dist/template-codegen/template-spec.js

@@ -0,0 +1,57 @@
+// The declarative JSON template-spec the CLI ports (C#/Python) consume, and TS
+// can spread into `generators`. The JSON shape is the cross-port contract
+// (SP-1 §4); a JSON Schema (template-spec.schema.json) sits beside it.
+import { ESCAPERS } from "@metaobjectsdev/render";
+import { templateGenerator } from "../generators/template-generator.js";
+const SCOPES = ["perEntity", "perPackage", "perModel"];
+const FORMATS = Object.keys(ESCAPERS);
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Validate + narrow an untyped JSON value into a TemplateSpecFile. Throws on
+ *  any shape violation (missing/empty required string, bad scope, non-object). */
+export function parseTemplateSpec(json) {
+    if (!isRecord(json) || !Array.isArray(json.generators)) {
+        throw new Error("template-spec: expected an object with a `generators` array");
+    }
+    const generators = json.generators.map((raw, i) => {
+        if (!isRecord(raw))
+            throw new Error(`template-spec generators[${i}]: expected an object`);
+        for (const key of ["name", "template", "scope", "outputPattern"]) {
+            if (typeof raw[key] !== "string" || raw[key] === "") {
+                throw new Error(`template-spec generators[${i}]: missing or empty required string '${key}'`);
+            }
+        }
+        if (!SCOPES.includes(raw.scope)) {
+            throw new Error(`template-spec generators[${i}]: scope must be one of ${SCOPES.join(" | ")}, got '${String(raw.scope)}'`);
+        }
+        const entry = {
+            name: raw.name,
+            template: raw.template,
+            scope: raw.scope,
+            outputPattern: raw.outputPattern,
+        };
+        if (raw.format !== undefined) {
+            if (typeof raw.format !== "string" || !FORMATS.includes(raw.format)) {
+                throw new Error(`template-spec generators[${i}]: format must be one of ${FORMATS.join(" | ")}, got '${String(raw.format)}'`);
+            }
+            entry.format = raw.format;
+        }
+        if (typeof raw.target === "string")
+            entry.target = raw.target;
+        return entry;
+    });
+    return { generators };
+}
+/** Map a parsed spec into runnable Generators (one templateGenerator per entry). */
+export function templateSpecToGenerators(spec) {
+    return spec.generators.map((e) => templateGenerator({
+        name: e.name,
+        template: e.template,
+        scope: e.scope,
+        outputPattern: e.outputPattern,
+        ...(e.format !== undefined ? { format: e.format } : {}),
+        ...(e.target !== undefined ? { target: e.target } : {}),
+    }));
+}
+//# sourceMappingURL=template-spec.js.map

package/dist/template-codegen/template-spec.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/codegen-ts",
-  "version": "0.12.5-rc.1",
+  "version": "0.13.0-rc.1",
   "description": "TypeScript codegen engine for MetaObjects — emits Drizzle, Zod, and Fastify artifacts.",
   "type": "module",
   "main": "./dist/index.js",
@@ -111,8 +111,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.12.5-rc.1",
-    "@metaobjectsdev/render": "0.12.5-rc.1",
+    "@metaobjectsdev/metadata": "0.13.0-rc.1",
+    "@metaobjectsdev/render": "0.13.0-rc.1",
     "@biomejs/js-api": "^0.7.0",
     "@biomejs/wasm-nodejs": "^1.9.4",
     "ts-poet": "^6.10.0"
@@ -123,9 +123,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",
-    "@metaobjectsdev/codegen-ts-react": "0.12.5-rc.1",
-    "@metaobjectsdev/migrate-ts": "0.12.5-rc.1",
-    "@metaobjectsdev/runtime-ts": "0.12.5-rc.1",
+    "@metaobjectsdev/codegen-ts-react": "0.13.0-rc.1",
+    "@metaobjectsdev/migrate-ts": "0.13.0-rc.1",
+    "@metaobjectsdev/runtime-ts": "0.13.0-rc.1",
     "bun-types": "latest",
     "drizzle-orm": "^0.36.0",
     "hono": "^4.6.0",

package/src/generator.ts

@@ -1,6 +1,7 @@
 import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
 import type { RenderContext } from "./render-context.js";
 import type { ResolvedGenConfig } from "./metaobjects-config.js";
+import { effectivePackage } from "./docs-paths.js";
 
 export interface EmittedFile {
   /** Path relative to ResolvedGenConfig.outDir. */
@@ -73,7 +74,9 @@ export function perEntity(
   };
 }
 
-/** Called once with all matching entities. Use for barrels and cross-entity files. */
+/** Called once with all matching entities. Use for barrels and cross-entity files.
+ *  @deprecated Use {@link perModel} — "run" is ambiguous under multi-target output
+ *  (it reads as "per target"); `perModel` names the data scope (the whole model). */
 export function oncePerRun(
   fn: (entities: MetaObject[], ctx: GenContext) =>
     | EmittedFile
@@ -86,3 +89,35 @@ export function oncePerRun(
     return Array.isArray(result) ? result : [result];
   };
 }
+
+/** App-scope convenience — run `fn` once over the whole model (all matched
+ *  entities). The canonical name for the one-shot scope (replaces `oncePerRun`). */
+export const perModel = oncePerRun;
+
+/** One-file-per-package convenience. Groups matched entities by `package`, runs
+ *  `fn` once per package — packages ascending, entities keeping `ctx.entities`
+ *  order. The package scope from codegen-concepts §10 (object + model already
+ *  exist via perEntity + perModel). */
+export function perPackage(
+  fn: (pkg: string, entities: MetaObject[], ctx: GenContext) =>
+    | EmittedFile
+    | EmittedFile[]
+    | Promise<EmittedFile | EmittedFile[]>,
+): (ctx: GenContext) => Promise<EmittedFile[]> {
+  return async (ctx) => {
+    const matched = ctx.entities.filter(ctx.matches);
+    const byPkg = new Map<string, MetaObject[]>();
+    for (const e of matched) {
+      const pkg = effectivePackage(e) ?? "";
+      let bucket = byPkg.get(pkg);
+      if (bucket === undefined) { bucket = []; byPkg.set(pkg, bucket); }
+      bucket.push(e);
+    }
+    const out: EmittedFile[] = [];
+    for (const pkg of [...byPkg.keys()].sort()) {
+      const r = await fn(pkg, byPkg.get(pkg)!, ctx);
+      out.push(...(Array.isArray(r) ? r : [r]));
+    }
+    return out;
+  };
+}

package/src/generators/index.ts

@@ -1,8 +1,19 @@
+// ADR-0034 scaffold-and-own — these built-in generator factories remain the engine's
+// internal composers, but importing them from `@metaobjectsdev/codegen-ts/generators`
+// into a consumer's `metaobjects.config.ts` is DEPRECATED. The recommended path is to
+// own copyable reference templates in your repo (`meta init` scaffolds them into
+// `codegen/generators/*.ts`) and import those locally. This package export will be
+// removed in a future major. See spec/decisions/ADR-0034-codegen-scaffold-and-own.md.
+
+/** @deprecated ADR-0034 — own a copy instead: `import { entityFile } from "./codegen/generators/entity"` (scaffolded by `meta init`). */
 export { entityFile, type EntityFileOpts } from "./entity-file.js";
+/** @deprecated ADR-0034 — own a copy instead: `import { queriesFile } from "./codegen/generators/queries"` (scaffolded by `meta init`). */
 export { queriesFile, type QueriesFileOpts } from "./queries-file.js";
 export { callableFile, type CallableFileOpts } from "./callable-file.js";
+/** @deprecated ADR-0034 — own a copy instead: `import { routesFile } from "./codegen/generators/routes"` (scaffolded by `meta init`). */
 export { routesFile, type RoutesFileOpts } from "./routes-file.js";
 export { routesFileHono, type RoutesFileHonoOpts } from "./routes-file-hono.js";
+/** @deprecated ADR-0034 — own a copy instead: `import { barrel } from "./codegen/generators/barrel"` (scaffolded by `meta init`). */
 export { barrel, type BarrelOpts } from "./barrel.js";
 /** @deprecated ADR-0021 D1 — neutral artifact owned by `meta docs` (ADR-0020); not part of the recommended `meta gen` suite. */
 export { mermaidErDiagram, type MermaidErOptions } from "./mermaid-er.js";

package/src/generators/template-generator.ts

@@ -17,6 +17,17 @@ import type { MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
 import { render, type Provider, type RenderFormat } from "@metaobjectsdev/render";
 import type { Generator, GenContext, EmittedFile, GeneratorFactory } from "../generator.js";
 import { projectProvider } from "../render-engine/framework-provider.js";
+import { expandOutputPattern } from "../template-codegen/output-pattern.js";
+import {
+  buildEntityTemplateData,
+  buildPackageTemplateData,
+  buildModelTemplateData,
+  packageOf,
+} from "../template-codegen/template-data.js";
+
+/** The three built-in walk scopes (SP-1 §3.1). Same vocabulary as the engine
+ *  helpers perEntity/perPackage/perModel. */
+export type TemplateScope = "perEntity" | "perPackage" | "perModel";
 
 export type TemplateFormat = RenderFormat;
 
@@ -34,8 +45,17 @@ export interface TemplateGeneratorOpts {
   name: string;
   /** Walk the loaded metadata tree and produce `{ data, outputPath }` tuples
    *  — one per emitted file. Pattern A (per-entity), pattern B (single
-   *  aggregator), pattern C (mixed), pattern D (filter inline) all fit. */
-  walk: (root: MetaRoot) => TemplateWalkResult[] | Promise<TemplateWalkResult[]>;
+   *  aggregator), pattern C (mixed), pattern D (filter inline) all fit.
+   *  Mutually exclusive with `scope` — provide exactly one. The power-user
+   *  escape hatch; most consumers declare a `scope` + `outputPattern` instead. */
+  walk?: (root: MetaRoot) => TemplateWalkResult[] | Promise<TemplateWalkResult[]>;
+  /** Built-in walk scope (SP-1 §3.1) — declarative alternative to `walk`. The
+   *  generator derives the neutral data dict (template-data.ts) per unit and
+   *  names each file via `outputPattern`. Mutually exclusive with `walk`. */
+  scope?: TemplateScope;
+  /** Output path pattern for the built-in `scope` walk: `{name}` `{Name}`
+   *  `{package}` (SP-1 §3.3). Required with `scope`; ignored with `walk`. */
+  outputPattern?: string;
   /** Template reference. Resolved by the configured Provider chain — by
    *  default the project's `templates/<ref>.mustache` first, then the
    *  framework defaults at `codegen-ts/templates/<ref>.mustache`. */
@@ -57,10 +77,53 @@ export interface TemplateGeneratorOpts {
   target?: string;
 }
 
+/** Derive a `walk` from a built-in scope + output pattern. Each scope yields the
+ *  neutral data dict for its unit and names the file via the pattern. */
+function scopeWalk(
+  scope: TemplateScope,
+  pattern: string,
+): (root: MetaRoot) => TemplateWalkResult[] {
+  return (root) => {
+    const concrete = root.objects().filter((o) => o.isAbstract !== true);
+    if (scope === "perEntity") {
+      return concrete.map((e) => ({
+        data: buildEntityTemplateData(e),
+        outputPath: expandOutputPattern(pattern, { name: e.name, package: packageOf(e) }),
+      }));
+    }
+    if (scope === "perPackage") {
+      const byPkg = new Map<string, MetaObject[]>();
+      for (const o of concrete) {
+        const pkg = packageOf(o);
+        let bucket = byPkg.get(pkg);
+        if (bucket === undefined) { bucket = []; byPkg.set(pkg, bucket); }
+        bucket.push(o);
+      }
+      return [...byPkg.keys()].sort().map((pkg) => ({
+        data: buildPackageTemplateData(pkg, byPkg.get(pkg)!),
+        outputPath: expandOutputPattern(pattern, { package: pkg }),
+      }));
+    }
+    // perModel — one file over the whole model.
+    return [{ data: buildModelTemplateData(root), outputPath: expandOutputPattern(pattern, {}) }];
+  };
+}
+
 export const templateGenerator = function templateGenerator(
   opts: TemplateGeneratorOpts,
 ): Generator {
   const fmt: TemplateFormat = opts.format ?? "text";
+  const hasWalk = typeof opts.walk === "function";
+  const hasScope = opts.scope !== undefined;
+  if (hasWalk === hasScope) {
+    throw new Error(
+      `templateGenerator(${opts.name}): provide exactly one of \`walk\` or (\`scope\` + \`outputPattern\`)`,
+    );
+  }
+  if (hasScope && (opts.outputPattern === undefined || opts.outputPattern === "")) {
+    throw new Error(`templateGenerator(${opts.name}): \`scope\` requires a non-empty \`outputPattern\``);
+  }
+  const walk = hasWalk ? opts.walk! : scopeWalk(opts.scope!, opts.outputPattern!);
   const generator: Generator = {
     name: opts.name,
     async generate(ctx: GenContext): Promise<EmittedFile[]> {
@@ -77,7 +140,7 @@ export const templateGenerator = function templateGenerator(
         );
         provider = projectProvider(process.cwd());
       }
-      const walkRes = await opts.walk(ctx.loadedRoot);
+      const walkRes = await walk(ctx.loadedRoot);
       const files: EmittedFile[] = [];
       for (const { data, outputPath } of walkRes) {
         let content: string;

package/src/index.ts

@@ -7,7 +7,27 @@ export { runGen } from "./runner.js";
 export type { RunGenOpts, RunGenResult } from "./runner.js";
 
 export type { Generator, GenContext, EmittedFile, GeneratorFactory } from "./generator.js";
-export { perEntity, oncePerRun } from "./generator.js";
+export { perEntity, perPackage, perModel, oncePerRun } from "./generator.js";
+
+// SP-1 declarative Mustache template-codegen — scope walks, neutral data dict,
+// output-pattern, and the JSON template-spec the CLI ports reuse.
+export { expandOutputPattern } from "./template-codegen/output-pattern.js";
+export {
+  buildEntityTemplateData,
+  buildPackageTemplateData,
+  buildModelTemplateData,
+} from "./template-codegen/template-data.js";
+export type {
+  FieldTemplateData,
+  EntityTemplateData,
+  IdentityTemplateData,
+  RelationshipTemplateData,
+  PackageTemplateData,
+  ModelTemplateData,
+} from "./template-codegen/template-data.js";
+export { parseTemplateSpec, templateSpecToGenerators } from "./template-codegen/template-spec.js";
+export type { TemplateSpecEntry, TemplateSpecFile } from "./template-codegen/template-spec.js";
+export type { TemplateScope } from "./generators/template-generator.js";
 
 // ADR-0021 D3 — stable-name generator registry + discoverability surface.
 export {
@@ -68,6 +88,29 @@ export { isTphDiscriminatorBase, tphConcreteSubtypes, collectTphSubtypeFields, t
 export type { TphPlan, TphSubtypePlan } from "./templates/tph-discriminator.js";
 export { isTphSubtype, tphDiscriminatorPin } from "./templates/zod-validators.js";
 
+// ADR-0034 reference-template composition helpers. Promoted to the public engine
+// surface so a COPIED reference generator (src/reference/*.ts → consumer's
+// codegen/generators/*.ts) imports only `@metaobjectsdev/codegen-ts`, never a
+// package-internal relative path. These are the assembly pieces the built-in
+// entity/queries composers use; the reference templates relocate that assembly.
+export { renderTphDiscriminatorUnion } from "./templates/tph-discriminator.js";
+export { hasWritableRdbSource } from "./source-detect.js";
+export { renderSharedEnumsFile, SHARED_ENUMS_BASENAME } from "./templates/enums-file.js";
+
+// ADR-0034 scaffold-and-own — reader for the copyable reference generators in
+// `src/reference/*.ts`. `meta init` uses this to copy them into the consumer's repo.
+export { resolveReferenceRoot, readReferenceTemplate, REFERENCE_GENERATOR_NAMES } from "./reference-templates.js";
+export type { ReferenceGeneratorName } from "./reference-templates.js";
+
+export {
+  renderFindByIdFn,
+  renderListFn,
+  renderCreateFn,
+  renderUpdateFn,
+  renderDeleteByIdFn,
+  getPkInfo,
+} from "./templates/queries.js";
+
 // Built-in template render functions — the composition seam for adopters who
 // want to call a built-in template, then post-process / append to its output
 // from their own Generator (added to `generators: [...]`) WITHOUT forking the

package/src/reference/barrel.ts

@@ -0,0 +1,66 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/barrel.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts instead of from the package:
+//   import { barrel } from "./codegen/generators/barrel";
+//
+// use-when:      you want a single `index.ts` re-exporting every generated entity module.
+// emits:         <target>/index.ts with one `export * from "./<Entity>"` per entity, alphabetical.
+// customize:     the export form (star vs named), ordering, grouping by package, what to include/exclude.
+// composes-with: entity.ts (this re-exports the files entity.ts emits).
+//
+// Everything below imports ONLY from `@metaobjectsdev/codegen-ts` (the stable engine).
+// The composition (`renderBarrel`) is inlined here so you own it — change it freely.
+
+import {
+  oncePerRun,
+  type Generator,
+  type GeneratorFactory,
+  type ExtStyle,
+  type ResolvedTarget,
+  barrelModuleSpecifier,
+  formatTs,
+  GENERATED_HEADER,
+} from "@metaobjectsdev/codegen-ts";
+
+interface BarrelEntry {
+  name: string;
+  package: string | undefined;
+}
+
+// --- composition (OWNED) — the barrel file body. Customize freely. ---
+function renderBarrel(
+  entries: BarrelEntry[],
+  extStyle: ExtStyle,
+  selfTarget: ResolvedTarget,
+  entityModuleTarget: ResolvedTarget,
+): string {
+  const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+  const exports = sorted
+    .map((e) => `export * from ${JSON.stringify(barrelModuleSpecifier(selfTarget, entityModuleTarget, e.package, e.name, extStyle))};`)
+    .join("\n");
+  return `// ${GENERATED_HEADER} — DO NOT EDIT.\n${exports}\n`;
+}
+
+export interface BarrelOpts {
+  target?: string;
+}
+
+export const barrel = function barrel(opts?: BarrelOpts): Generator {
+  const generator: Generator = {
+    name: "barrel",
+    generate: oncePerRun(async (entities, ctx) => ({
+      path: "index.ts",
+      content: await formatTs(
+        renderBarrel(
+          entities.map((e) => ({ name: e.name, package: e.package })),
+          ctx.renderContext!.extStyle,
+          ctx.renderContext!.selfTarget,
+          ctx.renderContext!.entityModuleTarget,
+        ),
+      ),
+    })),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<BarrelOpts>;

package/src/reference/entity.ts

@@ -0,0 +1,147 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/entity.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { entityFile } from "./codegen/generators/entity";
+//
+// use-when:      ALWAYS — this is the entity-module generator. It owns the shape of each
+//                generated <Entity>.ts (the Drizzle table, Zod schemas, inferred types,
+//                constants, filter allowlists). Start here and adapt the assembly.
+// emits:         <target>/<Entity>.ts per concrete object — and the shared-enums module once.
+//                Dispatches: abstract/value → interface + Zod; projection → read-only view decl;
+//                write-through entity → full Drizzle table path.
+// customize:     reorder/drop sections in `sections` below; change the header; swap a sub-renderer
+//                for your own (each render* is an engine primitive you call). To deeply own one
+//                section (e.g. the Drizzle emit), copy/replace that sub-render call with your code.
+// composes-with: queries.ts, routes.ts, barrel.ts (they import the files this emits).
+//
+// The composition (`renderEntity`) is the relocated body of the built-in entity composer —
+// byte-identical to start, now YOURS to change. It imports only public engine primitives.
+
+import { joinCode, type Code } from "ts-poet";
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import {
+  perEntity,
+  type EmittedFile,
+  type GenContext,
+  type Generator,
+  type GeneratorFactory,
+  type RenderContext,
+  // sub-renderers (engine primitives) — the LEGO blocks this composition assembles:
+  renderDrizzleSchema,
+  renderInferredTypes,
+  renderEnumTypeAliases,
+  renderZodValidators,
+  renderEntityConstants,
+  renderFilterAllowlist,
+  renderSortAllowlist,
+  renderFilterType,
+  renderTphDiscriminatorUnion,
+  isTphDiscriminatorBase,
+  renderProjectionDecl,
+  renderValueObjectFile,
+  renderSharedEnumsFile,
+  SHARED_ENUMS_BASENAME,
+  // predicates + helpers:
+  isProjection,
+  isAbstract,
+  hasWritableRdbSource,
+  // engine plumbing:
+  formatTs,
+  entityOutputPath,
+  GENERATED_HEADER,
+} from "@metaobjectsdev/codegen-ts";
+
+export interface RenderEntityOpts {
+  readonly allowlists?: boolean;
+}
+
+// --- composition (OWNED) — assembles one <Entity>.ts. Change this to change the output. ---
+function renderEntity(entity: MetaObject, ctx: RenderContext, opts?: RenderEntityOpts): string {
+  const runtime = ctx.selfTarget.runtime;
+  const allowlists = runtime ? (opts?.allowlists ?? true) : false;
+
+  // Abstract → shape only (interface + Zod), never a table.
+  if (isAbstract(entity)) {
+    return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
+  }
+  // Projection → read-only view declaration + read schema.
+  if (isProjection(entity)) {
+    return renderProjectionDecl(entity, ctx.loadedRoot, {
+      columnNamingStrategy: ctx.columnNamingStrategy,
+      dialect: ctx.dialect,
+      apiPrefix: ctx.apiPrefix,
+      timestampMode: ctx.timestampMode,
+      allowlists,
+      ctx,
+      includeViewDecl: runtime,
+    });
+  }
+  // Value-only / contract target → interface + Zod, no Drizzle table.
+  if (!runtime || !hasWritableRdbSource(entity)) {
+    return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
+  }
+
+  // Write-through entity → the full Drizzle table file. Reorder/drop sections freely.
+  const enumAliases = renderEnumTypeAliases(entity, ctx);
+  const tphBlock = renderTphDiscriminatorUnion(entity, ctx.loadedRoot);
+  const tphBase = tphBlock !== null && isTphDiscriminatorBase(entity, ctx.loadedRoot);
+  const sections: Code[] = [
+    renderDrizzleSchema(entity, ctx),
+    renderInferredTypes(entity, tphBase, ctx),
+    ...(enumAliases !== null ? [enumAliases] : []),
+    renderZodValidators(entity, ctx),
+    renderEntityConstants(entity, ctx.apiPrefix),
+    ...(allowlists ? [renderFilterAllowlist(entity), renderSortAllowlist(entity)] : []),
+    renderFilterType(entity),
+    ...(tphBlock !== null ? [tphBlock] : []),
+  ];
+
+  const body = joinCode(sections, { on: "\n" }).toString();
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Source metadata: ${entity.name} (${entity.fqn()})\n` +
+    `// Customize via ${entity.name}.extra.ts in this directory.\n`;
+  return header + body;
+}
+
+export interface EntityFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+  allowlists?: boolean;
+}
+
+export const entityFile = function entityFile(opts?: EntityFileOpts): Generator {
+  const allowlists = opts?.allowlists ?? true;
+  const perEntityEmit = perEntity(async (entity, ctx) => {
+    if (!ctx.renderContext) {
+      throw new Error("entity-file: renderContext is required (provided by runGen)");
+    }
+    if (isAbstract(entity) && !ctx.renderContext.emitAbstractShapes) {
+      return [];
+    }
+    return {
+      path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.ts`),
+      content: await formatTs(renderEntity(entity, ctx.renderContext, { allowlists })),
+    };
+  });
+
+  const generator: Generator = {
+    name: "entity-file",
+    emitsEntityModule: true,
+    generate: async (ctx: GenContext): Promise<EmittedFile[]> => {
+      const files = await perEntityEmit(ctx);
+      // FR-019: emit the shared-enums module once per run (null → no file).
+      const sharedEnums = renderSharedEnumsFile(ctx.loadedRoot);
+      if (sharedEnums !== null) {
+        files.push({ path: `${SHARED_ENUMS_BASENAME}.ts`, content: await formatTs(sharedEnums) });
+      }
+      return files;
+    },
+  };
+  if (opts?.filter) {
+    generator.filter = opts.filter;
+  }
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<EntityFileOpts>;