@nanobpm/urban 0.48.0 → 0.49.0

package/src/runtime/adapters/node.ts

@@ -21,6 +21,7 @@ import type {
   WatchHandle,
 } from "../core/host.ts";
 import { resolveModulePath } from "../core/module-path.ts";
+import { LOOPBACK_HOST } from "../core/manifest.ts";
 import { formatLogLine, levelEnabled, parseLogLevel } from "../core/logger.ts";
 
 /**
@@ -137,6 +138,14 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
         return [];
       }
     },
+    async listSubdirs(dir) {
+      try {
+        const entries = await readdir(abs(dir), { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+      } catch {
+        return [];
+      }
+    },
     async exists(p) {
       try {
         await stat(abs(p));
@@ -166,8 +175,8 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
         pathToFileURL(abs(entry)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
       await import(href);
     },
-    async serveHttp(port, handler) {
-      return await startNodeServer(port, handler);
+    async serveHttp(port, handler, bindHost) {
+      return await startNodeServer(port, handler, bindHost);
     },
     watch(onChange) {
       const onFsEvent = (_event: unknown, filename: string | Buffer | null) => {
@@ -216,7 +225,11 @@ function wrapNodeSqlite(db: DatabaseSync): SqliteDb {
   };
 }
 
-async function startNodeServer(port: number, handler: HttpHandler): Promise<HttpServer> {
+async function startNodeServer(
+  port: number,
+  handler: HttpHandler,
+  bindHost?: string,
+): Promise<HttpServer> {
   const server = createServer(async (nreq, nres) => {
     const chunks: Buffer[] = [];
     for await (const c of nreq) {
@@ -263,7 +276,27 @@ async function startNodeServer(port: number, handler: HttpHandler): Promise<Http
     sockets.add(socket);
     socket.once("close", () => sockets.delete(socket));
   });
-  await new Promise<void>((res) => server.listen(port, res));
+  // Bind to the requested interface (issue #235): `"127.0.0.1"` keeps the app loopback-only
+  // (secure default), `"0.0.0.0"` exposes it on the LAN. When no bind host is resolved we fail
+  // *closed* to loopback rather than inheriting Node's bind-all default, so a caller that omits
+  // it can never silently expose the server off-box.
+  const listenHost = bindHost ?? LOOPBACK_HOST;
+  // `server.listen` reports bind failures (EADDRINUSE/EACCES/…) via the `error` event, not the
+  // listening callback. Reject on the first such error so callers see the failure instead of
+  // hanging forever waiting for a `listening` that will never fire.
+  await new Promise<void>((res, rej) => {
+    const onError = (err: Error) => {
+      server.removeListener("listening", onListening);
+      rej(err);
+    };
+    const onListening = () => {
+      server.removeListener("error", onError);
+      res();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, listenHost);
+  });
   const addr = server.address();
   const actualPort = typeof addr === "object" && addr ? addr.port : port;
   return {

package/src/runtime/core/context.ts

@@ -1,7 +1,6 @@
 import type { AppManifest } from "./manifest.ts";
 import type { EngineClient, HostContext } from "./host.ts";
 import type { EngineSdkClient } from "../engine/sdk.ts";
-import type { TemplateSource } from "./modules/templates.ts";
 
 /** Everything a runtime module needs. Passed to each module's mount function. */
 export interface RuntimeContext {
@@ -10,9 +9,6 @@ export interface RuntimeContext {
   engine: EngineClient;
   /** App root directory (paths in the manifest are relative to this). */
   root: string;
-  /** Programmatic `{{name}}` template source for deploy-time substitution (globs or a
-   *  `name → content` map), merged over the manifest's `models.templates`. See `deployModels`. */
-  templates?: TemplateSource;
 }
 
 /** A mounted module returns a disposer so the runtime can tear it down cleanly. */

package/src/runtime/core/glob.ts

@@ -61,3 +61,27 @@ export async function expandPatterns(
   }
   return out;
 }
