feat(codegen-ts): routesFile({ registerAll: true }) registers every entity's routes in one call

An adopter estate found that no port generates an aggregate route registration, so
every new entity meant a hand edit to the host file in each port. For TypeScript the
two route generators can now emit it: `registerAll: true` adds `routes.index.ts`
(`routes.index.hono.ts` for Hono) at the target root, exporting `registerAllRoutes(...)`
that calls each generated entity's register function. Its doc comment carries the same
unauthenticated-by-default note as the per-entity files.

Off by default, so a project that does not ask gets no new file and `verify --codegen`
reports nothing new after an upgrade. The rendering is one engine function
(`renderRoutesIndex`, exported) that all four generators call, with handler names taken
from the same derivations the per-entity renderers use. Other ports: their route
templates are frozen for features; eject is the way to add one.

Tests: every import in the index resolves to a routes file the same run emitted and
names a function that file exports (Fastify and Hono, flat and package layout); TPH
subtypes and value objects are left out; a filter narrows it; nothing is emitted when
the option is off. ci-local --quick green.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M1mRRB1K2WdYy82kntMQdx

Author: dmealing

CHANGELOG.md

@@ -25,6 +25,11 @@ here.**
   with rows. The diff reports them as `hazards`, the CLI prints a warning, and the Postgres
   migration file carries the preparation step (a backfill `UPDATE` or the `SELECT` that finds
   violating rows) as a comment above the statement. `DiffResult` gains a `hazards` field.
+- **`routesFile({ registerAll: true })` and `routesFileHono({ registerAll: true })` emit one
+  module that registers every generated entity's routes.** `routes.index.ts` (or
+  `routes.index.hono.ts`) at the target root exports `registerAllRoutes(...)`, so adding an
+  entity no longer means editing the host file. Off by default: a project that does not ask
+  gets no new file. TypeScript only; in the other ports, eject the route generator.
 
 ### Fixed
 

agent-context/skills/metaobjects-runtime-ui/references/typescript.md

