fix(codegen-ts): api-docs relative import specifiers (copy-paste compiles) + document Hono when generated

Fix 1: render `./`-prefixed relative import specifiers in the api-docs code
blocks (human page imports, agent group headers, and example import blocks) so a
verbatim copy-paste consumer resolves against the co-located generated code
(no TS2307). The ApiSymbol.importPath data stays the bare module path (the
accuracy gate verifies it against the emitted file); only the rendered
`from "..."` gains the `./` prefix.

Fix 2: auto-detect the opt-in Hono routes generator. routesFileHono carries a
new `emitsHonoRoutes` marker; the runner aggregates it across the active suite
into ctx.config.includeHonoRoutes; api-docs reads it and documents the Hono CRUD
registrars exactly when routesFileHono() is wired (Fastify-only otherwise).

New gate api-docs-relative-imports.test.ts: asserts the rendered import blocks
are `./`-prefixed (flat + package layout), tsc-compiles a CRUD consumer written
from AGENT-API.md against the REAL generated entity+queries code (proves no
TS2307 + the CRUD call type-checks), and proves Hono auto-detection end-to-end
through runGen. Render goldens updated; other generators' goldens byte-identical.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

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

@@ -47,6 +47,12 @@ export interface Generator {
   /** Marks the generator that produces entity modules — the runner uses its
    *  target as the entity-module target for cross-target import resolution. */
   emitsEntityModule?: boolean;
+  /** Marks the OPT-IN Hono routes generator (routesFileHono). The runner
+   *  aggregates this across the active suite into `ctx.config.includeHonoRoutes`,
+   *  so a generator that documents the API surface (api-docs) can AUTO-DETECT
+   *  that Hono routes are actually being emitted and document them — rather than
+   *  silently omitting the Hono CRUD registrars whenever the variant is wired. */
+  emitsHonoRoutes?: boolean;
 }
 
 export type GeneratorFactory<TOpts = void> = TOpts extends void

server/typescript/packages/codegen-ts/src/generators/api-doc-render.ts

@@ -29,6 +29,40 @@ const AGENT_REF = "api/agent-api.md";
 
 const GENERATED_MARKER = `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`;
 
