@nanobpm/urban 0.29.0 → 0.30.0

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";