@nanobpm/urban 0.39.0 → 0.40.0

package/src/runtime/core/modules/instance-tracking.test.ts

@@ -1,4 +1,5 @@
 import { test } from "node:test";
+import { createLogger } from "../logger.ts";
 import assert from "node:assert/strict";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -148,7 +149,9 @@ async function withHarness(
     data,
     engine,
     env: () => undefined,
-    log: (level, msg) => logs.push({ level, msg }),
+    log: createLogger((level, msg) => {
+      logs.push({ level, msg });
+    }),
   };
   return {
     api,

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

@@ -262,6 +262,37 @@ test("renderer wires a column's processExplorer link to the console explorer", a
   assert.match(js, /"\/console\/explorer\?instance="\s*\+\s*encodeURIComponent\(keyStr\)/);
   assert.match(js, /target:\s*"_blank"/);
   assert.match(js, /rel:\s*"noopener noreferrer"/);
+  // Embedded in the console, a plain click routes the host explorer in place via
+  // hostNavigate("processExplorer", {instance}) + preventDefault; a modified
+  // click (new-tab intent) short-circuits so the native _blank anchor wins.
+  assert.match(js, /hostNavigate\("processExplorer",\s*\{\s*instance:\s*keyStr\s*\}\)/);
+  // Non-primary buttons (middle/right) and modified clicks keep the native
+  // new-tab behavior; only a plain primary click routes in-host.
+  assert.match(js, /ev\.button !== 0/);
+  assert.match(js, /ev\.metaKey \|\| ev\.ctrlKey \|\| ev\.shiftKey \|\| ev\.altKey/);
+  assert.match(js, /ev\.preventDefault\(\)/);
+});
+
+test("renderer exposes an embed-gated host-navigation bridge", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // In-host navigation is gated on being embedded in a SAME-ORIGIN console
+  // iframe: standalone (or a cross-origin framer, where postMessage to our own
+  // origin could never be delivered) hostNavigate returns false so callers keep
+  // the native new-window anchor. The payload is structured (target + params)
+  // and posted to the console origin — the host builds its own route, so row
+  // data can't smuggle a path. The same-origin gate reads parent.location.origin
+  // in a try/catch (a cross-origin parent throws under the same-origin policy).
+  assert.match(js, /window\.parent\.location\.origin === window\.location\.origin/);
+  assert.match(js, /const NANO_EMBEDDED =/);
+  assert.match(js, /function hostNavigate\(target, params\)/);
+  assert.match(js, /if \(!NANO_EMBEDDED\) return false;/);
+  assert.match(
+    js,
+    /window\.parent\.postMessage\(\s*\{\s*type:\s*"nano-navigate",\s*target:\s*target,\s*params:\s*params\s*\}\s*,\s*window\.location\.origin\s*\)/,
+  );
+  // The theme bridge reuses the same embed flag (no second window.parent probe).
+  assert.match(js, /if \(NANO_EMBEDDED\) \{/);
 });
 
 test("the renderer honours numeric actionForm fields", async () => {

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

@@ -608,7 +608,36 @@ function applyTheme(msg) {
     }
   }
 }
