@nanobpm/urban 0.28.0 → 0.30.0

package/src/toolkit/derivers/api.ts

@@ -0,0 +1,255 @@
+// 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
+// `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.
+
+import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { GENERATED_DIR } from "../artifact.ts";
+import {
+  collectOperations,
+  isObjectSchema,
+  type OpenApiDoc,
+  type OpenApiSchema,
+  type OperationInfo,
+  refName,
+} from "../../openapi/spec.ts";
+
+/** Filenames of the emitted artifacts (siblings of worker-io.d.ts in nano-generated/). */
+export const API_BINDINGS_DTS = "api-io.d.ts";
+export const API_BINDINGS_TS = "operations.ts";
+
+/** A TS identifier form of an operationId (used for the per-op type names). */
+function typeStem(operationId: string): string {
+  const cleaned = operationId.replace(/[^A-Za-z0-9]+/g, " ").trim();
+  const pascal = cleaned
+    .split(/\s+/)
+    .map((w) => (w.length > 0 ? w[0].toUpperCase() + w.slice(1) : ""))
+    .join("");
+  return /^[A-Za-z_]/.test(pascal) ? pascal : `Op${pascal}`;
+}
+
+/** Render a JSON-Schema (OpenAPI subset) as a TS type expression. Local component `$ref`s render as
+ *  their component name (emitted as named interfaces); unknown shapes fall back to `unknown`. */
+export function schemaToTs(schema: OpenApiSchema | undefined, depth = 0): string {
+  if (!schema || depth > 20) return "unknown";
+  if (schema.$ref) {
+    const name = refName(schema.$ref);
+    return name ? typeStem(name) : "unknown";
+  }
+  const nullable = schema.nullable === true;
+  const wrap = (t: string) => (nullable ? `${t} | null` : t);
+
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    return wrap(schema.enum.map((v) => JSON.stringify(v)).join(" | "));
+  }
+  if (schema.const !== undefined) return wrap(JSON.stringify(schema.const));
+
+  if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) {
+    return wrap(schema.oneOf.map((s) => schemaToTs(s, depth + 1)).join(" | "));
+  }
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+    return wrap(schema.anyOf.map((s) => schemaToTs(s, depth + 1)).join(" | "));
+  }
+  if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+    return wrap(schema.allOf.map((s) => schemaToTs(s, depth + 1)).join(" & "));
+  }
+
+  switch (schema.type) {
+    case "string":
+      return wrap("string");
+    case "integer":
+    case "number":
+      return wrap("number");
+    case "boolean":
+      return wrap("boolean");
+    case "null":
+      return "null";
+    case "array":
+      return wrap(`Array<${schemaToTs(schema.items, depth + 1)}>`);
+    case "object":
+      return wrap(objectToTs(schema, depth));
+    default:
+      // No `type`: infer object-ness from object-only keywords (shared with the runtime
+      // validator via isObjectSchema so types and validation agree); otherwise unknown.
+      if (isObjectSchema(schema)) return wrap(objectToTs(schema, depth));
+      return "unknown";
+  }
+}
+
+function objectToTs(schema: OpenApiSchema, depth: number): string {
+  const props = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  const entries = Object.entries(props).map(([key, ps]) => {
+    const opt = required.has(key) ? "" : "?";
+    const doc = typeof ps.description === "string" ? ps.description.replace(/\*\//g, "*\\/") : undefined;
+    const jsdoc = doc ? `/** ${doc} */ ` : "";
+    return `${jsdoc}${JSON.stringify(key)}${opt}: ${schemaToTs(ps, depth + 1)}`;
+  });
+  const extra = schema.additionalProperties;
+  if (extra && typeof extra === "object") {
+    // TS requires every named property type to be assignable to the index signature. When the
+    // schema also declares properties, a narrow index type (e.g. `number`) would make the emitted
+    // type invalid (TS2411), so fall back to `unknown`; with no declared properties we can use the
+    // precise additionalProperties type (the common "map" case).
+    const hasProps = Object.keys(props).length > 0;
+    entries.push(`[key: string]: ${hasProps ? "unknown" : schemaToTs(extra, depth + 1)}`);
+  } else if (extra !== false) {
+    // OpenAPI/JSON-Schema default: additional properties are allowed. Emit an index
+    // signature so the emitted type isn't stricter than the runtime validator, which only
+    // rejects extras when additionalProperties === false (otherwise excess-property errors
+    // on object literals would reject bodies the runtime accepts).
+    entries.push("[key: string]: unknown");
+  }
+  if (entries.length > 0) return `{ ${entries.join("; ")} }`;
+  // No declared properties and additionalProperties: false → a closed, empty object.
+  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 {
+  const ps = op.parameters.filter((p) => p.in === where);
+  if (ps.length === 0) return "{}";
+  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";
+    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 {
+  const ops = collectOperations(doc);
+  const components = doc.components?.schemas ?? {};
+
+  // Fail-closed on TypeScript name collisions: typeStem is lossy (non-alphanumerics collapse), so
+  // distinct component/operation names ("get-invoice" vs "get_invoice") can map to the same TS
+  // identifier and emit duplicate declarations that break typechecking. Surface it here (where
+  // `urban gen`/`urban check` reports it) rather than shipping broken generated types.
+  const emittedTypeNames = new Map<string, string>();
+  const claimTypeName = (typeName: string, source: string): void => {
+    const prior = emittedTypeNames.get(typeName);
+    if (prior !== undefined) {
+      throw new Error(
+        `OpenAPI spec produces a duplicate TypeScript type "${typeName}" from ${prior} and ${source} ` +
+          `— their names collapse to the same identifier; rename one to disambiguate (ADR 0058).`,
+      );
+    }
+    emittedTypeNames.set(typeName, source);
+  };
+  for (const name of Object.keys(components)) {
+    claimTypeName(typeStem(name), `component schema "${name}"`);
+  }
+  for (const op of ops) {
+    claimTypeName(`${typeStem(op.operationId)}Request`, `operationId "${op.operationId}"`);
+    claimTypeName(`${typeStem(op.operationId)}Response`, `operationId "${op.operationId}"`);
+  }
+
+  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 spec; erased to plain JS at compile.\n" +
+    "// eslint-disable\n\n";
+
+  const componentDecls = Object.entries(components)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([name, schema]) => `export type ${typeStem(name)} = ${schemaToTs(schema)};`)
+    .join("\n");
+
+  const opDecls = ops
+    .map((op) => {
+      const stem = typeStem(op.operationId);
+      // 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";
+      // 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";
+      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` +
+        `  body${bodyOpt}: ${bodyType};\n` +
+        `}\n` +
+        `export type ${stem}Response = ${resp};`
+      );
+    })
+    .join("\n\n");
+
+  const idUnion = ops.length > 0
+    ? ops.map((o) => JSON.stringify(o.operationId)).join(" | ")
+    : "never";
+
+  const mapEntries = ops
+    .map((op) => {
+      const stem = typeStem(op.operationId);
+      return `  ${JSON.stringify(op.operationId)}: { request: ${stem}Request; response: ${stem}Response };`;
+    })
+    .join("\n");
+
+  return (
+    header +
+    (componentDecls ? `${componentDecls}\n\n` : "") +
+    (opDecls ? `${opDecls}\n\n` : "") +
+    `/** Every declared operationId (ADR 0058): the delegate key set. */\n` +
+    `export type ApiOperationId = ${idUnion};\n\n` +
+    `/** Request/response contract per operationId. */\n` +
+    `export interface ApiOperations {\n${mapEntries}\n}\n`
+  );
+}
+
+/** Emit `operations.ts`: the typed `defineOperation` wrapper, keyed by operationId (mirrors the
+ *  generated typed `defineWorker`). Written verbatim (it never changes with the spec) — it only
+ *  re-types the runtime's `defineOperation`. */
+export function emitApiBindingsRuntime(): string {
+  return (
+    "// AUTO-GENERATED by @nanobpm/urban (ADR 0058): the typed `defineOperation`.\n" +
+    "// Re-exports the operation SDK and overrides `defineOperation` with an operationId-keyed\n" +
+    "// signature (the delegate's validated request + result typed from the spec). Erased to a\n" +
+    "// pass-through at runtime. Do not edit.\n" +
+    "// eslint-disable\n\n" +
+    `import { defineOperation as defineOperationRaw } from "@nanobpm/urban";\n` +
+    `import type { OperationHandler } from "@nanobpm/urban";\n` +
+    `import type { ApiOperationId, ApiOperations } from "./${API_BINDINGS_DTS}";\n\n` +
+    `type ReqFor<K extends ApiOperationId> = ApiOperations[K]["request"];\n` +
+    `type ResFor<K extends ApiOperationId> = ApiOperations[K]["response"];\n\n` +
+    `/**\n` +
+    ` * Typed \`defineOperation\`: \`id\` is constrained to the spec's declared operationIds\n` +
+    ` * (ADR 0058) so it autocompletes and rejects unknown ops, and the handler's request\n` +
+    ` * (validated params/query/body) + result are typed from the operation's schemas.\n` +
+    ` */\n` +
+    `export function defineOperation<K extends ApiOperationId>(\n` +
+    `  id: K,\n` +
+    `  handler: OperationHandler<ReqFor<K>, ResFor<K>>,\n` +
+    `): OperationHandler<ReqFor<K>, ResFor<K>> {\n` +
+    `  return defineOperationRaw(id, handler);\n` +
+    `}\n`
+  );
+}
+
+/** Derive the api artifacts from a parsed OpenAPI document. */
+export function deriveApi(doc: OpenApiDoc): DerivedArtifact[] {
+  return [
+    { path: `${GENERATED_DIR}/${API_BINDINGS_DTS}`, content: emitApiBindings(doc) },
+    { path: `${GENERATED_DIR}/${API_BINDINGS_TS}`, content: emitApiBindingsRuntime() },
+  ];
+}
+
+export const apiDeriver: Deriver<{ doc: OpenApiDoc }> = {
+  id: "openapi->api-io",
+  describe: "Derive api-io.d.ts (typed request/response per operationId) + the typed defineOperation.",
+  derive: ({ doc }) => deriveApi(doc),
+};

package/src/toolkit/gen.test.ts

@@ -165,3 +165,42 @@ test("the sweep never touches an authored (un-stamped) .bpmn", async () => {
   await runGen({ root: "/cf", io });
   assert.ok(io.files["/cf/processes/authored.bpmn"], "authored .bpmn must survive the sweep");
 });
+
+test("collectArtifacts trims api.spec whitespace so gen matches the runtime (no gen/runtime drift)", async () => {
+  const manifest = JSON.stringify({ id: "demo", data: { default: "app" }, api: { spec: "  openapi.json  " } });
+  const openapi = JSON.stringify({
+    openapi: "3.0.0",
+    paths: { "/ping": { get: { operationId: "ping", responses: { "200": {} } } } },
+  });
+  const io = memIO({ "/app/nano.app.json": manifest, "/app/openapi.json": openapi });
+  const res = await collectArtifacts({ root: "/app", io });
+  const paths = res.map((a) => a.path);
+  // The whitespace-padded spec path still resolved and derived the endpoint contracts.
+  assert.ok(paths.includes("nano-generated/api-io.d.ts"));
+});
+
+test("collectArtifacts resolves an api.spec with Windows-style separators (no gen/runtime drift)", async () => {
+  const manifest = JSON.stringify({ id: "demo", data: { default: "app" }, api: { spec: "specs\\openapi.json" } });
+  const openapi = JSON.stringify({
+    openapi: "3.0.0",
+    paths: { "/ping": { get: { operationId: "ping", responses: { "200": {} } } } },
+  });
+  const io = memIO({ "/app/nano.app.json": manifest, "/app/specs/openapi.json": openapi });
+  const res = await collectArtifacts({ root: "/app", io });
+  assert.ok(res.map((a) => a.path).includes("nano-generated/api-io.d.ts"));
+});
+
+test("collectArtifacts resolves an ABSOLUTE api.spec at its own path, not root-relative (no gen/runtime drift)", async () => {
+  // An absolute manifest spec path must resolve to itself — mirroring the runtime's resolveAppPath
+  // — not be stripped to a root-relative "/app/abs/openapi.json". Otherwise gen would read/derive a
+  // different file than the runtime dispatches against.
+  const manifest = JSON.stringify({ id: "demo", data: { default: "app" }, api: { spec: "/abs/openapi.json" } });
+  const openapi = JSON.stringify({
+    openapi: "3.0.0",
+    paths: { "/ping": { get: { operationId: "ping", responses: { "200": {} } } } },
+  });
+  // Only the absolute location holds the spec; a root-relative read would ENOENT.
+  const io = memIO({ "/app/nano.app.json": manifest, "/abs/openapi.json": openapi });
+  const res = await collectArtifacts({ root: "/app", io });
+  assert.ok(res.map((a) => a.path).includes("nano-generated/api-io.d.ts"));
+});

package/src/toolkit/gen.ts

@@ -4,12 +4,14 @@
 // 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 { sortArtifacts } from "./artifact.ts";
+import { isAbsolutePath, 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";
 import { deriveMeta } from "./derivers/meta.ts";
 import { deriveMessageBindings } from "./derivers/messages.ts";
+import { deriveApi } from "./derivers/api.ts";
+import { parseSpec } from "../openapi/spec.ts";
 import { deriveModels, type DerivedModels, type ModelError, MODEL_PROVENANCE } from "./models.ts";
 
 /** Minimal filesystem port. Node/Deno impls live in `fsio.ts`. */
@@ -56,9 +58,17 @@ export interface GenResult {
 }
 
 function join(root: string, rel: string): string {
-  // Trim either separator so callers may pass Windows-style paths; GenIO
-  // implementations accept forward slashes on all platforms.
-  return `${root.replace(/[/\\]+$/, "")}/${rel.replace(/^[/\\]+/, "")}`;
+  // Normalize Windows-style separators to forward slashes (GenIO uses forward slashes on all
+  // platforms — matching the runtime's resolveAppPath) and trim edge separators, so callers may
+  // pass either style without gen/runtime drift over where a file resolves.
+  const norm = (s: string): string => s.replace(/\\/g, "/");
+  // An absolute `rel` resolves to itself — never prefixed with `root` — mirroring the runtime's
+  // resolveAppPath (isAbsolutePath is the shared SoT in artifact.ts). Without this an absolute
+  // manifest path (e.g. "/abs/openapi.json") would be stripped to root-relative and gen would
+  // read/derive a different file than the runtime resolves. Trailing edge separators are still
+  // trimmed for stable, comparable artifact keys.
+  if (isAbsolutePath(rel)) return norm(rel).replace(/\/+$/, "");
+  return `${norm(root).replace(/\/+$/, "")}/${norm(rel).replace(/^\/+/, "")}`;
 }
 
 function dirOf(p: string): string {
@@ -112,6 +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 };
   } = JSON.parse(await io.readText(manifestPath));
 
   const artifacts: DerivedArtifact[] = [];
@@ -142,6 +153,15 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
     }
   }
 
+  // 4. OpenAPI `api` binding → typed endpoint contracts (ADR 0058). Fail-closed: a declared spec
+  //    that is missing or malformed throws here so `urban gen`/`urban check` surfaces it. Trim the
+  //    spec path so benign whitespace matches the runtime's readApiBinding (no gen/runtime drift).
+  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)));
+  }
+
   return { artifacts: sortArtifacts(artifacts), derived };
 }
 

package/src/toolkit/index.ts

@@ -98,13 +98,53 @@ export {
 } 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";
+
+// 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.ts";
+export type {
+  HttpMethodLower,
+  OpenApiDoc,
+  OpenApiParameter,
+  OpenApiSchema,
+  OperationInfo,
+} from "../openapi/spec.ts";
+
 // The registry of all derivers (for discovery / IDE migration).
 import { migrationsDeriver } from "./derivers/migrations.ts";
 import { domainDeriver } from "./derivers/domain.ts";
 import { workerIoDeriver } from "./derivers/worker-io.ts";
 import { metaDeriver } from "./derivers/meta.ts";
 import { messagesDeriver } from "./derivers/messages.ts";
-export const DERIVERS = [migrationsDeriver, domainDeriver, workerIoDeriver, metaDeriver, messagesDeriver] as const;
+import { apiDeriver } from "./derivers/api.ts";
+export const DERIVERS = [
+  migrationsDeriver,
+  domainDeriver,
+  workerIoDeriver,
+  metaDeriver,
+  messagesDeriver,
+  apiDeriver,
+] as const;
 
 // Gen orchestrator + IO
 export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.ts";