@nanobpm/urban 0.35.0 → 0.36.0

package/dist/toolkit/gen.js

@@ -98,7 +98,10 @@ async function collectAll(opts) {
     const specRef = typeof manifest.api?.spec === "string" ? manifest.api.spec.trim() : "";
     if (!opts.modelsOnly && specRef.length > 0) {
         const specText = await io.readText(join(root, specRef));
-        artifacts.push(...deriveApi(parseSpec(specText)));
+        const opsDir = typeof manifest.api?.dir === "string" && manifest.api.dir.trim().length > 0
+            ? manifest.api.dir.trim()
+            : undefined;
+        artifacts.push(...deriveApi(parseSpec(specText), opsDir));
     }
     return { artifacts: sortArtifacts(artifacts), derived };
 }

package/dist/toolkit/generate.d.ts

@@ -0,0 +1,27 @@
+import type { GenOptions, GenResult } from "./gen.ts";
+import type { OperationStubOutcome, StubOutcome } from "./scaffold.ts";
+import type { StubManifestEntry } from "./scaffold/workers.ts";
+export interface GenerateResult extends GenResult {
+    /** Worker-stub scaffolding outcomes (created / kept / would-create). */
+    workerStubs: StubOutcome[];
+    /** Operation-delegate scaffolding outcomes (created / kept / would-create). */
+    operationStubs: OperationStubOutcome[];
+    /** Worker manifest entries wired into `workers[]` (write mode only). */
+    wiredWorkers: StubManifestEntry[];
+    /** True when `workers[]` was patched (write mode, unwired workers present). */
+    manifestPatched: boolean;
+    /**
+     * App-relative paths of stubs that would be created — the scaffolding equivalent of `drift`.
+     * Populated in `check` mode (nothing is written); a caller should fail CI when non-empty.
+     */
+    missingStubs: string[];
+}
+/**
+ * Derive artifacts and scaffold the write-once handler stubs they reference, in one pass.
+ * In `check` mode nothing is written and any would-be-created stub is reported in `missingStubs`.
+ * Scaffolding is skipped when derivation is `incomplete` (never scaffold from a half-derived model);
+ * the caller reports the derivation failure first.
+ */
+export declare function generate(opts: GenOptions & {
+    check?: boolean;
+}): Promise<GenerateResult>;

package/dist/toolkit/generate.js

@@ -0,0 +1,47 @@
+// `urban gen`: the whole generation concern in one pass — derive artifacts (migrations, worker-I/O,
+// code-first models, OpenAPI contracts + controller) AND scaffold the write-once handler stubs those
+// artifacts reference (worker stubs from the model, operation-delegate stubs from the OpenAPI spec).
+//
+// This composes the pure derivation (`runGen`, gen.ts) with the write-once scaffolders (scaffold.ts)
+// WITHOUT a cycle: scaffold.ts already depends on gen.ts, so this leaf module depends on both and
+// neither depends back. Scaffolding is write-once (an existing, human-owned stub is never clobbered),
+// so folding it into `gen` is idempotent. `--check` writes nothing: a missing stub surfaces in
+// `missingStubs` exactly like a drifted artifact surfaces in `drift`, so CI fails when a stub the
+// generated controller imports isn't committed.
+import { runGen } from "./gen.js";
+import { scaffoldOperations, scaffoldWorkers } from "./scaffold.js";
+/**
+ * Derive artifacts and scaffold the write-once handler stubs they reference, in one pass.
+ * In `check` mode nothing is written and any would-be-created stub is reported in `missingStubs`.
+ * Scaffolding is skipped when derivation is `incomplete` (never scaffold from a half-derived model);
+ * the caller reports the derivation failure first.
+ */
+export async function generate(opts) {
+    const res = await runGen(opts);
+    const empty = {
+        ...res,
+        workerStubs: [],
+        operationStubs: [],
+        wiredWorkers: [],
+        manifestPatched: false,
+        missingStubs: [],
+    };
+    if (res.incomplete)
+        return empty;
+    const write = !opts.check;
+    const scaffoldOpts = { root: opts.root, io: opts.io, manifestFile: opts.manifestFile, write };
+    const workers = await scaffoldWorkers(scaffoldOpts);
+    const operations = await scaffoldOperations(scaffoldOpts);
+    const missingStubs = [
+        ...workers.outcomes.filter((o) => o.status === "would-create").map((o) => o.handlerPath),
+        ...operations.outcomes.filter((o) => o.status === "would-create").map((o) => o.handlerPath),
+    ];
+    return {
+        ...res,
+        workerStubs: workers.outcomes,
+        operationStubs: operations.outcomes,
+        wiredWorkers: workers.wired,
+        manifestPatched: workers.manifestPatched,
+        missingStubs,
+    };
+}

