@nanobpm/urban 0.17.1 → 0.19.0

package/src/runtime/adapters/node.ts

@@ -2,10 +2,12 @@
 // (with deno.ts) allowed to touch a concrete runtime.
 
 import { readFile, readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { watch as fsWatch, type FSWatcher } from "node:fs";
 import { createServer } from "node:http";
+import { register } from "node:module";
 import { isAbsolute, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 import type {
   HostContext,
@@ -28,6 +30,57 @@ export interface NodeHostOptions {
   importNonce?: string;
 }
 
+/** Resolve the in-process `@nanobpm/worker` shim URL relative to this adapter,
+ *  tolerating both the compiled package (`.js`, the published/`urban run` path)
+ *  and a from-source run (`.ts`). */
+function connectorShimUrl(): string {
+  const js = new URL("../connector-worker-sdk.js", import.meta.url);
+  if (existsSync(fileURLToPath(js))) return js.href;
+  return new URL("../connector-worker-sdk.ts", import.meta.url).href;
+}
+
+let connectorHooksRegistered = false;
+
+/**
+ * Register (once per process) the ESM customization hooks that let a connector
+ * pack's worker `entry` be imported in-process (ADR 0050, in-process port):
+ *   - a **resolve** hook aliasing the bare `@nanobpm/worker` specifier the pack
+ *     imports to the runtime's shim, so its `defineWorker(...)` registers into the
+ *     registry the runtime drains;
+ *   - a **load** hook that strips TypeScript from ANY `.ts` module resolved under
+ *     `node_modules` (Node refuses to type-strip there by default). In practice
+ *     only a connector pack's `.ts` entry and its `.ts` imports travel this path,
+ *     but the hook is process-global once registered, so it applies to every
+ *     subsequent `node_modules` `.ts` import — a safe superset (Node would
+ *     otherwise throw on such a file). The module's real URL is preserved so its
+ *     own bare imports (npm deps) still resolve.
+ * The hooks run on a separate thread, so the shim URL is baked into the hook
+ * source; the shim itself loads on the main thread (shared registry instance).
+ */
+function ensureConnectorHooks(): void {
+  if (connectorHooksRegistered) return;
+  const shim = JSON.stringify(connectorShimUrl());
+  const src =
+    `import { readFileSync } from "node:fs";\n` +
+    `import { fileURLToPath } from "node:url";\n` +
+    `import { stripTypeScriptTypes } from "node:module";\n` +
+    `const SHIM = ${shim};\n` +
+    `export async function resolve(spec, ctx, next) {\n` +
+    `  if (spec === "@nanobpm/worker") return { url: SHIM, shortCircuit: true };\n` +
+    `  return next(spec, ctx);\n` +
+    `}\n` +
+    `export async function load(url, ctx, next) {\n` +
+    `  const path = url.split("?")[0];\n` +
+    `  if (path.endsWith(".ts") && path.includes("/node_modules/")) {\n` +
+    `    const source = stripTypeScriptTypes(readFileSync(fileURLToPath(path), "utf8"), { mode: "strip" });\n` +
+    `    return { format: "module", source, shortCircuit: true };\n` +
+    `  }\n` +
+    `  return next(url, ctx);\n` +
+    `}\n`;
+  register("data:text/javascript," + encodeURIComponent(src));
+  connectorHooksRegistered = true;
+}
+
 export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
   const cwd = opts.cwd ?? process.cwd();
   const abs = (p: string) => (isAbsolute(p) ? p : resolve(cwd, p));
@@ -69,6 +122,16 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
         pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
       return import(href) as Promise<Record<string, unknown>>;
     },
+    async importConnectorModule(entry) {
+      ensureConnectorHooks();
+      // Import for side effects only: the pack's top-level `defineWorker(...)` runs
+      // and registers into the shim registry, which the caller drains. Apply the
+      // dev `importNonce` cache-buster (as importModule does) so a hot-reloaded
+      // pack entry is re-evaluated instead of served stale from the ESM cache.
+      const href =
+        pathToFileURL(abs(entry)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+      await import(href);
+    },
     async serveHttp(port, handler) {
       return await startNodeServer(port, handler);
     },

package/src/runtime/connector-worker-sdk.test.ts

@@ -0,0 +1,56 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  defineWorker,
+  drainDefinedWorkers,
+  type ConnectorWorkerJob,
+} from "./connector-worker-sdk.ts";
+
+test("defineWorker records handlers that drainDefinedWorkers returns then clears", () => {
+  drainDefinedWorkers(); // start clean
+  defineWorker({ type: "a:one", maxParallelJobs: 3, handle: async () => ({}) });
+  defineWorker({ type: "a:two", handle: async () => {} });
+  const first = drainDefinedWorkers();
+  assert.deepEqual(
+    first.map((w) => w.type),
+    ["a:one", "a:two"],
+  );
+  assert.equal(first[0].maxParallelJobs, 3);
+  // Draining empties the registry: a second drain sees nothing.
+  assert.deepEqual(drainDefinedWorkers(), []);
+});
+
+test("defineWorker rejects a missing type or non-function handle", () => {
+  assert.throws(() => defineWorker({ type: "", handle: async () => ({}) }), /type` is required/);
+  assert.throws(
+    () => defineWorker({ type: "x" } as unknown as Parameters<typeof defineWorker>[0]),
+    /handle must be a function/,
+  );
+  // A failed defineWorker must not leave a partial registration behind.
+  assert.deepEqual(drainDefinedWorkers(), []);
+});
+
+test("a registered handle receives the job facade and can complete", async () => {
+  drainDefinedWorkers();
+  let seen: ConnectorWorkerJob | undefined;
+  defineWorker({
+    type: "a:three",
+    async handle(job) {
+      seen = job;
+      await job.complete({ ok: true });
+    },
+  });
+  const [w] = drainDefinedWorkers();
+  const completed: Record<string, unknown>[] = [];
+  await w.handle({
+    jobKey: "j1",
+    type: "a:three",
+    processInstanceKey: "p1",
+    variables: { n: 1 },
+    complete: async (v) => void completed.push(v ?? {}),
+    fail: async () => {},
+    error: async () => {},
+  });
+  assert.equal(seen?.jobKey, "j1");
+  assert.deepEqual(completed, [{ ok: true }]);
+});

package/src/runtime/connector-worker-sdk.ts

@@ -0,0 +1,78 @@
+// The in-process `@nanobpm/worker` shim (ADR 0050, in-process port).
+//
+// A connector pack's `worker.ts` is a self-contained program that imports the
+// host-provided `@nanobpm/worker` SDK and calls `defineWorker({ type, handle })`.
+// The old Rust host ran each such worker as its own supervised child process. The
+// @nanobpm/urban runtime hosts app workers IN-PROCESS, so it hosts connector
+// workers the same way: it aliases the pack's `@nanobpm/worker` import to THIS
+// module, imports the pack entry, and reads back the registered handler(s) —
+// which it then registers on the engine like any other worker.
+//
+// `defineWorker` here does NOT connect to anything. It only records the handler in
+// a module-level registry that the runtime drains (`drainDefinedWorkers`). Because
+// the pack and the runtime resolve `@nanobpm/worker` to the SAME module URL, they
+// share this registry instance.
+//
+// This module is deliberately runtime-agnostic (no `node:*`, no `Deno`): it is the
+// contract surface, and the Node/Deno specifics of aliasing the import live in the
+// adapters.
+
+/** One activated job handed to a connector worker's `handle` (the subset the
+ *  `@nanobpm/worker` contract exposes; mirrors packages/connector-slack/types). */
+export interface ConnectorWorkerJob {
+  readonly jobKey: string;
+  readonly type: string;
+  readonly processInstanceKey: string;
+  readonly elementId?: string;
+  readonly variables: Record<string, unknown>;
+  /** Complete the job, optionally with output variables. */
+  complete(variables?: Record<string, unknown>): Promise<void>;
+  /** Fail the job (retryable). */
+  fail(message: string, retries?: number): Promise<void>;
+  /** Raise a BPMN error (routed to an error boundary event). */
+  error(code: string, message?: string): Promise<void>;
+}
+
+/** The options a connector worker passes to `defineWorker`. */
+export interface ConnectorWorkerOptions {
+  type: string;
+  maxParallelJobs?: number;
+  timeoutMs?: number;
+  /** Ignored in-process: the runtime owns the engine connection. Accepted so a
+   *  pack authored against the standalone SDK still type-checks and imports. */
+  baseUrl?: string;
+  worker?: string;
+  handle(job: ConnectorWorkerJob): Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+}
+
+/** A worker the runtime will register on the engine, drained from the registry. */
+export interface DefinedConnectorWorker {
+  type: string;
+  maxParallelJobs?: number;
+  handle: ConnectorWorkerOptions["handle"];
+}
+
+// Module-level registry. Shared across every importer of this module URL, which is
+// exactly how the pack's `defineWorker` call reaches the runtime's drain: both
+// resolve `@nanobpm/worker` to this file.
+const registered: DefinedConnectorWorker[] = [];
+
+/** The `@nanobpm/worker` entrypoint the pack calls. Records the handler; does not
+ *  connect. */
+export function defineWorker(opts: ConnectorWorkerOptions): void {
+  if (!opts || typeof opts.type !== "string" || opts.type.length === 0) {
+    throw new Error("defineWorker: `type` is required");
+  }
+  if (typeof opts.handle !== "function") {
+    throw new Error(`defineWorker("${opts.type}"): handle must be a function`);
+  }
+  registered.push({ type: opts.type, maxParallelJobs: opts.maxParallelJobs, handle: opts.handle });
+}
+
+/** Return every worker registered since the last drain, and clear the registry.
+ *  The runtime calls this immediately after importing one pack entry, so the
+ *  returned set belongs to that pack. */
+export function drainDefinedWorkers(): DefinedConnectorWorker[] {
+  const out = registered.splice(0, registered.length);
+  return out;
+}

package/src/runtime/core/host.ts

@@ -68,6 +68,16 @@ export interface HostContext {
    * between runtimes, so it lives behind the host seam.
    */
   importModule(path: string): Promise<Record<string, unknown>>;
+  /**
+   * Import a connector pack's worker `entry` (ADR 0050) with the bare
+   * `@nanobpm/worker` specifier the pack imports aliased to the runtime's
+   * in-process shim (`connector-worker-sdk.ts`), so its top-level
+   * `defineWorker(...)` registers into the shared registry. `entry` is an
+   * absolute path (already resolved from the installed pack). Hosts that cannot
+   * alias a bare specifier (or run no connector workers) may omit this; the
+   * connector mount then reports the workers as unsupported rather than crashing.
+   */
+  importConnectorModule?(entry: string): Promise<void>;
   /** Start an HTTP server. Routing is done by the caller inside `handler`. */
   serveHttp(port: number, handler: HttpHandler): Promise<HttpServer>;
   /**
@@ -100,6 +110,36 @@ export type JobHandler = (
   job: EngineJob,
 ) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
 
+/**
+ * A BPMN error raised by a job handler. When a handler throws this, the engine
+ * adapter reports it to the engine as a BPMN error (`throwError`) — routed to a
+ * matching error boundary/event subprocess — instead of a plain job failure
+ * (which retries then raises an incident). This is the runtime face of a
+ * connector worker's `job.error(code, message)` (ADR 0050): a non-retryable,
+ * modelled outcome. Handlers that throw any other error are failed (retried).
+ */
+export class BpmnError extends Error {
+  readonly errorCode: string;
+  constructor(errorCode: string, message?: string) {
+    super(message ?? errorCode);
+    this.name = "BpmnError";
+    this.errorCode = errorCode;
+  }
+}
+
+/** Structural guard: true for a {@link BpmnError} or any error carrying a
+ *  non-empty string `errorCode`, so the check survives module-duplication (a
+ *  BpmnError constructed against a different copy of this module still routes as
+ *  a BPMN error rather than a generic failure). */
+export function isBpmnError(err: unknown): err is { errorCode: string; message?: string } {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    typeof (err as { errorCode?: unknown }).errorCode === "string" &&
+    (err as { errorCode: string }).errorCode.length > 0
+  );
+}
+
 /** A registered worker subscription. */
 export interface WorkerSubscription {
   readonly jobType: string;

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

@@ -0,0 +1,206 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
+import { BpmnError } from "../host.ts";
+import type { AppManifest } from "../manifest.ts";
+import { defineWorker } from "../../connector-worker-sdk.ts";
+import { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors } from "./connectors.ts";
+
+/** A tiny engine that records registrations and can deliver a job to a handler. */
+class MiniEngine {
+  workers = new Map<string, JobHandler>();
+  async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
+    this.workers.set(jobType, handler);
+    return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };
+  }
+  deliver(jobType: string, job: EngineJob) {
+    const h = this.workers.get(jobType);
+    if (!h) throw new Error(`no worker for ${jobType}`);
+    return h(job);
+  }
+}
+
+interface FakeHostOptions {
+  files?: Record<string, string>;
+  env?: Record<string, string>;
+  /** Called on importConnectorModule(entry): register the pack's workers. */
+  onImport?: (entry: string) => void;
+  /** Omit importConnectorModule entirely (host cannot host connectors). */
+  noConnectorHost?: boolean;
+}
+
+function makeCtx(
+  manifest: Partial<AppManifest>,
+  engine: MiniEngine,
+  opts: FakeHostOptions = {},
+): { ctx: RuntimeContext; logs: Array<{ level: string; msg: string }> } {
+  const logs: Array<{ level: string; msg: string }> = [];
+  const files = opts.files ?? {};
+  const host: Record<string, unknown> = {
+    runtime: "node",
+    log: (level: string, msg: string) => logs.push({ level, msg }),
+    exists: async (p: string) => p in files,
+    readTextFile: async (p: string) => {
+      if (!(p in files)) throw new Error(`ENOENT ${p}`);
+      return files[p];
+    },
+    importModule: () => Promise.reject(new Error("no modules in this test")),
+  };
+  if (!opts.noConnectorHost) {
+    host.importConnectorModule = async (entry: string) => {
+      opts.onImport?.(entry);
+    };
+  }
+  const ctx = {
+    root: "/app",
+    manifest: { schemaVersion: 1, id: "t", name: "T", ...manifest } as AppManifest,
+    engine: engine as unknown as RuntimeContext["engine"],
+    host,
+  } as unknown as RuntimeContext;
+  return { ctx, logs };
+}
+
+function makeApp(env: Record<string, string> = {}): AppApi {
+  return { env: (n: string) => env[n], log: () => {} } as unknown as AppApi;
+}
+
+const PKG = "@nanobpm/nano-ide-connector-slack";
+const PACK_ID = "nano-ide-connector-slack";
+
+function slackFiles(): Record<string, string> {
+  return {
+    "/app/package.json": JSON.stringify({ dependencies: { [PKG]: "^1.0.0" } }),
+    [`/app/node_modules/${PKG}/nano-ide.ext.json`]: JSON.stringify({
+      id: PACK_ID,
+      workers: [
+        {
+          type: "slack:send-message",
+          entry: "worker.ts",
+          configFields: [{ key: "botToken", env: "SLACK_BOT_TOKEN" }],
+        },
+      ],
+    }),
+  };
+}
+
+test("resolveInstalledConnectors indexes packs by their manifest id", async () => {
+  const { ctx } = makeCtx({}, new MiniEngine(), { files: slackFiles() });
+  const packs = await resolveInstalledConnectors(ctx);
+  assert.deepEqual([...packs.keys()], [PACK_ID]);
+  assert.equal(packs.get(PACK_ID)?.dir, `node_modules/${PKG}`);
+});
+
+test("mountConnectors imports the pack entry and registers the drained worker", async () => {
+  const engine = new MiniEngine();
+  let importedEntry: string | undefined;
+  const { ctx, logs } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: PACK_ID }] },
+    engine,
+    {
+      files: slackFiles(),
+      onImport: (entry) => {
+        importedEntry = entry;
+        defineWorker({
+          type: "slack:send-message",
+          async handle(job) {
+            await job.complete({ echoed: job.variables.text });
+          },
+        });
+      },
+    },
+  );
+  const handle = await mountConnectors(ctx, makeApp({ SLACK_BOT_TOKEN: "xoxb-1" }));
+  assert.deepEqual(handle.jobTypes, ["slack:send-message"]);
+  assert.equal(importedEntry, `/app/node_modules/${PKG}/worker.ts`);
+  assert.ok(logs.some((l) => l.msg === "connector worker registered"));
+
+  const out = await engine.deliver("slack:send-message", {
+    jobKey: "j1",
+    jobType: "slack:send-message",
+    variables: { text: "hi" },
+  });
+  assert.deepEqual(out, { echoed: "hi" });
+});
+
+test("mountConnectors skips a worker whose required env is unset", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: PACK_ID }] },
+    engine,
+    { files: slackFiles(), onImport: () => assert.fail("must not import when env is missing") },
+  );
+  const handle = await mountConnectors(ctx, makeApp()); // no SLACK_BOT_TOKEN
+  assert.deepEqual(handle.jobTypes, []);
+  assert.ok(logs.some((l) => l.msg === "skipping connector worker: required env unset"));
+});
+
+test("mountConnectors fails closed when the connector pack is not installed", async () => {
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: PACK_ID }] },
+    engine,
+    { files: { "/app/package.json": JSON.stringify({ dependencies: {} }) } },
+  );
+  await assert.rejects(
+    () => mountConnectors(ctx, makeApp({ SLACK_BOT_TOKEN: "x" })),
+    /not installed/,
+  );
+});
+
+test("mountConnectors reports unsupported when the host cannot host connectors", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: PACK_ID }] },
+    engine,
+    { files: slackFiles(), noConnectorHost: true },
+  );
+  const handle = await mountConnectors(ctx, makeApp({ SLACK_BOT_TOKEN: "x" }));
+  assert.deepEqual(handle.jobTypes, []);
+  assert.ok(logs.some((l) => l.msg === "skipping connector worker: host cannot host connector packs"));
+});
+
+test("resolveInstalledConnectors surfaces a malformed app package.json", async () => {
+  const { ctx } = makeCtx({}, new MiniEngine(), {
+    files: { "/app/package.json": "{ not json" },
+  });
+  await assert.rejects(() => resolveInstalledConnectors(ctx), /failed to parse package\.json/);
+});
+
+test("mountConnectors fails closed on a duplicate worker type in one pack entry", async () => {
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: PACK_ID }] },
+    engine,
+    {
+      files: slackFiles(),
+      onImport: () => {
+        defineWorker({ type: "slack:send-message", async handle(job) { await job.complete({}); } });
+        defineWorker({ type: "slack:send-message", async handle(job) { await job.complete({}); } });
+      },
+    },
+  );
+  await assert.rejects(
+    () => mountConnectors(ctx, makeApp({ SLACK_BOT_TOKEN: "x" })),
+    /more than once/,
+  );
+});
+
+test("adaptConnectorHandler maps complete/fail/error(BpmnError) and a returned value", async () => {
+  const job: EngineJob = { jobKey: "j", jobType: "t", variables: {} };
+
+  const completes = adaptConnectorHandler({ type: "t", handle: async (j) => void (await j.complete({ a: 1 })) });
+  assert.deepEqual(await completes(job), { a: 1 });
+
+  const returns = adaptConnectorHandler({ type: "t", handle: async () => ({ b: 2 }) });
+  assert.deepEqual(await returns(job), { b: 2 });
+
+  const fails = adaptConnectorHandler({ type: "t", handle: async (j) => void (await j.fail("nope")) });
+  await assert.rejects(() => Promise.resolve(fails(job)), /nope/);
+
+  const errors = adaptConnectorHandler({ type: "t", handle: async (j) => void (await j.error("CODE", "boom")) });
+  await assert.rejects(
+    () => Promise.resolve(errors(job)),
+    (e: unknown) => e instanceof BpmnError && e.errorCode === "CODE",
+  );
+});