+
+/**
+ * Discover deployables under a convention directory (`resources/`), **shallow, one level deep**:
+ * the files directly under `dir` plus the files one sub-directory down (`dir/<subdir>/*`), but
+ * never deeper. The shallow bound is deliberate — deploy dedupes by basename (filename only), so a
+ * deep recursive walk would reintroduce cross-directory basename-collision risk. Sub-directory
+ * descent needs `host.listSubdirs`; a host that can't enumerate directories yields only the
+ * top-level files. Returns root-prefixed paths, sorted for determinism.
+ */
+export async function discoverResources(
+  host: HostContext,
+  root: string,
+  dir: string,
+): Promise<string[]> {
+  const base = joinPath(root, dir);
+  const out: string[] = [];
+  for (const name of await host.listDir(base)) out.push(joinPath(base, name));
+  const subdirs = host.listSubdirs ? await host.listSubdirs(base) : [];
+  for (const sub of subdirs.slice().sort()) {
+    const subBase = joinPath(base, sub);
+    for (const name of await host.listDir(subBase)) out.push(joinPath(subBase, name));
+  }
+  return out.sort();
+}

package/src/runtime/core/host.ts

@@ -80,6 +80,12 @@ export interface HostContext {
   readTextFile(path: string): Promise<string>;
   /** List file names (not directories) directly under `dir`. Returns [] if missing. */
   listDir(dir: string): Promise<string[]>;
+  /**
+   * List sub-directory names (not files) directly under `dir`. Returns [] if missing. Optional:
+   * the deploy-by-convention walk uses it to descend one level into `resources/<subdir>/` (a host
+   * that can't enumerate directories then deploys only the files directly under `resources/`).
+   */
+  listSubdirs?(dir: string): Promise<string[]>;
   /** True if the path exists (file or directory). */
   exists(path: string): Promise<boolean>;
   /** Open (creating if needed) a SQLite database at a filesystem path. */
@@ -99,8 +105,16 @@ export interface HostContext {
    * 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>;
+  /**
+   * Start an HTTP server. Routing is done by the caller inside `handler`. `bindHost` is the
+   * network interface to bind (e.g. `"127.0.0.1"` for loopback, `"0.0.0.0"` for all interfaces);
+   * the runtime always resolves it from the manifest `network.bind` setting (issue #235,
+   * loopback by default). It stays optional so hosts that can't bind-control still satisfy the
+   * contract, but the built-in node/deno adapters fail *closed* to loopback when it is omitted —
+   * they never inherit a bind-all default — so the secure-by-default guarantee can't silently
+   * regress.
+   */
+  serveHttp(port: number, handler: HttpHandler, bindHost?: string): 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:
@@ -174,6 +188,20 @@ export function isBpmnError(err: unknown): err is { errorCode: string; message?:
   );
 }
 
+/**
+ * The canonical presence rule for a form identifier ({@link EngineClient.getForm}): an
+ * empty or whitespace-only value is treated as *absent*. Returns the *trimmed* value when
+ * present (so a padded `" form-123 "` resolves against the space-free deployed key),
+ * otherwise `undefined`. This is the single source of truth shared by `getForm`'s
+ * resolution gate ({@link EngineClient.getForm} adapters) and the `taskInbox`
+ * `/api/form` route's presence check, so the two cannot drift on what counts as "an
+ * identifier was provided" (e.g. a whitespace-only `?formKey=   ` is absent in both).
+ */
+export function presentFormIdentifier(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
 /** A registered worker subscription. */
 export interface WorkerSubscription {
   readonly jobType: string;
@@ -195,6 +223,37 @@ export interface ProcessInstanceSnapshot {
   readonly state: ProcessInstanceState;
 }
 
+/**
+ * A single open user task as {@link EngineClient.searchUserTasks} reports it. Carries the
+ * task's identity plus its resolved form linkage so the `taskInbox` surface (ADR 0026) can
+ * fetch and render the linked `.form`. `formKey` is the engine's resolution of a
+ * `<zeebe:formDefinition formId="X" />` linkage to the latest deployed form at task-creation
+ * time; `externalFormReference` is a form linked outside the deployment. Both are absent for a
+ * task with no linked form (the surface then falls back to the raw key-list + complete path).
+ */
+export interface UserTaskSummary {
+  readonly userTaskKey: string;
+  readonly elementId?: string;
+  readonly variables?: Record<string, unknown>;
+  /** The resolved key of the linked deployed form, if the task has one. */
+  readonly formKey?: string;
+  /** An external form reference (a form linked outside the deployment), if any. */
+  readonly externalFormReference?: string;
+}
+
+/**
+ * A deployed form's form-js schema plus its identifying metadata, as
+ * {@link EngineClient.getForm} returns it. `schema` is the parsed form-js document
+ * (`{ type: "default", schemaVersion, components: [...] }`) that the surface renders
+ * client-side; `formKey`/`formId`/`version` identify the exact deployed form resolved.
+ */
+export interface FormSchema {
+  readonly formKey?: string;
+  readonly formId?: string;
+  readonly version?: number;
+  readonly schema: Record<string, unknown>;
+}
+
 /**
  * EngineClient is the seam onto a Nano engine. The SDK/REST-backed adapter implements
  * it against a live engine; tests implement it in-memory. Core modules depend only on this.
@@ -218,12 +277,23 @@ export interface EngineClient {
     correlationKey?: string;
     variables?: Record<string, unknown>;
   }): Promise<void>;
-  /** Search open user tasks (optionally by process instance). */
+  /** Search open user tasks (optionally by process instance). Each result carries the
+   *  task's resolved form linkage (`formKey`/`externalFormReference`) when present. */
   searchUserTasks(filter?: {
     processInstanceKey?: string;
     assignee?: string;
     candidateGroup?: string;
-  }): Promise<{ userTaskKey: string; elementId?: string; variables?: Record<string, unknown> }[]>;
+  }): Promise<UserTaskSummary[]>;
+  /**
+   * Fetch a deployed form's form-js schema for the `taskInbox` surface. Resolve by
+   * `formKey` (the linkage the engine attaches to a user task) or, as a best-effort
+   * fallback, by `formId`. An empty or whitespace-only identifier is treated as absent,
+   * so a blank `formKey` falls through to `formId`. How `formId` is addressed is
+   * adapter-specific: an adapter may pass it straight through as the lookup key, or
+   * resolve it to the latest deployed form's key. Returns `null` when no matching form
+   * exists — the caller then falls back to the no-form path.
+   */
+  getForm(input: { formKey?: string; formId?: string }): Promise<FormSchema | null>;
   /** Complete a user task. */
   completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
   /**

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

@@ -1,6 +1,19 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { expandEnvString, expandEnv, parseManifest, workerJobType } from "./manifest.ts";
+import {
+  expandEnvString,
+  expandEnv,
+  parseManifest,
+  workerJobType,
+  resolveBindMode,
+  resolveBindHost,
+  isBindMode,
+  bindModeToHost,
+  LOOPBACK_HOST,
+  ALL_INTERFACES_HOST,
+  NETWORK_KEYS,
+  type NetworkConfig,
+} from "./manifest.ts";
 
 test("expandEnvString: var, default, and empty fallback", () => {
   const env: Record<string, string> = { FOO: "bar" };
@@ -28,3 +41,50 @@ test("workerJobType returns the taskType", () => {
   assert.equal(workerJobType({ taskType: "a", handler: "h" }), "a");
   assert.equal(workerJobType({ taskType: "llm-job", llm: "gpt" }), "llm-job");
 });
+
+test("bind mode defaults to loopback when the manifest omits network (issue #235)", () => {
+  assert.equal(resolveBindMode({}), "loopback");
+  assert.equal(resolveBindMode({ network: {} }), "loopback");
+  assert.equal(resolveBindHost({}), LOOPBACK_HOST);
+  assert.equal(resolveBindHost({}), "127.0.0.1");
+});
+
+test("manifest network.bind selects the interface", () => {
+  assert.equal(resolveBindMode({ network: { bind: "all" } }), "all");
+  assert.equal(resolveBindHost({ network: { bind: "all" } }), ALL_INTERFACES_HOST);
+  assert.equal(resolveBindHost({ network: { bind: "all" } }), "0.0.0.0");
+  assert.equal(resolveBindHost({ network: { bind: "loopback" } }), "127.0.0.1");
+});
+
+// Drift guard: NETWORK_KEYS is the validator's single source of truth for `network`'s allowed
+// keys. Keep it complete as NetworkConfig grows — every declared key must be listed, or the
+// validator would reject a legitimate field. The `satisfies` pins each entry to a real key.
+test("NETWORK_KEYS lists every NetworkConfig key (issue #235)", () => {
+  const sample = { bind: "loopback" } satisfies Required<NetworkConfig>;
+  for (const key of Object.keys(sample)) {
+    assert.ok(
+      NETWORK_KEYS.some((known) => known === key),
+      `NETWORK_KEYS is missing the '${key}' NetworkConfig key`,
+    );
+  }
+});
+
+test("URBAN_BIND env overrides the manifest, invalid values are ignored", () => {
+  const env = (v: string | undefined) => (n: string) => (n === "URBAN_BIND" ? v : undefined);
+  // env override wins over the manifest in both directions
+  assert.equal(resolveBindMode({ network: { bind: "loopback" } }, env("all")), "all");
+  assert.equal(resolveBindMode({ network: { bind: "all" } }, env("loopback")), "loopback");
+  assert.equal(resolveBindHost({ network: { bind: "loopback" } }, env("all")), "0.0.0.0");
+  // an invalid or empty env value falls through to the manifest/default
+  assert.equal(resolveBindMode({ network: { bind: "all" } }, env("bogus")), "all");
+  assert.equal(resolveBindMode({}, env("")), "loopback");
+});
+
+test("isBindMode / bindModeToHost", () => {
+  assert.equal(isBindMode("loopback"), true);
+  assert.equal(isBindMode("all"), true);
+  assert.equal(isBindMode("nope"), false);
+  assert.equal(isBindMode(undefined), false);
+  assert.equal(bindModeToHost("loopback"), "127.0.0.1");
+  assert.equal(bindModeToHost("all"), "0.0.0.0");
+});

package/src/runtime/core/manifest.ts

@@ -9,7 +9,12 @@
 // used to cause.
 
 import type { HostContext } from "./host.ts";
-import type { AppManifest, Worker } from "@nanobpm/nano-app-schema";
+import { isRecord } from "./guards.ts";
+import type {
+  AppManifest,
+  InstanceTracking as SchemaInstanceTracking,
+  Worker,
+} from "@nanobpm/nano-app-schema";
 
 export type {
   ActionDecl,
@@ -21,7 +26,6 @@ export type {
   DataSource,
   DomainField,
   DomainType,
-  InstanceTracking,
   LlmBinding,
   Models,
   PagesSurface,
@@ -34,11 +38,141 @@ export type {
   Worker,
 } from "@nanobpm/nano-app-schema";
 
+/**
+ * `instanceTracking` binding, bridged to add the fail-open `terminalStatuses` selector.
+ *
+ * `terminalStatuses` is landing in the canonical schema (`@nanobpm/nano-app-schema`,
+ * Magikcraft/nano-bpm#769): an exclusion list — the runtime polls every row whose
+ * `statusField` is NOT in it — so a newly-added non-terminal status is reconciled by
+ * default instead of silently dropping out of an allow-list. Until that publishes and this
+ * package's dep is bumped, extend the schema type here so the reconciler can consume the
+ * field. Drop this augmentation and re-export `InstanceTracking` from the schema once the
+ * dep bump lands (No Drift Surfaces).
+ */
+export type InstanceTracking = SchemaInstanceTracking & {
+  /** Values of `statusField` considered finished. When set, every row NOT in one of these
+   *  is polled (fail-open). Requires `statusField`; mutually exclusive with `activeStatuses`. */
+  readonly terminalStatuses?: readonly string[];
+};
+
+/**
+ * A status selector (`activeStatuses`/`terminalStatuses`) counts as *configured* only when it is
+ * a non-empty array of non-empty strings. Both the reconciler's row selection and the manifest
+ * validator gate on this one predicate, so "is this selector active?" has a single definition and
+ * the two can't drift (No Drift Surfaces). Anything else — `undefined`, an empty array, a bare
+ * string, or an array holding a non-string/empty entry — is treated as *not configured*: the
+ * reconciler falls through to the fail-open poll-all path and the validator flags the malformed
+ * shape at author time (rather than letting e.g. `new Set("abandoned")` silently become a set of
+ * characters, or `activeStatuses.map(...)` crash on a non-array).
+ */
+export function isConfiguredStatusSelector(v: unknown): v is readonly string[] {
+  return Array.isArray(v) && v.length > 0 && v.every((s) => typeof s === "string" && s.length > 0);
+}
+
 /** The job type a worker subscribes to (schema key: `taskType`). */
 export function workerJobType(w: Worker): string | undefined {
   return w.taskType;
 }
 
+/**
+ * The valid HTTP bind modes, in declaration order. This is the single runtime source of
+ * truth for the set: {@link BindMode}, {@link isBindMode}, and the manifest validator
+ * (`collectManifestIssues`) all derive from it, so the allowed values live in one place.
+ */
+export const BIND_MODES = ["loopback", "all"] as const;
+
+/**
+ * Which interface the app's embedded HTTP server binds to (issue #235):
+ *  - `"loopback"` (default): `127.0.0.1` — secure-by-default; refuses off-box connections.
+ *  - `"all"`: `0.0.0.0` — reachable from other hosts on the LAN (distributed worker fleet).
+ */
+export type BindMode = (typeof BIND_MODES)[number];
+
+/**
+ * App-level network settings (issue #235). Absent ⇒ loopback.
+ *
+ * Mirrored locally — like the `api` binding (ADR 0058) — until `@nanobpm/nano-app-schema`
+ * folds `network` into `AppManifest` (the schema PR lands first). The manifest shape is
+ * owned by that package (ADR 0027), so we deliberately do NOT augment `AppManifest` via
+ * `declare module` (CI bans it): the field is threaded through the runtime-side helpers
+ * that take a `{ network?: NetworkConfig }` view and is read off the raw manifest object.
+ * Once the schema ships `network`, this local type (and the allow-list entry in
+ * validate.ts) can be deleted and the field flows from the schema like every other block.
+ */
+export interface NetworkConfig {
+  /** HTTP bind interface. Default `"loopback"`. */
+  bind?: BindMode;
+}
+
+/**
+ * The keys the runtime-side `network` block understands, as the single source of truth for
+ * the validator's `additionalProperties: false` check under `network`. Typed as
+ * `(keyof NetworkConfig)[]` so it can only ever list real {@link NetworkConfig} keys — a
+ * drift test (`manifest.test.ts`) asserts it stays complete as the block grows.
+ */
+export const NETWORK_KEYS: readonly (keyof NetworkConfig)[] = ["bind"];
+
+/** A runtime-side view of a manifest carrying the pending-schema `network` block. */
+export interface WithNetwork {
+  network?: NetworkConfig;
+}
+
+/** Loopback bind address — secure/local default. */
+export const LOOPBACK_HOST = "127.0.0.1";
+/** All-interfaces IPv4 bind address — LAN / distributed fleet. */
+export const ALL_INTERFACES_HOST = "0.0.0.0";
+
+/** Environment variable that overrides the manifest bind mode for ops. */
+export const BIND_ENV_VAR = "URBAN_BIND";
+
+/** True when `v` is a valid {@link BindMode}. */
+export function isBindMode(v: unknown): v is BindMode {
+  return BIND_MODES.some((mode) => mode === v);
+}
+
+/**
+ * Read the pending-schema `network.bind` off a raw manifest object. Because `network` is
+ * mirrored locally (not yet in `AppManifest`'s static shape), it is read reflectively —
+ * the same way the `api` binding is threaded (ADR 0058) — and validated with
+ * {@link isBindMode} so this always returns a real {@link BindMode} or `undefined`.
+ */
+function manifestBind(manifest: AppManifest | WithNetwork): BindMode | undefined {
+  const network = Reflect.get(manifest, "network");
+  if (!isRecord(network)) return undefined;
+  return isBindMode(network.bind) ? network.bind : undefined;
+}
+
+/**
+ * Resolve the effective HTTP bind mode: the `URBAN_BIND` env override wins when set to a
+ * valid value, else the manifest's `network.bind`, else `"loopback"` (secure by default).
+ * An env value that is present but invalid is ignored (falls through to the manifest/default);
+ * callers that want to surface that can check {@link isBindMode} on the raw env value.
+ */
+export function resolveBindMode(
+  manifest: AppManifest | WithNetwork,
+  lookup: (name: string) => string | undefined = () => undefined,
+): BindMode {
+  const envRaw = lookup(BIND_ENV_VAR);
+  if (isBindMode(envRaw)) return envRaw;
+  return manifestBind(manifest) ?? "loopback";
+}
+
+/** Map a {@link BindMode} to the concrete host address passed to the HTTP adapter. */
+export function bindModeToHost(mode: BindMode): string {
+  return mode === "all" ? ALL_INTERFACES_HOST : LOOPBACK_HOST;
+}
+
+/**
+ * Resolve the concrete bind host address from the manifest + environment.
+ * `"loopback"` ⇒ `127.0.0.1` (default), `"all"` ⇒ `0.0.0.0`.
+ */
+export function resolveBindHost(
+  manifest: AppManifest | WithNetwork,
+  lookup: (name: string) => string | undefined = () => undefined,
+): string {
+  return bindModeToHost(resolveBindMode(manifest, lookup));
+}
+
 const ENV_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
 
 /**

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

@@ -29,6 +29,7 @@ const engine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),

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

@@ -28,6 +28,7 @@ const engine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  getForm: async () => null,
   searchProcessInstances: async () => [],
   completeUserTask: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),

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

@@ -73,6 +73,7 @@ function cancelEngine(opts: {
     createInstance: notUsed("createInstance"),
     publishMessage: notUsed("publishMessage"),
     searchUserTasks: notUsed("searchUserTasks"),
+    getForm: notUsed("getForm"),
     completeUserTask: notUsed("completeUserTask"),
     registerWorker: notUsed("registerWorker"),
     close: notUsed("close"),

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

@@ -17,6 +17,7 @@ class MiniEngine implements EngineClient {
   async cancelInstance(): Promise<void> {}
   async publishMessage(): Promise<void> {}
   async searchUserTasks(): Promise<[]> { return []; }
+  async getForm(): Promise<null> { return null; }
   async completeUserTask(): Promise<void> {}
   async searchProcessInstances(): Promise<[]> { return []; }
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {

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

@@ -16,6 +16,7 @@ const noEngine: EngineClient = {
   cancelInstance: async () => {},
   publishMessage: async () => {},
   searchUserTasks: async () => [],
+  getForm: async () => null,
   completeUserTask: async () => {},
   searchProcessInstances: async () => [],
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),