@nanobpm/urban 0.1.0 → 0.3.0

package/src/toolkit/derivers/worker-io.test.ts

@@ -0,0 +1,75 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  deriveWorkerBindings,
+  emitWorkerBindings,
+  scanModelWorkers,
+  type WorkerIo,
+} from "./worker-io.ts";
+
+const XML = `<?xml version="1.0"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+                  xmlns:zeebe="http://camunda.org/schema/zeebe/1.0">
+  <bpmn:process id="orders">
+    <bpmn:serviceTask id="Charge" name="Charge card">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="orders.charge" />
+        <zeebe:ioMapping>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="Payment" />
+          <zeebe:property name="io.nanobpm.dataEnvelope.out" value="Receipt" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="Notify">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="orders.notify" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+  </bpmn:process>
+</bpmn:definitions>`;
+
+test("scanModelWorkers extracts task type, element id, process, and envelope io", () => {
+  const w = scanModelWorkers(XML);
+  const charge = w.find((x) => x.taskType === "orders.charge") as WorkerIo;
+  assert.ok(charge);
+  assert.equal(charge.elementId, "Charge");
+  assert.equal(charge.process, "orders");
+  assert.equal(charge.in, "Payment");
+  assert.equal(charge.out, "Receipt");
+  const notify = w.find((x) => x.taskType === "orders.notify") as WorkerIo;
+  assert.equal(notify.in, undefined);
+  assert.equal(notify.out, undefined);
+});
+
+test("emitWorkerBindings matches the console format (union + DomainTypes refs)", () => {
+  const out = emitWorkerBindings(
+    [{ taskType: "orders.charge", inputType: "Payment", outputType: "Receipt" }],
+    ["Payment", "Receipt"],
+  );
+  assert.match(out, /AUTO-GENERATED by nanobpmn from the App manifest \(ADR 0033 §3\)/);
+  assert.match(out, /import type \{ DomainTypes \} from ".\/domain-rows.d.ts";/);
+  assert.match(out, /export type WorkerTaskType = "orders.charge";/);
+  assert.match(out, /export interface WorkerInputs \{\n {2}"orders.charge": DomainTypes\["Payment"\];\n\}/);
+  assert.match(out, /export interface WorkerOutputs \{\n {2}"orders.charge": DomainTypes\["Receipt"\];\n\}/);
+});
+
+test("emitWorkerBindings falls back to string union + no import when nothing is declared", () => {
+  const out = emitWorkerBindings([{ taskType: "orders.notify" }], []);
+  assert.match(out, /export type WorkerTaskType = "orders.notify";/);
+  assert.doesNotMatch(out, /import type \{ DomainTypes \}/);
+  assert.match(out, /export interface WorkerInputs \{\}/);
+});
+
+test("deriveWorkerBindings is deterministic and emits worker-io.d.ts", () => {
+  const models = [{ path: "processes/orders.bpmn", xml: XML }];
+  const a1 = deriveWorkerBindings(models, ["Payment", "Receipt"]);
+  const a2 = deriveWorkerBindings(models, ["Payment", "Receipt"]);
+  assert.deepEqual(a1, a2);
+  assert.equal(a1[0].path, "nano-generated/worker-io.d.ts");
+  assert.match(a1[0].content, /"orders.charge": DomainTypes\["Payment"\]/);
+});
+
+test("a service task without a task definition is ignored", () => {
+  const xml = `<bpmn:process id="p"><bpmn:serviceTask id="X"></bpmn:serviceTask></bpmn:process>`;
+  assert.deepEqual(scanModelWorkers(xml), []);
+});

package/src/toolkit/derivers/worker-io.ts

