@nanobpm/urban 0.12.0 → 0.14.0

package/src/runtime/adapters/node.ts

@@ -2,6 +2,7 @@
 // (with deno.ts) allowed to touch a concrete runtime.
 
 import { readFile, readdir, stat } from "node:fs/promises";
+import { watch as fsWatch, type FSWatcher } from "node:fs";
 import { createServer } from "node:http";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -12,12 +13,19 @@ import type {
   HttpRequest,
   HttpServer,
   SqliteDb,
+  WatchHandle,
 } from "../core/host.ts";
 
 export interface NodeHostOptions {
   /** Base directory relative paths resolve against. Default process.cwd(). */
   cwd?: string;
   log?: HostContext["log"];
+  /**
+   * When set, appended as a `?v=<nonce>` query to dynamic import URLs so a changed
+   * handler/worker module is re-evaluated instead of served from the ESM cache. The
+   * dev server bumps this on every reload; production leaves it unset.
+   */
+  importNonce?: string;
 }
 
 export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
@@ -56,10 +64,35 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
       const db = new DatabaseSync(abs(path));
       return wrapNodeSqlite(db);
     },
-    importModule: (p) => import(pathToFileURL(abs(p)).href) as Promise<Record<string, unknown>>,
+    importModule: (p) => {
+      const href =
+        pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+      return import(href) as Promise<Record<string, unknown>>;
+    },
     async serveHttp(port, handler) {
       return await startNodeServer(port, handler);
     },
+    watch(onChange) {
+      const onFsEvent = (_event: unknown, filename: string | Buffer | null) => {
+        if (filename) onChange(String(filename));
+      };
+      // Recursive watch is supported on macOS, Windows, and — since Node 19.1.0 — Linux.
+      // This package requires Node >=22.6, so the recursive path is available on all three;
+      // the try/catch only trips on an unusual platform, where we degrade honestly to a
+      // non-recursive root watch (and warn) rather than silently miss nested changes.
+      let w: FSWatcher;
+      try {
+        w = fsWatch(cwd, { recursive: true }, onFsEvent);
+      } catch (err) {
+        log("warn", "recursive file watch unavailable — nested changes may be missed", {
+          error: String(err),
+        });
+        w = fsWatch(cwd, onFsEvent);
+      }
+      // A watcher error (e.g. the dir is removed) must not crash the dev server.
+      w.on("error", (err) => log("warn", "file watch error", { error: String(err) }));
+      return { close: () => w.close() } satisfies WatchHandle;
+    },
     now: () => Date.now(),
     log,
   };

package/src/runtime/core/host.ts

@@ -30,6 +30,11 @@ export interface HttpServer {
   stop(): Promise<void>;
 }
 
