@metaobjectsdev/codegen-ts 0.24.4 → 0.24.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/codegen-ts",
-  "version": "0.24.4",
+  "version": "0.24.5",
   "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.24.4",
-    "@metaobjectsdev/render": "0.24.4",
+    "@metaobjectsdev/metadata": "0.24.5",
+    "@metaobjectsdev/render": "0.24.5",
     "@biomejs/js-api": "^0.7.0",
     "@biomejs/wasm-nodejs": "^1.9.4",
     "@toon-format/toon": "^2.3.0",
@@ -124,9 +124,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",
-    "@metaobjectsdev/codegen-ts-react": "0.24.4",
-    "@metaobjectsdev/migrate-ts": "0.24.4",
-    "@metaobjectsdev/runtime-ts": "0.24.4",
+    "@metaobjectsdev/codegen-ts-react": "0.24.5",
+    "@metaobjectsdev/migrate-ts": "0.24.5",
+    "@metaobjectsdev/runtime-ts": "0.24.5",
     "bun-types": "latest",
     "drizzle-orm": "^0.38.0",
     "hono": "^4.6.0",

package/src/client-directive.ts

@@ -0,0 +1,36 @@
+// FR-040 §6.4 — the module-level client-component directive on generated CLIENT
+// artifacts (forms, hooks, grid columns, grid hooks).
+//
+// One implementation in the shared engine rather than a string literal in each of the
+// four UI generators: the directive must be the FIRST statement in the module to have
+// any effect, and "prepend a line" is the kind of thing four copies get subtly
+// different (a missing blank line, a single-quoted variant, or — the one that actually
+// breaks — emitted after the generated header comment in one and before it in another).
+//
+// Why this is a config knob and not metadata, and why it defaults OFF, is on
+// `MetaobjectsGenConfig.clientDirective`.
+
+/** The directive itself. Double-quoted to match the emitted code's own quote style. */
+export const CLIENT_DIRECTIVE = '"use client";';
+
+/**
+ * Prepend the client directive to a generated module body when the project asked for it.
+ *
+ * Placement is the whole point: a directive prologue is only honoured before any other
+ * statement, and — unlike a runtime statement — it must also precede the `@generated`
+ * header comment for some bundlers to see it, so this goes at absolute position 0.
+ * Idempotent: a body that already opens with the directive (a hand edit preserved
+ * through three-way merge, or an owned generator that adds its own) is returned
+ * unchanged rather than given a second copy.
+ *
+ * @param body    the rendered module source.
+ * @param enabled `ctx.clientDirective` — false (the default) returns `body` untouched,
+ *                so output is byte-identical for every project that does not opt in.
+ */
+export function withClientDirective(body: string, enabled: boolean): string {
+  if (!enabled) return body;
+  // Tolerate either quote style when checking, so an adopter's own `'use client'`
+  // is not doubled — but always EMIT the canonical form.
+  if (/^\s*['"]use client['"];?/.test(body)) return body;
+  return `${CLIENT_DIRECTIVE}\n\n${body}`;
+}

package/src/generators/routes-file-hono.ts

@@ -31,6 +31,15 @@ export interface RoutesFileHonoOpts {
  */
 export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts): Generator {
   const userFilter = opts?.filter ?? (() => true);
+  // Eligibility, minus the TPH question — stated ONCE so the emit set and the warn set
+  // below cannot drift apart. They differ only by `!isTphSubtype` vs `isTphSubtype`, and
+  // written out twice a later edit to one silently makes an entity either stop emitting
+  // without being named as held back, or get warned about while still emitting.
+  const passesOtherGates = (e: MetaObject): boolean =>
+    // ADR-0039: resolving — a concrete entity may inherit @emitRoutes via extends.
+    e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false
+    && hasAnyRdbSource(e)
+    && userFilter(e);
   const generator: Generator = {
     name: "routes-file-hono",
     // Marks this as the Hono routes generator so the runner can aggregate
@@ -46,18 +55,11 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
     // these to a discriminator-aware renderer; the Hono runtime has no discriminator
     // support yet, so this fails CLOSED and the run says so (see the warning below)
     // rather than shipping an artifact that returns the wrong rows.
-    filter: (e: MetaObject) =>
-      e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false
-      && hasAnyRdbSource(e)
-      && !isTphSubtype(e)
-      && userFilter(e),
+    filter: (e: MetaObject) => passesOtherGates(e) && !isTphSubtype(e),
     generate: async (ctx) => {
       // One note per run naming every TPH subtype held back, so the gap is visible at
       // `meta gen` time rather than discovered as missing endpoints in production.
-      const skipped = ctx.entities.filter(
-        (e) => e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false
-          && hasAnyRdbSource(e) && isTphSubtype(e) && userFilter(e),
-      );
+      const skipped = ctx.entities.filter((e) => passesOtherGates(e) && isTphSubtype(e));
       if (skipped.length > 0) {
         ctx.warn(
           `no Hono routes emitted for the TPH subtype(s) ${skipped.map((e) => e.name).join(", ")} — ` +

package/src/index.ts

@@ -110,7 +110,7 @@ export { renderSharedEnumsFile, SHARED_ENUMS_BASENAME } from "./templates/enums-
 
 // 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 { resolveReferenceRoot, readReferenceTemplate, REFERENCE_GENERATOR_NAMES, makeReferenceReader } from "./reference-templates.js";
 export type { ReferenceGeneratorName } from "./reference-templates.js";
 
 // ts-poet composition primitives, re-exported from THIS package's own ts-poet
@@ -161,6 +161,7 @@ export { renderFilterAllowlist, renderSortAllowlist } from "./templates/filter-a
 export { renderEntityConstants, resourcePath } from "./templates/entity-constants.js";
 export { renderQueriesFile } from "./templates/queries-file.js";
 export { renderRoutesFile } from "./templates/routes-file.js";
+export { renderRoutesFileHono } from "./templates/routes-file-hono.js";
 export { renderValueObjectFile } from "./templates/value-object-file.js";
 export { renderProjectionDecl } from "./templates/projection-decl.js";
 export type { ProjectionDeclOpts } from "./templates/projection-decl.js";
@@ -251,3 +252,7 @@ export type {
   SweepOrphansArgs,
   SweepOrphansResult,
 } from "./orphan-sweep.js";
+
+// FR-040 §6.4 — the client-component directive for generated CLIENT artifacts.
+// Public so an OWNED generator applies it the same way the built-ins do.
+export { withClientDirective, CLIENT_DIRECTIVE } from "./client-directive.js";

package/src/metaobjects-config.ts

@@ -108,6 +108,34 @@ export interface MetaobjectsGenConfig extends Omit<ResolvedGenConfig, "dbImport"
    * (e.g. `{ AuditLog: "auditLog", LlmTierConfig: "llmTierConfig" }`).
    */
   collectionNameOverrides?: Record<string, string>;
+  /**
+   * Prepend a module-level client-component directive — `"use client";` — to every
+   * generated CLIENT artifact (forms, hooks, grid columns, grid hooks). Defaults to
+   * `false`. FR-040 §6.4.
+   *
+   * **Why this is config and not a metadata attribute.** It is a fact about the
+   * adopter's BUNDLER TOPOLOGY, not about the entity — the metamodel contains nothing
+   * that could derive it, and every non-TS port would carry a registration it can never
+   * dispatch on, which is the `source.rdb @role` mistake that retired four members in
+   * 0.21.0. It sits here beside `extStyle` and `columnNamingStrategy` for the same
+   * reason `pluralizeCollections` does: a per-port codegen concern (ADR-0001), so
+   * config, and no cross-port conformance cost.
+   *
+   * **Why it defaults to `false`.** The generated form and hook modules genuinely ARE
+   * client components, so the directive is a true statement about them — but it is only
+   * REQUIRED by frameworks that compile server and client from one tree (React Server
+   * Components). Elsewhere it is inert and provokes module-level-directive warnings in
+   * some bundlers, so defaulting it on would put noise in every generated UI file for
+   * the majority to save the minority one line. The asymmetry that would argue for
+   * defaulting on — a runtime error for RSC adopters versus a build warning for
+   * everyone else — is what FR-040 itself removed: before it, an RSC adopter had no
+   * seam at all; now it is this flag, or `meta eject form` and a one-line prepend.
+   *
+   * Flipping the default needs EVIDENCE, not a guess about majorities — the standard
+   * `extStyle` was held to in 0.20.1, where the default moved because the documented
+   * quickstart provably failed under a stock `tsc --init`.
+   */
+  clientDirective?: boolean;
   /**
    * Drizzle timestamp column mode. "string" (default) types timestamp columns as
    * ISO-8601 strings (matches the generated Zod + cross-port wire contract); "date"
@@ -186,6 +214,7 @@ export interface NormalizedMetaobjectsGenConfig
   pluralizeCollections: boolean;
   collectionNameOverrides: Record<string, string>;
   timestampMode: "date" | "string";
+  clientDirective: boolean;
   apiPrefix: string;
   emitAbstractShapes: boolean;
   outputLayout: OutputLayout;
@@ -322,6 +351,7 @@ export function normalizeConfig(config: MetaobjectsGenConfig): NormalizedMetaobj
     // normalize to "string" on sqlite/D1 at this one choke point so the option
     // can never silently emit a non-compiling column + a disagreeing Zod schema.
     timestampMode: dialect === "sqlite" ? "string" : (config.timestampMode ?? "string"),
+    clientDirective: config.clientDirective ?? false,
     apiPrefix: config.apiPrefix ?? "",
     emitAbstractShapes: config.emitAbstractShapes ?? true,
     outputLayout: config.outputLayout ?? "flat",

package/src/naming.ts

@@ -191,5 +191,28 @@ export function routesHandlerName(entityName: string): string {
   return `${entityName.charAt(0).toLowerCase()}${entityName.slice(1)}Routes`;
 }
 
+
+/**
+ * The PascalCase base every generated symbol for a `template.*` node is built from —
+ * `render<Base>`, `parse<Base>`, `safeParse<Base>`, `<Base>Schema`, `<Base>Data`,
+ * `<Base>ValidationError`, `extractLenient<Base>WithLoader`.
+ *
+ * Kept here, and used by ALL of the template emitters, because they disagreed. Three
+ * generators named the same node three ways: `promptRender()`'s handle applied a private
+ * `pascal()` (`renderTriageTicket`), while `outputParser()` and the render-helper
+ * concatenated the raw name (`parsetriageTicket`, `type triageTicketData`). One `meta gen`
+ * run, one template, two conventions — and the skill's own examples use the lower-camel
+ * spelling that triggers it, so following the documentation is what produced it.
+ *
+ * An UpperCamel template name is unaffected (`pascal("TriageTicket") === "TriageTicket"`),
+ * so this only moves symbols for lower-camel names, which are exactly the ones that were
+ * spelled inconsistently.
+ */
+export function templateSymbolBase(templateName: string): string {
+  return templateName.length > 0
+    ? templateName[0]!.toUpperCase() + templateName.slice(1)
+    : templateName;
+}
+
 // Re-exported here for callers that import from codegen-ts's naming module.
 export { toKebabCase };

package/src/payload-codegen.ts

@@ -41,6 +41,7 @@ import {
   stripPackage,
 } from "@metaobjectsdev/metadata";
 import { enumValues } from "./enum-meta.js";
+import { templateSymbolBase } from "./naming.js";
 import { enumUnionAliasName, enumUnionString } from "./templates/inferred-types.js";
 import { assignEmittedNames } from "./naming/collision-names.js";
 
@@ -258,9 +259,9 @@ export function generatePayloadInterfacesBatch(
   return out.length === 0 ? "" : out.join("\n\n") + "\n";
 }
 
-function pascal(s: string): string {
-  return s.length > 0 ? s[0]!.toUpperCase() + s.slice(1) : s;
-}
+// Delegates to the shared authority so this emitter cannot drift from the parser and
+// render-helper again (naming.ts / templateSymbolBase).
+const pascal = templateSymbolBase;
 
 /** Emit a typed render handle binding a template's @textRef + @format and typing its payload. */
 export function generateRenderHandle(root: MetaData, templateName: string): string {

package/src/prompt-generator-gate.ts

@@ -0,0 +1,73 @@
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_PROMPT, TEMPLATE_ATTR_RESPONSE_REF } from "@metaobjectsdev/metadata";
+import type { Generator } from "./generator.js";
+
+/**
+ * Generators that turn a declared `template.*` into runnable prompt code. Names, not
+ * identities, because an adopter may wrap or re-export them (ADR-0034 scaffold-and-own
+ * makes owning a copy the encouraged path) and a wrapper keeps the name.
+ */
+const PROMPT_GENERATOR_NAMES: ReadonlySet<string> = new Set([
+  "prompt-render",
+  "output-parser",
+  "render-helper",
+  "output-prompt",
+]);
+
+/**
+ * A declared prompt with no prompt generator wired produced NOTHING and said NOTHING.
+ *
+ * `meta gen` emitted the payload value objects (they are `object.value` nodes, which the
+ * entity generator picks up) and stopped there: no `render<Name>()`, no parser, no
+ * response-format fragment. `meta verify` then reported "1 template(s) clean", which reads
+ * as confirmation that the prompt is fine. So the fourth pillar produced two type files and
+ * a green gate, and the adopter had neither a send side nor a receive side.
+ *
+ * The wiring IS documented — but only in the prompts skill's per-language reference
+ * fragment, which SKILL.md points at in its final line, while the skill body walks the
+ * entire declaration without once saying a generator is required. Found by declaring a
+ * `template.prompt` in a from-scratch app exactly as that skill teaches.
+ *
+ * This follows the `layout.dataGrid` precedent (#287, data-grid-gate.ts): tell the adopter
+ * at `meta gen` time rather than adding a doc line that gets missed the same way. It is a
+ * WARNING — the exit code is untouched — and it is **self-extinguishing**: wire any one
+ * prompt generator and it goes quiet forever, so a project that has made this choice
+ * deliberately is never nagged.
+ *
+ * It must live in the runner rather than in a generator, because the whole condition is
+ * that the generator which would speak up is not running.
+ */
+export function warnMissingPromptGenerators(
+  root: MetaData,
+  generators: readonly Generator[],
+  warn: (msg: string) => void,
+): void {
+  if (generators.some((g) => PROMPT_GENERATOR_NAMES.has(g.name))) return;
+
+  // ADR-0039: resolving children — a template may arrive through an overlay or extends.
+  const templates = root
+    .children()
+    .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_PROMPT);
+  if (templates.length === 0) return;
+
+  const names = templates.map((t) => t.name).join(", ");
+  // A @responseRef is what asks for the inbound tier (ADR-0052), so a responding prompt
+  // is missing strictly more than an outbound-only one. Name that, rather than making the
+  // adopter infer which half is absent.
+  const responding = templates.filter((t) => typeof t.attr(TEMPLATE_ATTR_RESPONSE_REF) === "string");
+  const receiveHalf =
+    responding.length > 0
+      ? ` ${responding.length === templates.length ? "All" : `${responding.length} of them`} ` +
+        `declare a @responseRef, so the parser and response-format fragment are missing too — ` +
+        `add outputParser().`
+      : "";
+
+  warn(
+    `${templates.length} declared template.prompt (${names}) generated no prompt code: ` +
+      `no prompt generator is wired, so there is no render function to send one and nothing ` +
+      `read a reply. Add promptRender() to \`generators\` in metaobjects.config.ts ` +
+      `(import it from "@metaobjectsdev/codegen-ts/generators").${receiveHalf} ` +
+      `The payload value objects were emitted regardless — those are object.value nodes, ` +
+      `which is why this looked like it had worked.`,
+  );
+}

package/src/reference/barrel.ts

@@ -6,6 +6,9 @@
 // shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
 // reach for `Bun.*` globals here; they are undefined and take the whole run down with
 // `Bun is not defined`. Use `node:` builtins instead.
+// targets:       nothing framework-specific — it re-exports whatever the other generators
+//                emitted. `extStyle` decides whether the re-export specifiers carry a
+//                `.js` extension.
 // 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.

package/src/reference/entity.ts

@@ -6,6 +6,13 @@
 // shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
 // reach for `Bun.*` globals here; they are undefined and take the whole run down with
 // `Bun is not defined`. Use `node:` builtins instead.
+// targets:       Drizzle ORM + Zod. The emitted module is a Drizzle table plus Zod
+//                insert/update schemas; the column mapping follows `dialect`. On the
+//                default (vanilla) path, replace the `renderDrizzleSchema` /
+//                `renderZodValidators` calls to target a different ORM or validator — the
+//                metadata walk that feeds them is ORM-neutral. (The `isWriteThrough`
+//                branch calls `renderEntityFile` instead — a narrow #214 read-view case,
+//                not the default.)
 // 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.

package/src/reference/queries.ts

@@ -6,6 +6,11 @@
 // shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
 // reach for `Bun.*` globals here; they are undefined and take the whole run down with
 // `Bun is not defined`. Use `node:` builtins instead.
+// targets:       Drizzle. Emitted helpers take `db` as a PARAMETER rather than importing
+//                a module singleton, so they compose with any caller that already holds a
+//                connection — including a server-rendered component. Swap the
+//                `render<Verb>Fn` primitives (findById/list/create/update/deleteById) and
+//                the inline `Db` type block above them to emit for another query builder.
 // 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 source-backed object (any source.rdb kind,

package/src/reference/routes-hono.ts

@@ -0,0 +1,103 @@
+// REFERENCE TEMPLATE — copy this into your repo (e.g. codegen/generators/routes-hono.ts) and own it.
+// Then import it LOCALLY in metaobjects.config.ts:
+//   import { routesFileHono } from "./codegen/generators/routes-hono.js";
+//
+// RUNTIME: this file executes under whatever runs `meta gen`, and the published CLI's
+// shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
+// reach for `Bun.*` globals here; they are undefined and take the whole run down with
+// `Bun is not defined`.
+// targets:       Hono. The emitted file imports `mountCrudRoutes` from
+//                `@metaobjectsdev/runtime-ts/hono` and takes its persistence client as
+//                INJECTED DEPS (`register<Entity>Routes(app, { db })`) rather than a
+//                module-singleton import — which is what makes it portable to any host
+//                that can hand Hono a request. If your framework is not Hono, THIS is the
+//                file to retarget: swap the mount helper and the exported signature; the
+//                metadata walk above it is framework-neutral and stays as-is.
+// use-when:      you want generated Hono CRUD routes per entity.
+// emits:         <target>/<Entity>.routes.hono.ts — full CRUD for write-through entities,
+//                read-only (GET list + GET :id) for projections. Skipped for any sourceless
+//                object and for TPH subtypes.
+// customize:     this generator is YOURS — edit it freely. For the emitted route
+//                composition, call `renderRoutesFileHono` (exported from the engine) and
+//                wrap its result, or replace the call entirely.
+// composes-with: entity.ts (imports the table/schemas/allowlists), queries.ts.
+
+import { type MetaObject } from "@metaobjectsdev/metadata";
+import {
+  perEntity,
+  type Generator,
+  type GeneratorFactory,
+  renderRoutesFileHono,
+  isTphSubtype,
+  hasAnyRdbSource,
+  formatTs,
+  entityOutputPath,
+  CODEGEN_ATTR_EMIT_ROUTES,
+} from "@metaobjectsdev/codegen-ts";
+
+export interface RoutesFileHonoOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts): Generator {
+  const userFilter = opts?.filter ?? (() => true);
+  // Eligibility, minus the TPH question — stated ONCE so the emit set and the warn set
+  // below cannot drift apart. They differ only by `!isTphSubtype` vs `isTphSubtype`, and
+  // written out twice a later edit to one silently makes an entity either stop emitting
+  // without being named as held back, or get warned about while still emitting.
+  // (Same shape as tanstack's grid generator, which factors it the same way.)
+  const passesOtherGates = (e: MetaObject): boolean =>
+    // ADR-0039: resolving — a concrete entity may inherit @emitRoutes via extends.
+    e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false
+    && hasAnyRdbSource(e)
+    && userFilter(e);
+  const generator: Generator = {
+    name: "routes-file-hono",
+    // Marks this as the Hono routes generator so the runner can aggregate
+    // `ctx.config.includeHonoRoutes` and api-docs auto-documents the Hono surface.
+    emitsHonoRoutes: true,
+    // ADR-0039: resolving — a concrete entity may inherit @emitRoutes via extends.
+    //
+    // TPH subtypes are EXCLUDED, matching the Fastify generator. A TPH subtype shares
+    // its base's table, so mounting vanilla CRUD for it produced routes with no
+    // discriminator scoping at all: the list returned EVERY subtype's rows, and
+    // get/patch/delete by id happily operated on rows belonging to a different
+    // subtype. Silently wrong data, which is worse than no route. Fastify dispatches
+    // these to a discriminator-aware renderer; the Hono runtime has no discriminator
+    // support yet, so this fails CLOSED and the run says so (see the warning below)
+    // rather than shipping an artifact that returns the wrong rows.
+    filter: (e: MetaObject) => passesOtherGates(e) && !isTphSubtype(e),
+    generate: async (ctx) => {
+      // One note per run naming every TPH subtype held back, so the gap is visible at
+      // `meta gen` time rather than discovered as missing endpoints in production.
+      const skipped = ctx.entities.filter((e) => passesOtherGates(e) && isTphSubtype(e));
+      if (skipped.length > 0) {
+        ctx.warn(
+          `no Hono routes emitted for the TPH subtype(s) ${skipped.map((e) => e.name).join(", ")} — ` +
+          "the Hono adapter has no discriminator scoping yet, so per-subtype CRUD would " +
+          "return and mutate OTHER subtypes' rows. Use routesFile() (Fastify), which " +
+          "dispatches TPH correctly, or hand-write the scoped routes.",
+        );
+      }
+      return emit(ctx);
+    },
+  };
+  const emit = perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error("routes-file-hono: renderContext is required (provided by runGen)");
+      }
+      return {
+        path: entityOutputPath(
+          ctx.config.outputLayout ?? "flat",
+          entity.package,
+          `${entity.name}.routes.hono.ts`,
+        ),
+        content: await formatTs(renderRoutesFileHono(entity, ctx.renderContext)),
+      };
+  });
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<RoutesFileHonoOpts>;

package/src/reference/routes.ts

@@ -6,6 +6,11 @@
 // shebang is `#!/usr/bin/env node` — so it runs under NODE even in a Bun project. Do not
 // reach for `Bun.*` globals here; they are undefined and take the whole run down with
 // `Bun is not defined`. Use `node:` builtins instead.
+// targets:       Fastify. The emitted file imports `mountCrudRoutes` from
+//                `@metaobjectsdev/runtime-ts/drizzle-fastify` and binds a
+//                module-singleton `db`. THIS is the file to retarget for another HTTP
+//                framework; see also the routes-hono template, whose deps-injected shape
+//                ports more easily to hosts that hand you a request.
 // use-when:      you want generated Fastify REST routes per entity. Drop it and hand-write routes
 //                if you need bespoke endpoints — or keep it and add handlers via <Entity>.extra.ts.
 // emits:         <target>/<Entity>.routes.ts — full CRUD for write-through entities, read-only

package/src/reference-templates.ts

@@ -13,37 +13,77 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** Basenames (no extension) of the copyable reference generators shipped in `src/reference/`. */
-export const REFERENCE_GENERATOR_NAMES = ["entity", "queries", "routes", "barrel"] as const;
+export const REFERENCE_GENERATOR_NAMES = ["entity", "queries", "routes", "routes-hono", "barrel"] as const;
 export type ReferenceGeneratorName = (typeof REFERENCE_GENERATOR_NAMES)[number];
 
-/** A directory is the reference root iff it holds the entity reference template. */
-function isReferenceRoot(dir: string): boolean {
-  return existsSync(join(dir, "entity.ts"));
+/** A directory is a reference root iff it holds the first template the reader was told to expect. */
+function isReferenceRoot(dir: string, sentinel: string): boolean {
+  return existsSync(join(dir, `${sentinel}.ts`));
 }
 
 /**
- * Resolve the `src/reference/` directory holding the copyable reference generators.
- * Works in dev (this module runs from `src/`, templates at `./reference/`) and in a
- * published install (this module runs from `dist/`, templates at `../src/reference/`,
- * since `src/` ships alongside `dist/`). Walks up checking both layouts at each level.
+ * FR-040 §4.1 — build a reference-template reader for ONE package. `moduleUrl` is the
+ * calling module's `import.meta.url`, so each package resolves its OWN `src/reference/`.
+ * `names[0]` is the sentinel that identifies the directory.
+ *
+ * Works in dev (module runs from `src/`, templates at `./reference/`) and in a published
+ * install (module runs from `dist/`, templates at `../src/reference/`, since `src/` ships
+ * alongside `dist/`). Walks up checking both layouts at each level.
  */
-export function resolveReferenceRoot(): string {
-  let dir = dirname(fileURLToPath(import.meta.url));
-  for (let i = 0; i < 8; i++) {
-    for (const candidate of [join(dir, "reference"), join(dir, "src", "reference")]) {
-      if (isReferenceRoot(candidate)) return candidate;
+export function makeReferenceReader(moduleUrl: string, names: readonly [string, ...string[]]) {
+  // A non-empty tuple type, so `names[0]` is `string` outright — this used to need a
+  // runtime empty-check plus a re-bound const, because `noUncheckedIndexedAccess`
+  // narrowing does not survive into the closures below. Every call site already passes
+  // an `as const` tuple or an array literal, so the type costs nothing and deletes both.
+  const sentinel: string = names[0];
+
+  function resolveReferenceRoot(): string {
+    let dir = dirname(fileURLToPath(moduleUrl));
+    for (let i = 0; i < 8; i++) {
+      for (const candidate of [join(dir, "reference"), join(dir, "src", "reference")]) {
+        if (isReferenceRoot(candidate, sentinel)) return candidate;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
     }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
+    throw new Error(
+      "reference templates not found — looked for `reference/` and `src/reference/` " +
+        `walking up from ${dir}.`,
+    );
   }
-  throw new Error(
-    "codegen-ts reference templates not found — looked for `reference/` and `src/reference/` " +
-      "walking up from the codegen-ts module.",
-  );
+
+  return {
+    resolveReferenceRoot,
+    /**
+     * Read one template by name. The name is checked against `names` FIRST: this is a
+     * public export, so `name` is an untrusted `string` at runtime (the per-package
+     * wrappers narrow to a literal union, but types are erased). Without the check it
+     * interpolates straight into a path, so any caller threading a CLI argument through
+     * reads whatever file the string points at. The allowlist is already a parameter —
+     * enforcing it here makes the guarantee structural instead of something every call
+     * site has to remember, and it is the reason `meta eject` needs no check of its own.
+     */
+    readReferenceTemplate: (name: string): string => {
+      if (!names.includes(name)) {
+        throw new Error(
+          `unknown reference template "${name}". Available: ${names.join(", ")}.`,
+        );
+      }
+      return readFileSync(join(resolveReferenceRoot(), `${name}.ts`), "utf8");
+    },
+  };
+}
+
+// This package's own reader — the back-compatible named exports `meta init` uses.
+const ownReader = makeReferenceReader(import.meta.url, REFERENCE_GENERATOR_NAMES);
+
+/** Resolve the `src/reference/` directory holding this package's reference generators. */
+export function resolveReferenceRoot(): string {
+  return ownReader.resolveReferenceRoot();
 }
 
 /** Read the raw source of one reference generator (e.g. `"entity"` → the text of `entity.ts`). */
 export function readReferenceTemplate(name: ReferenceGeneratorName): string {
-  return readFileSync(join(resolveReferenceRoot(), `${name}.ts`), "utf8");
+  return ownReader.readReferenceTemplate(name);
 }

package/src/render-context.ts

@@ -52,6 +52,13 @@ export interface RenderContext {
    * doc comment on `MetaobjectsGenConfig.timestampMode` in metaobjects-config.ts.
    */
   timestampMode: "date" | "string";
+  /**
+   * Prepend `"use client";` to generated CLIENT artifacts (forms, hooks, grid
+   * columns, grid hooks). Defaults to false. A bundler-topology fact the adopter
+   * declares — see `MetaobjectsGenConfig.clientDirective` for why it is config
+   * rather than metadata, and why the default is off. FR-040 §6.4.
+   */
+  clientDirective: boolean;
   /** 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. */
@@ -101,11 +108,12 @@ export interface RenderContext {
 }
 
 /** 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" | "valueObjectNames" | "valueObjectEmittedName" | "resolveValueObjectName" | "selfTarget" | "entityModuleTarget" | "collectionName"> & {
+export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "timestampMode" | "clientDirective" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "valueObjectNames" | "valueObjectEmittedName" | "resolveValueObjectName" | "selfTarget" | "entityModuleTarget" | "collectionName"> & {
   extStyle?: ExtStyle;
   omImport?: string;
   columnNamingStrategy?: ColumnNamingStrategy;
   timestampMode?: "date" | "string";
+  clientDirective?: boolean;
   apiPrefix?: string;
   emitAbstractShapes?: boolean;
   outputLayout?: OutputLayout;
@@ -184,6 +192,7 @@ export function makeRenderContext(opts: RenderContextInput): RenderContext {
     // a unit test or a generator invoked outside `runGen`, must get the same
     // safe-no-op guarantee). See MetaobjectsGenConfig.timestampMode's doc comment.
     timestampMode: opts.dialect === "sqlite" ? "string" : (opts.timestampMode ?? "string"),
+    clientDirective: opts.clientDirective ?? false,
     apiPrefix: opts.apiPrefix ?? "",
     emitAbstractShapes: opts.emitAbstractShapes ?? true,
     outputLayout,

package/src/runner.ts

@@ -1,4 +1,5 @@
 import { join, relative, resolve, isAbsolute, dirname } from "node:path";
+import { warnMissingPromptGenerators } from "./prompt-generator-gate.js";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { existsSync, readFileSync } from "node:fs";
@@ -366,6 +367,11 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   // CRUD surface it actually emits (rather than silently omitting it).
   const includeHonoRoutes = config.generators.some((g) => g.emitsHonoRoutes === true);
 
+  // A declared template.prompt with no prompt generator wired emits nothing and, before
+  // this, said nothing — while `meta verify` reported the template "clean". See
+  // prompt-generator-gate.ts. Self-extinguishing; warning only.
+  warnMissingPromptGenerators(root, config.generators, (m) => warnings.push(m));
+
   // 4. Run each generator with a per-target render context; collect with full path.
   const emitted: { fullPath: string; content: string; generatedBy: string }[] = [];
   // FR-038 §8 — generators that opted into orphan reconciliation, paired with the
@@ -411,6 +417,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       pluralizeCollections: config.pluralizeCollections,
       collectionNameOverrides: config.collectionNameOverrides,
       timestampMode: config.timestampMode,
+      clientDirective: config.clientDirective,
       apiPrefix: config.apiPrefix,
       emitAbstractShapes: config.emitAbstractShapes,
       outputLayout: selfTarget.outputLayout,