@nanobpm/urban 0.35.0 → 0.37.0

package/src/toolkit/scaffold/operations.ts

@@ -0,0 +1,75 @@
+// Pure planner for the write-once operation-delegate scaffolder (ADR 0059). Given a parsed OpenAPI
+// document, it plans one typed delegate stub per declared `operationId` — the ONE part of the HTTP
+// surface that cannot be derived from the spec (the handler *body* is human logic). Everything here
+// is pure and testable like a deriver; the impure write-if-absent edge lives in `../scaffold.ts`.
+//
+// scaffold ≠ derive: stubs are human-owned files under `<dir>/<operationId>.ts`, so they are planned
+// once and never overwritten — unlike the derived `nano-generated/` tree (which includes the
+// controller registry that statically imports these delegates and type-checks the whole set).
+
+import { DEFAULT_OPERATIONS_DIR, normalizeApiDir } from "../api-dir.ts";
+import { assertUniqueOperationIds, collectOperations, type OpenApiDoc } from "../../openapi/spec.ts";
+
+export { DEFAULT_OPERATIONS_DIR };
+
+/** One planned operation-delegate stub. */
+export interface OperationStubPlan {
+  operationId: string;
+  /** App-relative delegate path: `<dir>/<operationId>.ts`. */
+  handlerPath: string;
+  /** The stub file contents (a typed `defineOperation` that throws `NotImplemented` → HTTP 501). */
+  stub: string;
+}
+
+/** Normalize an `api.dir` to a clean relative segment (see `normalizeApiDir`); rejects absolute
+ *  paths and `..` segments so stubs are scaffolded where the runtime resolves delegates from. */
+function normalizeDir(dir: string): string {
+  return normalizeApiDir(dir);
+}
+
+/** Number of `../` hops from `<dir>/<file>.ts` back up to the app root (dir may be nested). */
+function upToRoot(dir: string): string {
+  const depth = dir.split("/").filter((s) => s.length > 0).length;
+  return "../".repeat(depth);
+}
+
+/** Render a stub matching a real hand-authored operation delegate (default-exported, typed via the
+ *  generated `defineOperation`). It throws `NotImplemented` so the endpoint returns 501 until the
+ *  body is implemented — never a silent 500, never a drift from the contract. */
+export function renderOperationStub(operationId: string, dir: string = DEFAULT_OPERATIONS_DIR): string {
+  const up = upToRoot(normalizeDir(dir));
+  const key = JSON.stringify(operationId);
+  return (
+    `// Operation delegate stub for the \`${operationId}\` endpoint, scaffolded from the OpenAPI spec\n` +
+    `// (ADR 0059). This file is yours to edit — \`urban gen\` will never overwrite it. The\n` +
+    `// generated controller (nano-generated/controller.ts) imports this default export and\n` +
+    `// type-checks it against the spec, so the signature cannot drift. Implement the body below\n` +
+    `// (the validated \`{ req, params, query, body }\` input + the injected \`app\`) and delete the throw.\n` +
+    `import { NotImplemented } from "@nanobpm/urban";\n` +
+    `import { defineOperation } from ${JSON.stringify(`${up}nano-generated/operations.ts`)};\n` +
+    `\n` +
+    `export default defineOperation(${key}, async (input, app) => {\n` +
+    `  // \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
+    `  // through the injected \`app\` API. Return \`{ status?, headers?, body? }\` (or nothing → 204).\n` +
+    `  throw new NotImplemented(${key});\n` +
+    `});\n`
+  );
+}
+
+/**
+ * Plan write-once delegate stubs from the spec: one per declared `operationId` (collectOperations
+ * already skips ops without a safe id). The planner emits a plan for every operation; the impure
+ * edge (`scaffoldOperations`) keeps an existing file verbatim and creates only the absent ones.
+ */
+export function planOperationScaffold(
+  doc: OpenApiDoc,
+  dir: string = DEFAULT_OPERATIONS_DIR,
+): OperationStubPlan[] {
+  assertUniqueOperationIds(doc);
+  const cleanDir = normalizeDir(dir);
+  return collectOperations(doc).map((op) => ({
+    operationId: op.operationId,
+    handlerPath: `${cleanDir}/${op.operationId}.ts`,
+    stub: renderOperationStub(op.operationId, cleanDir),
+  }));
+}

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;
@@ -92,7 +92,7 @@ export function renderWorkerStub(
 
   return (
     `// Handler stub for the \`${taskType}\` service task, scaffolded from the model (ADR 0056).\n` +
-    `// This file is yours to edit — \`urban stubs\` will never overwrite it. Implement the body\n` +
+    `// This file is yours to edit — \`urban gen\` will never overwrite it. Implement the body\n` +
     `// below (use \`app.data.table(...)\` for state) and delete the throw.\n` +
     `import type { AppJobHandler } from "@nanobpm/urban/worker";\n` +
     generatedImport +
@@ -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

@@ -11,12 +11,16 @@ import {
   type SkippedWorker,
   type StubManifestEntry,
 } from "./scaffold/workers.ts";
+import { planOperationScaffold } from "./scaffold/operations.ts";
+import { parseSpec } from "../openapi/spec.ts";
 
 /** The manifest fields the scaffolder reads. */
 interface ScaffoldManifest {
   types?: Record<string, unknown>;
   models?: { processes?: string[] };
   workers?: ScaffoldWorker[];
+  externalTaskTypes?: string[];
+  api?: { spec?: string; dir?: string };
 }
 
 export interface ScaffoldOptions {
@@ -61,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[] = [];
@@ -102,3 +111,56 @@ export async function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRu
 
   return { outcomes, skipped, wired, manifestPatched, write };
 }
+
+/** One planned operation-delegate outcome (write-once). */
+export interface OperationStubOutcome {
+  operationId: string;
+  handlerPath: string;
+  status: StubStatus;
+}
+
+export interface OperationScaffoldRun {
+  outcomes: OperationStubOutcome[];
+  write: boolean;
+}
+
+/**
+ * Scaffold write-once operation-delegate stubs from the app's OpenAPI spec (ADR 0059). One typed
+ * `defineOperation` stub per declared `operationId`, created only if absent (human-owned files are
+ * kept verbatim). Dry-run by default. A no-op when the app declares no `api.spec`.
+ */
+export async function scaffoldOperations(opts: ScaffoldOptions): Promise<OperationScaffoldRun> {
+  const { root, io } = opts;
+  const write = opts.write ?? false;
+  const manifestFile = opts.manifestFile ?? "nano.app.json";
+  const manifestPath = joinPath(root, manifestFile);
+
+  const manifest: ScaffoldManifest = JSON.parse(await io.readText(manifestPath));
+  const specRef = typeof manifest.api?.spec === "string" ? manifest.api.spec.trim() : "";
+  if (specRef.length === 0) return { outcomes: [], write };
+
+  const specText = await io.readText(joinPath(root, specRef));
+  const dir =
+    typeof manifest.api?.dir === "string" && manifest.api.dir.trim().length > 0
+      ? manifest.api.dir.trim()
+      : undefined;
+  const plans = planOperationScaffold(parseSpec(specText), dir);
+
+  const outcomes: OperationStubOutcome[] = [];
+  for (const plan of plans) {
+    const abs = joinPath(root, plan.handlerPath);
+    const exists = await io.exists(abs);
+    let status: StubStatus;
+    if (exists) {
+      status = "kept"; // human-owned — never clobber
+    } else if (write) {
+      await io.writeText(abs, plan.stub);
+      status = "created";
+    } else {
+      status = "would-create";
+    }
+    outcomes.push({ operationId: plan.operationId, handlerPath: plan.handlerPath, status });
+  }
+
+  return { outcomes, write };
+}