package/dist/toolkit/index.d.ts

@@ -13,7 +13,7 @@ export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, }
 export type { MetaDecl } from "./derivers/meta.ts";
 export { deriveMessageBindings, emitMessageBindings, emitMessageBindingsRuntime, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "./derivers/messages.ts";
 export type { MessageIo, MessageBindingDecl } from "./derivers/messages.ts";
-export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, } from "./derivers/api.ts";
+export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, emitApiController, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, API_CONTROLLER_TS, } from "./derivers/api.ts";
 export { collectOperations, HTTP_METHODS, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, refName, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../openapi/spec.ts";
 export type { HttpMethodLower, OpenApiDoc, OpenApiParameter, OpenApiSchema, OperationInfo, } from "../openapi/spec.ts";
 export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<{
@@ -26,9 +26,12 @@ export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import(
     declaredTypeIds: Iterable<string>;
 }>, import("./artifact.ts").Deriver<{
     doc: import("../openapi/spec.ts").OpenApiDoc;
+    operationsDir?: string;
 }>];
 export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.ts";
 export type { GenIO, GenOptions, GenResult } from "./gen.ts";
+export { generate } from "./generate.ts";
+export type { GenerateResult } from "./generate.ts";
 export { createNodeGenIO } from "./fsio.ts";
 export { deriveModels, isWorkflow, bpmnFilename, processesOutDir, DEFAULT_WORKFLOW_PATTERNS, PROCESSES_DIR, MODEL_PROVENANCE, } from "./models.ts";
 export type { DerivedModels, DerivedModelInfo, ModelError, ModelsManifest } from "./models.ts";
@@ -36,5 +39,9 @@ export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffo
 export type { ScaffoldWorker, SkippedWorker, SkipReason, StubManifestEntry, WorkerScaffoldPlan, WorkerStubPlan, } from "./scaffold/workers.ts";
 export { scaffoldWorkers } from "./scaffold.ts";
 export type { ScaffoldOptions, ScaffoldRun, StubOutcome, StubStatus } from "./scaffold.ts";
+export { planOperationScaffold, renderOperationStub } from "./scaffold/operations.ts";
+export type { OperationStubPlan } from "./scaffold/operations.ts";
+export { scaffoldOperations } from "./scaffold.ts";
+export type { OperationScaffoldRun, OperationStubOutcome } from "./scaffold.ts";
 export { addConnector } from "./addConnector.ts";
 export type { AddConnectorOptions, AddConnectorResult } from "./addConnector.ts";

package/dist/toolkit/index.js

@@ -11,7 +11,7 @@ export { deriveWorkerBindings, emitWorkerBindings, emitWorkerBindingsRuntime, ov
 export { byModelPath, typeRefFor } from "./derivers/worker-io.js";
 export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, } from "./derivers/meta.js";
 export { deriveMessageBindings, emitMessageBindings, emitMessageBindingsRuntime, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "./derivers/messages.js";
-export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, } from "./derivers/api.js";
+export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, emitApiController, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, API_CONTROLLER_TS, } from "./derivers/api.js";
 // The OpenAPI machinery the deriver + runtime share (ADR 0058).
 export { collectOperations, HTTP_METHODS, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, refName, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../openapi/spec.js";
 // The registry of all derivers (for discovery / IDE migration).
@@ -31,10 +31,14 @@ export const DERIVERS = [
 ];
 // Gen orchestrator + IO
 export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.js";
+export { generate } from "./generate.js";
 export { createNodeGenIO } from "./fsio.js";
 // Code-first model derivation (workflows/*.ts → BPMN)
 export { deriveModels, isWorkflow, bpmnFilename, processesOutDir, DEFAULT_WORKFLOW_PATTERNS, PROCESSES_DIR, MODEL_PROVENANCE, } from "./models.js";
 // Worker-stub scaffolder (ADR 0056): write-once handler stubs from the model.
 export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffold/workers.js";
 export { scaffoldWorkers } from "./scaffold.js";
+// Operation-delegate scaffolder (ADR 0059): write-once typed delegate stubs from the OpenAPI spec.
+export { planOperationScaffold, renderOperationStub } from "./scaffold/operations.js";
+export { scaffoldOperations } from "./scaffold.js";
 export { addConnector } from "./addConnector.js";

package/dist/toolkit/scaffold/operations.d.ts

@@ -0,0 +1,21 @@
+import { DEFAULT_OPERATIONS_DIR } from "../api-dir.ts";
+import { 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;
+}
+/** 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 declare function renderOperationStub(operationId: string, dir?: string): string;
+/**
+ * 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 declare function planOperationScaffold(doc: OpenApiDoc, dir?: string): OperationStubPlan[];

package/dist/toolkit/scaffold/operations.js

@@ -0,0 +1,55 @@
+// 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.js";
+import { assertUniqueOperationIds, collectOperations } from "../../openapi/spec.js";
+export { DEFAULT_OPERATIONS_DIR };
+/** 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) {
+    return normalizeApiDir(dir);
+}
+/** Number of `../` hops from `<dir>/<file>.ts` back up to the app root (dir may be nested). */
+function upToRoot(dir) {
+    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, dir = DEFAULT_OPERATIONS_DIR) {
+    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, dir = DEFAULT_OPERATIONS_DIR) {
+    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/dist/toolkit/scaffold/workers.js

@@ -41,7 +41,7 @@ export function renderWorkerStub(taskType, typedIn, typedOut) {
         ? `  // \`job.variables\` is typed as WorkerInputs[${key}].`
         : `  // \`job.variables\` is an open Record<string, unknown> (no declared input type).`;
     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 +

package/dist/toolkit/scaffold.d.ts

@@ -29,3 +29,19 @@ export interface ScaffoldRun {
 }
 /** Scaffold write-once worker stubs from the model, wiring them into `manifest.workers[]`. */
 export declare function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRun>;
+/** 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 declare function scaffoldOperations(opts: ScaffoldOptions): Promise<OperationScaffoldRun>;

package/dist/toolkit/scaffold.js

@@ -4,6 +4,8 @@
 // human-owned, so an existing file is KEPT verbatim, never clobbered (the opposite of `runGen`).
 import { joinPath, readModels } from "./gen.js";
 import { planWorkerScaffold, } from "./scaffold/workers.js";
+import { planOperationScaffold } from "./scaffold/operations.js";
+import { parseSpec } from "../openapi/spec.js";
 /** Scaffold write-once worker stubs from the model, wiring them into `manifest.workers[]`. */
 export async function scaffoldWorkers(opts) {
     const { root, io } = opts;
@@ -52,3 +54,41 @@ export async function scaffoldWorkers(opts) {
     }
     return { outcomes, skipped, wired, manifestPatched, write };
 }
+/**
+ * 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) {
+    const { root, io } = opts;
+    const write = opts.write ?? false;
+    const manifestFile = opts.manifestFile ?? "nano.app.json";
+    const manifestPath = joinPath(root, manifestFile);
+    const manifest = 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 = [];
+    for (const plan of plans) {
+        const abs = joinPath(root, plan.handlerPath);
+        const exists = await io.exists(abs);
+        let status;
+        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 };
+}

package/package.json

@@ -1,76 +1,76 @@
 {
-  "name": "@nanobpm/urban",
-  "version": "0.35.0",
-  "description": "Urban: build and run code-first apps on Nano \u2014 runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
-  "license": "Apache-2.0",
-  "type": "module",
-  "keywords": [
-    "nanobpm",
-    "urban",
-    "cli",
-    "runtime",
-    "codegen",
-    "derivation",
-    "nano-app",
-    "rad"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nanobpm/nano-ide.git",
-    "directory": "packages/urban"
-  },
-  "engines": {
-    "node": ">=22.6"
-  },
-  "bin": {
-    "urban": "src/bin.mjs"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "default": "./dist/runtime/index.js"
-    },
-    "./toolkit": {
-      "types": "./dist/toolkit/index.d.ts",
-      "default": "./dist/toolkit/index.js"
-    },
-    "./worker": {
-      "types": "./dist/worker.d.ts",
-      "default": "./dist/worker.js"
-    },
-    "./source": "./src/index.ts"
-  },
-  "files": [
-    "dist",
-    "src",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepack": "npm run build",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "node --test --experimental-strip-types \"src/**/*.test.ts\"",
-    "test:deno": "deno test -A --no-check src/"
-  },
-  "dependencies": {
-    "@nanobpm/nano-app-schema": "^0.4.0",
-    "@nanobpm/nano-sdk": "^1.2.3",
-    "@nanobpm/workflow": "^0.8.0",
-    "bpmn-auto-layout": "^2.0.0-alpha.2",
-    "create-urban-app": "^0.9.0",
-    "yaml": "^2.9.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.20.1",
-    "typescript": "^5.9.3"
-  }
+	"name": "@nanobpm/urban",
+	"version": "0.36.0",
+	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
+	"license": "Apache-2.0",
+	"type": "module",
+	"keywords": [
+		"nanobpm",
+		"urban",
+		"cli",
+		"runtime",
+		"codegen",
+		"derivation",
+		"nano-app",
+		"rad"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nanobpm/nano-ide.git",
+		"directory": "packages/urban"
+	},
+	"engines": {
+		"node": ">=22.6"
+	},
+	"bin": {
+		"urban": "src/bin.mjs"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./runtime": {
+			"types": "./dist/runtime/index.d.ts",
+			"default": "./dist/runtime/index.js"
+		},
+		"./toolkit": {
+			"types": "./dist/toolkit/index.d.ts",
+			"default": "./dist/toolkit/index.js"
+		},
+		"./worker": {
+			"types": "./dist/worker.d.ts",
+			"default": "./dist/worker.js"
+		},
+		"./source": "./src/index.ts"
+	},
+	"files": [
+		"dist",
+		"src",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "npm run build",
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"test": "node --test --experimental-strip-types \"src/**/*.test.ts\"",
+		"test:deno": "deno test -A --no-check src/"
+	},
+	"dependencies": {
+		"@nanobpm/nano-app-schema": "^0.4.0",
+		"@nanobpm/nano-sdk": "^1.2.3",
+		"@nanobpm/workflow": "^0.8.0",
+		"bpmn-auto-layout": "^2.0.0-alpha.2",
+		"create-urban-app": "^0.9.0",
+		"yaml": "^2.9.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.20.1",
+		"typescript": "^5.9.3"
+	}
 }

