@nanobpm/urban 0.38.0 → 0.40.0

package/src/runtime/core/modules/api.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 { AppManifest } from "../manifest.ts";
@@ -36,7 +37,7 @@ const engine: EngineClient = {
 const data = new DataLayer(new Map(), undefined, {});
 
 function appFixture(): AppApi {
-  return { manifest: { schemaVersion: 1, id: "t", name: "T" }, data, engine, env: () => undefined, log: () => {} };
+  return { manifest: { schemaVersion: 1, id: "t", name: "T" }, data, engine, env: () => undefined, log: createLogger(() => {}) };
 }
 
 const spec = JSON.stringify({
@@ -88,6 +89,7 @@ function build(
   specText = spec,
   env: (v: string) => string | undefined = () => undefined,
   existsPaths: string[] = [],
+  app: AppApi = appFixture(),
 ): Built {
   const imported: string[] = [];
   const logs: Array<{ level: string; msg: string }> = [];
@@ -114,7 +116,7 @@ function build(
   const manifest: AppManifest = { schemaVersion: 1, id: "t", name: "T" };
   if (api) Reflect.set(manifest, "api", api);
   const ctx: RuntimeContext = { root: "/app", manifest, engine, host };
-  const handle = mountApi(ctx, appFixture());
+  const handle = mountApi(ctx, app);
   const router = makeRouter(handle.routes);
   return { router: (r) => Promise.resolve(router(r)), imported, logs, handle };
 }
@@ -137,6 +139,40 @@ test("no api binding → no routes (no-op for actions-only apps)", () => {
   return router(req("GET", "/app/api/invoices/1")).then((res) => assert.equal(res.status, 404));
 });
 
+test("a delegate's app.log is bound to the request's correlation context", async () => {
+  const captured: Array<{ level: string; msg: string; fields?: Record<string, unknown> }> = [];
+  const capturingApp: AppApi = {
+    manifest: { schemaVersion: 1, id: "t", name: "T" },
+    data,
+    engine,
+    env: () => undefined,
+    log: createLogger((level, msg, fields) => {
+      captured.push({ level, msg, fields });
+    }),
+  };
+  const handler: OperationHandler = (_input, app) => {
+    app.log.info("creating invoice", { amount: 5 });
+    return { status: 201, body: { id: "i1", amount: 5 } };
+  };
+  const { router } = build(
+    { spec: "openapi.json", dir: "operations" },
+    { "/app/operations/createInvoice": { default: handler } },
+    spec,
+    () => undefined,
+    [],
+    capturingApp,
+  );
+  const res = await router(req("POST", "/app/api/invoices", { body: JSON.stringify({ id: "i1", amount: 5 }) }));
+  assert.equal(res.status, 201);
+  assert.equal(captured.length, 1);
+  assert.equal(captured[0].level, "info");
+  assert.equal(captured[0].msg, "creating invoice");
+  assert.deepEqual(
+    { ...captured[0].fields },
+    { method: "POST", path: "/invoices", operationId: "createInvoice", amount: 5 },
+  );
+});
+
 test("routes an operation to its delegate with validated params + body", async () => {
   const seen: unknown[] = [];
   const handler: OperationHandler = (input) => {

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

@@ -640,8 +640,17 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     // required), so pass `undefined` to those handlers rather than leaking a parsed value through
     // a body-less type.
     const handlerBody = op.requestBodySchema !== undefined || op.requestBodyRequired ? body : undefined;
+    // Hand the delegate an AppApi whose `log` is bound to this request's correlation context, so its
+    // lines self-tag with `{ method, path, operationId }` without the author threading it.
+    const requestApp: AppApi = {
+      ...app,
+      log: app.log.child({ method, path: op.path, operationId: op.operationId }),
+    };
     try {
-      const result = await handler({ req, params: coercedParams, query: coercedQuery, body: handlerBody }, app);
+      const result = await handler(
+        { req, params: coercedParams, query: coercedQuery, body: handlerBody },
+        requestApp,
+      );
       if (!result) return { status: 204 };
       const status = result.status ?? 200;
       // Optional response validation (dev by default): warn-only, never blocks the response.

package/src/runtime/core/modules/cancel.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";
@@ -108,7 +109,9 @@ async function withHarness(engine: EngineClient, seedStatus = "converging"): Pro
     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/connectors.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";
@@ -83,7 +84,7 @@ function makeApp(env: Record<string, string> = {}): AppApi {
     data: new DataLayer(new Map(), undefined, {}),
     engine: new MiniEngine(),
     env: (n: string) => env[n],
-    log: () => {},
+    log: createLogger(() => {}),
   };
 }
 

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/artifact.ts

@@ -23,6 +23,25 @@ export interface Deriver<I> {
  * drop-in for the IDE's own codegen (ADR 0053). One drift domain, gitignored, never committed. */
 export const GENERATED_DIR = "nano-generated";
 
+/**
+ * Files that live in `GENERATED_DIR` but are NOT produced by `urban gen`. These are materialized by
+ * a different writer — the runtime SDK shims and the `urban data` / console-host dataops path, which
+ * derives the typed wrappers from the *live* DB (something `urban gen` can't do without a running
+ * datasource). `urban gen`'s stale-file sweep must own only what it emits, so it protects these by
+ * name: it never deletes them even though it didn't (re)write them this run. Basenames, relative to
+ * `GENERATED_DIR`. Keep in sync with the emitters' filename constants (DOMAIN_BINDINGS,
+ * WORKER_BINDINGS_TS, MESSAGE_BINDINGS_TS, DOMAIN_MODEL_JSON) + the `./data-sdk.ts`/`./worker-sdk.ts`
+ * shim imports the generated wrappers reference.
+ */
+export const RUNTIME_MATERIALIZED_ARTIFACTS: readonly string[] = [
+  "domain.ts",
+  "workers.ts",
+  "messages.ts",
+  "domain.json",
+  "data-sdk.ts",
+  "worker-sdk.ts",
+];
+
 /** Stable ordering so artifact lists compare deterministically. */
 export function sortArtifacts(a: DerivedArtifact[]): DerivedArtifact[] {
   return [...a].sort((x, y) => (x.path < y.path ? -1 : x.path > y.path ? 1 : 0));

package/src/toolkit/gen.test.ts

@@ -103,6 +103,59 @@ test("collectArtifacts touches no writes", async () => {
   assert.equal(Object.keys(io.files).length, before);
 });
 
+test("runGen sweeps stale files from nano-generated/ (write mode)", async () => {
+  const io = memIO(fixture());
+  // A stale artifact left by a prior gen (e.g. a renamed `data_sdk.ts` orphan) that this run does
+  // not re-emit. It must be removed so the app can't import a dead generated module.
+  io.files["/app/nano-generated/data_sdk.ts"] = "// stale, renamed away";
+  io.files["/app/nano-generated/old-worker-io.d.ts"] = "// stale";
+  const res = await runGen({ root: "/app", io });
+  assert.deepEqual(res.swept, [
+    "nano-generated/data_sdk.ts",
+    "nano-generated/old-worker-io.d.ts",
+  ]);
+  assert.ok(!("/app/nano-generated/data_sdk.ts" in io.files), "stale file removed");
+  assert.ok(!("/app/nano-generated/old-worker-io.d.ts" in io.files), "stale file removed");
+  // Current artifacts survive.
+  assert.ok("/app/nano-generated/worker-io.d.ts" in io.files, "fresh artifact kept");
+});
+
+test("runGen never sweeps runtime-materialized wrappers gen does not emit", async () => {
+  const io = memIO(fixture());
+  // The SDK shims + `urban data`/console dataops wrappers live in nano-generated/ but are not
+  // produced by `urban gen`; the app needs them at runtime, so the sweep must protect them.
+  for (const name of ["domain.ts", "workers.ts", "messages.ts", "domain.json", "data-sdk.ts", "worker-sdk.ts"]) {
+    io.files[`/app/nano-generated/${name}`] = `// runtime-materialized ${name}`;
+  }
+  const res = await runGen({ root: "/app", io });
+  assert.deepEqual(res.swept, [], "no runtime-materialized file swept");
+  for (const name of ["domain.ts", "workers.ts", "messages.ts", "domain.json", "data-sdk.ts", "worker-sdk.ts"]) {
+    assert.ok(`/app/nano-generated/${name}` in io.files, `${name} preserved`);
+  }
+});
+
+test("gen --check never sweeps (read-only)", async () => {
+  const io = memIO(fixture());
+  await runGen({ root: "/app", io });
+  io.files["/app/nano-generated/stale.ts"] = "// stale";
+  const res = await runGen({ root: "/app", io, check: true });
+  assert.deepEqual(res.swept, []);
+  assert.ok("/app/nano-generated/stale.ts" in io.files, "check mode leaves stale files untouched");
+});
+
+test("modelsOnly (urban derive) never sweeps nano-generated type-contract outputs", async () => {
+  const io = memIO(fixture());
+  // A prior `urban gen` wrote the type-contract outputs.
+  await runGen({ root: "/app", io });
+  assert.ok("/app/nano-generated/worker-io.d.ts" in io.files, "precondition: gen wrote outputs");
+  // `urban derive` (modelsOnly) derives only models — its artifacts carry no nano-generated/*, so
+  // the sweep must be a no-op here; otherwise it would wipe the type contracts above.
+  const res = await runGen({ root: "/app", io, modelsOnly: true });
+  assert.deepEqual(res.swept, []);
+  assert.ok("/app/nano-generated/worker-io.d.ts" in io.files, "derive preserved the type contracts");
+  assert.ok("/app/nano-generated/app.schema.sql" in io.files, "derive preserved the migrations");
+});
+
 // --- code-first model derivation (urban gen / urban derive) ---
 
 const GreetIn = envelope("GreetIn", { who: "string" });