+/** A handle to an active filesystem watch; call close() to stop watching. */
+export interface WatchHandle {
+  close(): void;
+}
+
 /** A tiny synchronous SQLite handle — the subset the runtime needs. */
 export interface SqliteDb {
   /** Execute one or more statements with no result (DDL, PRAGMA, migrations). */
@@ -65,19 +70,30 @@ export interface HostContext {
   importModule(path: string): Promise<Record<string, unknown>>;
   /** Start an HTTP server. Routing is done by the caller inside `handler`. */
   serveHttp(port: number, handler: HttpHandler): Promise<HttpServer>;
+  /**
+   * Recursively watch the app root for file changes, invoking `onChange` with the
+   * changed path (app-root-relative when the runtime reports it that way). Optional:
+   * hosts that cannot watch omit it, and callers fall back to run-once. Returns a
+   * handle whose close() stops watching.
+   */
+  watch?(onChange: (path: string) => void): WatchHandle;
   /** Current wall-clock time in ms since epoch (seam for tests). */
   now(): number;
   /** Structured log sink. */
   log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
 }
 
-/** A job handed to a worker handler, plus the ack/fail callbacks. */
-export interface EngineJob {
+/** A job handed to a worker handler, plus the ack/fail callbacks. `In` types the process
+ *  variables carried on the job; it defaults to an open record when a handler doesn't
+ *  declare a concrete input shape. The `object` bound (rather than `Record<string, unknown>`)
+ *  lets plain `interface` shapes be used as `In` — interfaces lack the implicit index
+ *  signature that a `Record` bound would demand. */
+export interface EngineJob<In extends object = Record<string, unknown>> {
   jobKey: string;
   jobType: string;
   processInstanceKey?: string;
   elementId?: string;
-  variables: Record<string, unknown>;
+  variables: In;
 }
 
 export type JobHandler = (

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

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
 import type { AppManifest } from "../manifest.ts";
-import { mountWorkers, sdkDecisionEvaluator } from "./workers.ts";
+import { mountWorkers, sdkDecisionEvaluator, type AppJobHandler } from "./workers.ts";
 
 /** A tiny engine that records registrations and can deliver a job to a handler. */
 class MiniEngine {
@@ -156,3 +156,55 @@ test("sdkDecisionEvaluator throws a clear error when the SDK lacks evaluateDecis
   const evaluate = sdkDecisionEvaluator({});
   await assert.rejects(evaluate("risk", {}), /does not support evaluateDecision.*"risk"/);
 });
+
+// ── 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.
+test("AppJobHandler carries optional In/Out variable types", async () => {
+  // `In` is a plain interface — the `object` bound (not `Record<string, unknown>`) makes this
+  // work, since interfaces have no implicit index signature.
+  interface In {
+    prKey: string;
+    round: number;
+    summary?: string;
+  }
+  interface Out {
+    ok: boolean;
+  }
+
+  // In + Out: job.variables is typed as In, the return must be Out (or void).
+  const typed: AppJobHandler<In, Out> = async (job) => {
+    const key: string = job.variables.prKey; // typed access compiles
+    const n: number = job.variables.round;
+    return { ok: key.length > 0 && n >= 0 };
+  };
+
+  // In only: Out defaults to an open variables map, so any plain object of completion
+  // variables may be returned.
+  const inOnly: AppJobHandler<In> = (job) => ({ echoed: job.variables.prKey });
+
+  // No parameters: fully open — the pre-generics behaviour.
+  const open: AppJobHandler = (job) => ({ count: Object.keys(job.variables).length });
+
+  // Returning nothing (void) is allowed under any parameterisation.
+  const voidReturn: AppJobHandler<In> = () => {};
+
+  const job: EngineJob<In> = {
+    jobKey: "1",
+    jobType: "pr.finalize",
+    variables: { prKey: "p1", round: 2 },
+  };
+  // The open handler defaults `In` to a record; interface-typed jobs aren't assignable to it,
+  // so hand it a plainly-typed job (the pre-generics shape).
+  const openJob: EngineJob = {
+    jobKey: "2",
+    jobType: "pr.finalize",
+    variables: { prKey: "p1", round: 2 },
+  };
+  const app = {} as AppApi;
+
+  assert.deepEqual(await typed(job, app), { ok: true });
+  assert.deepEqual(await inOnly(job, app), { echoed: "p1" });
+  assert.deepEqual(await open(openJob, app), { count: 2 });
+  assert.equal(await voidReturn(job, app), undefined);
+});

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

@@ -42,11 +42,26 @@ export function sdkDecisionEvaluator(sdk: unknown): DecisionEvaluator {
   };
 }
 
-/** A handler as authored by an app: the job plus the injected app API. */
-export type AppJobHandler = (
-  job: EngineJob,
+/**
+ * A handler as authored by an app: the job plus the injected app API.
+ *
+ * Both type parameters are optional:
+ *   - `In`  types `job.variables` (the process variables the job carries).
+ *   - `Out` types the completion **variables map** the handler returns to the engine.
+ * Each defaults to an open `Record<string, unknown>`, so `AppJobHandler`,
+ * `AppJobHandler<In>`, and `AppJobHandler<In, Out>` are all valid.
+ *
+ * The bound is `extends object` (not `Record<string, unknown>`) so a plain `interface In {…}`
+ * / `interface Out {…}` can be supplied — interfaces have no implicit index signature and so
+ * don't satisfy a `Record` bound. The looser bound means `Out` is not *forced* to be a plain
+ * variables map at the type level; authors are expected to return a JSON-object of completion
+ * variables (not a `Date`, `Map`, array, etc.), which is what the engine sends on job
+ * completion. Both parameters are erased at runtime — they only shape authoring-time types.
+ */
+export type AppJobHandler<In extends object = Record<string, unknown>, Out extends object = Record<string, unknown>> = (
+  job: EngineJob<In>,
   app: AppApi,
-) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+) => Promise<Out | void> | Out | void;
 
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order:

package/src/runtime/devserver.test.ts

@@ -0,0 +1,330 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { runDev, shouldReload, type DevDeps } from "./devserver.ts";
+import type { HostContext } from "./core/host.ts";
+import type { UrbanApp } from "./core/runtime.ts";
+
+const delay = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+test("shouldReload triggers on source files and the manifest", () => {
+  for (const p of [
+    "nano.app.json",
+    "processes/greet.bpmn",
+    "decisions/route.dmn",
+    "forms/greet.form",
+    "workers/greet.ts",
+    "workers/greet.js",
+    "db/migrations/001_init.sql",
+    "./processes/greet.bpmn",
+  ]) {
+    assert.equal(shouldReload(p), true, `expected reload for ${p}`);
+  }
+});
+
+test("shouldReload ignores generated output, deps, VCS and db churn", () => {
+  for (const p of [
+    "nano-generated/greeting.schema.sql",
+    "nano-generated/urban-workers.d.ts",
+    "node_modules/left-pad/index.js",
+    ".git/index",
+    "dist/index.js",
+    "db/app.db",
+    "db/app.db-wal",
+    "db/app.db-shm",
+    "db/app.sqlite-journal",
+    "README.md",
+    "notes.txt",
+    "",
+  ]) {
+    assert.equal(shouldReload(p), false, `expected no reload for ${p}`);
+  }
+});
+
+test("shouldReload honours a custom manifest filename", () => {
+  assert.equal(shouldReload("config/app.json", "config/app.json"), true, "custom manifest reloads");
+  assert.equal(shouldReload("app.config.json", "app.config.json"), true, "by basename too");
+  // A .json that is NOT the configured manifest is not a source file.
+  assert.equal(shouldReload("tsconfig.json"), false, "unrelated json ignored");
+  assert.equal(shouldReload("config/app.json"), false, "custom manifest ignored under default");
+});
+
+test("stop() cancels a pending debounced reload", async () => {
+  const starts: string[] = [];
+  const stops: string[] = [];
+  let clock = 1;
+  let watch!: ReturnType<typeof fakeHost>;
+  const deps: DevDeps = {
+    makeHost: () => ((watch = fakeHost()), watch.host),
+    startApp: async () => {
+      const id = `a${starts.length}`;
+      starts.push(id);
+      return fakeApp(stops, id);
+    },
+    regenerate: async () => ({ count: 0 }),
+    now: () => clock++,
+  };
+  const dev = await runDev({ debounceMs: 50, log: () => {} }, deps);
+  watch.fire("workers/x.ts"); // schedules a reload 50ms out
+  await dev.stop(); // stop before the debounce fires
+  await delay(80);
+  assert.equal(starts.length, 1, "pending reload was cancelled by stop()");
+  assert.equal(watch.closed(), true, "watcher closed");
+  assert.deepEqual(stops, ["a0"], "the running app was stopped exactly once");
+});
+
+test("stop() during an in-flight reload does not start a replacement app", async () => {
+  const starts: string[] = [];
+  const stops: string[] = [];
+  let clock = 1;
+  const hosts: ReturnType<typeof fakeHost>[] = [];
+  // Gate the boot app's stop() so we can flip shutdown mid-reload, in the window
+  // between the old app being stopped and the new one starting.
+  let releaseStop!: () => void;
+  const stopGate = new Promise<void>((r) => (releaseStop = r));
+
+  const deps: DevDeps = {
+    makeHost: () => {
+      const h = fakeHost();
+      hosts.push(h);
+      return h.host;
+    },
+    startApp: async () => {
+      const id = `a${starts.length}`;
+      starts.push(id);
+      if (id === "a0") {
+        return {
+          ...fakeApp(stops, id),
+          async stop() {
+            await stopGate; // block the first reload inside app.stop()
+            stops.push(id);
+          },
+        } as UrbanApp;
+      }
+      return fakeApp(stops, id);
+    },
+    regenerate: async () => ({ count: 0 }),
+    now: () => clock++,
+  };
+
+  const dev = await runDev({ debounceMs: 5, log: () => {} }, deps);
+  hosts[0].fire("workers/x.ts"); // triggers a reload; it will block inside app.stop()
+  await delay(20);
+  const stopping = dev.stop(); // flips `stopped` while the reload is parked in app.stop()
+  releaseStop(); // let the old app finish stopping; reload must now bail, not start a0's replacement
+  await stopping;
+
+  assert.deepEqual(starts, ["a0"], "no replacement app started during teardown");
+  assert.deepEqual(stops, ["a0"], "the running app was stopped exactly once");
+  assert.equal(hosts[0].closed(), true, "watcher closed");
+});
+
+test("import nonce is unique per reload even within the same millisecond", async () => {
+  const starts: string[] = [];
+  const stops: string[] = [];
+  const nonces: string[] = [];
+  const hosts: ReturnType<typeof fakeHost>[] = [];
+  const deps: DevDeps = {
+    makeHost: (nonce) => {
+      nonces.push(nonce);
+      const h = fakeHost();
+      hosts.push(h);
+      return h.host;
+    },
+    startApp: async () => {
+      const id = `a${starts.length}`;
+      starts.push(id);
+      return fakeApp(stops, id);
+    },
+    regenerate: async () => ({ count: 0 }),
+    now: () => 42, // frozen clock: nonce uniqueness must come from the reload counter
+  };
+  const dev = await runDev({ debounceMs: 1, log: () => {} }, deps);
+  // The watcher is registered on the boot host only; fire both changes through it.
+  hosts[0].fire("workers/a.ts");
+  await delay(15);
+  hosts[0].fire("workers/b.ts");
+  await delay(15);
+  await dev.stop();
+  assert.equal(nonces.length, 3, "boot + two reloads built three hosts");
+  assert.equal(new Set(nonces).size, 3, "every import nonce is distinct");
+});
+
+test("a change during an in-flight reload doesn't detach stop() from it", async () => {
+  // Regression: schedule() used to overwrite `inFlight` with reload()'s already-resolved
+  // no-op promise when a reload was already running, so stop() wouldn't await the real
+  // reload and could tear down while it started a replacement app (a leak).
+  const starts: string[] = [];
+  const stops: string[] = [];
+  const hosts: ReturnType<typeof fakeHost>[] = [];
+  let clock = 1;
+  // Gate a1's start so reload #1 parks *past* the shutdown checks, inside startApp.
+  let releaseStart!: () => void;
+  const startGate = new Promise<void>((r) => (releaseStart = r));
+
+  const deps: DevDeps = {
+    makeHost: () => {
+      const h = fakeHost();
+      hosts.push(h);
+      return h.host;
+    },
+    startApp: async () => {
+      const id = `a${starts.length}`;
+      starts.push(id);
+      if (id === "a1") await startGate; // park reload #1 inside startApp
+      return fakeApp(stops, id);
+    },
+    regenerate: async () => ({ count: 0 }),
+    now: () => clock++,
+  };
+
+  const dev = await runDev({ debounceMs: 5, log: () => {} }, deps);
+  hosts[0].fire("workers/a.ts"); // reload #1: stops a0, then parks starting a1
+  await delay(20);
+  hosts[0].fire("workers/b.ts"); // a second change lands while reload #1 is in flight
+  await delay(20);
+
+  const stopping = dev.stop(); // must await the real reload #1, not a stale resolved promise
+  releaseStart(); // let reload #1 finish starting a1
+  await stopping;
+
+  assert.deepEqual(starts, ["a0", "a1"], "reload #1 started its replacement app");
+  assert.deepEqual(stops, ["a0", "a1"], "stop() awaited reload #1 and stopped a1 (no leak)");
+});
+
+// A minimal fake host: runDev only calls host.watch on it.
+function fakeHost(): { host: HostContext; fire: (p: string) => void; closed: () => boolean } {
+  let cb: ((p: string) => void) | undefined;
+  let closed = false;
+  const host = {
+    watch(onChange: (p: string) => void) {
+      cb = onChange;
+      return { close: () => (closed = true) };
+    },
+  } as unknown as HostContext;
+  return { host, fire: (p) => cb?.(p), closed: () => closed };
+}
+
+function fakeApp(stops: string[], id: string): UrbanApp {
+  return {
+    manifest: { id } as UrbanApp["manifest"],
+    root: ".",
+    async start() {},
+    async stop() {
+      stops.push(id);
+    },
+    inspect: () => ({ app: id }),
+    data: undefined,
+    security: undefined,
+    httpPort: undefined,
+  };
+}
+
+test("runDev derives + starts once, then hot-reloads on a relevant change", async () => {
+  const gens: string[] = [];
+  const starts: string[] = [];
+  const stops: string[] = [];
+  const nonces: string[] = [];
+  const hosts: ReturnType<typeof fakeHost>[] = [];
+  let clock = 1000;
+
+  const deps: DevDeps = {
+    makeHost: (nonce) => {
+      nonces.push(nonce);
+      const h = fakeHost();
+      hosts.push(h);
+      return h.host;
+    },
+    startApp: async (_host) => {
+      const id = `app#${starts.length}`;
+      starts.push(id);
+      return fakeApp(stops, id);
+    },
+    regenerate: async (root, mf) => {
+      gens.push(`${root}:${mf}`);
+      return { count: 2 };
+    },
+    now: () => clock++,
+  };
+
+  const logs: string[] = [];
+  const dev = await runDev(
+    { root: ".", manifestPath: "nano.app.json", debounceMs: 5, log: (m) => logs.push(m) },
+    deps,
+  );
+
+  assert.deepEqual(gens, [".:nano.app.json"], "gen ran once at boot");
+  assert.deepEqual(starts, ["app#0"], "app started once at boot");
+  assert.equal(stops.length, 0, "nothing stopped yet");
+
+  // runDev registers the watcher on the boot host only; fire through it.
+  const bootWatch = hosts[0];
+
+  // An irrelevant change (the sqlite db) must NOT reload.
+  bootWatch.fire("db/app.db");
+  await delay(20);
+  assert.equal(starts.length, 1, "db churn did not reload");
+
+  // A relevant change reloads: stop old, regen, start new with a fresh nonce.
+  bootWatch.fire("processes/greet.bpmn");
+  await delay(20);
+  assert.deepEqual(stops, ["app#0"], "old app stopped");
+  assert.equal(gens.length, 2, "gen reran on reload");
+  assert.deepEqual(starts, ["app#0", "app#1"], "new app started");
+  assert.notEqual(nonces[0], nonces[1], "import nonce changed across reload");
+
+  await dev.stop();
+  assert.equal(bootWatch.closed(), true, "watcher closed on stop");
+  assert.deepEqual(stops, ["app#0", "app#1"], "current app stopped on shutdown");
+});
+
+test("runDev coalesces a burst of changes into a single reload (debounce)", async () => {
+  const starts: string[] = [];
+  const stops: string[] = [];
+  let clock = 1;
+  let watch!: ReturnType<typeof fakeHost>;
+
+  const deps: DevDeps = {
+    makeHost: () => ((watch = fakeHost()), watch.host),
+    startApp: async () => {
+      const id = `a${starts.length}`;
+      starts.push(id);
+      return fakeApp(stops, id);
+    },
+    regenerate: async () => ({ count: 0 }),
+    now: () => clock++,
+  };
+
+  const dev = await runDev({ debounceMs: 15, log: () => {} }, deps);
+  for (const p of ["workers/a.ts", "workers/b.ts", "forms/c.form"]) watch.fire(p);
+  await delay(40);
+  assert.equal(starts.length, 2, "three rapid edits produced exactly one reload");
+  await dev.stop();
+});
+
+test("runDev survives a failing reload and keeps the previous app running", async () => {
+  const stops: string[] = [];
+  let boom = false;
+  let clock = 1;
+  let watch!: ReturnType<typeof fakeHost>;
+  const logs: string[] = [];
+
+  const deps: DevDeps = {
+    makeHost: () => ((watch = fakeHost()), watch.host),
+    startApp: async () => fakeApp(stops, "app"),
+    regenerate: async () => {
+      if (boom) throw new Error("bad manifest");
+      return { count: 1 };
+    },
+    now: () => clock++,
+  };
+
+  const dev = await runDev({ debounceMs: 5, log: (m) => logs.push(m) }, deps);
+  boom = true;
+  watch.fire("nano.app.json");
+  await delay(20);
+  assert.ok(
+    logs.some((l) => l.includes("reload failed")),
+    "a failed reload is reported, not thrown",
+  );
+  await dev.stop();
+});