@@ -0,0 +1,176 @@
+// Deriver: BPMN models → `worker-io.d.ts`, the worker type map (ADR 0033 §3). Scans each
+// process for service tasks and extracts the Zeebe task type plus the data-envelope in/out
+// contract (io.nanobpm.dataEnvelope.in / .out, carried as zeebe:property). It emits the SAME
+// `worker-io.d.ts` the console generates (a faithful port of `emitWorkerBindings` in the
+// server's domain_types.ts), so the toolkit is a drop-in for the IDE's codegen (ADR 0053).
+
+import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { GENERATED_DIR } from "../artifact.ts";
+
+export interface ModelSource {
+  /** Path (used only for diagnostics/ordering). */
+  path: string;
+  xml: string;
+}
+
+export interface WorkerIo {
+  taskType: string;
+  elementId?: string;
+  process?: string;
+  /** Data-envelope input type id (io.nanobpm.dataEnvelope.in). */
+  in?: string;
+  /** Data-envelope output type id (io.nanobpm.dataEnvelope.out). */
+  out?: string;
+}
+
+/** Filename the console uses; kept identical so the artifact is a drop-in. */
+export const WORKER_BINDINGS_DTS = "worker-io.d.ts";
+/** The domain type declarations `worker-io.d.ts` imports from (console: domain-rows.d.ts). */
+export const DOMAIN_DTS = "domain-rows.d.ts";
+
+const ENVELOPE_IN = "io.nanobpm.dataEnvelope.in";
+const ENVELOPE_OUT = "io.nanobpm.dataEnvelope.out";
+
+function attr(tag: string, name: string): string | undefined {
+  const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+  return m ? m[1] : undefined;
+}
+
+function processId(xml: string): string | undefined {
+  const m = xml.match(/<bpmn:process\b[^>]*>/);
+  return m ? attr(m[0], "id") : undefined;
+}
+
+/** Scan one BPMN document for service-task worker I/O. */
+export function scanModelWorkers(xml: string): WorkerIo[] {
+  const proc = processId(xml);
+  const out: WorkerIo[] = [];
+  const blockRe = /<bpmn:serviceTask\b([^>]*)>([\s\S]*?)<\/bpmn:serviceTask>/g;
+  let m: RegExpExecArray | null;
+  while ((m = blockRe.exec(xml)) !== null) {
+    const openAttrs = m[1];
+    const body = m[2];
+    const elementId = attr(`<x ${openAttrs}>`, "id");
+    const tdMatch = body.match(/<zeebe:taskDefinition\b[^>]*>/);
+    if (!tdMatch) continue;
+    const taskType = attr(tdMatch[0], "type");
+    if (!taskType) continue;
+
+    const io: WorkerIo = { taskType, elementId, process: proc };
+    const propRe = /<zeebe:property\b[^>]*>/g;
+    let p: RegExpExecArray | null;
+    while ((p = propRe.exec(body)) !== null) {
+      const pname = attr(p[0], "name");
+      const pvalue = attr(p[0], "value");
+      if (pname === ENVELOPE_IN && pvalue) io.in = pvalue;
+      else if (pname === ENVELOPE_OUT && pvalue) io.out = pvalue;
+    }
+    out.push(io);
+  }
+  return out;
+}
+
+// --- Faithful port of the console's emitWorkerBindings (domain_types.ts) so the emitted
+//     worker-io.d.ts is byte-compatible with the IDE's own codegen. ---
+
+function typeRefFor(id: string | undefined, declared: Set<string>): string | undefined {
+  return id != null && declared.has(id) ? `DomainTypes[${JSON.stringify(id)}]` : undefined;
+}
+
+export interface WorkerBindingDecl {
+  taskType?: string;
+  inputType?: string;
+  outputType?: string;
+}
+
+/** Emit `worker-io.d.ts` from worker bindings + the set of declared domain type ids. */
+export function emitWorkerBindings(
+  workers: WorkerBindingDecl[],
+  declaredTypeIds: Iterable<string>,
+): string {
+  const declared = new Set(declaredTypeIds);
+  const propKey = (t: string) => JSON.stringify(t);
+  const taskTypes = [
+    ...new Set(
+      workers
+        .map((w) => w?.taskType)
+        .filter((t): t is string => typeof t === "string" && t.length > 0),
+    ),
+  ];
+  const taskTypeUnion = taskTypes.length > 0
+    ? taskTypes.map((t) => JSON.stringify(t)).join(" | ")
+    : "string";
+  const inputs: string[] = [];
+  const outputs: string[] = [];
+  for (const w of workers) {
+    if (typeof w?.taskType !== "string" || w.taskType.length === 0) continue;
+    const inRef = typeRefFor(w.inputType, declared);
+    if (inRef) inputs.push(`  ${propKey(w.taskType)}: ${inRef};`);
+    const outRef = typeRefFor(w.outputType, declared);
+    if (outRef) outputs.push(`  ${propKey(w.taskType)}: ${outRef};`);
+  }
+
+  const header =
+    "// AUTO-GENERATED by nanobpmn from the App manifest (ADR 0033 §3).\n" +
+    "// The bridge from the process model to the worker type system: each declared\n" +
+    "// worker's `taskType` maps to the TS type of its input payload (`job.variables`)\n" +
+    "// and result, so the typed `defineWorker` types a handler by its job type. Do\n" +
+    "// not edit — regenerated from the manifest. Erased to plain JS at compile.\n" +
+    "// eslint-disable\n";
+
+  const needsRegistry = inputs.length > 0 || outputs.length > 0;
+  const importTypes = needsRegistry
+    ? `import type { DomainTypes } from "./${DOMAIN_DTS}";\n`
+    : "";
+
+  const inputsIface = inputs.length > 0
+    ? `export interface WorkerInputs {\n${inputs.join("\n")}\n}\n`
+    : `export interface WorkerInputs {}\n`;
+  const outputsIface = outputs.length > 0
+    ? `export interface WorkerOutputs {\n${outputs.join("\n")}\n}\n`
+    : `export interface WorkerOutputs {}\n`;
+  const headersIface = `export interface WorkerHeaders {}\n`;
+
+  return `${header}\n` +
+    importTypes +
+    `\n/** Untyped fallback for a job whose worker declares no input/output type. */\n` +
+    `export type WorkerVars = Record<string, unknown>;\n\n` +
+    `/** Untyped fallback for a job whose worker declares no custom headers. */\n` +
+    `export type WorkerHdrs = Record<string, unknown>;\n\n` +
+    `/** Every declared worker \`taskType\` (ADR 0033 §3): the model-derived set the\n` +
+    ` * typed \`defineWorker\` accepts, so \`type\` autocompletes and rejects unknown jobs. */\n` +
+    `export type WorkerTaskType = ${taskTypeUnion};\n\n` +
+    `/** Input payload (\`job.variables\`) per declared worker, keyed by \`taskType\`. */\n` +
+    inputsIface +
+    `\n/** Output payload (worker result) per declared worker, keyed by \`taskType\`. */\n` +
+    outputsIface +
+    `\n/** Custom headers (\`job.customHeaders\`) per declared worker, keyed by \`taskType\`.\n` +
+    ` * Header values are strings on the wire, so each declared key maps to \`string\`;\n` +
+    ` * the extra index signature keeps undeclared headers accessible (non-breaking). */\n` +
+    headersIface;
+}
+
+/**
+ * Derive `nano-generated/worker-io.d.ts` from BPMN models. `declaredTypeIds` is the set of
+ * domain type ids declared in the manifest `types` — an envelope in/out only becomes a typed
+ * ref when it names a declared type (matches the console's typeRefFor).
+ */
+export function deriveWorkerBindings(
+  models: ModelSource[],
+  declaredTypeIds: Iterable<string> = [],
+): DerivedArtifact[] {
+  const workers: WorkerBindingDecl[] = [];
+  for (const model of [...models].sort((a, b) => (a.path < b.path ? -1 : 1))) {
+    for (const w of scanModelWorkers(model.xml)) {
+      workers.push({ taskType: w.taskType, inputType: w.in, outputType: w.out });
+    }
+  }
+  const content = emitWorkerBindings(workers, declaredTypeIds);
+  return [{ path: `${GENERATED_DIR}/${WORKER_BINDINGS_DTS}`, content }];
+}
+
+export const workerIoDeriver: Deriver<{ models: ModelSource[]; declaredTypeIds: Iterable<string> }> = {
+  id: "model->worker-io",
+  describe: "Derive worker-io.d.ts (task type + data-envelope in/out) from BPMN models.",
+  derive: ({ models, declaredTypeIds }) => deriveWorkerBindings(models, declaredTypeIds),
+};

