feat(codegen-ts): add copyable reference template library (#86)

* feat(codegen-ts): reference template library (ADR-0034 scaffold-and-own, step 1)

Adds src/reference/{entity,queries,routes,barrel}.ts — self-contained COPYABLE
reference generators a consumer copies into their repo and owns, importing only the
public engine (@metaobjectsdev/codegen-ts) + ts-poet + @metaobjectsdev/metadata. Each
carries a use-when / emits / customize / composes-with header. entity relocates the
full renderEntityFile composition (full ownership); queries owns the vanilla-CRUD
composition and delegates TPH/projection variants; barrel relocates renderBarrel;
routes stays generator-level (its vanilla composition pulls in internal M:N junction
logic — renderM2mMounts — that we deliberately do NOT promote; the header documents
how to copy renderRoutesFile's body for deeper ownership).

Promotes the composition's assembly helpers to public (re-exports only — already
exported from their modules): renderTphDiscriminatorUnion, hasWritableRdbSource,
renderSharedEnumsFile, SHARED_ENUMS_BASENAME, and the queries CRUD-block renderers
(renderFindByIdFn/List/Create/Update/DeleteById + getPkInfo).

Purely additive — no existing generator or export removed (deprecation + the meta init
scaffolding + guidance rewrite are later steps). reference/ excluded from the tsc build
(scaffold assets). Verified: byte-identical built-in-vs-reference over 5 fixtures (68
assertions), full codegen-ts suite 831 pass, tsc --noEmit strict of reference/* against
the public API clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LuZWKnWzYGVnESijL7uuky

* no-mistakes(document): document codegen-ts reference template library in CHANGELOG

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,22 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Added
+- **codegen-ts — reference template library (ADR-0034 scaffold-and-own, step 1):**
+  new in-repo, copyable reference generators under `src/reference/`
+  (`entity` / `queries` / `routes` / `barrel`) — self-contained starting points a
+  consumer copies into their repo and owns, importing only the public engine
+  (`@metaobjectsdev/codegen-ts`) plus `ts-poet` and `@metaobjectsdev/metadata`.
+  Each carries a `use-when / emits / customize / composes-with` header. Purely
+  additive — no existing generator or export was removed; the templates are
+  scaffold assets excluded from the package build. To keep a copied generator on
+  public imports only, the engine now also re-exports the assembly helpers those
+  templates use: `renderTphDiscriminatorUnion`, `hasWritableRdbSource`,
+  `renderSharedEnumsFile` / `SHARED_ENUMS_BASENAME`, and the queries CRUD-block
+  renderers (`renderFindByIdFn`, `renderListFn`, `renderCreateFn`,
+  `renderUpdateFn`, `renderDeleteByIdFn`, `getPkInfo`). (`meta init` scaffolding,
+  generator-export deprecation, and the guidance rewrite are later steps.)
+
 ### Fixed
 - **cli — `meta init` gitignore hardening:** the scaffolded
   `.metaobjects/.gitignore` previously ignored only `.gen-state/`, so a

server/typescript/packages/codegen-ts/src/index.ts

@@ -68,6 +68,23 @@ 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";
+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

server/typescript/packages/codegen-ts/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>;

server/typescript/packages/codegen-ts/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>;

server/typescript/packages/codegen-ts/src/reference/queries.ts

@@ -0,0 +1,124 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/queries.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { queriesFile } from "./codegen/generators/queries";
+//
+// use-when:      you want generated typed CRUD finders (find<E>ById, list<E>s, create/update/delete)
+//                over Drizzle. Drop it if you hand-write your data access.
+// emits:         <target>/<Entity>.queries.ts per write-through entity.
+// customize:     the vanilla CRUD assembly below is OWNED — reorder, drop verbs (e.g. no delete),
+//                change the Db type alias, add your own finders. The render<Verb>Fn primitives emit
+//                each block; call your own instead to change a verb's body.
+// composes-with: entity.ts (imports the table + InsertSchema it emits).
+//
+// NOTE: the advanced TPH-base + projection variants delegate to the engine's composer
+// (`renderQueriesFile`) — they're rarely customized. To own those too, copy their branches
+// out of the package source. The vanilla path here is byte-identical to the built-in.
+
+import { code, joinCode, type Code } from "ts-poet";
+import { OBJECT_SUBTYPE_VALUE, type MetaObject } from "@metaobjectsdev/metadata";
+import {
+  perEntity,
+  type Generator,
+  type GeneratorFactory,
+  type RenderContext,
+  entityModuleSpecifier,
+  renderFindByIdFn,
+  renderListFn,
+  renderCreateFn,
+  renderUpdateFn,
+  renderDeleteByIdFn,
+  isTphDiscriminatorBase,
+  isProjection,
+  isTphSubtype,
+  renderQueriesFile, // engine composer — used for the delegated variants
+  formatTs,
+  entityOutputPath,
+  GENERATED_HEADER,
+} from "@metaobjectsdev/codegen-ts";
+
+// --- composition (OWNED for the common case) ---
+function renderQueries(obj: MetaObject, ctx: RenderContext): string {
+  // Advanced variants delegate to the engine (byte-identical). Own them by copying their source.
+  if (isTphDiscriminatorBase(obj, ctx.loadedRoot) || isProjection(obj)) {
+    return renderQueriesFile(obj, ctx);
+  }
+
+  const entityName = obj.name;
+  const entityFileName = entityModuleSpecifier(
+    ctx.selfTarget,
+    ctx.entityModuleTarget,
+    obj.package,
+    entityName,
+    ctx.extStyle,
+  );
+  const varName = ctx.collectionName(entityName);
+
+  // `db` is parameter-passed into every finder (ADR-0008). Emit the dialect-correct
+  // Drizzle type alias so signatures typecheck without the consumer constructing one.
+  const dbTypeImport =
+    ctx.dialect === "postgres"
+      ? `import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";`
+      : `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`;
+  const dbTypeAlias =
+    ctx.dialect === "postgres"
+      ? `type Db = PgDatabase<PgQueryResultHKT, Record<string, never>>;`
+      : `type Db = BaseSQLiteDatabase<"sync" | "async", unknown>;`;
+
+  const literalImports = code`
+${dbTypeImport}
+${dbTypeAlias}
+
+import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON.stringify(entityFileName)};
+`;
+
+  const sections: Code[] = [
+    literalImports,
+    renderFindByIdFn(obj, ctx),
+    renderListFn(obj, ctx),
+    renderCreateFn(obj, ctx),
+    renderUpdateFn(obj, ctx),
+    renderDeleteByIdFn(obj, ctx),
+  ];
+
+  const body = joinCode(sections, { on: "\n" }).toString();
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Source metadata: ${entityName} (${obj.fqn()})\n` +
+    `// Customize via ${entityName}.extra.ts in this directory (additional queries, custom logic).\n`;
+  return header + body;
+}
+
+export interface QueriesFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+// value objects have no identity (findById/updateById would target a non-existent column),
+// and TPH subtypes emit no standalone queries file — both are skipped unconditionally.
+const skipNonQueryable = (e: MetaObject): boolean =>
+  e.subType !== OBJECT_SUBTYPE_VALUE && !isTphSubtype(e);
+
+export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generator {
+  const userFilter = opts?.filter;
+  const filter: (e: MetaObject) => boolean = userFilter
+    ? (e) => skipNonQueryable(e) && userFilter(e)
+    : skipNonQueryable;
+
+  const generator: Generator = {
+    name: "queries-file",
+    filter,
+    generate: perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error("queries-file: renderContext is required (provided by runGen)");
+      }
+      return {
+        path: entityOutputPath(ctx.config.outputLayout ?? "flat", entity.package, `${entity.name}.queries.ts`),
+        content: await formatTs(renderQueries(entity, ctx.renderContext)),
+      };
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<QueriesFileOpts>;