@terpjs/contract 0.5.10 → 0.6.1

package/bin/terp-routes.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * The `terp-routes` executable (ADR 0092) — a real entry point, deliberately.
+ *
+ * This file exists instead of an `import.meta.url === process.argv[1]` guard inside the
+ * module: npm installs a bin as a shim/symlink, so the module's own URL and argv[1] do
+ * NOT match when it is invoked as `terp-routes`, and such a guard silently skips the
+ * whole program while still exiting 0. That failure is invisible in the worst possible
+ * way — a drift check that passes because it never ran.
+ */
+import { run } from "../src/routes-codegen.js";
+
+try {
+  process.exit(run(process.argv.slice(2)));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/contract",
-  "version": "0.5.10",
+  "version": "0.6.1",
   "type": "module",
   "description": "Terp frontend contract \u2014 the OpenAPI-generated TypeScript client, design tokens, and the stack-agnostic module/route/nav + auth types.",
   "exports": {
@@ -10,18 +10,23 @@
     "./tokens.css": "./src/tokens.css"
   },
   "types": "./src/index.ts",
+  "bin": {
+    "terp-routes": "./bin/terp-routes.js"
+  },
   "scripts": {
     "generate": "openapi-typescript ./openapi.json --output ./src/schema.d.ts",
     "tokens": "node scripts/build-tokens.mjs",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   },
   "devDependencies": {
     "openapi-typescript": "^7.13.0",
     "style-dictionary": "^5.5.0",
-    "typescript": "^5.9.3"
+    "vitest": "^4.1.9"
   },
   "dependencies": {
-    "openapi-fetch": "^0.17.0"
+    "openapi-fetch": "^0.17.0",
+    "typescript": "^5.9.3"
   },
   "license": "Apache-2.0",
   "repository": {

package/src/routes-codegen.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * `terp-routes` — emit an app's route types from its module manifests (ADR 0092).
+ *
+ * A Terp app's router is built at RUNTIME from manifest data, so TanStack Router's
+ * type registry is empty and nothing checks a route path or a param name: the raw read
+ * was an unchecked cast, and a typo'd path was a dead link that shipped green. The
+ * information to check them is already checked in — `routes` is a static array of
+ * object literals — so this generator extracts it and writes a committed
+ * `src/routes.gen.d.ts` that augments `TerpRouteTable` in @terpjs/react-core.
+ *
+ * Extraction is FAIL CLOSED, which is the whole point: a route whose `path` is not a
+ * plain string literal (a template literal, a constant, a spread) cannot be read
+ * statically, so the generator refuses and NAMES it instead of quietly emitting a
+ * partial map — a table missing a route is worse than no table, because it turns a real
+ * path into a type error and teaches authors to distrust the check.
+ *
+ * Scope is the app's own manifests (`src/modules/<name>/module.tsx`). Routes a packaged
+ * area mounts (react-core's admin area) are deliberately NOT keyed: the artifact stays a
+ * pure function of the app's own source, so it never drifts because a dependency's
+ * internals changed. Link to those paths with `Link` / the router's own `navigate`.
+ *
+ * Usage:
+ *   terp-routes                      # write src/routes.gen.d.ts
+ *   terp-routes --check              # exit non-zero when the committed file is stale
+ *   terp-routes --out <file> --modules-dir <dir>
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import ts from "typescript";
+
+/** The declaration file's header — states what regenerates it, so an editor stops. */
+const HEADER = [
+  "// Generated by `terp routes` from this app's module manifests. Do not edit.",
+  "//",
+  "// Maps every route path the manifests declare to that route's params, so",
+  "// useRouteParams / useRouteParam / useTerpNavigate check paths and param names at",
+  "// compile time (ADR 0092). Regenerate after changing a manifest route — `terp verify`",
+  "// fails on a stale copy. Routes mounted by a packaged area (the admin area) are not",
+  "// keyed here: this file is a pure function of this app's own manifests.",
+  "",
+  'import "@terpjs/react-core";',
+  "",
+  'declare module "@terpjs/react-core" {',
+  "  interface TerpRouteTable {",
+];
+
+/** Param names a manifest path declares, in order. Both dialects: `:id` and `$id`. */
+export function paramNamesOf(routePath) {
+  return [...routePath.matchAll(/(?:^|\/)[:$]([A-Za-z_][A-Za-z0-9_]*)/g)].map((match) => match[1]);
+}
+
+/** The canonical table key: the manifest's stack-agnostic spelling (`:id`). */
+export function canonicalPath(routePath) {
+  return routePath.replace(/(^|\/)\$([A-Za-z_][A-Za-z0-9_]*)/g, "$1:$2");
+}
+
+/**
+ * Every route path a source file's `defineModuleManifest(...)` calls declare.
+ *
+ * Returns `{ paths, problems }`. A shape that cannot be read statically lands in
+ * `problems` (with file:line) rather than being skipped — the caller refuses on any.
+ */
+export function extractRoutePaths(sourceText, label) {
+  const source = ts.createSourceFile(label, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const paths = [];
+  const problems = [];
+  let manifests = 0;
+
+  const at = (node) => {
+    const { line } = source.getLineAndCharacterOfPosition(node.getStart(source));
+    return `${label}:${line + 1}`;
+  };
+
+  const readRoutesArray = (routesValue) => {
+    if (!ts.isArrayLiteralExpression(routesValue)) {
+      problems.push(
+        `${at(routesValue)}: \`routes\` is not an array literal, so its paths cannot be read ` +
+          "statically. Declare the routes inline in defineModuleManifest(...).",
+      );
+      return;
+    }
+    for (const element of routesValue.elements) {
+      if (!ts.isObjectLiteralExpression(element)) {
+        problems.push(
+          `${at(element)}: a route is not an object literal (a spread or a reference?), so its ` +
+            "path cannot be read statically. Declare each route inline.",
+        );
+        continue;
+      }
+      const pathProperty = element.properties.find(
+        (property) =>
+          ts.isPropertyAssignment(property) &&
+          (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+          property.name.text === "path",
+      );
+      if (pathProperty === undefined) {
+        problems.push(`${at(element)}: a route declares no \`path\`.`);
+        continue;
+      }
+      const value = pathProperty.initializer;
+      if (!ts.isStringLiteral(value)) {
+        problems.push(
+          `${at(value)}: a route \`path\` is not a plain string literal, so it cannot be read ` +
+            "statically. Write the path inline (e.g. path: \"/records/:recordId\").",
+        );
+        continue;
+      }
+      paths.push(value.text);
+    }
+  };
+
+  const visit = (node) => {
+    if (
+      ts.isCallExpression(node) &&
+      ((ts.isIdentifier(node.expression) && node.expression.text === "defineModuleManifest") ||
+        (ts.isPropertyAccessExpression(node.expression) &&
+          node.expression.name.text === "defineModuleManifest"))
+    ) {
+      manifests += 1;
+      const [argument] = node.arguments;
+      if (argument === undefined || !ts.isObjectLiteralExpression(argument)) {
+        problems.push(
+          `${at(node)}: defineModuleManifest was not called with an object literal, so its routes ` +
+            "cannot be read statically.",
+        );
+      } else {
+        const routes = argument.properties.find(
+          (property) =>
+            ts.isPropertyAssignment(property) &&
+            (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+            property.name.text === "routes",
+        );
+        if (routes === undefined) {
+          problems.push(`${at(argument)}: the manifest declares no \`routes\`.`);
+        } else {
+          readRoutesArray(routes.initializer);
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+
+  if (manifests === 0) {
+    problems.push(
+      `${label}: no defineModuleManifest(...) call found. A module slot declares its routes there; ` +
+        "a module whose manifest is built elsewhere cannot be extracted.",
+    );
+  }
+  return { paths, problems };
+}
+
+/** The module files to scan: `<modulesDir>/<name>/module.tsx` (or `.ts`), sorted. */
+export function moduleFiles(modulesDir) {
+  if (!fs.existsSync(modulesDir)) {
+    return [];
+  }
+  const found = [];
+  for (const entry of fs.readdirSync(modulesDir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    for (const basename of ["module.tsx", "module.ts"]) {
+      const candidate = path.join(modulesDir, entry.name, basename);
+      if (fs.existsSync(candidate)) {
+        found.push(candidate);
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+/** Render the declaration file for *paths* — deterministic: deduped, sorted, LF. */
+export function renderRouteTable(paths) {
+  const unique = [...new Set(paths.map(canonicalPath))].sort();
+  const lines = [...HEADER];
+  for (const routePath of unique) {
+    const params = paramNamesOf(routePath);
+    const shape =
+      params.length === 0
+        ? "Record<never, never>"
+        : `{ ${params.map((name) => `${name}: string`).join("; ")} }`;
+    lines.push(`    ${JSON.stringify(routePath)}: ${shape};`);
+  }
+  lines.push("  }", "}", "");
+  return lines.join("\n");
+}
+
+/**
+ * Extract from every module file under *modulesDir* and render the declaration file.
+ * Throws with every problem listed when any route resists static reading (fail closed).
+ */
+export function generateRouteTable(modulesDir) {
+  const files = moduleFiles(modulesDir);
+  if (files.length === 0) {
+    throw new Error(
+      `No module slots found under ${modulesDir}. A Terp app declares its routes in ` +
+        "src/modules/<name>/module.tsx; pass --modules-dir if this app keeps them elsewhere.",
+    );
+  }
+  const paths = [];
+  const problems = [];
+  for (const file of files) {
+    const result = extractRoutePaths(fs.readFileSync(file, "utf8"), path.relative(process.cwd(), file).split(path.sep).join("/"));
+    paths.push(...result.paths);
+    problems.push(...result.problems);
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      "terp routes refused to emit a partial route table — every route must be readable " +
+        "statically, or the generated types would turn a real path into a type error:\n" +
+        problems.map((problem) => `  - ${problem}`).join("\n"),
+    );
+  }
+  return renderRouteTable(paths);
+}
+
+/** Parse `--flag value` / `--flag` argv into a plain object. */
+function parseArgs(argv) {
+  const options = { out: "src/routes.gen.d.ts", modulesDir: "src/modules", check: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--check") {
+      options.check = true;
+    } else if (argument === "--out") {
+      options.out = argv[(index += 1)];
+    } else if (argument === "--modules-dir") {
+      options.modulesDir = argv[(index += 1)];
+    } else {
+      throw new Error(`terp-routes: unknown argument ${argument}`);
+    }
+  }
+  if (options.out === undefined || options.modulesDir === undefined) {
+    throw new Error("terp-routes: --out and --modules-dir need a value");
+  }
+  return options;
+}
+
+/** The CLI: write the table, or (with --check) refuse a stale committed copy. */
+export function run(argv, { cwd = process.cwd(), log = console.log } = {}) {
+  const options = parseArgs(argv);
+  const outPath = path.resolve(cwd, options.out);
+  const rendered = generateRouteTable(path.resolve(cwd, options.modulesDir));
+  const onDisk = fs.existsSync(outPath) ? fs.readFileSync(outPath, "utf8") : null;
+
+  if (options.check) {
+    if (onDisk === rendered) {
+      log(`terp routes: ${options.out} is current`);
+      return 0;
+    }
+    log(
+      `${options.out} is ${onDisk === null ? "missing" : "stale"} — the module manifests declare ` +
+        "different routes than the committed route table.\nFix: npm --prefix frontend run routes " +
+        "(or `uv run terp routes`), then commit the regenerated file.",
+    );
+    return 1;
+  }
+
+  if (onDisk === rendered) {
+    log(`terp routes: ${options.out} unchanged`);
+    return 0;
+  }
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  // newline unchanged: the rendered text is LF-only, so the committed artifact stays
+  // byte-stable on Windows and the --check comparison never trips on line endings.
+  fs.writeFileSync(outPath, rendered, "utf8");
+  log(`terp routes: wrote ${options.out}`);
+  return 0;
+}
+
+// No self-executing guard here on purpose: `bin/terp-routes.js` is the entry point. An
+// `import.meta.url === argv[1]` check does not hold when npm invokes the bin through its
+// shim, and it fails by doing nothing at exit 0 — a check that silently never checks.

package/src/routes-codegen.test.js

@@ -0,0 +1,273 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  canonicalPath,
+  extractRoutePaths,
+  generateRouteTable,
+  moduleFiles,
+  paramNamesOf,
+  renderRouteTable,
+  run,
+} from "./routes-codegen.js";
+
+// The route-types generator (ADR 0092): it turns manifest route literals into the
+// declaration file that makes a wrong path or param name a typecheck error. Its two
+// contracts are determinism (a committed artifact that drift-checks) and failing closed
+// (never emit a partial table, because a missing route reads as a *wrong* route).
+
+const temporaries = [];
+
+afterEach(() => {
+  for (const directory of temporaries.splice(0)) {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+/** An app tree with one module per entry: `{ notes: "<module.tsx source>" }`. */
+function appWithModules(modules) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "terp-routes-"));
+  temporaries.push(root);
+  for (const [name, source] of Object.entries(modules)) {
+    const directory = path.join(root, "src", "modules", name);
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(path.join(directory, "module.tsx"), source, "utf8");
+  }
+  return root;
+}
+
+function manifest(routes) {
+  return [
+    'import { defineModuleManifest } from "@terpjs/contract";',
+    "export const manifest = defineModuleManifest({",
+    '  name: "x",',
+    `  routes: [${routes}],`,
+    "});",
+  ].join("\n");
+}
+
+describe("param extraction from a path", () => {
+  it("reads both dialects and canonicalises to the manifest spelling", () => {
+    expect(paramNamesOf("/records/:recordId")).toEqual(["recordId"]);
+    expect(paramNamesOf("/records/$recordId")).toEqual(["recordId"]);
+    expect(paramNamesOf("/spaces/:spaceId/items/:itemId")).toEqual(["spaceId", "itemId"]);
+    expect(paramNamesOf("/records")).toEqual([]);
+    // The packaged admin manifest uses the TanStack spelling; the table is keyed the
+    // stack-agnostic way, so both spellings land on one key.
+    expect(canonicalPath("/admin/users/$userId")).toBe("/admin/users/:userId");
+    expect(canonicalPath("/records/:recordId")).toBe("/records/:recordId");
+  });
+});
+
+describe("extraction from a module manifest", () => {
+  it("reads every route path a manifest declares", () => {
+    const { paths, problems } = extractRoutePaths(
+      manifest('{ path: "/records", view: "List" }, { path: "/records/:recordId", view: "Detail" }'),
+      "module.tsx",
+    );
+    expect(problems).toEqual([]);
+    expect(paths).toEqual(["/records", "/records/:recordId"]);
+  });
+
+  it("reads a manifest declared as a property value, not only `export const manifest`", () => {
+    // The packaged admin area's shape: defineModuleManifest(...) inside an object literal.
+    const { paths, problems } = extractRoutePaths(
+      [
+        'import { defineModuleManifest } from "@terpjs/contract";',
+        "export const adminModule = {",
+        '  manifest: defineModuleManifest({ name: "a", routes: [{ path: "/admin", view: "Hub" }] }),',
+        "};",
+      ].join("\n"),
+      "module.tsx",
+    );
+    expect(problems).toEqual([]);
+    expect(paths).toEqual(["/admin"]);
+  });
+
+  it("refuses a path that is not a plain string literal, naming file and line", () => {
+    const { paths, problems } = extractRoutePaths(
+      manifest("{ path: `/records/${base}`, view: \"List\" }"),
+      "src/modules/records/module.tsx",
+    );
+    expect(paths).toEqual([]);
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain("src/modules/records/module.tsx:4");
+    expect(problems[0]).toContain("not a plain string literal");
+  });
+
+  it("refuses a spread route and a non-literal routes array", () => {
+    const spread = extractRoutePaths(manifest("...shared"), "module.tsx");
+    expect(spread.problems[0]).toContain("not an object literal");
+
+    const dynamic = extractRoutePaths(
+      [
+        'import { defineModuleManifest } from "@terpjs/contract";',
+        "export const manifest = defineModuleManifest({ name: \"x\", routes: buildRoutes() });",
+      ].join("\n"),
+      "module.tsx",
+    );
+    expect(dynamic.problems[0]).toContain("not an array literal");
+  });
+
+  it("refuses a module slot with no manifest call at all", () => {
+    const { problems } = extractRoutePaths("export const views = {};", "module.tsx");
+    expect(problems[0]).toContain("no defineModuleManifest");
+  });
+
+  it("refuses a route with no path", () => {
+    const { problems } = extractRoutePaths(manifest('{ view: "List" }'), "module.tsx");
+    expect(problems[0]).toContain("declares no `path`");
+  });
+});
+
+describe("rendering the declaration file", () => {
+  it("is deterministic: deduped, sorted, LF-only, one trailing newline", () => {
+    const first = renderRouteTable(["/b", "/a", "/b"]);
+    const second = renderRouteTable(["/b", "/b", "/a"]);
+    expect(first).toBe(second);
+    expect(first).not.toContain("\r");
+    expect(first.endsWith("}\n")).toBe(true);
+    expect(first.indexOf('"/a"')).toBeLessThan(first.indexOf('"/b"'));
+  });
+
+  it("types a parameterised route's params and leaves a paramless route empty", () => {
+    const rendered = renderRouteTable(["/records/:recordId", "/records", "/s/:a/i/:b"]);
+    expect(rendered).toContain('"/records": Record<never, never>;');
+    expect(rendered).toContain('"/records/:recordId": { recordId: string };');
+    expect(rendered).toContain('"/s/:a/i/:b": { a: string; b: string };');
+  });
+
+  it("augments the react-core table so the app's own types pick it up", () => {
+    const rendered = renderRouteTable(["/"]);
+    expect(rendered).toContain('declare module "@terpjs/react-core"');
+    expect(rendered).toContain("interface TerpRouteTable");
+    // A module augmentation only applies from a file that IS a module.
+    expect(rendered).toContain('import "@terpjs/react-core";');
+  });
+});
+
+describe("generating across an app's module slots", () => {
+  it("merges every slot and dedupes a path two modules claim", () => {
+    const root = appWithModules({
+      home: manifest('{ path: "/", view: "Home" }'),
+      notes: manifest('{ path: "/", view: "NotesList" }, { path: "/notes/:noteId", view: "Note" }'),
+    });
+    const rendered = generateRouteTable(path.join(root, "src", "modules"));
+    expect(rendered.match(/"\/":/g)).toHaveLength(1);
+    expect(rendered).toContain('"/notes/:noteId": { noteId: string };');
+  });
+
+  it("refuses the whole run when any one slot resists static reading", () => {
+    const root = appWithModules({
+      good: manifest('{ path: "/good", view: "G" }'),
+      bad: manifest("{ path: ROUTES.bad, view: \"B\" }"),
+    });
+    expect(() => generateRouteTable(path.join(root, "src", "modules"))).toThrow(
+      /refused to emit a partial route table/,
+    );
+  });
+
+  it("refuses an app with no module slots rather than emitting an empty table", () => {
+    const root = appWithModules({});
+    expect(() => generateRouteTable(path.join(root, "src", "modules"))).toThrow(/No module slots/);
+  });
+
+  it("finds module.ts as well as module.tsx, in a stable order", () => {
+    const root = appWithModules({ b: manifest('{ path: "/b", view: "B" }') });
+    const plain = path.join(root, "src", "modules", "a");
+    fs.mkdirSync(plain, { recursive: true });
+    fs.writeFileSync(path.join(plain, "module.ts"), manifest('{ path: "/a", view: "A" }'), "utf8");
+    expect(moduleFiles(path.join(root, "src", "modules")).map((file) => path.basename(path.dirname(file)))).toEqual(["a", "b"]);
+  });
+});
+
+describe("the CLI's write and --check modes", () => {
+  it("writes the table, then reports it unchanged on a second run", () => {
+    const root = appWithModules({ home: manifest('{ path: "/", view: "Home" }') });
+    const messages = [];
+    const log = (message) => messages.push(message);
+
+    expect(run([], { cwd: root, log })).toBe(0);
+    const written = fs.readFileSync(path.join(root, "src", "routes.gen.d.ts"), "utf8");
+    expect(written).toContain('"/": Record<never, never>;');
+    expect(messages[0]).toContain("wrote");
+
+    expect(run([], { cwd: root, log })).toBe(0);
+    expect(messages[1]).toContain("unchanged");
+  });
+
+  it("--check passes on a current file and refuses a stale or missing one, with the fix", () => {
+    const root = appWithModules({ home: manifest('{ path: "/", view: "Home" }') });
+    const messages = [];
+    const log = (message) => messages.push(message);
+
+    // Missing: the app never generated.
+    expect(run(["--check"], { cwd: root, log })).toBe(1);
+    expect(messages.at(-1)).toContain("missing");
+    expect(messages.at(-1)).toContain("run routes");
+
+    run([], { cwd: root, log: () => {} });
+    expect(run(["--check"], { cwd: root, log })).toBe(0);
+    expect(messages.at(-1)).toContain("is current");
+
+    // Stale: a manifest gained a route after the last generate.
+    fs.writeFileSync(
+      path.join(root, "src", "modules", "home", "module.tsx"),
+      manifest('{ path: "/", view: "Home" }, { path: "/late/:lateId", view: "Late" }'),
+      "utf8",
+    );
+    expect(run(["--check"], { cwd: root, log })).toBe(1);
+    expect(messages.at(-1)).toContain("stale");
+  });
+
+  it("the shipped bin actually runs the generator (a bin that no-ops would fake every check)", () => {
+    // Regression guard for a real bug: the module used to self-execute behind an
+    // `import.meta.url === process.argv[1]` guard, which does NOT hold when npm invokes
+    // the bin through its shim — so `terp-routes --check` did nothing and exited 0. A
+    // drift check that passes because it never ran is worse than no check, and only
+    // spawning the actual executable can catch it.
+    const bin = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "bin", "terp-routes.js");
+    const root = appWithModules({ home: manifest('{ path: "/", view: "Home" }') });
+
+    const written = spawnSync(process.execPath, [bin], { cwd: root, encoding: "utf8" });
+    expect(written.status).toBe(0);
+    expect(written.stdout).toContain("wrote");
+    expect(fs.existsSync(path.join(root, "src", "routes.gen.d.ts"))).toBe(true);
+
+    const current = spawnSync(process.execPath, [bin, "--check"], { cwd: root, encoding: "utf8" });
+    expect(current.status).toBe(0);
+    expect(current.stdout).toContain("is current");
+
+    // And it reports a real drift with a non-zero exit, not a silent pass.
+    fs.writeFileSync(
+      path.join(root, "src", "modules", "home", "module.tsx"),
+      manifest('{ path: "/", view: "Home" }, { path: "/added/:addedId", view: "Added" }'),
+      "utf8",
+    );
+    const stale = spawnSync(process.execPath, [bin, "--check"], { cwd: root, encoding: "utf8" });
+    expect(stale.status).toBe(1);
+    expect(stale.stdout).toContain("stale");
+
+    // A manifest it cannot read statically exits 2 and names the file.
+    fs.writeFileSync(
+      path.join(root, "src", "modules", "home", "module.tsx"),
+      manifest("{ path: ROUTES.home, view: \"Home\" }"),
+      "utf8",
+    );
+    const refused = spawnSync(process.execPath, [bin], { cwd: root, encoding: "utf8" });
+    expect(refused.status).toBe(2);
+    expect(refused.stderr).toContain("refused to emit a partial route table");
+  });
+
+  it("honours --out and --modules-dir, and refuses an unknown argument", () => {
+    const root = appWithModules({ home: manifest('{ path: "/", view: "Home" }') });
+    expect(run(["--out", "types/routes.d.ts", "--modules-dir", "src/modules"], { cwd: root, log: () => {} })).toBe(0);
+    expect(fs.existsSync(path.join(root, "types", "routes.d.ts"))).toBe(true);
+    expect(() => run(["--nope"], { cwd: root, log: () => {} })).toThrow(/unknown argument/);
+  });
+});