@nanobpm/urban 0.36.0 → 0.38.0

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.ts

@@ -122,7 +122,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 +162,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 };

package/src/toolkit/scaffold/workers.test.ts

@@ -99,6 +99,16 @@ test("planWorkerScaffold: skips already-wired, orchestrator, and duplicates", ()
   assert.equal(reasons["t.new"], "duplicate");
 });
 
+test("planWorkerScaffold: skips a task type declared external (out-of-process worker)", () => {
+  const models = [
+    model("a.bpmn", "p1", serviceTask("A", "senior:review"), serviceTask("B", "t.new")),
+  ];
+  const { plans, skipped } = planWorkerScaffold(models, [], [], ["senior:review"]);
+  assert.deepEqual(plans.map((p) => p.taskType), ["t.new"]);
+  const reasons = Object.fromEntries(skipped.map((s) => [s.taskType, s.reason]));
+  assert.equal(reasons["senior:review"], "external");
+});
+
 test("planWorkerScaffold: colliding slugs get a numeric suffix", () => {
   const m = model("a.bpmn", "p", serviceTask("A", "orders.charge"), serviceTask("B", "orders-charge"));
   const { plans } = planWorkerScaffold([m], [], []);
@@ -195,3 +205,28 @@ test("scaffoldWorkers is idempotent: a second --write run is a no-op", async ()
   assert.equal(run2.manifestPatched, false, "no new wiring on the second run");
   assert.equal(JSON.stringify(io.files), snapshot, "files unchanged on re-run");
 });
+
+test("scaffoldWorkers reads manifest.externalTaskTypes and skips those (never scaffolds/wires)", async () => {
+  const files = {
+    "/app/nano.app.json": JSON.stringify({
+      id: "demo",
+      models: { processes: ["processes/*.bpmn"] },
+      externalTaskTypes: ["senior:review"],
+    }),
+    "/app/processes/p.bpmn": model("p.bpmn", "p",
+      serviceTask("A", "senior:review"),
+      serviceTask("B", "t.new"),
+    ).xml,
+  };
+  const io = memIO(files);
+  const run = await scaffoldWorkers({ root: "/app", io, write: true });
+  // Only the app-hosted task is scaffolded; the external one is skipped.
+  assert.deepEqual(run.outcomes.map((o) => o.taskType), ["t.new"]);
+  assert.ok(run.skipped.some((s) => s.taskType === "senior:review" && s.reason === "external"));
+  assert.equal(io.files["/app/workers/senior-review/worker.ts"], undefined, "external task gets no stub");
+  const manifest = JSON.parse(io.files["/app/nano.app.json"]);
+  assert.ok(
+    !manifest.workers?.some((w: { taskType: string }) => w.taskType === "senior:review"),
+    "external task is never wired into workers[]",
+  );
+});

package/src/toolkit/scaffold/workers.ts

@@ -39,7 +39,7 @@ export interface WorkerStubPlan {
   manifestEntry: StubManifestEntry;
 }
 
-export type SkipReason = "already-wired" | "orchestrator" | "duplicate";
+export type SkipReason = "already-wired" | "orchestrator" | "duplicate" | "external";
 
 export interface SkippedWorker {
   taskType: string;
@@ -110,14 +110,17 @@ export function renderWorkerStub(
 
 /**
  * Plan write-once handler stubs from the models. A stub is planned for each service-task
- * `taskType` that is NOT already wired in the manifest, NOT the imperative orchestrator, and
- * not a duplicate of one already planned. `declaredTypeIds` are the manifest `types` ids — an
- * envelope `in`/`out` is typed only when it names one (matching the worker-io deriver).
+ * `taskType` that is NOT already wired in the manifest, NOT the imperative orchestrator, NOT
+ * declared external (serviced by an out-of-process worker), and not a duplicate of one already
+ * planned. `declaredTypeIds` are the manifest `types` ids — an envelope `in`/`out` is typed only
+ * when it names one (matching the worker-io deriver). `externalTaskTypes` are the manifest's
+ * declared external task types, which the app owns the model for but deliberately does not host.
  */
 export function planWorkerScaffold(
   models: ModelSource[],
   workers: ScaffoldWorker[] = [],
   declaredTypeIds: Iterable<string> = [],
+  externalTaskTypes: Iterable<string> = [],
 ): WorkerScaffoldPlan {
   const wired = new Set(
     workers
@@ -125,6 +128,7 @@ export function planWorkerScaffold(
       .filter((t): t is string => typeof t === "string" && t.length > 0),
   );
   const declared = new Set(declaredTypeIds);
+  const external = new Set(externalTaskTypes);
 
   const plans: WorkerStubPlan[] = [];
   const skipped: SkippedWorker[] = [];
@@ -138,6 +142,10 @@ export function planWorkerScaffold(
         skipped.push({ taskType, reason: "orchestrator" });
         continue;
       }
+      if (external.has(taskType)) {
+        skipped.push({ taskType, reason: "external" });
+        continue;
+      }
       if (wired.has(taskType)) {
         skipped.push({ taskType, reason: "already-wired" });
         continue;

package/src/toolkit/scaffold.ts

@@ -19,6 +19,7 @@ interface ScaffoldManifest {
   types?: Record<string, unknown>;
   models?: { processes?: string[] };
   workers?: ScaffoldWorker[];
+  externalTaskTypes?: string[];
   api?: { spec?: string; dir?: string };
 }
 
@@ -64,7 +65,12 @@ export async function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRu
   const models = await readModels(root, io, manifest);
   const declaredTypeIds = Object.keys(manifest.types ?? {});
 
-  const { plans, skipped } = planWorkerScaffold(models, manifest.workers ?? [], declaredTypeIds);
+  const { plans, skipped } = planWorkerScaffold(
+    models,
+    manifest.workers ?? [],
+    declaredTypeIds,
+    manifest.externalTaskTypes ?? [],
+  );
 
   const outcomes: StubOutcome[] = [];
   const wired: StubManifestEntry[] = [];