package/src/cli.test.ts

@@ -14,7 +14,6 @@ test("urban data exits 0 with a parseable envelope on an unreadable request", as
     root: ".",
     manifest: "nano.app.json",
     check: false,
-    write: false,
     deno: false,
     models: true,
     stdout: false,

package/src/cli.ts

@@ -25,7 +25,7 @@ import { denoGlobal, processGlobal } from "./runtime/adapters/globals.ts";
 import { errorMessage, isRecord } from "./runtime/core/guards.ts";
 import { scaffold, slugify } from "create-urban-app";
 import type { DataRequest } from "./runtime/index.ts";
-import { addConnector, createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.ts";
+import { addConnector, createNodeGenIO, previewModels, generate, runGen } from "./toolkit/index.ts";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
@@ -50,7 +50,6 @@ interface Flags {
   manifest: string;
   port?: number;
   check: boolean;
-  write: boolean;
   deno: boolean;
   models: boolean;
   stdout: boolean;
@@ -62,7 +61,7 @@ interface Flags {
 }
 
 function parse(argv: string[]): Flags {
-  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
+  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
   const need = (i: number, flag: string): string => {
     const v = argv[i];
     if (v === undefined || v.startsWith("-")) throw new Error(`flag ${flag} requires a value`);
@@ -73,7 +72,6 @@ function parse(argv: string[]): Flags {
     if (a === "-h" || a === "--help") f.help = true;
     else if (a === "-v" || a === "--version") f.version = true;
     else if (a === "--check") f.check = true;
-    else if (a === "--write") f.write = true;
     else if (a === "--deno") f.deno = true;
     else if (a === "--no-models") f.models = false;
     else if (a === "--models") f.models = true;
@@ -108,11 +106,12 @@ Usage:
   urban new <name> [--root <path>] [--deno] [--style model|code]    scaffold a new Urban app
                                     (--code-first is shorthand for --style code)
   urban check                       validate the manifest
-  urban gen [--check] [--no-models] derive artifacts (migrations, worker-io, + code-first models)
+  urban gen [--check] [--no-models] derive artifacts + scaffold write-once handler stubs
+                                    (--check: verify up-to-date without writing; a missing stub or
+                                    drifted artifact fails — run \`urban gen\`)
                                     (--no-models: skip writing derived .bpmn; type-contracts only)
   urban derive [--check|--stdout]   derive code-first models only (workflows/*.ts → processes/*.bpmn)
                                     (--stdout: print {models,incomplete} JSON without writing)
-  urban stubs [--write]             scaffold write-once handler stubs from the model
   urban add <pkg> [--no-install]    install a connector pack + wire it into nano.app.json
   urban run                         materialize + serve the app
   urban dev                         run + watch sources, hot-reload on change
@@ -148,23 +147,43 @@ async function cmdCheck(f: Flags): Promise<number> {
 
 async function cmdGen(f: Flags): Promise<number> {
   const io = createNodeGenIO();
-  const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
+  const res = await generate({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
   if (res.incomplete) {
     console.error(`✖ ${res.modelErrors.length} workflow(s) failed to derive:`);
     for (const e of res.modelErrors) console.error(`  • ${e.path}: ${e.message}`);
     return 1;
   }
   if (f.check) {
-    if (res.drift.length === 0) {
-      console.log(`✔ generated artifacts are up to date (${res.artifacts.length} checked)`);
+    if (res.drift.length === 0 && res.missingStubs.length === 0) {
+      console.log(`✔ generated artifacts + handler stubs are up to date (${res.artifacts.length} checked)`);
       return 0;
     }
-    console.error(`✖ ${res.drift.length} generated artifact(s) are out of date — run \`urban gen\`:`);
-    for (const p of res.drift) console.error(`  • ${p}`);
+    if (res.drift.length > 0) {
+      console.error(`✖ ${res.drift.length} generated artifact(s) are out of date — run \`urban gen\`:`);
+      for (const p of res.drift) console.error(`  • ${p}`);
+    }
+    if (res.missingStubs.length > 0) {
+      console.error(`✖ ${res.missingStubs.length} handler stub(s) missing — run \`urban gen\`:`);
+      for (const p of res.missingStubs) console.error(`  • ${p}`);
+    }
     return 1;
   }
   console.log(`✔ generated ${res.artifacts.length} artifact(s):`);
   for (const a of res.artifacts) console.log(`  • ${a.path}`);
+
+  // Write-once handler stubs scaffolded as part of generation (workers from the model, operation
+  // delegates from the OpenAPI spec). Existing, human-owned stubs are kept verbatim.
+  const created = [
+    ...res.workerStubs.filter((o) => o.status === "created").map((o) => o.handlerPath),
+    ...res.operationStubs.filter((o) => o.status === "created").map((o) => o.handlerPath),
+  ];
+  if (created.length > 0) {
+    console.log(`✔ scaffolded ${created.length} handler stub(s):`);
+    for (const p of created) console.log(`  + ${p}`);
+  }
+  if (res.manifestPatched) {
+    console.log(`✔ wired ${res.wiredWorkers.length} worker(s) into ${f.manifest}`);
+  }
   return 0;
 }
 
@@ -217,38 +236,6 @@ async function cmdDerive(f: Flags): Promise<number> {
   return 0;
 }
 
-async function cmdStubs(f: Flags): Promise<number> {
-  const io = createNodeGenIO();
-  const run = await scaffoldWorkers({ root: f.root, io, manifestFile: f.manifest, write: f.write });
-
-  const created = run.outcomes.filter((o) => o.status === "created");
-  const would = run.outcomes.filter((o) => o.status === "would-create");
-  const kept = run.outcomes.filter((o) => o.status === "kept");
-  const typing = (o: { typedIn: boolean; typedOut: boolean }) =>
-    o.typedIn || o.typedOut ? ` (typed${o.typedIn ? " in" : ""}${o.typedOut ? " out" : ""})` : "";
-
-  if (run.write) {
-    console.log(`✔ scaffolded ${created.length} worker stub(s):`);
-    for (const o of created) console.log(`  + ${o.handlerPath}${typing(o)}`);
-    if (run.manifestPatched) {
-      console.log(`✔ wired ${run.wired.length} worker(s) into ${f.manifest}`);
-    }
-  } else {
-    if (would.length === 0) {
-      console.log(`✔ no new worker stubs to scaffold`);
-    } else {
-      console.log(`Would scaffold ${would.length} worker stub(s) — run with --write to apply:`);
-      for (const o of would) console.log(`  + ${o.handlerPath}${typing(o)}`);
-    }
-  }
-  for (const o of kept) console.log(`  = ${o.handlerPath} (kept — already exists)`);
-  if (run.skipped.length > 0) {
-    console.log(`  skipped ${run.skipped.length}: ` +
-      run.skipped.map((s) => `${s.taskType} (${s.reason})`).join(", "));
-  }
-  return 0;
-}
-
 async function cmdRun(f: Flags, mount?: Record<string, boolean>): Promise<number> {
   const app = await runFromEnv({
     root: f.root,
@@ -430,8 +417,6 @@ export async function main(argv: string[]): Promise<number> {
       return cmdGen(f);
     case "derive":
       return cmdDerive(f);
-    case "stubs":
-      return cmdStubs(f);
     case "add":
       return cmdAdd(f);
     case "data":

package/src/openapi/spec.ts

@@ -265,6 +265,30 @@ export function collectOperations(doc: OpenApiDoc): OperationInfo[] {
   return out;
 }
 
+/**
+ * Throw if the document declares the same `operationId` on more than one operation. An operationId
+ * must be unique across the whole OpenAPI document (it names the delegate module `<dir>/<operationId>`
+ * AND the generated controller registry key), so a duplicate would silently overwrite an earlier
+ * entry in the emitted object literal — dispatching the wrong delegate while still type-checking — and
+ * make the scaffolder plan the same stub twice. Called by the gen/scaffold path so `urban gen`
+ * fails loudly on an incoherent spec instead of shipping a mis-dispatching registry.
+ */
+export function assertUniqueOperationIds(doc: OpenApiDoc): void {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+  for (const op of collectOperations(doc)) {
+    if (seen.has(op.operationId)) duplicates.add(op.operationId);
+    seen.add(op.operationId);
+  }
+  if (duplicates.size > 0) {
+    const list = [...duplicates].sort().join(", ");
+    throw new Error(
+      `OpenAPI spec declares duplicate operationId(s): ${list}. Each operationId must be unique — ` +
+        "it names the delegate module and the generated controller registry key.",
+    );
+  }
+}
+
 /** "method path" pointers for every operation that declares no `operationId`. Such operations are
  *  unroutable (no delegate to bind), so the runtime mount logs them at `warn` and skips them. */
 export function operationsWithoutId(doc: OpenApiDoc): string[] {