@nanobpm/urban 0.18.0 → 0.20.0

package/src/runtime/core/modules/datasource.migrations.test.ts

@@ -0,0 +1,114 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../../adapters/node.ts";
+import { provisionData } from "./datasource.ts";
+import type { RuntimeContext } from "../context.ts";
+import type { EngineClient } from "../host.ts";
+import type { AppManifest } from "../manifest.ts";
+
+// provisionData never touches the engine — a bare stub is enough for these datasource tests.
+const noEngine = {} as EngineClient;
+
+async function fixture(migrations: Record<string, string>): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-mig-"));
+  await mkdir(join(dir, "db", "migrations"), { recursive: true });
+  for (const [name, sql] of Object.entries(migrations)) {
+    await writeFile(join(dir, "db", "migrations", name), sql);
+  }
+  return dir;
+}
+
+function ctx(dir: string): RuntimeContext {
+  const manifest = {
+    schemaVersion: 1,
+    id: "mig-fixture",
+    name: "Migration Fixture",
+    data: {
+      default: "app",
+      sources: { app: { driver: "sqlite", url: "file:./app.db", migrations: "db/migrations" } },
+    },
+  } as unknown as AppManifest;
+  return { manifest, host: createNodeHost({ cwd: dir, log: () => {} }), engine: noEngine, root: "." };
+}
+
+function columns(dir: string, table: string): string[] {
+  const db = createNodeHost({ cwd: dir, log: () => {} }).openSqlite(join(dir, "app.db"));
+  try {
+    return db.all<{ name: string }>(`PRAGMA table_info(${table})`).map((r) => r.name);
+  } finally {
+    db.close();
+  }
+}
+
+function ledger(dir: string): string[] {
+  const db = createNodeHost({ cwd: dir, log: () => {} }).openSqlite(join(dir, "app.db"));
+  try {
+    return db.all<{ name: string }>("SELECT name FROM _urban_migrations ORDER BY name").map((r) => r.name);
+  } finally {
+    db.close();
+  }
+}
+
+test("migrations apply once and are skipped on the next boot (idempotent)", async () => {
+  const dir = await fixture({
+    "001_init.sql": "CREATE TABLE rounds (id INTEGER PRIMARY KEY, summary TEXT);",
+    "002_transcript.sql": "ALTER TABLE rounds ADD COLUMN transcript TEXT;",
+  });
+  try {
+    const first = await provisionData(ctx(dir));
+    assert.deepEqual(first.source("app").migrationsApplied, ["001_init.sql", "002_transcript.sql"]);
+    first.closeAll();
+
+    assert.deepEqual(ledger(dir), ["001_init.sql", "002_transcript.sql"]);
+    assert.ok(columns(dir, "rounds").includes("transcript"));
+
+    // Second boot: everything is already recorded, so nothing re-runs (no "duplicate column").
+    const second = await provisionData(ctx(dir));
+    assert.deepEqual(second.source("app").migrationsApplied, []);
+    second.closeAll();
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("a failing migration rolls back atomically — schema is never left ahead of the ledger", async () => {
+  // Models the real urban-pr-review failure: an interrupted/failing migration must NOT leave a
+  // column present while its `_urban_migrations` row is missing, or every future boot re-applies
+  // it and dies with "duplicate column name". 002 adds `transcript`, then hits an error.
+  const dir = await fixture({
+    "001_init.sql": "CREATE TABLE rounds (id INTEGER PRIMARY KEY, summary TEXT);",
+    "002_transcript.sql":
+      "ALTER TABLE rounds ADD COLUMN transcript TEXT;\nINSERT INTO does_not_exist VALUES (1);",
+  });
+  try {
+    await assert.rejects(
+      provisionData(ctx(dir)),
+      /migration "002_transcript.sql" failed and was rolled back/,
+    );
+
+    // The whole migration rolled back: 001 is applied, but 002 left NO trace.
+    assert.deepEqual(ledger(dir), ["001_init.sql"]);
+    assert.ok(
+      !columns(dir, "rounds").includes("transcript"),
+      "the partially-applied ALTER must have been rolled back",
+    );
+
+    // Repair the migration and re-boot: because the earlier attempt left no partial state,
+    // `transcript` applies cleanly instead of colliding — the poisoned state can never arise.
+    await writeFile(
+      join(dir, "db", "migrations", "002_transcript.sql"),
+      "ALTER TABLE rounds ADD COLUMN transcript TEXT;",
+    );
+    const repaired = await provisionData(ctx(dir));
+    assert.deepEqual(repaired.source("app").migrationsApplied, ["002_transcript.sql"]);
+    repaired.closeAll();
+
+    assert.deepEqual(ledger(dir), ["001_init.sql", "002_transcript.sql"]);
+    assert.ok(columns(dir, "rounds").includes("transcript"));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/core/modules/datasource.ts

@@ -188,11 +188,30 @@ async function applyMigrations(
   for (const file of files) {
     if (applied.has(file)) continue;
     const sql = await host.readTextFile(`${dir}/${file}`);
-    db.exec(sql);
-    db.run("INSERT INTO _urban_migrations (name, applied_at) VALUES (?, ?)", [
-      file,
-      new Date(host.now()).toISOString(),
-    ]);
+    // Apply the migration and record it in the ledger atomically. SQLite DDL is
+    // transactional, so wrapping both in one BEGIN/COMMIT makes a migration all-or-nothing:
+    // either the schema change AND its `_urban_migrations` row commit together, or neither
+    // does. Without this, an interruption (or an error later in the file's SQL) can leave the
+    // schema changed but the migration unrecorded — which poisons every future boot, because
+    // the runner then re-applies the "unapplied" migration and hits e.g. "duplicate column".
+    // Migration files must therefore not contain their own transaction-control statements.
+    db.exec("BEGIN");
+    try {
+      db.exec(sql);
+      db.run("INSERT INTO _urban_migrations (name, applied_at) VALUES (?, ?)", [
+        file,
+        new Date(host.now()).toISOString(),
+      ]);
+      db.exec("COMMIT");
+    } catch (err) {
+      db.exec("ROLLBACK");
+      throw new Error(
+        `migration "${file}" failed and was rolled back (no partial schema change, not recorded as applied): ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+        { cause: err },
+      );
+    }
     newlyApplied.push(file);
   }
   return newlyApplied;

package/src/runtime/core/modules/pages.test.ts

@@ -89,6 +89,19 @@ test("GET /app/runtime.js serves the renderer module", async () => {
   assert.match(res.body ?? "", /pc:refresh/);
 });
 
+test("renderer wires a column's linkField to a new-tab anchor", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A column declaring `linkField` renders its text as a link to that field's
+  // URL, opened safely in a new tab. Guard the whole shape so the feature can't
+  // silently regress: the field is read, http(s) is required, and the anchor
+  // opens in a new tab with a hardened rel.
+  assert.match(js, /col\.linkField/);
+  assert.match(js, /\^https\?:/);
+  assert.match(js, /target: "_blank"/);
+  assert.match(js, /rel: "noopener noreferrer"/);
+});
+
 test("GET /app/pages/<id> returns the page json, 404 for unknown", async () => {
   const ok = await dispatch("GET", "/app/pages/home");
   assert.equal(ok.status, 200);

package/src/runtime/core/modules/pages.ts

@@ -427,6 +427,27 @@ function renderText(node) {
   return el(v === "heading" ? "h1" : "p", { class: cls }, node.props.text || "");
 }
 
+// A grid td cell. When the column declares linkField, the cell text (the
+// column's own value) becomes a link to the URL held in that other field,
+// opened in a new tab. Only http(s) hrefs are linked — anything else (e.g. a
+// javascript: URL smuggled through row data) falls back to plain text — and
+// external links get rel=noopener noreferrer so the opened page can't reach
+// window.opener. Shared by the top-level grid and child grids.
+function gridCell(col, row) {
+  const text = row[col.field] == null ? "" : String(row[col.field]);
+  if (col.linkField) {
+    const href = row[col.linkField] == null ? "" : String(row[col.linkField]);
+    if (text !== "" && /^https?:\/\//i.test(href)) {
+      return el(
+        "td",
+        {},
+        el("a", { class: "pc-link", href, target: "_blank", rel: "noopener noreferrer" }, text),
+      );
+    }
+  }
+  return el("td", {}, text);
+}
+
 function renderActionForm(node) {
   const p = node.props;
   const card = el("section", { class: "pc-card" });
@@ -587,7 +608,7 @@ function renderDataGrid(node) {
         cbody.append(el("tr", {}, el("td", { colspan: cspan }, "None")));
       }
       for (const cr of rows) {
-        const cells = ccols.map((c) => el("td", {}, cr[c.field] == null ? "" : String(cr[c.field])));
+        const cells = ccols.map((c) => gridCell(c, cr));
         if (cg.lazyField) {
           const lf = cg.lazyField;
           const has = cr[lf.field] != null && String(cr[lf.field]).trim() !== "";
@@ -641,7 +662,7 @@ function renderDataGrid(node) {
   }
 
   function renderRow(row) {
-    const cells = cols.map((c) => el("td", {}, row[c.field] == null ? "" : String(row[c.field])));
+    const cells = cols.map((c) => gridCell(c, row));
     let toggle = null;
     if (hasExtra) {
       const actionCell = el("td", { class: "pc-row-actions" });

package/src/runtime/core/modules/workers.test.ts

@@ -157,6 +157,19 @@ test("sdkDecisionEvaluator throws a clear error when the SDK lacks evaluateDecis
   await assert.rejects(evaluate("risk", {}), /does not support evaluateDecision.*"risk"/);
 });
 
+test("mountWorkers silently skips a connector-backed worker (mountConnectors owns it)", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: "nano-ide-connector-slack" }] },
+    engine,
+  );
+  const handle = await mountWorkers(ctx, makeApp());
+  assert.deepEqual(handle.jobTypes, []);
+  assert.equal(engine.workers.size, 0);
+  // No spurious "neither a handler nor an llm" warning for a connector worker.
+  assert.ok(!logs.some((l) => l.msg.includes("neither a handler nor an llm")));
+});
+
 // ── AppJobHandler generics: optional In/Out type parameters ──────────────────────────────
 // These are primarily compile-time assertions (the suite is typechecked by `tsc --noEmit`),
 // with a runtime smoke that a typed handler still returns its output when delivered a job.

package/src/runtime/core/modules/workers.ts

@@ -109,6 +109,10 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
   for (const decl of decls as Worker[]) {
     const jobType = workerJobType(decl);
     if (!jobType) continue;
+    // Connector-backed workers (a `connector` field, no handler/llm) are mounted
+    // separately by mountConnectors — skip them here silently so they don't trip
+    // the "neither handler nor llm" warning below on every startup.
+    if (decl.connector) continue;
     if (!decl.handler) {
       // LLM-backed worker (schema `oneOf` handler|llm): synthesise a handler that runs
       // the job through the bound LLM (and optional decision rails) instead of loading a

package/src/runtime/core/runtime.ts

@@ -12,6 +12,7 @@ import { makeRouter, type Route } from "./router.ts";
 import { deployModels } from "./modules/deploy.ts";
 import { provisionData, DataLayer } from "./modules/datasource.ts";
 import { mountWorkers } from "./modules/workers.ts";
+import { mountConnectors } from "./modules/connectors.ts";
 import { mountSurfaces } from "./modules/surfaces.ts";
 import { mountTriggers } from "./modules/triggers.ts";
 import { mountSecurity, type SecurityPolicy } from "./modules/security.ts";
@@ -169,6 +170,11 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           const w = await mountWorkers(ctx, api);
           mounted.push(w);
           describe.workers = w.describe?.();
+          // Connector-pack workers share the `workers` flag: same lifecycle, same
+          // engine, distinguished only by a `connector` field on the declaration.
+          const c = await mountConnectors(ctx, api);
+          mounted.push(c);
+          if (c.jobTypes.length > 0) describe.connectors = c.describe?.();
         }
 
         const routes: Route[] = [];

package/src/runtime/core/validate.test.ts

@@ -72,6 +72,30 @@ test("data.default must reference an existing source", () => {
   assert.ok(issues.some((i) => i.path === "data.default"));
 });
 
+test("a worker connection must reference a declared connections entry", () => {
+  const missing = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "a.b", connector: "slack", connection: "slack" }],
+  });
+  assert.ok(missing.some((i) => i.path === "workers[0].connection"));
+
+  const present = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "a.b", connector: "slack", connection: "slack" }],
+    connections: { slack: { type: "slack" } },
+  });
+  assert.ok(!present.some((i) => i.path === "workers[0].connection"));
+});
+
+test("a non-object connections does not throw and flags the reference", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "a.b", connector: "slack", connection: "slack" }],
+    connections: "nope",
+  });
+  assert.ok(issues.some((i) => i.path === "workers[0].connection"));
+});
+
 test("validateManifest throws ManifestValidationError with issues", () => {
   assert.throws(() => validateManifest({ schemaVersion: 1 }), (e: unknown) => {
     assert.ok(e instanceof ManifestValidationError);

package/src/runtime/core/validate.ts

@@ -76,14 +76,38 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
       if (!workerJobType(w)) {
         issues.push({ path: `workers[${i}]`, message: "missing taskType" });
       }
-      // The schema allows a worker backed by either a `handler` file or an `llm`
-      // binding (oneOf). Require exactly one — don't force `handler`.
-      const hasHandler = typeof w?.handler === "string" && w.handler.length > 0;
-      const hasLlm = typeof w?.llm === "string" && w.llm.length > 0;
-      if (!hasHandler && !hasLlm) {
-        issues.push({ path: `workers[${i}]`, message: "worker requires a `handler` or `llm`" });
-      } else if (hasHandler && hasLlm) {
-        issues.push({ path: `workers[${i}]`, message: "worker declares both `handler` and `llm` (mutually exclusive)" });
+      // A worker is backed by exactly one of: a `handler` file, an `llm` binding,
+      // or an installed `connector` pack (ADR 0050). The schema models these as a
+      // oneOf; enforce the "exactly one" here without forcing `handler`. Whether a
+      // `connector` actually resolves to an installed pack is a runtime seam check
+      // (mountConnectors), not something this static manifest check can see.
+      const backings: string[] = [];
+      if (typeof w?.handler === "string" && w.handler.length > 0) backings.push("handler");
+      if (typeof w?.llm === "string" && w.llm.length > 0) backings.push("llm");
+      if (typeof w?.connector === "string" && w.connector.length > 0) backings.push("connector");
+      if (backings.length === 0) {
+        issues.push({
+          path: `workers[${i}]`,
+          message: "worker requires a `handler`, `llm`, or `connector`",
+        });
+      } else if (backings.length > 1) {
+        issues.push({
+          path: `workers[${i}]`,
+          message: `worker declares ${backings.join(" + ")} (mutually exclusive)`,
+        });
+      }
+      // A `connection` must reference a declared top-level `connections` entry.
+      if (typeof w?.connection === "string" && w.connection.length > 0) {
+        const conns =
+          man.connections && typeof man.connections === "object" && !Array.isArray(man.connections)
+            ? (man.connections as Record<string, unknown>)
+            : undefined;
+        if (!conns || !(w.connection in conns)) {
+          issues.push({
+            path: `workers[${i}].connection`,
+            message: `no such connection "${w.connection}" (add it to connections)`,
+          });
+        }
       }
     });
   }

package/src/runtime/engine/nanosdk.test.ts

@@ -9,6 +9,7 @@ import {
   type NanoSdkJobWorker,
   type NanoSdkJobWorkerConfig,
 } from "./nanosdk.ts";
+import { BpmnError } from "../core/host.ts";
 
 /** A fake nano-sdk client that records calls and lets a test drive its job worker. */
 function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient & {
@@ -266,6 +267,81 @@ test("registerWorker fails the job when the handler throws", async () => {
   assert.equal(failBody?.retries, 0);
 });
 
+test("registerWorker routes a thrown BpmnError to the engine's error()", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("svc", () => {
+    throw new BpmnError("NOT_FOUND", "no such record");
+  });
+  const rec = client.workers[0];
+  let errorBody: { errorCode: string; errorMessage?: string } | undefined;
+  await rec.dispatch({
+    jobKey: "j1",
+    variables: {},
+    async complete() {
+      throw new Error("should not complete");
+    },
+    async fail() {
+      throw new Error("should not fail — a BPMN error is not a job failure");
+    },
+    async error(body: { errorCode: string; errorMessage?: string }) {
+      errorBody = body;
+      return "raised";
+    },
+  } as unknown as NanoSdkActivatedJob);
+  assert.equal(errorBody?.errorCode, "NOT_FOUND");
+  assert.equal(errorBody?.errorMessage, "no such record");
+});
+
+test("registerWorker falls back to fail() for a BpmnError when the SDK has no error()", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("svc", () => {
+    throw new BpmnError("NOT_FOUND", "no such record");
+  });
+  const rec = client.workers[0];
+  let failBody: { errorMessage: string } | undefined;
+  await rec.dispatch({
+    jobKey: "j1",
+    variables: {},
+    async complete() {
+      throw new Error("should not complete");
+    },
+    async fail(body: { errorMessage: string }) {
+      failBody = body;
+      return "failed";
+    },
+    // no error() — older transport
+  } as unknown as NanoSdkActivatedJob);
+  assert.equal(failBody?.errorMessage, "no such record");
+});
+
+test("registerWorker falls back to fail() when the BPMN error report itself throws", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("svc", () => {
+    throw new BpmnError("NOT_FOUND", "no such record");
+  });
+  const rec = client.workers[0];
+  let failBody: { errorMessage: string } | undefined;
+  await rec.dispatch({
+    jobKey: "j1",
+    variables: {},
+    async complete() {
+      throw new Error("should not complete");
+    },
+    async error() {
+      throw new Error("transport down");
+    },
+    async fail(body: { errorMessage: string }) {
+      failBody = body;
+      return "failed";
+    },
+  } as unknown as NanoSdkActivatedJob);
+  // The job must still be acknowledged via fail() rather than silently dropped.
+  assert.equal(failBody?.errorMessage, "no such record");
+});
+
 test("close stops every worker and closes the SDK client", async () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);

package/src/runtime/engine/nanosdk.ts

@@ -17,6 +17,7 @@ import type {
   JobHandler,
   WorkerSubscription,
 } from "../core/host.ts";
+import { isBpmnError } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 
 /** Coerce an engine response's process-instance key to a non-empty string, or
@@ -38,6 +39,10 @@ export interface NanoSdkActivatedJob {
   variables?: Record<string, unknown>;
   complete(variables?: Record<string, unknown>): Promise<unknown>;
   fail(body: { errorMessage: string; retries?: number }): Promise<unknown>;
+  /** Raise a BPMN error (Zeebe `ThrowError`) routed to an error boundary/event.
+   *  Present on the nano-sdk enriched job at runtime; typed here so the adapter
+   *  can honour a handler's {@link BpmnError} (ADR 0050). */
+  error?(e: { errorCode: string; errorMessage?: string }): Promise<unknown>;
 }
 
 /** Config for a nano-sdk job worker (the subset this adapter sets). */
@@ -233,6 +238,31 @@ export class SdkEngineClient implements EngineClient {
           const out = await handler(engineJob);
           return await job.complete((out as Record<string, unknown> | undefined) ?? {});
         } catch (err) {
+          // A handler-raised BPMN error is a modelled, non-retryable outcome:
+          // report it as a BPMN error (routed to an error boundary/event) rather
+          // than a plain failure. If the transport lacks `error` (older SDK) — or
+          // the `error` call itself fails — fall through to the `fail` path below
+          // so the job is still acknowledged rather than left to lock-timeout.
+          if (isBpmnError(err) && typeof job.error === "function") {
+            // `message` is typed loosely (the guard survives module duplication),
+            // so coerce to a string before slicing to avoid a secondary crash.
+            const raw = (err as { message?: unknown }).message;
+            const message = typeof raw === "string" && raw.length > 0 ? raw : err.errorCode;
+            this.log("info", `handler ${jobType} raised BPMN error`, {
+              errorCode: err.errorCode,
+            });
+            try {
+              return await job.error({
+                errorCode: err.errorCode,
+                errorMessage: message.slice(0, 500),
+              });
+            } catch (errReportErr) {
+              this.log("warn", `handler ${jobType}: BPMN error report failed, failing the job`, {
+                err: errReportErr instanceof Error ? errReportErr.message : String(errReportErr),
+              });
+              // fall through to the fail path
+            }
+          }
           const message = err instanceof Error ? err.message : String(err);
           this.log("error", `handler ${jobType} threw`, { err: message });
           try {

package/src/runtime/index.ts

@@ -55,6 +55,18 @@ export type {
 } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 
+// BPMN error contract: a handler throws `BpmnError(code)` to raise a modelled
+// error routed to an error boundary (ADR 0050), instead of a retryable failure.
+export { BpmnError, isBpmnError } from "./core/host.ts";
+
+// Connector packs (ADR 0050, in-process port)
+export {
+  adaptConnectorHandler,
+  mountConnectors,
+  resolveInstalledConnectors,
+} from "./core/modules/connectors.ts";
+export type { ConnectorsHandle } from "./core/modules/connectors.ts";
+
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";