@nanobpm/urban 0.37.0 → 0.39.0

package/src/toolkit/derivers/api.test.ts

@@ -139,10 +139,167 @@ test("required query params aren't undefined-widened; optional ones use the ? mo
     },
   };
   const out = emitApiBindings(qdoc);
-  assert.match(out, /"q": string \| string\[\]/); // required → present, not optional
+  assert.match(out, /"q": string/); // required scalar string → present, coerced to its schema type
   assert.doesNotMatch(out, /"q"\?:/); // not optional
-  assert.doesNotMatch(out, /"q": string \| string\[\] \| undefined/); // not undefined-widened
-  assert.match(out, /"page"\?: string \| string\[\]/); // optional → ? modifier
+  assert.doesNotMatch(out, /"q": string \| undefined/); // not undefined-widened
+  assert.match(out, /"page"\?: string/); // optional → ? modifier
+});
+
+test("params are typed by their schema (coerced), not the raw wire string", () => {
+  const pdoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/things/{id}": {
+        get: {
+          operationId: "getThing",
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: "integer" } },
+            { name: "verbose", in: "query", schema: { type: "boolean" } },
+            { name: "tags", in: "query", schema: { type: "array", items: { type: "string" } } },
+            { name: "raw", in: "query" }, // no schema → raw wire type
+          ],
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(pdoc);
+  assert.match(out, /"id": number/); // integer path param → number, not string
+  assert.match(out, /"verbose"\?: boolean/); // boolean query → boolean
+  assert.match(out, /"tags"\?: Array<string>/); // array query → Array<item>
+  assert.match(out, /"raw"\?: string \| string\[\]/); // schemaless query → raw wire type
+});
+
+test("the response type unions every documented JSON response body (success + error)", () => {
+  const rdoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: {
+      schemas: {
+        Ok: { type: "object", properties: { ok: { type: "boolean" } }, additionalProperties: false },
+        Err: { type: "object", properties: { error: { type: "string" } }, additionalProperties: false },
+      },
+    },
+    paths: {
+      "/do": {
+        post: {
+          operationId: "doIt",
+          responses: {
+            "200": { content: { "application/json": { schema: { $ref: "#/components/schemas/Ok" } } } },
+            "400": { content: { "application/json": { schema: { $ref: "#/components/schemas/Err" } } } },
+          },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(rdoc);
+  assert.match(out, /export type DoItResponse = Ok \| Err;/); // both bodies in the union
+});
+
+test("an ejected operation keeps raw wire param/query types + an unknown body (runtime skips coercion)", () => {
+  const edoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/raw/{id}": {
+        post: {
+          operationId: "rawOp",
+          "x-urban-eject": true,
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: "integer" } },
+            { name: "n", in: "query", schema: { type: "integer" } },
+          ],
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { type: "object", properties: { a: { type: "string" } } } } },
+          },
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(edoc);
+  assert.match(out, /"id": string/); // ejected integer path param stays a raw wire string
+  assert.match(out, /"n"\?: string \| string\[\]/); // ejected query param stays raw wire
+  assert.match(out, /body: unknown;/); // ejected body is unvalidated → unknown
+});
+
+test("whole-surface eject (manifest api.eject) types every op as ejected (raw params, unknown body)", () => {
+  const sdoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/thing/{id}": {
+        post: {
+          operationId: "doThing",
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: "integer" } },
+            { name: "q", in: "query", required: true, schema: { type: "integer" } },
+          ],
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { type: "object", properties: { a: { type: "string" } } } } },
+          },
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  // Without the surface flag the op is fully typed…
+  const typed = emitApiBindings(sdoc, false);
+  assert.match(typed, /"id": number/);
+  assert.match(typed, /"q": number/);
+  // …with whole-surface eject it degrades to raw wire + unknown body, matching the runtime.
+  const ejected = emitApiBindings(sdoc, true);
+  assert.match(ejected, /"id": string/); // raw wire path param
+  assert.match(ejected, /"q"\?: string \| string\[\]/); // required query param becomes optional + raw
+  assert.match(ejected, /body: unknown;/);
+});
+
+test("an ejected required query param is typed optional (runtime does not enforce presence)", () => {
+  const edoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    paths: {
+      "/raw": {
+        get: {
+          operationId: "rawReq",
+          "x-urban-eject": true,
+          parameters: [{ name: "req", in: "query", required: true, schema: { type: "integer" } }],
+          responses: { "200": {} },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(edoc);
+  assert.match(out, /"req"\?: string \| string\[\]/); // required-but-ejected → optional raw wire
+});
+
+test("a component or operationId colliding with a fixed generated name fails the drift gate", () => {
+  const cdoc: OpenApiDoc = {
+    openapi: "3.0.0",
+    components: { schemas: { ApiOperations: { type: "string" } } },
+    paths: { "/z": { get: { operationId: "getZ", responses: { "200": {} } } } },
+  };
+  assert.throws(() => emitApiBindings(cdoc), /duplicate TypeScript type "ApiOperations"/);
+});
+
+test("a documented-but-bodyless status is excluded from the response union", () => {
+  const rdoc: OpenApiDoc = {
+    openapi: "3.1.0",
+    components: {
+      schemas: { Err: { type: "object", properties: { error: { type: "string" } }, additionalProperties: false } },
+    },
+    paths: {
+      "/x": {
+        get: {
+          operationId: "getX",
+          responses: {
+            "204": {}, // documented, no JSON body → not in the union
+            default: { content: { "application/json": { schema: { $ref: "#/components/schemas/Err" } } } },
+          },
+        },
+      },
+    },
+  };
+  const out = emitApiBindings(rdoc);
+  assert.match(out, /export type GetXResponse = Err;/); // only the schema'd default body
 });
 
 test("request body optionality follows requestBody.required (runtime passes undefined when absent)", () => {

package/src/toolkit/derivers/api.ts

@@ -1,7 +1,8 @@
 // Deriver: an OpenAPI document → `api-io.d.ts` (the endpoint type map) + `operations.ts` (the typed
 // `defineOperation` wrapper). ADR 0058: the contract-first endpoint surface. This is the authoring
 // half — per `operationId` it emits a `Request`/`Response` type from the operation's parameters,
-// requestBody, and first success response, plus an `ApiOperationId` union — mirroring how
+// requestBody, and response (a union of every documented JSON response body), plus an
+// `ApiOperationId` union — mirroring how
 // `worker-io.d.ts` types `defineWorker` from the model (ADR 0033 §3). The runtime
 // (`runtime/core/modules/api.ts`) is the matching half: it validates + routes from the SAME spec via
 // the shared `openapi/spec.ts`, so types and runtime never drift.
@@ -117,23 +118,34 @@ function objectToTs(schema: OpenApiSchema, depth: number): string {
   return "Record<string, never>";
 }
 
-/** The `params`/`query` object type for an operation, from its parameters (strings on the wire). */
-function paramsTs(op: OperationInfo, where: "path" | "query"): string {
+/** The `params`/`query` object type for an operation, from its parameters. Values are coerced to
+ *  their declared schema type before the delegate receives them (the runtime coerces + validates,
+ *  then forwards the coerced value), so a param's type is its schema type — not the raw wire string.
+ *  A parameter with no schema, or ANY parameter of an ejected operation (whose runtime skips
+ *  coercion/validation and hands the delegate the raw request), keeps the raw wire type (`string`,
+ *  or `string | string[]` for query). Ejected query params are also made optional: the runtime does
+ *  not enforce presence for ejected ops, so a "required" query param may in fact be absent. */
+function paramsTs(op: OperationInfo, where: "path" | "query", ejected: boolean): string {
   const ps = op.parameters.filter((p) => p.in === where);
   if (ps.length === 0) return "{}";
+  const rawWire = where === "query" ? "string | string[]" : "string";
   const fields = ps.map((p) => {
-    const opt = p.required ? "" : "?";
-    // Query values arrive as strings (or string[] for repeated keys); path params are single
-    // strings. Optionality is carried by the `?` modifier — don't fold `undefined` into the
-    // value type, or required query params would still accept undefined.
-    const t = where === "query" ? "string | string[]" : "string";
+    // Coerced to the schema type (number/boolean/array/enum/…); optionality is carried by the `?`
+    // modifier — don't fold `undefined` into the value type, or required params would still accept
+    // undefined. Schemaless params, and every param of an ejected op, fall back to the raw wire type.
+    // A required query param of an ejected op is nonetheless optional here (runtime skips presence);
+    // path params stay as declared (the route only matches when every path segment is present).
+    const opt = ejected && where === "query" ? "?" : p.required ? "" : "?";
+    const t = ejected || !p.schema ? rawWire : schemaToTs(p.schema);
     return `${JSON.stringify(p.name)}${opt}: ${t}`;
   });
   return `{ ${fields.join("; ")} }`;
 }
 
-/** Emit `api-io.d.ts`: named component types + per-operation Request/Response + the id union. */
-export function emitApiBindings(doc: OpenApiDoc): string {
+/** Emit `api-io.d.ts`: named component types + per-operation Request/Response + the id union.
+ *  `surfaceEject` reflects the manifest's whole-surface `api.eject` (which the deriver otherwise
+ *  can't see): when set, EVERY operation is treated as ejected (raw params/query, `unknown` body). */
+export function emitApiBindings(doc: OpenApiDoc, surfaceEject = false): string {
   const ops = collectOperations(doc);
   const components = doc.components?.schemas ?? {};
 
@@ -152,6 +164,11 @@ export function emitApiBindings(doc: OpenApiDoc): string {
     }
     emittedTypeNames.set(typeName, source);
   };
+  // Reserve the fixed generated declarations (the operation-id union + operations map) up front, so
+  // a component or operationId whose stem collapses onto one of them fails the drift gate with a
+  // clear rename message instead of silently emitting a duplicate, uncompilable declaration.
+  claimTypeName("ApiOperationId", "the generated operation-id union");
+  claimTypeName("ApiOperations", "the generated operations map");
   for (const name of Object.keys(components)) {
     claimTypeName(typeStem(name), `component schema "${name}"`);
   }
@@ -162,8 +179,9 @@ export function emitApiBindings(doc: OpenApiDoc): string {
 
   const header =
     "// AUTO-GENERATED by @nanobpm/urban from the app's OpenAPI spec (ADR 0058).\n" +
-    "// The endpoint type map: each operationId maps to its typed request (path/query params +\n" +
-    "// JSON body) and success response, derived from the spec. Do not edit — regenerated from\n" +
+    "// The endpoint type map: each operationId maps to its typed request (coerced path/query params\n" +
+    "// + JSON body) and response (a union of every documented JSON response body), derived from the\n" +
+    "// spec. Do not edit — regenerated from\n" +
     "// the spec; erased to plain JS at compile.\n" +
     "// eslint-disable\n\n";
 
@@ -175,22 +193,38 @@ export function emitApiBindings(doc: OpenApiDoc): string {
   const opDecls = ops
     .map((op) => {
       const stem = typeStem(op.operationId);
+      const ejected = surfaceEject || op.eject;
+      // An ejected operation (`x-urban-eject`, or the whole surface via manifest `api.eject`)
+      // bypasses the generated coercion/validation — its delegate reads the raw request — so its
+      // input is NOT schema-shaped at runtime: params/query stay raw wire types and the body is
+      // unvalidated (`unknown`). Typing it by the schema would claim guarantees the runtime doesn't
+      // make. (ADR 0059 documents the ejection exception.)
       // With a schema → the typed body. Required but no JSON schema → `unknown` (a body IS
       // required at runtime, just of an unknown shape). Otherwise (optional, absent) → `undefined`.
-      const bodyType = op.requestBodySchema
-        ? schemaToTs(op.requestBodySchema)
-        : op.requestBodyRequired
-          ? "unknown"
-          : "undefined";
+      const bodyType = ejected
+        ? "unknown"
+        : op.requestBodySchema
+          ? schemaToTs(op.requestBodySchema)
+          : op.requestBodyRequired
+            ? "unknown"
+            : "undefined";
       // An optional (or absent) request body is passed to the delegate as `undefined` at runtime,
       // so mark it optional in the type rather than forcing handlers to treat it as always-present.
       const bodyOpt = op.requestBodyRequired ? "" : "?";
-      const resp = op.responseSchema ? schemaToTs(op.responseSchema) : "unknown";
+      // Response type: a union of every documented JSON response body (success + errors), so a
+      // handler that returns a documented error body typechecks against its operation's response
+      // type. Bodyless documented statuses carry no schema and are skipped here. Deduped (identical
+      // schemas collapse), stable order. No documented JSON body → unknown.
+      const respSeen = new Set<string>();
+      const respParts = op.responseSchemas
+        .flatMap((e) => (e.schema ? [schemaToTs(e.schema)] : []))
+        .filter((t) => (respSeen.has(t) ? false : (respSeen.add(t), true)));
+      const resp = respParts.length > 0 ? respParts.join(" | ") : "unknown";
       const summary = op.summary ? `/** ${op.summary.replace(/\*\//g, "*\\/")} */\n` : "";
       return (
         `${summary}export interface ${stem}Request {\n` +
-        `  params: ${paramsTs(op, "path")};\n` +
-        `  query: ${paramsTs(op, "query")};\n` +
+        `  params: ${paramsTs(op, "path", ejected)};\n` +
+        `  query: ${paramsTs(op, "query", ejected)};\n` +
         `  body${bodyOpt}: ${bodyType};\n` +
         `}\n` +
         `export type ${stem}Response = ${resp};`
@@ -308,18 +342,24 @@ export function emitApiController(doc: OpenApiDoc, operationsDir: string = DEFAU
 }
 
 /** Derive the api artifacts from a parsed OpenAPI document. `operationsDir` is the manifest's
- *  `api.dir` (default `operations/`) — the controller's static delegate imports resolve into it. */
-export function deriveApi(doc: OpenApiDoc, operationsDir: string = DEFAULT_OPERATIONS_DIR): DerivedArtifact[] {
+ *  `api.dir` (default `operations/`) — the controller's static delegate imports resolve into it.
+ *  `surfaceEject` is the manifest's whole-surface `api.eject`: when set, every operation is typed as
+ *  ejected (raw params/query, `unknown` body) so the generated types match the runtime. */
+export function deriveApi(
+  doc: OpenApiDoc,
+  operationsDir: string = DEFAULT_OPERATIONS_DIR,
+  surfaceEject = false,
+): DerivedArtifact[] {
   return [
-    { path: `${GENERATED_DIR}/${API_BINDINGS_DTS}`, content: emitApiBindings(doc) },
+    { path: `${GENERATED_DIR}/${API_BINDINGS_DTS}`, content: emitApiBindings(doc, surfaceEject) },
     { path: `${GENERATED_DIR}/${API_BINDINGS_TS}`, content: emitApiBindingsRuntime() },
     { path: `${GENERATED_DIR}/${API_CONTROLLER_TS}`, content: emitApiController(doc, operationsDir) },
   ];
 }
 
-export const apiDeriver: Deriver<{ doc: OpenApiDoc; operationsDir?: string }> = {
+export const apiDeriver: Deriver<{ doc: OpenApiDoc; operationsDir?: string; surfaceEject?: boolean }> = {
   id: "openapi->api-io",
   describe:
     "Derive api-io.d.ts (typed request/response per operationId) + the typed defineOperation + the delegate registry.",
-  derive: ({ doc, operationsDir }) => deriveApi(doc, operationsDir),
+  derive: ({ doc, operationsDir, surfaceEject }) => deriveApi(doc, operationsDir, surfaceEject),
 };

package/src/toolkit/gen.test.ts

@@ -103,6 +103,59 @@ test("collectArtifacts touches no writes", async () => {
   assert.equal(Object.keys(io.files).length, before);
 });
 
+test("runGen sweeps stale files from nano-generated/ (write mode)", async () => {
+  const io = memIO(fixture());
+  // A stale artifact left by a prior gen (e.g. a renamed `data_sdk.ts` orphan) that this run does
+  // not re-emit. It must be removed so the app can't import a dead generated module.
+  io.files["/app/nano-generated/data_sdk.ts"] = "// stale, renamed away";
+  io.files["/app/nano-generated/old-worker-io.d.ts"] = "// stale";
+  const res = await runGen({ root: "/app", io });
+  assert.deepEqual(res.swept, [
+    "nano-generated/data_sdk.ts",
+    "nano-generated/old-worker-io.d.ts",
+  ]);
+  assert.ok(!("/app/nano-generated/data_sdk.ts" in io.files), "stale file removed");
+  assert.ok(!("/app/nano-generated/old-worker-io.d.ts" in io.files), "stale file removed");
+  // Current artifacts survive.
+  assert.ok("/app/nano-generated/worker-io.d.ts" in io.files, "fresh artifact kept");
+});
+
+test("runGen never sweeps runtime-materialized wrappers gen does not emit", async () => {
+  const io = memIO(fixture());
+  // The SDK shims + `urban data`/console dataops wrappers live in nano-generated/ but are not
+  // produced by `urban gen`; the app needs them at runtime, so the sweep must protect them.
+  for (const name of ["domain.ts", "workers.ts", "messages.ts", "domain.json", "data-sdk.ts", "worker-sdk.ts"]) {
+    io.files[`/app/nano-generated/${name}`] = `// runtime-materialized ${name}`;
+  }
+  const res = await runGen({ root: "/app", io });
+  assert.deepEqual(res.swept, [], "no runtime-materialized file swept");
+  for (const name of ["domain.ts", "workers.ts", "messages.ts", "domain.json", "data-sdk.ts", "worker-sdk.ts"]) {
+    assert.ok(`/app/nano-generated/${name}` in io.files, `${name} preserved`);
+  }
+});
+
+test("gen --check never sweeps (read-only)", async () => {
+  const io = memIO(fixture());
+  await runGen({ root: "/app", io });
+  io.files["/app/nano-generated/stale.ts"] = "// stale";
+  const res = await runGen({ root: "/app", io, check: true });
+  assert.deepEqual(res.swept, []);
+  assert.ok("/app/nano-generated/stale.ts" in io.files, "check mode leaves stale files untouched");
+});
+
+test("modelsOnly (urban derive) never sweeps nano-generated type-contract outputs", async () => {
+  const io = memIO(fixture());
+  // A prior `urban gen` wrote the type-contract outputs.
+  await runGen({ root: "/app", io });
+  assert.ok("/app/nano-generated/worker-io.d.ts" in io.files, "precondition: gen wrote outputs");
+  // `urban derive` (modelsOnly) derives only models — its artifacts carry no nano-generated/*, so
+  // the sweep must be a no-op here; otherwise it would wipe the type contracts above.
+  const res = await runGen({ root: "/app", io, modelsOnly: true });
+  assert.deepEqual(res.swept, []);
+  assert.ok("/app/nano-generated/worker-io.d.ts" in io.files, "derive preserved the type contracts");
+  assert.ok("/app/nano-generated/app.schema.sql" in io.files, "derive preserved the migrations");
+});
+
 // --- code-first model derivation (urban gen / urban derive) ---
 
 const GreetIn = envelope("GreetIn", { who: "string" });

package/src/toolkit/gen.ts

@@ -4,7 +4,7 @@
 // pure; all IO is confined here behind a tiny FS port so the same code runs on Node and Deno.
 
 import type { DerivedArtifact } from "./artifact.ts";
-import { isAbsolutePath, sortArtifacts } from "./artifact.ts";
+import { GENERATED_DIR, isAbsolutePath, RUNTIME_MATERIALIZED_ARTIFACTS, sortArtifacts } from "./artifact.ts";
 import { deriveMigrations, type ToolkitManifest } from "./derivers/migrations.ts";
 import { deriveDomain } from "./derivers/domain.ts";
 import { deriveWorkerBindings, type ModelSource } from "./derivers/worker-io.ts";
@@ -51,6 +51,8 @@ export interface GenResult {
   artifacts: DerivedArtifact[];
   /** Paths that differ from disk (only populated by `check`). */
   drift: string[];
+  /** App-relative paths of stale files removed from `nano-generated/` (only populated in write mode). */
+  swept: string[];
   /** True if any code-first workflow failed to import/derive. */
   incomplete: boolean;
   /** Per-file model-derivation errors (empty on success). */
@@ -122,7 +124,7 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
   const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
   const manifest: ToolkitManifest & {
     models?: { processes?: string[]; workflows?: string[] };
-    api?: { spec?: string; dir?: string };
+    api?: { spec?: string; dir?: string; eject?: boolean };
   } = JSON.parse(await io.readText(manifestPath));
 
   const artifacts: DerivedArtifact[] = [];
@@ -162,7 +164,7 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
     const opsDir = typeof manifest.api?.dir === "string" && manifest.api.dir.trim().length > 0
       ? manifest.api.dir.trim()
       : undefined;
-    artifacts.push(...deriveApi(parseSpec(specText), opsDir));
+    artifacts.push(...deriveApi(parseSpec(specText), opsDir, manifest.api?.eject === true));
   }
 
   return { artifacts: sortArtifacts(artifacts), derived };
@@ -199,7 +201,30 @@ export async function runGen(opts: GenOptions & { check?: boolean }): Promise<Ge
     }
   }
 
-  return { artifacts, drift, incomplete: derived.incomplete, modelErrors: derived.errors };
+  // Stale-artifact sweep of `nano-generated/` (clean break, nano-bpm#: gen owns its output dir).
+  // The dir is gitignored and fully codegen-owned, so any file this run did not (re)write is stale
+  // from a prior gen — a renamed or removed artifact (e.g. an old `data_sdk.ts`) whose orphan the
+  // app might still import. Remove it. The one exception is the runtime-materialized set: the SDK
+  // shims + the `urban data`/console dataops wrappers gen does NOT emit but the app needs at runtime
+  // (RUNTIME_MATERIALIZED_ARTIFACTS). Protect those by name. Write mode only; skipped when io.remove
+  // is absent (the sweep is best-effort, mirroring the `.bpmn` sweep above). NOT on `modelsOnly`
+  // (`urban derive`): that path derives only models, so `artifacts` carries no `nano-generated/*` and
+  // sweeping would wrongly wipe the type-contract outputs a prior `urban gen` wrote.
+  const swept: string[] = [];
+  if (!opts.check && !opts.modelsOnly && !derived.incomplete && io.remove) {
+    const keep = new Set(
+      artifacts.map((a) => a.path).filter((p) => p.startsWith(`${GENERATED_DIR}/`)),
+    );
+    for (const name of RUNTIME_MATERIALIZED_ARTIFACTS) keep.add(`${GENERATED_DIR}/${name}`);
+    for (const name of await io.listDir(join(root, GENERATED_DIR))) {
+      const rel = `${GENERATED_DIR}/${name}`;
+      if (keep.has(rel)) continue;
+      await io.remove(join(root, rel));
+      swept.push(rel);
+    }
+  }
+
+  return { artifacts, drift, swept: swept.sort(), incomplete: derived.incomplete, modelErrors: derived.errors };
 }
 
 export { dirOf, join as joinPath };