+// ---------------------------------------------------------------------------
+// Relative-import RENDER prefix.
+//
+// An `ApiSymbol.importPath` is the generated module's path RELATIVE TO the
+// codegen output dir (flat → `Product.queries`; package → the package-folded
+// `acme/shop/Product.queries`). It is the DATA the accuracy gate verifies
+// against the emitted file, so it stays a bare module path.
+//
+// The generated files import each OTHER with `./`-prefixed RELATIVE specifiers
+// (`from "./Product"`), so a copy-paste consumer co-located in the generated
+// output dir must do the same — a BARE specifier (`from "Product.queries"`)
+// only resolves with a non-default `baseUrl` and otherwise fails TS2307. The
+// renderers therefore `./`-prefix the importPath in every rendered `from "…"`
+// (the human page, the agent group headers, AND the example import blocks),
+// without touching the underlying importPath data. A consumer importing from
+// elsewhere adjusts the prefix (stated once in the page's import note).
+// ---------------------------------------------------------------------------
+
+/** The `./`-prefixed RELATIVE specifier for a documented module path (the form a
+ *  co-located consumer copy-pastes). Already-relative paths pass through. */
+function relSpecifier(importPath: string): string {
+  return importPath.startsWith("./") || importPath.startsWith("../")
+    ? importPath
+    : `./${importPath}`;
+}
+
+/** Rewrite the `from "<module>"` tail of an example `import { … } from "<module>";`
+ *  line to the `./`-prefixed relative specifier — the example imports are
+ *  pre-composed in the ApiModel (reusing each symbol's bare importPath), so the
+ *  `./` prefix is applied at render time alongside the section/header imports. */
+function relImportLine(line: string): string {
+  return line.replace(/(\bfrom\s+")([^"]+)(")/, (_m, pre, mod, post) => `${pre}${relSpecifier(mod)}${post}`);
+}
+
 // The human-facing section ORDER + HEADING per ApiSymbolKind. A unit's page
 // renders only the kinds it actually carries, always in this canonical order
 // (so two runs over the same model are byte-stable regardless of symbol order).
@@ -221,7 +255,7 @@ function importLineFor(s: ApiSymbol): string {
   // registrar named on the symbol instead of the "METHOD /path" name.
   const isRouteKind = s.kind === "rest" || s.kind === "rest-hono";
   const imported = isRouteKind ? s.registrar ?? s.name : s.name;
-  return `import { ${imported} } from "${s.importPath}"`;
+  return `import { ${imported} } from "${relSpecifier(s.importPath)}"`;
 }
 
 /** Group a unit's symbols into ordered sections (one per present kind), each a
@@ -253,7 +287,9 @@ function entityPageVM(unit: ApiUnitDoc): EntityPageVM {
  *  string. Undefined when the unit has no runnable example. */
 function unitExampleBlock(example: UnitExample | undefined): string | undefined {
   if (example === undefined) return undefined;
-  const lines = [...example.imports];
+  // The example imports are pre-composed in the ApiModel from the symbols' bare
+  // importPaths; `./`-prefix each at render time so the copy-paste block resolves.
+  const lines = example.imports.map(relImportLine);
   if (example.imports.length > 0 && example.body.length > 0) lines.push("");
   lines.push(...example.body);
   return lines.join("\n");
@@ -469,7 +505,7 @@ function agentGroups(unit: ApiUnitDoc): AgentGroupVM[] {
   return order.map((mod) => {
     const g = byModule.get(mod)!;
     return {
-      importHeader: `import { ${g.names.join(", ")} } from "${mod}"`,
+      importHeader: `import { ${g.names.join(", ")} } from "${relSpecifier(mod)}"`,
       symbols: g.symbols,
     };
   });

server/typescript/packages/codegen-ts/src/generators/api-docs-file.ts

@@ -64,9 +64,15 @@ export const apiDocsFile = function apiDocsFile(opts?: ApiDocsFileOpts): Generat
       // ONE ApiModel feeds every form (Task-1 builder; Task-2 renderers). The
       // pkMap is reused from the run's renderContext when present (the real gen
       // run always provides it) and derived otherwise.
+      // Auto-detect: document the OPT-IN Hono CRUD surface iff the Hono routes
+      // generator is actually in the run. The runner aggregates each generator's
+      // `emitsHonoRoutes` marker into ctx.config.includeHonoRoutes, so api-docs
+      // "just works" — it documents Hono exactly when `routesFileHono` is wired,
+      // and omits it (Fastify-only) otherwise. No explicit opt needed.
       const model = buildApiModel(ctx.loadedRoot, {
         loadedRoot: ctx.loadedRoot,
         outputLayout: layout,
+        includeHonoRoutes: ctx.config.includeHonoRoutes ?? false,
         ...(ctx.renderContext?.pkMap !== undefined && { pkMap: ctx.renderContext.pkMap }),
       });
 

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

@@ -27,6 +27,9 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
   const userFilter = opts?.filter ?? (() => true);
   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,
     filter: (e: MetaObject) => e.ownAttr(CODEGEN_ATTR_EMIT_ROUTES) !== false && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {

server/typescript/packages/codegen-ts/src/metaobjects-config.ts

@@ -42,6 +42,11 @@ export interface ResolvedGenConfig {
   dialect: Dialect;
   /** "flat" (default) — all files in outDir; "package" — files placed in a sub-path derived from each entity's metadata package. */
   outputLayout?: OutputLayout;
+  /** Whether the OPT-IN Hono routes generator (routesFileHono) is active in the
+   *  run — aggregated by the runner from the suite's `emitsHonoRoutes` markers.
+   *  api-docs reads this to AUTO-DETECT whether to document the Hono CRUD surface
+   *  (it otherwise mirrors the default Fastify-only suite). Undefined ⇒ false. */
+  includeHonoRoutes?: boolean;
 }
 
 export interface MetaobjectsGenConfig extends ResolvedGenConfig {

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

@@ -143,6 +143,11 @@ 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) {
@@ -173,6 +178,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         dbImport: selfTarget.dbImport,
         dialect: config.dialect,
         outputLayout: selfTarget.outputLayout,
+        includeHonoRoutes,
       },
       renderContext,
       ...(projectRoot !== undefined && { projectRoot }),

server/typescript/packages/codegen-ts/test/golden/api-doc-render.test.ts

@@ -96,7 +96,7 @@ const db = drizzle(new Pool({ connectionString: process.env.DATABASE_URL }));
 ## Example
 
 \`\`\`ts
-import { createProduct, findProductById, updateProduct, deleteProductById } from "Product.queries";
+import { createProduct, findProductById, updateProduct, deleteProductById } from "./Product.queries";
 
 const created = await createProduct(db, { name: "…" });
 const found = await findProductById(db, created.id);
@@ -111,7 +111,7 @@ const removed = await deleteProductById(db, created.id);
 The typed shape of a Product row, generated from its metadata.
 
 \`\`\`ts
-import { Product } from "Product"
+import { Product } from "./Product"
 \`\`\`
 
 Fields:
@@ -128,23 +128,23 @@ Fields:
 Fetch a single Product by its primary key; null when not found.
 
 \`\`\`ts
-import { findProductById } from "Product.queries"
+import { findProductById } from "./Product.queries"
 \`\`\`
 
 ### \`listProducts(db: Db, opts?: { limit?: number; offset?: number }): Promise<Product[]>\`
 
 List Product rows with optional limit/offset paging.
 
 \`\`\`ts
-import { listProducts } from "Product.queries"
+import { listProducts } from "./Product.queries"
 \`\`\`
 
 ### \`createProduct(db: Db, data: unknown): Promise<Product>\`
 
 Validate (via ProductInsertSchema) and insert a new Product.
 
 \`\`\`ts
-import { createProduct } from "Product.queries"
+import { createProduct } from "./Product.queries"
 \`\`\`
 
 Request body (data):
@@ -160,7 +160,7 @@ Throws: ZodError when data fails ProductInsertSchema validation.
 Partially update an existing Product by primary key; null when not found.
 
 \`\`\`ts
-import { updateProduct } from "Product.queries"
+import { updateProduct } from "./Product.queries"
 \`\`\`
 
 Request body (data):
@@ -176,7 +176,7 @@ Throws: ZodError when data fails the partial ProductInsertSchema validation.
 Delete a Product by primary key; true when a row was removed.
 
 \`\`\`ts
-import { deleteProductById } from "Product.queries"
+import { deleteProductById } from "./Product.queries"
 \`\`\`
 
 ## REST
@@ -186,7 +186,7 @@ import { deleteProductById } from "Product.queries"
 List Product (supports filter/sort/paging query params).
 
 \`\`\`ts
-import { productRoutes } from "Product.routes"
+import { productRoutes } from "./Product.routes"
 \`\`\`
 
 Response body:
@@ -203,7 +203,7 @@ Mount: \`await productRoutes(fastify)\`
 Fetch a single Product by id (404 when not found).
 
 \`\`\`ts
-import { productRoutes } from "Product.routes"
+import { productRoutes } from "./Product.routes"
 \`\`\`
 
 Response body:
@@ -220,7 +220,7 @@ Mount: \`await productRoutes(fastify)\`
 Create a Product (body validated by ProductInsertSchema).
 
 \`\`\`ts
-import { productRoutes } from "Product.routes"
+import { productRoutes } from "./Product.routes"
 \`\`\`
 
 Request body:
@@ -236,7 +236,7 @@ Mount: \`await productRoutes(fastify)\`
 Partially update a Product by id (body validated by ProductUpdateSchema).
 
 \`\`\`ts
-import { productRoutes } from "Product.routes"
+import { productRoutes } from "./Product.routes"
 \`\`\`
 
 Request body:
@@ -252,7 +252,7 @@ Mount: \`await productRoutes(fastify)\`
 Delete a Product by id.
 
 \`\`\`ts
-import { productRoutes } from "Product.routes"
+import { productRoutes } from "./Product.routes"
 \`\`\`
 
 Mount: \`await productRoutes(fastify)\`
@@ -264,7 +264,7 @@ Mount: \`await productRoutes(fastify)\`
 Zod schema validating the body of a create<Product> / POST request (auto-generated PKs excluded).
 
 \`\`\`ts
-import { ProductInsertSchema } from "Product"
+import { ProductInsertSchema } from "./Product"
 \`\`\`
 
 Accepted fields:
@@ -278,7 +278,7 @@ Accepted fields:
 Zod schema validating the body of an update / PATCH request (all fields optional).
 
 \`\`\`ts
-import { ProductUpdateSchema } from "Product"
+import { ProductUpdateSchema } from "./Product"
 \`\`\`
 
 Accepted fields:
@@ -299,11 +299,11 @@ describe("renderEntityApiPage — human per-unit page", () => {
     const { model } = await loadModel();
     const out = renderEntityApiPage(unit(model, "Product"), provider);
     // Import per symbol — the #1 actionability fix.
-    expect(out).toContain(`import { findProductById } from "Product.queries"`);
-    expect(out).toContain(`import { Product } from "Product"`);
-    expect(out).toContain(`import { ProductInsertSchema } from "Product"`);
+    expect(out).toContain(`import { findProductById } from "./Product.queries"`);
+    expect(out).toContain(`import { Product } from "./Product"`);
+    expect(out).toContain(`import { ProductInsertSchema } from "./Product"`);
     // REST wires through the route registrar (not an importable endpoint fn).
-    expect(out).toContain(`import { productRoutes } from "Product.routes"`);
+    expect(out).toContain(`import { productRoutes } from "./Product.routes"`);
     expect(out).toContain("Mount: `await productRoutes(fastify)`");
     // Computed-but-previously-dropped throws now surfaces on the human page.
     expect(out).toContain("Throws: ZodError when data fails ProductInsertSchema validation.");
@@ -351,7 +351,7 @@ describe("renderEntityApiPage — human per-unit page", () => {
 Build one.
 
 \`\`\`ts
-import { makeWidget } from "Widget.queries"
+import { makeWidget } from "./Widget.queries"
 \`\`\`
 
 \`\`\`ts
@@ -433,19 +433,19 @@ Generated API reference for this project; call these exactly as written. Imports
 
 ## Product
 
-\`import { Product, ProductInsertSchema, ProductUpdateSchema } from "Product"\`
+\`import { Product, ProductInsertSchema, ProductUpdateSchema } from "./Product"\`
 - \`interface Product { id: number; name?: string }\` — The typed shape of a Product row, generated from its metadata.
 - \`ProductInsertSchema: ZodType<{ name?: string }>\` — Zod schema validating the body of a create<Product> / POST request (auto-generated PKs excluded).
 - \`ProductUpdateSchema: ZodType<{ name?: string }>\` — Zod schema validating the body of an update / PATCH request (all fields optional).
 
-\`import { findProductById, listProducts, createProduct, updateProduct, deleteProductById } from "Product.queries"\`
+\`import { findProductById, listProducts, createProduct, updateProduct, deleteProductById } from "./Product.queries"\`
 - \`findProductById(db: Db, id: number): Promise<Product | null>\` — Fetch a single Product by its primary key; null when not found.
 - \`listProducts(db: Db, opts?: { limit?: number; offset?: number }): Promise<Product[]>\` — List Product rows with optional limit/offset paging.
 - \`createProduct(db: Db, data: { name?: string }): Promise<Product>\` — Validate (via ProductInsertSchema) and insert a new Product. [throws: ZodError when data fails ProductInsertSchema validation.]
 - \`updateProduct(db: Db, id: number, data: { name?: string }): Promise<Product | null>\` — Partially update an existing Product by primary key; null when not found. [throws: ZodError when data fails the partial ProductInsertSchema validation.]
 - \`deleteProductById(db: Db, id: number): Promise<boolean>\` — Delete a Product by primary key; true when a row was removed.
 
-\`import { productRoutes } from "Product.routes"\`
+\`import { productRoutes } from "./Product.routes"\`
 - \`GET /products -> { id: number; name?: string }\` — List Product (supports filter/sort/paging query params).
 - \`GET /products/:id -> { id: number; name?: string }\` — Fetch a single Product by id (404 when not found).
 - \`POST /products body: { name?: string }\` — Create a Product (body validated by ProductInsertSchema).
@@ -462,16 +462,16 @@ const removed = await deleteProductById(db, created.id);
 
 ## SummaryVO
 
-\`import { SummaryVO } from "SummaryVO"\`
+\`import { SummaryVO } from "./SummaryVO"\`
 - \`interface SummaryVO { headline: string }\` — The typed shape of a SummaryVO row, generated from its metadata.
 
 ## ProductSummary
 
-\`import { extractProductSummary, extractLenientProductSummary } from "ProductSummary.extractor"\`
+\`import { extractProductSummary, extractLenientProductSummary } from "./ProductSummary.extractor"\`
 - \`extractProductSummary(root: MetaRoot, text: string): SummaryVO // SummaryVO: { headline: string }\` — Parse dirty LLM json text into a strict, fully-typed SummaryVO graph. [throws: Error when a @required field is lost (the strict opt-in gate).]
 - \`extractLenientProductSummary(root: MetaRoot, text: string): ExtractionResult<ProductSummaryExtracted>\` — Never-throwing extract; inspect report for lost/defaulted fields.
 
-\`import { renderProductSummary } from "ProductSummary.render"\`
+\`import { renderProductSummary } from "./ProductSummary.render"\`
 - \`renderProductSummary(payload: SummaryVO, provider: Provider): string\` — Render the ProductSummary document from a typed SummaryVO payload.
 
 Example:
@@ -543,12 +543,12 @@ describe("renderAgentApi — condensed agent/LLM form", () => {
     // The import header names the module AND the importable identifier; the
     // bullet names the callable signature. Together an agent has the exact import
     // + the call shape for createProduct.
-    expect(out).toContain(`import { findProductById, listProducts, createProduct, updateProduct, deleteProductById } from "Product.queries"`);
+    expect(out).toContain(`import { findProductById, listProducts, createProduct, updateProduct, deleteProductById } from "./Product.queries"`);
     // T2: the agent form now inlines the create payload SHAPE in place of the
     // opaque `data: unknown`, so an agent knows what fields to pass.
     expect(out).toContain("`createProduct(db: Db, data: { name?: string }): Promise<Product>`");
     // REST endpoints are wired through the entity's route registrar import.
-    expect(out).toContain(`import { productRoutes } from "Product.routes"`);
+    expect(out).toContain(`import { productRoutes } from "./Product.routes"`);
   });
 
   test("throws is surfaced as a compact [throws: …] marker", async () => {