@@ -176,6 +176,12 @@ import { registerAuthorRoutes } from "./generated/Author.routes";
 registerAuthorRoutes(app, { db });   // GET/POST/PATCH/PUT/DELETE under apiPrefix
 ```
 
+To register every entity at once, pass `registerAll: true` to the generator
+(`routesFile({ registerAll: true })` / `routesFileHono({ registerAll: true })`). It also
+emits `routes.index.ts` (`routes.index.hono.ts` for Hono) at the target root with one
+`registerAllRoutes(...)`, so a new entity needs no edit to the host file. It is off by
+default.
+
 The routes call `parseFilterParams` (from `@metaobjectsdev/runtime-ts/drizzle-fastify`)
 to validate `?filter[..][..]=..&sort=..&limit=&offset=` against the generated
 `<Entity>FilterAllowlist` / `<Entity>SortAllowlist`, returning HTTP 400 on an

docs/features/own-your-codegen.md

@@ -209,7 +209,10 @@ rather than off this page; its own JSDoc carries the recipe with the right one.)
 
 Both are executed as tests (`runtime-ts/test/route-auth-seam.test.ts`) rather than
 asserted in prose. For mounting *fewer* endpoints, narrow the generator:
-`routesFile({ expose: ["list", "get"] })`. What neither can express is a row-ownership
+`routesFile({ expose: ["list", "get"] })`. To register every entity's routes in one call,
+pass `registerAll: true`: the generator also emits `routes.index.ts` (or
+`routes.index.hono.ts`) with a `registerAllRoutes(...)`, so adding an entity needs no edit
+to your host file. What neither can express is a row-ownership
 rule — "only the owner may read this row" is not a property of a mount — so hand-write
 those verbs and narrow the generated file around them.
 

examples/advanced-modeling/codegen/generators/routes.ts

@@ -45,6 +45,8 @@ import {
   isTphSubtype,
   servesReadApi,
   formatTs,
+  renderRoutesIndex,
+  routesIndexFileName,
   entityOutputPath,
   effectivePackage,
 } from "@metaobjectsdev/codegen-ts";
@@ -61,11 +63,26 @@ export interface RoutesFileOpts {
    * only remove the whole surface, not restrict it to a subset of verbs.
    */
   expose?: ExposeOption;
+  /**
+   * Also emit `routes.index.ts` at the target root: one `registerAllRoutes(...)` that registers every
+   * entity this generator emitted a routes file for, so adding an entity needs no edit to
+   * your host file. Off by default, so a project that does not ask gets no new file.
+   */
+  registerAll?: boolean;
   target?: string;
 }
 
 export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator {
   const userFilter = opts?.filter ?? (() => true);
+  const emitEntities = perEntity(async (entity, ctx) => {
+    if (!ctx.renderContext) {
+      throw new Error("routes-file: renderContext is required (provided by runGen)");
+    }
+    return {
+      path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.routes.ts`),
+      content: await formatTs(renderRoutesFile(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),
+    };
+  });
   const generator: Generator = {
     name: "routes-file",
     // TPH subtypes get no standalone routes file (their routes live in the discriminator
@@ -76,15 +93,16 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator
     // abstract objects: an abstract level has no table of its own to mount.
     filter: (e: MetaObject) =>
       servesReadApi(e) && !isTphSubtype(e) && userFilter(e),
-    generate: perEntity(async (entity, ctx) => {
-      if (!ctx.renderContext) {
-        throw new Error("routes-file: renderContext is required (provided by runGen)");
-      }
-      return {
-        path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.routes.ts`),
-        content: await formatTs(renderRoutesFile(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),
-      };
-    }),
+    generate: async (ctx) => {
+      const files = await emitEntities(ctx);
+      if (!opts?.registerAll) return files;
+      const matched = ctx.entities.filter(ctx.matches);
+      if (matched.length === 0 || !ctx.renderContext) return files;
+      return [...files, {
+        path: routesIndexFileName("fastify"),
+        content: await formatTs(renderRoutesIndex(matched, ctx.renderContext, "fastify")),
+      }];
+    },
   };
   if (opts?.target) {
     generator.target = opts.target;

examples/showcase/codegen/generators/routes.ts

@@ -45,6 +45,8 @@ import {
   isTphSubtype,
   servesReadApi,
   formatTs,
+  renderRoutesIndex,
+  routesIndexFileName,
   entityOutputPath,
   effectivePackage,
 } from "@metaobjectsdev/codegen-ts";
@@ -61,11 +63,26 @@ export interface RoutesFileOpts {
    * only remove the whole surface, not restrict it to a subset of verbs.
    */
   expose?: ExposeOption;
+  /**
+   * Also emit `routes.index.ts` at the target root: one `registerAllRoutes(...)` that registers every
+   * entity this generator emitted a routes file for, so adding an entity needs no edit to
+   * your host file. Off by default, so a project that does not ask gets no new file.
+   */
+  registerAll?: boolean;
   target?: string;
 }
 
 export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator {
   const userFilter = opts?.filter ?? (() => true);
+  const emitEntities = perEntity(async (entity, ctx) => {
+    if (!ctx.renderContext) {
+      throw new Error("routes-file: renderContext is required (provided by runGen)");
+    }
+    return {
+      path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.routes.ts`),
+      content: await formatTs(renderRoutesFile(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),
+    };
+  });
   const generator: Generator = {
     name: "routes-file",
     // TPH subtypes get no standalone routes file (their routes live in the discriminator
@@ -76,15 +93,16 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator
     // abstract objects: an abstract level has no table of its own to mount.
     filter: (e: MetaObject) =>
       servesReadApi(e) && !isTphSubtype(e) && userFilter(e),
-    generate: perEntity(async (entity, ctx) => {
-      if (!ctx.renderContext) {
-        throw new Error("routes-file: renderContext is required (provided by runGen)");
-      }
-      return {
-        path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.routes.ts`),
-        content: await formatTs(renderRoutesFile(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),
-      };
-    }),
+    generate: async (ctx) => {
+      const files = await emitEntities(ctx);
+      if (!opts?.registerAll) return files;
+      const matched = ctx.entities.filter(ctx.matches);
+      if (matched.length === 0 || !ctx.renderContext) return files;
+      return [...files, {
+        path: routesIndexFileName("fastify"),
+        content: await formatTs(renderRoutesIndex(matched, ctx.renderContext, "fastify")),
+      }];
+    },
   };
   if (opts?.target) {
     generator.target = opts.target;

fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-runtime-ui/references/typescript.md

@@ -176,6 +176,12 @@ import { registerAuthorRoutes } from "./generated/Author.routes";
 registerAuthorRoutes(app, { db });   // GET/POST/PATCH/PUT/DELETE under apiPrefix
 ```
 
+To register every entity at once, pass `registerAll: true` to the generator
+(`routesFile({ registerAll: true })` / `routesFileHono({ registerAll: true })`). It also
+emits `routes.index.ts` (`routes.index.hono.ts` for Hono) at the target root with one
+`registerAllRoutes(...)`, so a new entity needs no edit to the host file. It is off by
+default.
+
 The routes call `parseFilterParams` (from `@metaobjectsdev/runtime-ts/drizzle-fastify`)
 to validate `?filter[..][..]=..&sort=..&limit=&offset=` against the generated
 `<Entity>FilterAllowlist` / `<Entity>SortAllowlist`, returning HTTP 400 on an

fixtures/agent-context-conformance/ts-requirements/expected/.claude/skills/metaobjects-runtime-ui/references/typescript.md

@@ -176,6 +176,12 @@ import { registerAuthorRoutes } from "./generated/Author.routes";
 registerAuthorRoutes(app, { db });   // GET/POST/PATCH/PUT/DELETE under apiPrefix
 ```
 
+To register every entity at once, pass `registerAll: true` to the generator
+(`routesFile({ registerAll: true })` / `routesFileHono({ registerAll: true })`). It also
+emits `routes.index.ts` (`routes.index.hono.ts` for Hono) at the target root with one
+`registerAllRoutes(...)`, so a new entity needs no edit to the host file. It is off by
+default.
+
 The routes call `parseFilterParams` (from `@metaobjectsdev/runtime-ts/drizzle-fastify`)
 to validate `?filter[..][..]=..&sort=..&limit=&offset=` against the generated
 `<Entity>FilterAllowlist` / `<Entity>SortAllowlist`, returning HTTP 400 on an

server/typescript/packages/codegen-ts/src/generators/routes-file-hono.ts

@@ -2,6 +2,7 @@ import type { MetaObject } from "@metaobjectsdev/metadata";
 import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
 import { renderRoutesFileHono } from "../templates/routes-file-hono.js";
 import { servesReadApi } from "../api-surface.js";
+import { renderRoutesIndex, routesIndexFileName } from "../templates/routes-index.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
 import { isTphSubtype } from "../templates/zod-validators.js";
@@ -20,6 +21,12 @@ export interface RoutesFileHonoOpts {
    * only remove the whole surface, not restrict it to a subset of verbs.
    */
   expose?: ExposeOption;
+  /**
+   * Also emit `routes.index.hono.ts` at the target root: one `registerAllRoutes(...)` that registers every
+   * entity this generator emitted a routes file for, so adding an entity needs no edit to
+   * your host file. Off by default, so a project that does not ask gets no new file.
+   */
+  registerAll?: boolean;
   target?: string;
 }
 
@@ -79,7 +86,14 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
           "dispatches TPH correctly, or hand-write the scoped routes.",
         );
       }
-      return emit(ctx);
+      const files = await emit(ctx);
+      if (!opts?.registerAll) return files;
+      const matched = ctx.entities.filter(ctx.matches);
+      if (matched.length === 0 || !ctx.renderContext) return files;
+      return [...files, {
+        path: routesIndexFileName("hono"),
+        content: await formatTs(renderRoutesIndex(matched, ctx.renderContext, "hono")),
+      }];
     },
   };
   const emit = perEntity(async (entity, ctx) => {

server/typescript/packages/codegen-ts/src/generators/routes-file.ts

@@ -3,6 +3,7 @@ import { perEntity, type Generator, type GeneratorFactory } from "../generator.j
 import { renderRoutesFile } from "../templates/routes-file.js";
 import { isTphSubtype } from "../templates/zod-validators.js";
 import { servesReadApi } from "../api-surface.js";
+import { renderRoutesIndex, routesIndexFileName } from "../templates/routes-index.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
 import { resolveExpose, type ExposeOption } from "../routes-expose.js";
@@ -20,6 +21,12 @@ export interface RoutesFileOpts {
    * only remove the whole surface, not restrict it to a subset of verbs.
    */
   expose?: ExposeOption;
+  /**
+   * Also emit `routes.index.ts` at the target root: one `registerAllRoutes(...)` that registers every
+   * entity this generator emitted a routes file for, so adding an entity needs no edit to
+   * your host file. Off by default, so a project that does not ask gets no new file.
+   */
+  registerAll?: boolean;
   target?: string;
 }
 
@@ -41,20 +48,30 @@ export interface RoutesFileOpts {
  */
 export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator {
   const userFilter = opts?.filter ?? (() => true);
+  const emitEntities = perEntity(async (entity, ctx) => {
+    if (!ctx.renderContext) {
+      throw new Error("routes-file: renderContext is required (provided by runGen)");
+    }
+    return {
+      path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.routes.ts`),
+      content: await formatTs(renderRoutesFile(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),
+    };
+  });
   const generator: Generator = {
     name: "routes-file",
     // Always set: AND-composes the built-in gates with the optional user filter.
     filter: (e: MetaObject) =>
       servesReadApi(e) && !isTphSubtype(e) && userFilter(e),
-    generate: perEntity(async (entity, ctx) => {
-      if (!ctx.renderContext) {
-        throw new Error("routes-file: renderContext is required (provided by runGen)");
-      }
-      return {
-        path: entityOutputPath(ctx.config.outputLayout ?? "flat", effectivePackage(entity), `${entity.name}.routes.ts`),
-        content: await formatTs(renderRoutesFile(entity, ctx.renderContext, resolveExpose(entity, opts?.expose))),
-      };
-    }),
+    generate: async (ctx) => {
+      const files = await emitEntities(ctx);
+      if (!opts?.registerAll) return files;
+      const matched = ctx.entities.filter(ctx.matches);
+      if (matched.length === 0 || !ctx.renderContext) return files;
+      return [...files, {
+        path: routesIndexFileName("fastify"),
+        content: await formatTs(renderRoutesIndex(matched, ctx.renderContext, "fastify")),
+      }];
+    },
   };
   if (opts?.target) {
     generator.target = opts.target;

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

@@ -228,6 +228,7 @@ export { CRUD_VERBS, TPH_POLYMORPHIC_VERBS, resolveExpose, intersectExpose, expo
 export type { CrudVerb, ExposeOption } from "./routes-expose.js";
 export { renderRoutesFile } from "./templates/routes-file.js";
 export { renderRoutesFileHono } from "./templates/routes-file-hono.js";
+export { renderRoutesIndex, routesIndexFileName, type RoutesIndexFlavor } from "./templates/routes-index.js";
 export { renderValueObjectFile } from "./templates/value-object-file.js";
 export { renderNamesDecl } from "./templates/names-decl.js";
 export type { NamesDeclOpts } from "./templates/names-decl.js";