-if (window.parent && window.parent !== window) {
+// True when this app runs inside the Nano console's same-origin iframe (vs a
+// standalone CLI run). Gates the theme bridge below AND in-host link navigation:
+// embedded, a processExplorer link routes the console in place; standalone, the
+// link keeps its native new-window behavior. The same-origin probe matters: a
+// cross-origin framer is also window.parent, but postMessage to our own origin
+// would never reach it and hostNavigate would still preventDefault the link —
+// so a cross-origin embed must fall through to the native _blank anchor. Reading
+// parent.location.origin throws under the same-origin policy for a cross-origin
+// parent, so the try/catch is the origin gate.
+const NANO_EMBEDDED = (() => {
+  if (!window.parent || window.parent === window) return false;
+  try {
+    return window.parent.location.origin === window.location.origin;
+  } catch {
+    return false;
+  }
+})();
+
+// Ask the framing console to navigate in-host. Returns true when a message was
+// posted (embedded) so the caller can suppress the native anchor; false
+// standalone so it falls through to the new-window <a>. The payload is
+// structured (target + params), never a raw href — the console constructs its
+// own route, so app/row data can't smuggle a path or scheme across the boundary.
+function hostNavigate(target, params) {
+  if (!NANO_EMBEDDED) return false;
+  window.parent.postMessage({ type: "nano-navigate", target: target, params: params }, window.location.origin);
+  return true;
+}
+
+if (NANO_EMBEDDED) {
   window.addEventListener("message", (ev) => {
     // Same-origin proxy (posture A): only trust a message from the framing
     // parent AND from our own origin. ev.source alone is insufficient — a
@@ -723,8 +752,12 @@ function renderText(node) {
 //      non-empty key (after trimming surrounding whitespace) produces a link.
 //      Unknown link kinds fall back to plain text so an unrecognised schema
 //      can't render a broken anchor.
-// Both open in a new tab with rel=noopener noreferrer so the opened page can't
-// reach window.opener. Shared by the top-level grid and child grids.
+// The external linkField anchor always opens in a new tab (rel=noopener
+// noreferrer). The processExplorer anchor does too when the app runs
+// standalone, but when embedded in the console a plain click instead routes the
+// host's own explorer view in place via the nano-navigate postMessage bridge
+// (a modified/middle click keeps the new-tab behavior). 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) {
@@ -745,7 +778,22 @@ function gridCell(col, row) {
       return el(
         "td",
         {},
-        el("a", { class: "pc-link", href, target: "_blank", rel: "noopener noreferrer" }, text),
+        el("a", {
+          class: "pc-link",
+          href,
+          target: "_blank",
+          rel: "noopener noreferrer",
+          // Embedded in the console a plain primary click routes the host's
+          // explorer in place (via the nano-navigate bridge) instead of opening
+          // a new window. A non-primary button (middle/right = new-tab/context
+          // intent), a modified click (⌘/ctrl/shift/alt = new-tab intent) and
+          // any standalone run fall through to the native anchor above.
+          onclick: (ev) => {
+            if (ev.button !== 0) return;
+            if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
+            if (hostNavigate("processExplorer", { instance: keyStr })) ev.preventDefault();
+          },
+        }, text),
       );
     }
   }

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

@@ -6,6 +6,7 @@ import assert from "node:assert/strict";
 import { mountSurfaces } from "./surfaces.ts";
 import type { EngineClient, HostContext, HttpRequest, HttpResponse } from "../host.ts";
 import { DataLayer } from "./datasource.ts";
+import { createLogger } from "../logger.ts";
 
 function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurfaces>[0] {
   const host: HostContext = {
@@ -53,7 +54,7 @@ const fakeApp: Parameters<typeof mountSurfaces>[1] = {
   data: new DataLayer(new Map(), undefined, {}),
   engine: fakeEngine,
   env: () => undefined,
-  log: () => {},
+  log: createLogger(() => {}),
 };
 
 async function render(route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> }): Promise<string> {

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

@@ -1,4 +1,5 @@
 import { test } from "node:test";
+import { createLogger } from "../logger.ts";
 import assert from "node:assert/strict";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import type { EngineClient, HostContext, HttpRequest } from "../host.ts";
@@ -46,7 +47,9 @@ function fakeApp(): { app: AppApi; calls: EngineCall[]; logs: Array<{ level: str
     data: new DataLayer(new Map(), undefined, {}),
     engine,
     env: () => undefined,
-    log: (level: string, msg: string) => logs.push({ level, msg }),
+    log: createLogger((level: string, msg: string) => {
+      logs.push({ level, msg });
+    }),
   };
   return { app, calls, logs };
 }

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

@@ -1,4 +1,5 @@
 import { test } from "node:test";
+import { createLogger } from "../logger.ts";
 import assert from "node:assert/strict";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import type { EngineClient, EngineJob, HostContext, JobHandler, WorkerSubscription } from "../host.ts";
@@ -63,7 +64,7 @@ function makeApp(over: Partial<AppApi> = {}): AppApi {
     data: new DataLayer(new Map(), undefined, {}),
     engine: new MiniEngine(),
     env: (n) => env[n],
-    log: () => {},
+    log: createLogger(() => {}),
     ...over,
   };
 }
@@ -194,7 +195,63 @@ test("mountWorkers silently skips a connector-backed worker (mountConnectors own
   assert.ok(!logs.some((l) => l.msg.includes("neither a handler nor an llm")));
 });
 
-// ── AppJobHandler generics: optional In/Out type parameters ──────────────────────────────
+test("mountWorkers binds the job's correlation context onto the handler's app.log", async () => {
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx({ workers: [{ taskType: "charge", handler: "workers/charge.ts" }] }, engine);
+  const captured: Array<{ level: string; msg: string; fields?: Record<string, unknown> }> = [];
+  // The handler logs through the injected app; assert the runtime pre-bound the job context.
+  const handler: AppJobHandler = (_job, app) => {
+    app.log.info("charging", { amount: 100 });
+    return { ok: true };
+  };
+  ctx.host.importModule = async () => ({ default: handler });
+  const app = makeApp({
+    log: createLogger((level, msg, fields) => {
+      captured.push({ level, msg, fields });
+    }),
+  });
+  await mountWorkers(ctx, app);
+  await engine.deliver("charge", {
+    jobKey: "j-7",
+    jobType: "charge",
+    processInstanceKey: "pi-42",
+    elementId: "Task_Charge",
+    variables: {},
+  });
+  assert.equal(captured.length, 1);
+  assert.equal(captured[0].level, "info");
+  assert.equal(captured[0].msg, "charging");
+  assert.deepEqual(
+    { ...captured[0].fields },
+    {
+      jobKey: "j-7",
+      jobType: "charge",
+      processInstanceKey: "pi-42",
+      elementId: "Task_Charge",
+      amount: 100,
+    },
+  );
+});
+
+test("mountWorkers omits absent instance/element from the bound log context", async () => {
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx({ workers: [{ taskType: "ping", handler: "workers/ping.ts" }] }, engine);
+  const captured: Array<Record<string, unknown> | undefined> = [];
+  const handler: AppJobHandler = (_job, app) => {
+    app.log.warn("no instance");
+  };
+  ctx.host.importModule = async () => ({ default: handler });
+  const app = makeApp({
+    log: createLogger((_level, _msg, fields) => {
+      captured.push(fields);
+    }),
+  });
+  await mountWorkers(ctx, app);
+  await engine.deliver("ping", { jobKey: "j-1", jobType: "ping", variables: {} });
+  assert.equal(captured.length, 1);
+  assert.deepEqual({ ...captured[0] }, { jobKey: "j-1", jobType: "ping" });
+});
+
 // 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 () => {

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

@@ -72,6 +72,20 @@ function isAppJobHandler(value: unknown): value is AppJobHandler {
   return typeof value === "function";
 }
 
+/**
+ * Hand a handler an {@link AppApi} whose `log` is bound to the job's correlation context, so every
+ * line the handler emits self-tags with `{ jobKey, jobType, processInstanceKey, elementId }` without
+ * the author threading it. Undefined fields (e.g. a job dispatched without an instance) are omitted
+ * so the bound context stays clean. The rest of the API is shared by reference — only `log` is
+ * per-job.
+ */
+function withJobLog(app: AppApi, job: EngineJob): AppApi {
+  const bindings: Record<string, unknown> = { jobKey: job.jobKey, jobType: job.jobType };
+  if (job.processInstanceKey !== undefined) bindings.processInstanceKey = job.processInstanceKey;
+  if (job.elementId !== undefined) bindings.elementId = job.elementId;
+  return { ...app, log: app.log.child(bindings) };
+}
+
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order:
  *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)
@@ -167,7 +181,7 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
     const wrapped: JobHandler = (job) =>
       runInJobContext(
         { instanceKey: job.processInstanceKey, elementId: job.elementId, jobType },
-        () => handler(job, app),
+        () => handler(job, withJobLog(app, job)),
       );
     const sub = await ctx.engine.registerWorker(jobType, wrapped, {
       workerName: `${ctx.manifest.id}:${jobType}`,

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

@@ -304,6 +304,28 @@ test("task-inbox /api/complete returns 400 on a malformed JSON body", async () =
   }
 });
 
+test("app.log is an app-level structured logger routed to the host sink", async () => {
+  const dir = await makeFixture();
+  const logs: Array<{ level: string; msg: string; fields?: Record<string, unknown> }> = [];
+  const host = createNodeHost({ cwd: dir, log: (level, msg, fields) => logs.push({ level, msg, fields }) });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  app.log.info("booting", { pid: 1 });
+  assert.deepEqual(
+    // `fields` is the merged bag, deliberately a null-prototype object (untrusted-key hardening);
+    // spread it so the assertion compares contents, not prototype.
+    logs.filter((l) => l.msg === "booting").map((l) => ({ ...l, fields: { ...l.fields } })),
+    [{ level: "info", msg: "booting", fields: { pid: 1 } }],
+  );
+  // ergonomic methods + child binding are present on the handle logger
+  const bound = app.log.child({ region: "eu" });
+  bound.warn("slow");
+  assert.deepEqual(
+    logs.filter((l) => l.msg === "slow").map((l) => ({ ...l, fields: { ...l.fields } })),
+    [{ level: "warn", msg: "slow", fields: { region: "eu" } }],
+  );
+});
+
 test("resolvePort prefers explicit, then $PORT, then 8090; rejects bad $PORT", () => {
   assert.equal(resolvePort(3000, "9999"), 3000);
   assert.equal(resolvePort(undefined, "9999"), 9999);

package/src/runtime/core/runtime.ts

@@ -13,6 +13,7 @@ import { deployModels } from "./modules/deploy.ts";
 import type { TemplateSource } from "./modules/templates.ts";
 import { provisionData, DataLayer } from "./modules/datasource.ts";
 import { installExecStore, type JobExecContext } from "./execContext.ts";
+import { createLogger, type Logger } from "./logger.ts";
 import { mountWorkers } from "./modules/workers.ts";
 import { mountConnectors } from "./modules/connectors.ts";
 import { mountSurfaces } from "./modules/surfaces.ts";
@@ -99,6 +100,10 @@ export interface UrbanApp {
   stop(): Promise<void>;
   /** A structured snapshot of what is mounted. */
   inspect(): Record<string, unknown>;
+  /** An app-level structured {@link Logger} for the entrypoint (`main.ts`). It carries no
+   * per-request/per-job correlation (worker handlers and route delegates get a child logger bound
+   * to their job/request context via `AppApi.log`); use it for boot/shutdown lifecycle lines. */
+  readonly log: Logger;
   /** The provisioned data layer (available after start when `data` is mounted). */
   readonly data: DataLayer | undefined;
   readonly security: SecurityPolicy | undefined;
@@ -123,6 +128,11 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
   };
   const ctx = { manifest, host, engine, root, templates: opts.templates };
 
+  // One app-level structured logger over the host sink, shared by the entrypoint (exposed as
+  // `app.log`) and the per-invocation `AppApi.log` (workers/route delegates `child()` it with their
+  // correlation context).
+  const appLog = createLogger((l, m, f) => host.log(l, m, f));
+
   // Install the ambient job-execution store once per process (idempotent) so worker dispatch can
   // stamp write-provenance onto DataLayer inserts. Absent-safe: a host without `createAsyncStore`
   // leaves provenance capture disabled.
@@ -173,6 +183,7 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
   const app: UrbanApp = {
     manifest,
     root,
+    log: appLog,
     get data() {
       return data;
     },
@@ -197,7 +208,7 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           engine,
           sdk: engineSdk(engine),
           env: (n) => host.env(n),
-          log: (l, m, f) => host.log(l, m, f),
+          log: appLog,
         };
 
         if (flags.workers) {

package/src/runtime/devserver.test.ts

@@ -3,6 +3,7 @@ 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";
+import { createLogger } from "./core/logger.ts";
 
 const delay = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
 
@@ -226,6 +227,7 @@ function fakeApp(stops: string[], id: string): UrbanApp {
       stops.push(id);
     },
     inspect: () => ({ app: id }),
+    log: createLogger(() => {}),
     data: undefined,
     security: undefined,
     httpPort: undefined,

package/src/runtime/engine/nanosdk.ts

@@ -138,7 +138,7 @@ export interface NanoSdkClient {
   close?(): void | Promise<void>;
 }
 
-type Log = (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
+type Log = (level: "debug" | "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
 
 /**
  * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,

package/src/runtime/index.ts

@@ -54,6 +54,8 @@ export type {
   WorkerSubscription,
 } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
+// Structured logging surface (see core/logger.ts): the shape of `AppApi.log`.
+export type { Logger, LogLevel, LogFields } from "./core/logger.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.

package/src/toolkit/scaffold/operations.ts

@@ -50,7 +50,9 @@ export function renderOperationStub(operationId: string, dir: string = DEFAULT_O
     `\n` +
     `export default defineOperation(${key}, async (input, app) => {\n` +
     `  // \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
-    `  // through the injected \`app\` API. Return \`{ status?, headers?, body? }\` (or nothing → 204).\n` +
+    `  // through the injected \`app\` API. Structured logs via \`app.log.info("…", { … })\` are\n` +
+    `  // auto-tagged with this request's { method, path, operationId } (ADR 0061).\n` +
+    `  // Return \`{ status?, headers?, body? }\` (or nothing → 204).\n` +
     `  throw new NotImplemented(${key});\n` +
     `});\n`
   );

package/src/toolkit/scaffold/workers.ts

@@ -101,6 +101,8 @@ export function renderWorkerStub(
     varsNote +
     `\n` +
     `  // Reach app state and services through the injected \`app\` API.\n` +
+    `  // Structured logs: \`app.log.info("done", { … })\` — auto-tagged with this job's\n` +
+    `  // { jobKey, jobType, processInstanceKey, elementId } (ADR 0061).\n` +
     `  throw new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
     `};\n` +
     `\n` +

package/src/worker.ts

@@ -19,3 +19,4 @@
 export type { AppJobHandler } from "./runtime/core/modules/workers.ts";
 export type { EngineJob, JobHandler } from "./runtime/core/host.ts";
 export type { AppApi } from "./runtime/core/context.ts";
+export type { Logger, LogLevel, LogFields } from "./runtime/core/logger.ts";