package/src/toolkit/fsio.test.ts

@@ -0,0 +1,21 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeGenIO } from "./fsio.ts";
+
+test("listDir returns file names only, excluding subdirectories", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "urban-fsio-"));
+  await writeFile(join(dir, "a.bpmn"), "<definitions/>");
+  await writeFile(join(dir, "b.txt"), "x");
+  await mkdir(join(dir, "nested"));
+  const io = createNodeGenIO();
+  const names = (await io.listDir(dir)).sort();
+  assert.deepEqual(names, ["a.bpmn", "b.txt"]);
+});
+
+test("listDir returns empty for a missing directory", async () => {
+  const io = createNodeGenIO();
+  assert.deepEqual(await io.listDir(join(tmpdir(), "urban-fsio-does-not-exist-xyz")), []);
+});

package/src/toolkit/fsio.ts

@@ -0,0 +1,36 @@
+// Node/Deno filesystem implementation of the GenIO port. Uses node:fs/promises, which both
+// Node and Deno provide, so a single implementation serves both runtimes.
+
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { GenIO } from "./gen.ts";
+
+export function createNodeGenIO(): GenIO {
+  return {
+    async readText(path: string): Promise<string> {
+      return readFile(path, "utf8");
+    },
+    async writeText(path: string, content: string): Promise<void> {
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, content);
+    },
+    async listDir(path: string): Promise<string[]> {
+      try {
+        // The GenIO contract is file names only — exclude subdirectories so
+        // pattern expansion never hands a directory to readText()/JSON.parse.
+        const entries = await readdir(path, { withFileTypes: true });
+        return entries.filter((e) => e.isFile()).map((e) => e.name);
+      } catch {
+        return [];
+      }
+    },
+    async exists(path: string): Promise<boolean> {
+      try {
+        await stat(path);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/src/toolkit/gen.test.ts

@@ -0,0 +1,85 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { runGen, collectArtifacts, type GenIO } from "./gen.ts";
+
+/** In-memory filesystem for deterministic, IO-free gen tests. */
+function memIO(files: Record<string, string>): GenIO & { files: Record<string, string> } {
+  return {
+    files,
+    async readText(p) {
+      if (!(p in files)) throw new Error(`ENOENT ${p}`);
+      return files[p];
+    },
+    async writeText(p, c) {
+      files[p] = c;
+    },
+    async listDir(p) {
+      const prefix = p.replace(/\/+$/, "") + "/";
+      const names = new Set<string>();
+      for (const f of Object.keys(files)) {
+        if (f.startsWith(prefix)) {
+          const rest = f.slice(prefix.length);
+          if (!rest.includes("/")) names.add(rest);
+        }
+      }
+      return [...names];
+    },
+    async exists(p) {
+      return p in files;
+    },
+  };
+}
+
+const MANIFEST = JSON.stringify({
+  id: "demo",
+  data: { default: "app" },
+  models: { processes: ["processes/*.bpmn"] },
+  types: { greeting: { table: "greetings", fields: { who: { type: "string" } } } },
+});
+
+const BPMN = `<bpmn:process id="p" xmlns:bpmn="x" xmlns:zeebe="y">
+  <bpmn:serviceTask id="T"><bpmn:extensionElements>
+    <zeebe:taskDefinition type="demo.do" />
+  </bpmn:extensionElements></bpmn:serviceTask>
+</bpmn:process>`;
+
+function fixture(): Record<string, string> {
+  return {
+    "/app/nano.app.json": MANIFEST,
+    "/app/processes/p.bpmn": BPMN,
+  };
+}
+
+test("runGen writes migrations and the worker index", async () => {
+  const io = memIO(fixture());
+  const res = await runGen({ root: "/app", io });
+  const paths = res.artifacts.map((a) => a.path).sort();
+  assert.deepEqual(paths, [
+    "nano-generated/app.schema.sql",
+    "nano-generated/worker-io.d.ts",
+  ]);
+  assert.ok(io.files["/app/nano-generated/app.schema.sql"].includes("CREATE TABLE"));
+  assert.ok(io.files["/app/nano-generated/worker-io.d.ts"].includes("demo.do"));
+});
+
+test("gen --check reports no drift right after a write", async () => {
+  const io = memIO(fixture());
+  await runGen({ root: "/app", io });
+  const res = await runGen({ root: "/app", io, check: true });
+  assert.deepEqual(res.drift, []);
+});
+
+test("gen --check detects drift when a generated file is stale", async () => {
+  const io = memIO(fixture());
+  await runGen({ root: "/app", io });
+  io.files["/app/nano-generated/worker-io.d.ts"] = "// stale";
+  const res = await runGen({ root: "/app", io, check: true });
+  assert.deepEqual(res.drift, ["nano-generated/worker-io.d.ts"]);
+});
+
+test("collectArtifacts touches no writes", async () => {
+  const io = memIO(fixture());
+  const before = Object.keys(io.files).length;
+  await collectArtifacts({ root: "/app", io });
+  assert.equal(Object.keys(io.files).length, before);
+});

package/src/toolkit/gen.ts

@@ -0,0 +1,109 @@
+// The gen orchestrator: the one impure edge of the toolkit. It reads an app's manifest and
+// models, runs the pure derivers, and either writes the artifacts to disk (`urban gen`) or
+// compares them against what's on disk and reports drift (`urban gen --check`). The derivers stay
+// 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 { deriveMigrations, type ToolkitManifest } from "./derivers/migrations.ts";
+import { deriveWorkerBindings, type ModelSource } from "./derivers/worker-io.ts";
+
+/** Minimal filesystem port. Node/Deno impls live in `fsio.ts`. */
+export interface GenIO {
+  readText(path: string): Promise<string>;
+  writeText(path: string, content: string): Promise<void>;
+  /** File names (not paths) in a directory; empty if it does not exist. */
+  listDir(path: string): Promise<string[]>;
+  exists(path: string): Promise<boolean>;
+}
+
+export interface GenOptions {
+  root: string;
+  io: GenIO;
+  manifestFile?: string;
+}
+
+export interface GenResult {
+  artifacts: DerivedArtifact[];
+  /** Paths that differ from disk (only populated by `check`). */
+  drift: string[];
+}
+
+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(/^[/\\]+/, "")}`;
+}
+
+function dirOf(p: string): string {
+  const i = p.lastIndexOf("/");
+  return i <= 0 ? "." : p.slice(0, i);
+}
+
+/** Resolve a `dir/*.ext` (or literal) manifest pattern to file paths relative to root. */
+async function expandPattern(root: string, io: GenIO, pattern: string): Promise<string[]> {
+  const star = pattern.indexOf("*");
+  if (star === -1) {
+    return (await io.exists(join(root, pattern))) ? [pattern] : [];
+  }
+  const slash = pattern.lastIndexOf("/", star);
+  const dir = slash === -1 ? "." : pattern.slice(0, slash);
+  const tail = pattern.slice(slash + 1); // e.g. "*.bpmn"
+  const ext = tail.startsWith("*") ? tail.slice(1) : tail;
+  const names = await io.listDir(join(root, dir));
+  return names
+    .filter((n) => n.endsWith(ext))
+    .map((n) => (dir === "." ? n : `${dir}/${n}`))
+    .sort();
+}
+
+/** Collect all artifacts a run would produce, without touching disk beyond reads. */
+export async function collectArtifacts(opts: GenOptions): Promise<DerivedArtifact[]> {
+  const { root, io } = opts;
+  const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
+  const manifest = JSON.parse(await io.readText(manifestPath)) as ToolkitManifest & {
+    models?: { processes?: string[] };
+  };
+
+  const artifacts: DerivedArtifact[] = [];
+
+  // 1. types → migrations
+  if (manifest.types && Object.keys(manifest.types).length > 0) {
+    artifacts.push(...deriveMigrations(manifest));
+  }
+
+  // 2. models → worker I/O index
+  const procPatterns = manifest.models?.processes ?? [];
+  const models: ModelSource[] = [];
+  for (const pat of procPatterns) {
+    for (const rel of await expandPattern(root, io, pat)) {
+      models.push({ path: rel, xml: await io.readText(join(root, rel)) });
+    }
+  }
+  if (models.length > 0) {
+    const declaredTypeIds = Object.keys(manifest.types ?? {});
+    artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
+  }
+
+  return sortArtifacts(artifacts);
+}
+
+/** Run the derivers and write artifacts (or, with `check`, report drift without writing). */
+export async function runGen(opts: GenOptions & { check?: boolean }): Promise<GenResult> {
+  const artifacts = await collectArtifacts(opts);
+  const { root, io } = opts;
+  const drift: string[] = [];
+
+  for (const a of artifacts) {
+    const abs = join(root, a.path);
+    if (opts.check) {
+      const current = (await io.exists(abs)) ? await io.readText(abs) : null;
+      if (current !== a.content) drift.push(a.path);
+    } else {
+      await io.writeText(abs, a.content);
+    }
+  }
+  return { artifacts, drift };
+}
+
+export { dirOf, join as joinPath };

package/src/toolkit/index.ts

@@ -0,0 +1,37 @@
+// The Urban derivation toolkit — the shared derivation library. The IDE and the
+// `urban gen` CLI are peer callers of these pure derivers (ADR 0053). Code-first
+// process authoring is provided by `@nanobpm/workflow` (`defineFlow`), not here
+// (ADR 0054) — the toolkit derives migrations and worker I/O from the model.
+
+// Artifact + deriver contract
+export type { DerivedArtifact, Deriver } from "./artifact.ts";
+export { GENERATED_DIR, sortArtifacts } from "./artifact.ts";
+
+// Derivers
+export {
+  deriveMigrations,
+  migrationsDeriver,
+  sqlType,
+  createTableSql,
+} from "./derivers/migrations.ts";
+export type { ToolkitManifest, ToolkitType, ToolkitField } from "./derivers/migrations.ts";
+
+export {
+  deriveWorkerBindings,
+  emitWorkerBindings,
+  workerIoDeriver,
+  scanModelWorkers,
+  WORKER_BINDINGS_DTS,
+  DOMAIN_DTS,
+} from "./derivers/worker-io.ts";
+export type { ModelSource, WorkerIo, WorkerBindingDecl } from "./derivers/worker-io.ts";
+
+// The registry of all derivers (for discovery / IDE migration).
+import { migrationsDeriver } from "./derivers/migrations.ts";
+import { workerIoDeriver } from "./derivers/worker-io.ts";
+export const DERIVERS = [migrationsDeriver, workerIoDeriver] as const;
+
+// Gen orchestrator + IO
+export { collectArtifacts, runGen, joinPath } from "./gen.ts";
+export type { GenIO, GenOptions, GenResult } from "./gen.ts";
+export { createNodeGenIO } from "./fsio.ts";