@metaobjectsdev/codegen-ts 0.9.0 → 0.11.0-rc.1

package/src/naming.ts

@@ -58,9 +58,79 @@ export function viewNameFromProjection(
   return "v" + sep + applyColumnNamingStrategy(projectionName, strategy);
 }
 
-/** PascalCase entity → camelCase plural for the Drizzle table variable. */
-export function variableNameFromEntity(entityName: string): string {
-  return pluralize(toCamelCase(entityName.charAt(0).toLowerCase() + entityName.slice(1)));
+/** Codegen control over how an entity name lowers to its collection (table)
+ *  variable name. Both knobs are project-level codegen config (ADR-0001 —
+ *  naming is a per-port codegen concern, NOT a metadata attribute), so they
+ *  carry no cross-port conformance cost. */
+export interface CollectionNameOptions {
+  /** Auto-pluralize the camelCase entity name. Default `true` (e.g.
+   *  `AgentConfig` → `agentConfigs`). Set `false` to keep it singular
+   *  (`agentConfig`). */
+  pluralize?: boolean;
+  /** Per-entity exact var-name overrides, keyed by the bare entity name. Wins
+   *  over `pluralize` — the escape hatch for the handful of tables a global
+   *  rule gets wrong (e.g. `{ AuditLog: "auditLog", LlmTierConfig: "llmTierConfig" }`). */
+  overrides?: Record<string, string>;
+}
+
+/** PascalCase entity → camelCase Drizzle table variable. Auto-pluralizes by
+ *  default; `opts` lets a project turn pluralization off globally and/or pin
+ *  exact names per entity. With no `opts` the behavior is the historical
+ *  always-pluralize (callers like the relation-resolver that only need the
+ *  cosmetic query-API member name pass nothing). */
+export function variableNameFromEntity(entityName: string, opts?: CollectionNameOptions): string {
+  const override = opts?.overrides?.[entityName];
+  if (override !== undefined && override.length > 0) return override;
+  const camel = toCamelCase(entityName.charAt(0).toLowerCase() + entityName.slice(1));
+  return opts?.pluralize === false ? camel : pluralize(camel);
+}
+
+// ---------------------------------------------------------------------------
+// Generated CRUD-helper symbol names (single source of truth).
+//
+// The queries generator (templates/queries.ts) emits one exported async function
+// per CRUD verb whose NAME is derived purely from the entity name. These helpers
+// are the canonical spelling of those names so anything that needs to REFER to a
+// generated symbol (e.g. the api-docs ApiModel builder) derives the exact same
+// string the generator emits — no drift, no invented names. The queries template
+// itself uses these so the two can never disagree.
+// ---------------------------------------------------------------------------
+
+/** Generated read-by-PK helper name: `find<Entity>ById`. */
+export function findByIdFnName(entityName: string): string {
+  return `find${entityName}ById`;
+}
+
+/** Generated list helper name: `list<Plural>` (PascalCase plural). */
+export function listFnName(entityName: string): string {
+  return `list${pluralize(entityName)}`;
+}
+
+/** Generated create helper name: `create<Entity>`. */
+export function createFnName(entityName: string): string {
+  return `create${entityName}`;
+}
+
+/** Generated update helper name: `update<Entity>`. */
+export function updateFnName(entityName: string): string {
+  return `update${entityName}`;
+}
+
+/** Generated delete-by-PK helper name: `delete<Entity>ById`. */
+export function deleteByIdFnName(entityName: string): string {
+  return `delete${entityName}ById`;
+}
+
+/**
+ * Generated Fastify route-registrar name: camelCase `<entity>Routes`. The routes
+ * generator (templates/routes-file.ts) emits a single exported
+ * `export async function <entity>Routes(fastify)` that mounts the entity's CRUD
+ * verb set — this is the symbol an adopter imports to wire the endpoints. Kept
+ * here as the single source of truth so the routes template and the api-docs
+ * ApiModel builder derive the exact same spelling (no drift).
+ */
+export function routesHandlerName(entityName: string): string {
+  return `${entityName.charAt(0).toLowerCase()}${entityName.slice(1)}Routes`;
 }
 
 // Re-exported here for callers that import from codegen-ts's naming module.

package/src/payload-codegen.ts

@@ -23,6 +23,8 @@ import {
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_TEXT_REF,
   TEMPLATE_ATTR_FORMAT,
+  refMatchesObject,
+  stripPackage,
 } from "@metaobjectsdev/metadata";
 import { enumValues } from "./enum-meta.js";
 import { enumUnionAliasName, enumUnionString } from "./templates/inferred-types.js";
@@ -45,7 +47,9 @@ const SCALAR_TS: Record<string, string> = {
 };
 
 function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+  // FR-032 — @payloadRef/@responseRef are FQN after the desugar/sweep; match on
+  // the effective FQN resolution key (with bare back-compat).
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
 /**
@@ -61,7 +65,7 @@ function fieldTsType(
   ownerName: string,
 ): { type: string; refVo?: string; enumAlias?: { name: string; decl: string } } {
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
-    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     const refName = typeof ref === "string" ? ref : "unknown";
     // isArray is a structural property on MetaData, not an attr.
     const isArray = field.isArray;
@@ -92,7 +96,7 @@ function fieldTsType(
 
 /** True iff the field's @required is explicitly set to true. */
 function isFieldRequired(field: MetaData): boolean {
-  return field.ownAttr(FIELD_ATTR_REQUIRED) === true;
+  return field.attr(FIELD_ATTR_REQUIRED) === true;
 }
 
 function emitInterface(
@@ -168,14 +172,21 @@ export function generateRenderHandle(root: MetaData, templateName: string): stri
   const tmpl = root.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.name === templateName);
   if (!tmpl) throw new Error(`template "${templateName}" not found`);
   const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  // FR-032 — @payloadRef is an FQN after the desugar/sweep; the generated TS
+  // TYPE NAME is the resolved value-object's bare name (an FQN like
+  // `acme::ai::Payload` is not a valid TS identifier). Fall back to the last
+  // `::`-segment when the VO is not in this root (defensive).
+  const payloadType =
+    (typeof payloadRef === "string" ? findObject(root, payloadRef)?.name : undefined) ??
+    (typeof payloadRef === "string" ? stripPackage(payloadRef) : String(payloadRef));
   const textRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF);
   const format = (tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text";
   const fn = `render${pascal(templateName)}`;
   return [
     `import { render, type Provider } from "@metaobjectsdev/render";`,
-    `import type { ${payloadRef} } from "./payloads.js";`,
+    `import type { ${payloadType} } from "./payloads.js";`,
     ``,
-    `export function ${fn}(payload: ${payloadRef}, provider: Provider): string {`,
+    `export function ${fn}(payload: ${payloadType}, provider: Provider): string {`,
     `  return render({ ref: ${JSON.stringify(textRef)}, payload, format: ${JSON.stringify(format)}, provider });`,
     `}`,
     ``,

package/src/pk-resolver.ts

@@ -30,7 +30,9 @@ export function buildPkMap(root: MetaRoot): Map<string, PkInfo> {
     // primaryIdentity() resolves the primary identity across the super-chain.
     const primary = obj.primaryIdentity();
     if (!primary) continue;
-    const fields = primary.ownAttr(IDENTITY_ATTR_FIELDS);
+    // attr() (effective) not ownAttr() — @fields/@generation can be inherited when the
+    // identity node-level `extends` a base identity without restating them (#56).
+    const fields = primary.attr(IDENTITY_ATTR_FIELDS);
     if (!Array.isArray(fields) && typeof fields !== "string") continue;
     const fieldsList = Array.isArray(fields) ? fields : [fields];
     if (fieldsList.length === 0) continue;
@@ -38,7 +40,7 @@ export function buildPkMap(root: MetaRoot): Map<string, PkInfo> {
     // findField() resolves the field across the super-chain (handles extends:).
     const pkField = obj.findField(pkFieldName);
     const fieldSubType = pkField?.subType ?? FIELD_SUBTYPE_LONG; // sane default
-    const generation = primary.ownAttr(IDENTITY_ATTR_GENERATION);
+    const generation = primary.attr(IDENTITY_ATTR_GENERATION);
     const info: PkInfo = { fieldName: pkFieldName, fieldSubType };
     if (typeof generation === "string") info.generation = generation;
     result.set(obj.name, info);

package/src/projection/extract-view-spec.ts

@@ -1,5 +1,6 @@
 import {
   TYPE_FIELD,
+  TYPE_IDENTITY,
   TYPE_ORIGIN,
   TYPE_RELATIONSHIP,
   MetaSource,
@@ -79,33 +80,62 @@ export function projectionViewName(
   return viewName(projection, { columnNamingStrategy });
 }
 
+/**
+ * FR-024 (ADR-0029): the entity NAMED by a node's dotted extends ref — the
+ * owner part of `<owner>.<child>...` resolved as an object. Mirrors the
+ * loader's `_refNamedOwner`: the ref names the anchor, never the physical
+ * declaring ancestor of an inherited child.
+ */
+function refNamedOwner(node: MetaData, root: MetaRoot): MetaObject | undefined {
+  const ref = (node as { superRef?: string }).superRef;
+  if (ref === undefined) return undefined;
+  const lastSep = ref.lastIndexOf("::");
+  const tail = lastSep === -1 ? ref : ref.slice(lastSep + 2);
+  const dot = tail.indexOf(".");
+  if (dot <= 0) return undefined;
+  return root.findObject(tail.slice(0, dot)) ?? undefined;
+}
+
 function baseEntityFor(
   projection: MetaObject,
   root: MetaRoot,
 ): MetaObject {
-  // v1: base entity is the resolved super (set via `extends:` in metadata).
-  const superModel = projection.superResolved;
-  const superName = superModel?.name ?? projection.superRef;
-  if (!superName) {
-    throw new Error(
-      `Projection ${projection.name}: missing extends — projections must extend a writable entity in v1.`,
-    );
+  // FR-024 base-anchor rules (mirror the loader's _deriveBaseEntity):
+  // 1) the extends-bound identity anchors the base entity;
+  // 2) else the single distinct entity targeted by extends-bound fields.
+  // The pre-FR-024 object-level `extends:` firehose is removed (B4b cutover).
+  //
+  // COUPLING NOTE: this intentionally derives the anchor ONLY from the ref's
+  // named owner (refNamedOwner), NOT the loader's `superResolved.parent`
+  // fallback for a non-dotted identity extends. That fallback is unreachable
+  // here because the loader gate (validate-identity-passthrough →
+  // ERR_PROJECTION_IDENTITY_NOT_EXTENDED) rejects any projection whose identity
+  // is not dotted-extends-bound before codegen runs. If that loader gate is
+  // ever loosened, this function must grow the same fallback.
+  for (const identity of projection
+    .ownChildren()
+    .filter((c) => c.type === TYPE_IDENTITY)) {
+    const named = refNamedOwner(identity, root);
+    if (named !== undefined) return named;
   }
-  const base =
-    superModel instanceof MetaObject ? superModel : root.findObject(superName);
-  if (!base) {
-    throw new Error(
-      `Projection ${projection.name}: extends "${superName}" does not resolve to any entity.`,
-    );
+  const targets = new Set<MetaObject>();
+  for (const f of projection.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+    const named = refNamedOwner(f, root);
+    if (named !== undefined && named !== projection) targets.add(named);
   }
-  return base;
+  if (targets.size === 1) return [...targets][0]!;
+  throw new Error(
+    `Projection ${projection.name}: cannot derive the base entity — declare an ` +
+      `extends-bound identity (identity.primary { name, extends: "<Entity>.<identity>" }) ` +
+      `to anchor the base (FR-024).`,
+  );
 }
 
 function sourceColumnNameFor(
   entityField: MetaData,
   ctx: ExtractContext,
 ): string {
-  const col = entityField.ownAttr(FIELD_ATTR_COLUMN);
+  const col = entityField.attr(FIELD_ATTR_COLUMN);
   if (typeof col === "string" && col !== "") return col;
   return columnNameFromField(entityField.name, ctx.columnNamingStrategy);
 }
@@ -270,22 +300,11 @@ function buildSelectSpec(
 ): SelectSpec {
   const columns: SelectColumn[] = [];
 
-  // Inherited fields from extends parent — emit as passthrough on baseAlias.
-  // Skip fields that the projection has overridden with an explicit origin.
-  // fields() is effective-by-default, so multi-level inheritance (base → BaseEntity) works.
-  for (const baseField of base.fields()) {
-    const overridden = projection.ownChildren().find(
-      (c) => c.type === TYPE_FIELD && c.name === baseField.name,
-    );
-    if (overridden) continue;
-    columns.push({
-      kind: "passthrough",
-      fieldName: baseField.name,
-      dbColAlias: sourceColumnNameFor(baseField, ctx),
-      sourceAlias: joinTree.baseAlias,
-      sourceColumn: sourceColumnNameFor(baseField, ctx),
-    });
-  }
+  // FR-024 (ADR-0028): the projection's DECLARED field set IS the exposure —
+  // the inclusive list, fail-closed by construction. The pre-FR-024 loop that
+  // emitted every base-entity field as an implicit passthrough (the firehose)
+  // is removed with the B4b cutover: base columns are declared explicitly as
+  // extends-bound fields (`{ field.int: { name: id, extends: "Program.id" } }`).
 
   // Fields explicitly declared on the projection.
   for (const field of projection.ownChildren()) {

package/src/relation-resolver.ts

@@ -5,11 +5,14 @@
 //
 // Reads identity.reference declarations to determine the physical reference side.
 
-import type { MetaRoot } from "@metaobjectsdev/metadata";
+import type { MetaRoot, MetaObject, MetaRelationship } from "@metaobjectsdev/metadata";
 import {
   RELATIONSHIP_ATTR_CARDINALITY,
   RELATIONSHIP_ATTR_OBJECT_REF,
+  RELATIONSHIP_ATTR_THROUGH,
   CARDINALITY_ONE,
+  CARDINALITY_MANY,
+  deriveM2MFields,
   stripPackage,
 } from "@metaobjectsdev/metadata";
 import { variableNameFromEntity } from "./naming.js";
@@ -26,6 +29,22 @@ export interface RelationEntry {
   fkField?: string;
   /** For cardinality 'one': the target entity's PK field (e.g., "id") */
   targetPkField?: string;
+  /**
+   * FR-018 M:N navigation fields. Present only for a many-to-many navigation (a
+   * `@cardinality: "many"` relationship that declares `@through`). The Drizzle
+   * relations() block emits `many(<junction>)` for these; the routes file emits
+   * a `mountM2mRoute(...)` traversal. The junction FK fields are DERIVED from the
+   * junction entity's two `identity.reference` children (the SSOT), never
+   * restated on the relationship.
+   */
+  /** The junction/through entity name (e.g., "PostTag"). M:N entries only. */
+  junctionEntity?: string;
+  /** Junction FK field holding the source-side key (logical field name, e.g. "postId"). M:N only. */
+  sourceJoinField?: string;
+  /** Junction FK field holding the target-side key (logical field name, e.g. "tagId"). M:N only. */
+  targetJoinField?: string;
+  /** Undirected self-join: union both junction FK columns at read time. M:N only. */
+  symmetric?: boolean;
 }
 
 /** Map from entity name → list of relations for that entity's relations() block */
@@ -51,6 +70,16 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
 
     for (const child of obj.relationships()) {
       const cardinality = child.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) as string | undefined;
+
+      // FR-018 M:N: `@cardinality: "many"` + `@through` — derive the junction FK
+      // columns from the junction's identity.reference children and register a
+      // many(junction) navigation on the source.
+      if (cardinality === CARDINALITY_MANY && child.ownAttr(RELATIONSHIP_ATTR_THROUGH) !== undefined) {
+        const m2m = buildM2mEntry(obj, child as MetaRelationship, root);
+        if (m2m) ensure(obj.name).push(m2m);
+        continue;
+      }
+
       if (cardinality !== CARDINALITY_ONE) continue;
 
       const targetEntityRaw = child.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
@@ -83,5 +112,78 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
     }
   }
 
+  // FR-018: junction entities reached via @through need their two belongs-to
+  // one() sides so the through-table is navigable in the Drizzle relational
+  // query API (db.query.posts.findMany({ with: { tags: { with: { tag: true }}}})).
+  // A junction is any entity named by some M:N relationship's @through.
+  for (const junctionName of collectJunctionNames(root)) {
+    const junction = root.findObject(junctionName);
+    if (!junction) continue;
+    const entries = ensure(junctionName);
+    for (const ref of junction.referenceIdentities()) {
+      const targetRaw = ref.targetEntity;
+      const fkField = ref.fields[0];
+      if (!targetRaw || !fkField) continue;
+      const targetEntity = stripPackage(targetRaw);
+      // The relation member is named after the target entity (camel singular);
+      // multiple references to the same entity (self-join junction) are
+      // disambiguated by the FK field name.
+      const refName = ref.name && ref.name.length > 0
+        ? ref.name
+        : variableNameFromEntity(targetEntity);
+      entries.push({
+        name: refName,
+        cardinality: "one",
+        targetEntity,
+        fkField,
+        targetPkField: "id",
+      });
+    }
+  }
+
   return result;
 }
+
+/** Names of all entities that are the `@through` junction of some M:N relationship. */
+function collectJunctionNames(root: MetaRoot): Set<string> {
+  const names = new Set<string>();
+  for (const obj of root.objects()) {
+    for (const rel of obj.relationships()) {
+      if (rel.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) !== CARDINALITY_MANY) continue;
+      const through = rel.ownAttr(RELATIONSHIP_ATTR_THROUGH) as string | undefined;
+      if (through) names.add(stripPackage(through));
+    }
+  }
+  return names;
+}
+
+/**
+ * Build the source-side M:N navigation entry: derive the junction FK fields from
+ * the junction's two identity.reference children (the SSOT), handling hetero /
+ * directed-self-join / symmetric. Returns null (skips the entry) if derivation
+ * fails — the loader validation pass surfaces the actionable error separately.
+ */
+function buildM2mEntry(
+  source: MetaObject,
+  rel: MetaRelationship,
+  root: MetaRoot,
+): RelationEntry | null {
+  const targetRaw = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
+  const throughRaw = rel.ownAttr(RELATIONSHIP_ATTR_THROUGH) as string | undefined;
+  if (!targetRaw || !throughRaw) return null;
+  let fields;
+  try {
+    fields = deriveM2MFields(rel, source, root);
+  } catch {
+    return null;
+  }
+  return {
+    name: rel.name,
+    cardinality: "many",
+    targetEntity: stripPackage(targetRaw),
+    junctionEntity: stripPackage(throughRaw),
+    sourceJoinField: fields.sourceField,
+    targetJoinField: fields.targetField,
+    symmetric: rel.symmetric,
+  };
+}

package/src/render-context.ts

@@ -6,6 +6,7 @@ import type { PkInfo } from "./pk-resolver.js";
 import type { RelationMap } from "./relation-resolver.js";
 import type { ColumnNamingStrategy } from "./metaobjects-config.js";
 import type { OutputLayout, ResolvedTarget } from "./import-path.js";
+import { variableNameFromEntity } from "./naming.js";
 
 /**
  * How to format cross-entity import specifiers in generated files.
@@ -37,12 +38,26 @@ export interface RenderContext {
   extStyle: ExtStyle;
   /** Column naming strategy: how field names map to DB column names. Defaults to "snake_case". */
   columnNamingStrategy: ColumnNamingStrategy;
+  /**
+   * Drizzle timestamp column mode. "string" (default) types timestamp columns as
+   * ISO-8601 strings (matching the generated Zod + cross-port wire contract);
+   * "date" uses drizzle's native JS-Date mode (for consumers whose hand-written
+   * code works with `Date`). Opt in via `codegen.timestampMode`.
+   */
+  timestampMode: "date" | "string";
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
   apiPrefix: string;
   /** Whether abstract entities emit their shape artifact (type-only interface / value-object file). Defaults to true. Instance/write artifacts are never emitted for abstract entities regardless. */
   emitAbstractShapes: boolean;
   /** Output layout mode: "flat" (default) — all files in outDir; "package" — sub-paths from entity metadata package. */
   outputLayout: OutputLayout;
+  /**
+   * Resolve an entity name to its Drizzle collection (table) variable name,
+   * applying the project's pluralization config + per-entity overrides. Every
+   * template that emits or references a table var goes through this so the
+   * declaration and all references agree. Defaults to always-pluralize.
+   */
+  collectionName: (entityName: string) => string;
   /** The target THIS generator emits to (drives path layout + same-target imports). */
   selfTarget: ResolvedTarget;
   /** Where entity files live (drives cross-target entity imports). */
@@ -52,19 +67,28 @@ export interface RenderContext {
   relationMap: RelationMap;
   /** Entity name → its metadata package (undefined if the entity has no package). Built once per run. */
   packageOf: Map<string, string | undefined>;
+  /** FR-019: module specifier to import externally-PROVIDED shared enums from
+   *  (`@provided: true` declarations). Undefined when unset — referencing a
+   *  provided enum without it is a codegen-time error. */
+  providedEnumModule?: string;
 }
 
-/** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). */
-export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget"> & {
+/** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). `collectionName` is built from `pluralizeCollections` + `collectionNameOverrides` (both default to always-pluralize). */
+export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "timestampMode" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget" | "collectionName"> & {
   extStyle?: ExtStyle;
   omImport?: string;
   columnNamingStrategy?: ColumnNamingStrategy;
+  timestampMode?: "date" | "string";
   apiPrefix?: string;
   emitAbstractShapes?: boolean;
   outputLayout?: OutputLayout;
   packageOf?: Map<string, string | undefined>;
   selfTarget?: ResolvedTarget;
   entityModuleTarget?: ResolvedTarget;
+  /** Auto-pluralize collection (table) variable names. Default true. */
+  pluralizeCollections?: boolean;
+  /** Per-entity exact collection-var-name overrides, keyed by bare entity name. */
+  collectionNameOverrides?: Record<string, string>;
 };
 
 /** Append the configured extension to a cross-entity module specifier. */
@@ -82,16 +106,22 @@ export function makeRenderContext(opts: RenderContextInput): RenderContext {
     outputLayout,
     dbImport: opts.dbImport,
   };
+  const collectionNameOpts = {
+    pluralize: opts.pluralizeCollections ?? true,
+    overrides: opts.collectionNameOverrides ?? {},
+  };
   return {
     ...opts,
     extStyle: opts.extStyle ?? "none",
     omImport: opts.omImport ?? "../index",
     columnNamingStrategy: opts.columnNamingStrategy ?? "snake_case",
+    timestampMode: opts.timestampMode ?? "string",
     apiPrefix: opts.apiPrefix ?? "",
     emitAbstractShapes: opts.emitAbstractShapes ?? true,
     outputLayout,
     packageOf: opts.packageOf ?? new Map(),
     selfTarget: defaultTarget,
     entityModuleTarget: opts.entityModuleTarget ?? defaultTarget,
+    collectionName: (entityName: string) => variableNameFromEntity(entityName, collectionNameOpts),
   };
 }

package/src/render-engine/embedded-templates.generated.ts

@@ -0,0 +1,14 @@
+// @generated from templates/*/*.mustache — DO NOT EDIT.
+// Regenerate: bun run scripts/generate-embedded-templates.ts (or scripts/sync-doc-templates.sh).
+//
+// Embedded framework doc templates so they resolve inside the
+// `bun build --compile` standalone `meta` binary, where the on-disk
+// `templates/` directory is unavailable. Keys are provider resolve refs
+// (path under templates/ minus the .mustache suffix).
+export const EMBEDDED_FRAMEWORK_TEMPLATES: Record<string, string> = {
+  "api/agent-api.md": "{{{generatedMarker}}}\n\n# {{title}}\n\nGenerated API reference for {{project}}; call these exactly as written. {{importNote}}\n{{#hasSetup}}\n\n## Setup\n{{#setup}}\n- `{{handle}}` — {{{note}}} `{{{snippetInline}}}`\n{{/setup}}\n{{/hasSetup}}\n{{#units}}\n\n## {{node}}\n{{#groups}}\n\n`{{importHeader}}`\n{{#symbols}}\n- `{{signature}}` — {{usage}}{{#throwsMarker}} {{throwsMarker}}{{/throwsMarker}}\n{{/symbols}}\n{{/groups}}\n{{#example}}\n\nExample:\n```ts\n{{{example}}}\n```\n{{/example}}\n{{/units}}\n",
+  "api/entity-api.md": "{{{generatedMarker}}}\n\n# {{node}} API\n{{#modelPageHref}}\n\n**Model / metadata:** [{{node}}]({{modelPageHref}})\n{{/modelPageHref}}\n\n> Import paths are relative to your generated-output directory.\n{{#hasSetup}}\n\n## Setup\n\nObtain the runtime handles the calls below need:\n{{#setup}}\n\n- `{{handle}}` — {{{note}}}\n\n```ts\n{{{snippet}}}\n```\n{{/setup}}\n{{/hasSetup}}\n{{#unitExample}}\n\n## Example\n\n```ts\n{{{unitExample}}}\n```\n{{/unitExample}}\n{{#sections}}\n\n## {{heading}}\n{{#symbols}}\n\n### `{{signature}}`\n\n{{usage}}\n\n```ts\n{{importLine}}\n```\n{{#hasFields}}\n\n{{fieldsCaption}}:\n\n| Field | Type | Required | Notes |\n|---|---|---|---|\n{{#fieldRows}}\n| `{{field}}` | `{{{type}}}` | {{required}} | {{notes}} |\n{{/fieldRows}}\n{{/hasFields}}\n{{#mountNote}}\n\nMount: {{{mountNote}}}\n{{/mountNote}}\n{{#throws}}\n\nThrows: {{throws}}\n{{/throws}}\n{{#example}}\n\n```ts\n{{{example}}}\n```\n{{/example}}\n{{/symbols}}\n{{/sections}}\n",
+  "api/index.md": "{{{generatedMarker}}}\n\n# {{title}}\n\n{{intro}}\n{{#hasEntities}}\n\n## Entities\n\n{{#entities}}\n- [{{node}}]({{href}}) — {{summary}} ({{symbolCount}} symbol{{^one}}s{{/one}})\n{{/entities}}\n{{/hasEntities}}\n{{#hasTemplates}}\n\n## Templates\n\n{{#templates}}\n- [{{node}}]({{href}}) — {{summary}} ({{symbolCount}} symbol{{^one}}s{{/one}})\n{{/templates}}\n{{/hasTemplates}}\n",
+  "docs/entity-page.md": "{{{generatedMarker}}}\n\n# {{entity.name}}\n{{#summaryLead}}\n\n{{{.}}}\n{{/summaryLead}}\n{{#descriptionQuote}}\n\n{{{.}}}\n{{/descriptionQuote}}\n{{#apiRefs.0}}\n\n**API reference:** {{/apiRefs.0}}{{#apiRefs}}[{{label}}]({{href}}){{^last}} · {{/last}}{{/apiRefs}}{{#apiRefs.0}}\n{{/apiRefs.0}}\n\n{{{preambleHeader}}}\n{{#hasIdentities}}\n\n## Identity\n\n{{#identities}}\n- {{{bullet}}}\n{{/identities}}\n{{/hasIdentities}}\n{{#hasNeighborhoodEr}}\n\n## In context\n\n{{{neighborhoodErBlock}}}\n{{/hasNeighborhoodEr}}\n{{#fields.hasFields}}\n\n## Fields\n\n| Field | Type | Required | Column | Rules |\n|---|---|---|---|---|\n{{#fields.rows}}\n| {{{fieldCell}}} | {{{typeCell}}} | {{requiredCell}} | {{{storageCell}}} | {{{rulesCell}}} |\n{{/fields.rows}}\n{{/fields.hasFields}}\n{{#fieldDetails.hasDetails}}\n\n## Field details\n\n{{#fieldDetails.rows}}\n{{{block}}}\n\n{{/fieldDetails.rows}}\n{{/fieldDetails.hasDetails}}\n{{#hasRelationships}}\n\n## Relationships\n\n{{#relationships}}\n- {{{bullet}}}\n{{/relationships}}\n{{/hasRelationships}}\n{{#hasUsedBy}}\n\n## Used by\n\n{{#usedBy}}\n- {{{bullet}}}\n{{/usedBy}}\n{{/hasUsedBy}}\n",
+  "docs/template-page.md": "{{{generatedMarker}}}\n\n# {{name}}\n{{#descriptionQuote}}\n\n{{{.}}}\n{{/descriptionQuote}}\n\n**Kind:** {{kind}}\n\n## Output\n{{^isEmail}}\n\n- Format: `{{format}}`\n{{/isEmail}}\n{{#isEmail}}\n\nMultipart email — rendered as the following parts:\n\n| Part | Source | Format | Escaping |\n|---|---|---|---|\n{{#parts}}\n| {{label}} | `{{ref}}` | `{{format}}` | {{#escaped}}escaped{{/escaped}}{{^escaped}}raw{{/escaped}} |\n{{/parts}}\n{{/isEmail}}\n\n## Input\n\n- Payload: [`{{payload.name}}`]({{payload.link}})\n{{#hasRequiredTags}}\n- Required fields:{{#requiredTags}} `{{.}}`{{/requiredTags}}\n{{/hasRequiredTags}}\n\n## Render contract\n\n- Every field referenced by the template is validated against the payload at generation time; an unknown field fails generation.\n{{#maxChars}}\n- Maximum length: {{.}} characters (rendering longer output fails).\n{{/maxChars}}\n{{#hasRequiredTags}}\n- Required tags must be present:{{#requiredTags}} `{{.}}`{{/requiredTags}}\n{{/hasRequiredTags}}\n\n## Source\n\n{{#sourceRefs}}\n- `{{.}}`\n{{/sourceRefs}}\n{{#templateSourceSection}}\n\n{{{.}}}\n{{/templateSourceSection}}\n\n## Capability\n\n{{capability}}\n",
+};

package/src/render-engine/framework-provider.ts

@@ -16,6 +16,7 @@ import type { Provider } from "@metaobjectsdev/render";
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { EMBEDDED_FRAMEWORK_TEMPLATES } from "./embedded-templates.generated.js";
 
 /** Canonical shipped template — used to verify a candidate framework
  *  templates directory actually contains our defaults. Without this check a
@@ -31,8 +32,11 @@ const CANONICAL_TEMPLATE_REL = "docs/entity-page.md.mustache";
  *
  *  Returns `undefined` when no on-disk templates dir can be found — e.g. inside
  *  the `bun build --compile` standalone binary, whose `import.meta.url` is a
- *  `/$bunfs/root` virtual path with no real `package.json` alongside it. The
- *  embedded-template fallback (see `FileSystemProvider`) covers that case. */
+ *  `/$bunfs/root` virtual path with no real `package.json` alongside it. In that
+ *  case `FrameworkTemplatesProvider.resolve` falls back to the bundled
+ *  `EMBEDDED_FRAMEWORK_TEMPLATES` (embedded-templates.generated.ts), a plain
+ *  string module generated from the canonical templates/docs/*.mustache and
+ *  compiled into the binary. */
 function findFrameworkTemplatesDir(start: string): string | undefined {
   let dir = start;
   while (true) {
@@ -81,23 +85,33 @@ export class FileSystemProvider implements Provider {
 }
 
 /** The framework defaults provider — resolves refs against codegen-ts's own
- *  on-disk `templates/` directory.
+ *  on-disk `templates/` directory, falling back to the bundled
+ *  `EMBEDDED_FRAMEWORK_TEMPLATES` when no on-disk dir exists.
  *
  *  Resolution is lazy: the directory is located on first `resolve()`, not at
  *  module import. This keeps merely importing this module side-effect-free,
  *  which matters for the `bun build --compile` standalone `meta` binary — its
  *  `import.meta.url` is a `/$bunfs/root` virtual path with no on-disk
- *  `templates/` dir, so eager resolution at import time used to throw before
- *  any command (even `--help` or the schema ops `migrate`/`verify --db`) could
- *  run. Now non-codegen commands import cleanly; only the codegen doc path
- *  (which the standalone binary doesn't target) needs the on-disk dir. */
+ *  `templates/` dir.
+ *
+ *  ON-DISK FIRST, then embedded: the source/install layout (and adopter
+ *  overrides chained ahead of this provider via `projectProvider`) always wins,
+ *  so local edits to the shipped package `templates/` still take effect. Only
+ *  when the on-disk dir is unresolved (the compiled binary) — or a ref the dir
+ *  doesn't contain — do we consult the embedded map, which is generated from
+ *  the same canonical templates and compiled into the binary. Unknown refs are
+ *  `undefined` in the map, which is the correct miss. */
 class FrameworkTemplatesProvider implements Provider {
   resolve(ref: string): string | undefined {
+    // On-disk first: dev/install layout, plus shipped-package edits.
     const dir = frameworkTemplatesDir();
-    if (dir === undefined) return undefined;
-    const path = join(dir, `${ref}.mustache`);
-    if (!existsSync(path)) return undefined;
-    return readFileSync(path, "utf-8");
+    if (dir !== undefined) {
+      const path = join(dir, `${ref}.mustache`);
+      if (existsSync(path)) return readFileSync(path, "utf-8");
+    }
+    // Embedded fallback: the binary case (no on-disk dir) or a ref the on-disk
+    // dir doesn't carry. `undefined` for unknown refs is the correct miss.
+    return EMBEDDED_FRAMEWORK_TEMPLATES[ref];
   }
 }
 

package/src/runner.ts

@@ -20,6 +20,10 @@ import {
  *  from untrusted sources (e.g. MCP). Mirrors the guard in legacy generate.ts. */
 const VALID_ENTITY_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+/** ADR-0025: doc generators whose single door is `meta docs`. If a `meta gen`
+ *  config still lists one (by its stable `name`), the runner warns + skips it. */
+const DEPRECATED_DOC_GENERATORS = new Set(["docs-file", "api-docs"]);
+
 export interface RunGenOpts {
   config: MetaobjectsGenConfig;
   metadata: MetaData;
@@ -143,9 +147,24 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     root.objects().map((o) => [o.name, o.package]),
   );
 
+  // Auto-detect: is the OPT-IN Hono routes generator in the active suite? If so,
+  // surface it on every generator's ctx.config so api-docs documents the Hono
+  // CRUD surface it actually emits (rather than silently omitting it).
+  const includeHonoRoutes = config.generators.some((g) => g.emitsHonoRoutes === true);
+
   // 4. Run each generator with a per-target render context; collect with full path.
   const emitted: { fullPath: string; content: string; generatedBy: string }[] = [];
   for (const generator of config.generators) {
+    // ADR-0025: `meta docs` is the single docs door. A `meta gen` config that
+    // still lists a deprecated doc generator is warned + skipped, not run — the
+    // generator stays as `meta docs`'s internal engine.
+    if (DEPRECATED_DOC_GENERATORS.has(generator.name)) {
+      warnings.push(
+        `[${generator.name}] docs are produced by 'meta docs' (ADR-0025); ` +
+        `remove ${generator.name === "api-docs" ? "apiDocsFile()" : "docsFile()"} from generators. Skipped.`,
+      );
+      continue;
+    }
     const selfTarget = targetOf(generator);
     const renderContext = makeRenderContext({
       dialect: config.dialect,
@@ -154,6 +173,9 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       dbImport: selfTarget.dbImport,
       extStyle: config.extStyle,
       columnNamingStrategy: config.columnNamingStrategy,
+      pluralizeCollections: config.pluralizeCollections,
+      collectionNameOverrides: config.collectionNameOverrides,
+      timestampMode: config.timestampMode,
       apiPrefix: config.apiPrefix,
       emitAbstractShapes: config.emitAbstractShapes,
       outputLayout: selfTarget.outputLayout,
@@ -162,6 +184,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       packageOf,
       selfTarget,
       entityModuleTarget,
+      ...(config.providedEnumModule !== undefined && { providedEnumModule: config.providedEnumModule }),
     });
     const ctx: GenContext = {
       entities: safeEntities,
@@ -173,6 +196,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         dbImport: selfTarget.dbImport,
         dialect: config.dialect,
         outputLayout: selfTarget.outputLayout,
+        includeHonoRoutes,
       },
       renderContext,
       ...(projectRoot !== undefined && { projectRoot }),