@nanobpm/urban 0.77.3 → 0.78.0

package/src/runtime/index.ts

@@ -214,6 +214,71 @@ export type {
   LineageStoreOptions,
 } from "./core/modules/lineage-store.ts";
 
+// ─────────────────────────────────────────── Read models ────────────────────────────────────────
+// The declare-once, compile-to-both derived read-model primitive (ADR 0065): a closed expression DSL
+// (`col`/`lit`/comparisons/`and`/`or`/`not`/`caseWhen`/`exists`) declared ONCE via `defineReadModel`,
+// compiled to BOTH a SQLite VIEW select-list (`compileToSqlSelect`) and an in-process TS function
+// (`compileToFn`) from the SAME AST, plus the framework-derived managed VIEW DDL and the parity guard
+// that replaces per-projection hand-written parity tests.
+//
+// SIBLING REGISTRATION POINTS (ADR 0065 rollout — see core/read-model.ts for the full seam docs):
+//   • `readModelRegistry`  — register a `defineReadModel(...)` result; the boot path (core/modules/
+//     workers.ts) applies its managed VIEW. The `writer-source-inversion` task registers here.
+//   • `projectionRegistry` — register a canonical engine-truth projection NAME usable in `exists(...)`.
+//     The `canonical-projections` task registers `urban_open_user_tasks` / `urban_instance_state`.
+export {
+  and,
+  assertReadModelParity,
+  assertSqlIdentifier,
+  caseWhen,
+  col,
+  compileToFn,
+  compileToSqlSelect,
+  defineReadModel,
+  deriveReadModelViewDdl,
+  eq,
+  exists,
+  gt,
+  gte,
+  lit,
+  lt,
+  lte,
+  neq,
+  not,
+  or,
+  pcol,
+  ProjectionRegistry,
+  projectionRegistry,
+  ReadModelRegistry,
+  readModelRegistry,
+  when,
+} from "./core/read-model.ts";
+export type {
+  AndExpr,
+  BaseRow,
+  CaseExpr,
+  ColExpr,
+  CompareExpr,
+  CompareOp,
+  DerivationFn,
+  ExistsExpr,
+  Expr,
+  Literal,
+  LitExpr,
+  NotExpr,
+  OrExpr,
+  ParityDb,
+  ParityOptions,
+  ParitySample,
+  ProjColExpr,
+  ProjectionRows,
+  ProjectionSource,
+  ReadModel,
+  ReadModelDecl,
+  SqlCompileOptions,
+  WhenClause,
+} from "./core/read-model.ts";
+
 // Phase — the framework-level *domain phase* primitive (issue #266): derive "which phase is this
 // instance in?" from the BPMN scope hierarchy + write-provenance (Tier 0, zero declaration), an
 // optional `nano:phase` override (Tier 1), and a lineage rollup for the epic frontier (Tier 2).

package/src/toolkit/addConnector.test.ts

@@ -67,6 +67,24 @@ test("addConnector wires a pack-backed worker + a connection into nano.app.json"
   });
 });
 
+test("addConnector preserves the manifest's existing indentation (no lint reformat)", async () => {
+  // Regression (nano-ide#454): the scaffold's Biome config formats nano.app.json with tabs, so a
+  // hard-coded 2-space rewrite here would turn `npm run lint` red the moment a connector is
+  // enabled in a fresh app. addConnector must round-trip the manifest's own indentation, like
+  // `urban gen` does via detectJsonIndent.
+  const tabManifest = `${JSON.stringify({ schemaVersion: 1, id: "t", name: "T" }, null, "\t")}\n`;
+  const io = memIO({ ...baseFiles(), "app/nano.app.json": tabManifest });
+  await addConnector({ root: "app", pkg: PKG, io });
+  const written = io.files["app/nano.app.json"];
+  assert.match(written, /\n\t"workers"/, "tab indentation is preserved");
+  assert.doesNotMatch(written, /\n {2}"workers"/, "no 2-space indentation was introduced");
+
+  const twoSpace = `${JSON.stringify({ schemaVersion: 1, id: "t", name: "T" }, null, 2)}\n`;
+  const io2 = memIO({ ...baseFiles(), "app/nano.app.json": twoSpace });
+  await addConnector({ root: "app", pkg: PKG, io: io2 });
+  assert.match(io2.files["app/nano.app.json"], /\n {2}"workers"/, "2-space indentation is preserved");
+});
+
 test("addConnector is idempotent — re-running does not duplicate entries", async () => {
   const io = memIO(baseFiles());
   await addConnector({ root: "app", pkg: PKG, io });

package/src/toolkit/addConnector.ts

@@ -14,6 +14,7 @@
 
 import type { GenIO } from "./gen.ts";
 import { errorMessage, isRecord } from "../runtime/core/guards.ts";
+import { detectJsonIndent } from "./scaffold.ts";
 
 /** A config field a pack declares (subset of ext-types `ConfigField`). */
 interface PackConfigField {
@@ -116,13 +117,15 @@ export async function addConnector(opts: AddConnectorOptions): Promise<AddConnec
   if (!(await io.exists(appManifestPath))) {
     throw new Error(`no ${manifestFile} at ${appManifestPath} — run this inside an Urban app.`);
   }
+  let appRaw: string;
   let app: {
     workers?: { taskType?: string; connector?: string; connection?: string; handler?: string; llm?: string }[];
     connections?: Record<string, Record<string, unknown>>;
     [k: string]: unknown;
   };
   try {
-    app = JSON.parse(await io.readText(appManifestPath));
+    appRaw = await io.readText(appManifestPath);
+    app = JSON.parse(appRaw);
   } catch (err) {
     throw new Error(`failed to parse ${appManifestPath}: ${errorMessage(err)}`);
   }
@@ -223,7 +226,10 @@ export async function addConnector(opts: AddConnectorOptions): Promise<AddConnec
     wired.push({ taskType: spec.type, alreadyPresent: false });
   }
 
-  await io.writeText(appManifestPath, JSON.stringify(app, null, 2) + "\n");
+  // Preserve the manifest's own indentation (default tab, matching the scaffold's Biome config)
+  // so enabling a connector never reformats nano.app.json out from under `npm run lint` — the same
+  // fidelity `urban gen` gives via detectJsonIndent, kept as the single source of truth.
+  await io.writeText(appManifestPath, `${JSON.stringify(app, null, detectJsonIndent(appRaw))}\n`);
 
   return {
     packId: pack.id,

package/src/toolkit/derivers/generated-lint.test.ts

@@ -149,7 +149,7 @@ function lintUnderScaffold(
   biomeBin: string,
   dirs: string[],
 ): { status: number | null; stdout: string; stderr: string } {
-  const templateBiome = JSON.parse(readFileSync(join(templateDir, "biome.json"), "utf8"));
+  const templateBiome = JSON.parse(readFileSync(join(templateDir, "_biome.json"), "utf8"));
   // Copy the scaffold's GritQL plugin (bans `as` assertions) next to the config so its relative
   // path resolves, then reuse the template's exact ruleset — force-scoped to the generated dirs so
   // the guard tracks the scaffold standard without depending on the template's own `includes`.
@@ -320,7 +320,7 @@ function lintWithTemplateConfigVerbatim(
   templateDir: string,
   biomeBin: string,
 ): { status: number | null; stdout: string; stderr: string } {
-  const templateBiome = JSON.parse(readFileSync(join(templateDir, "biome.json"), "utf8"));
+  const templateBiome = JSON.parse(readFileSync(join(templateDir, "_biome.json"), "utf8"));
   cpSync(join(templateDir, "plugins"), join(work, "plugins"), { recursive: true });
   const config = { ...templateBiome, $schema: undefined, root: true };
   writeFileSync(join(work, "biome.json"), `${JSON.stringify(config, null, "\t")}\n`);

package/src/toolkit/scaffold/operations.test.ts

@@ -34,6 +34,49 @@ test("renderOperationStub adjusts the generated-import depth for a nested api.di
   assert.match(stub, /import \{ defineOperation \} from "\.\.\/\.\.\/nano-generated\/operations\.ts";/);
 });
 
+test("operation stub is lint-clean under the scaffold config: tab-indented, both params referenced", () => {
+  // Guards the same two failure modes as the worker stub (nano-ide#454): the scaffold's Biome
+  // config formats with tabs and enables correctness/noUnusedFunctionParameters, so a
+  // space-indented body or an unused `input`/`app` makes a freshly generated operation fail the
+  // app's own `biome check`. Body lines must be tab-indented and both params read before the
+  // author fills in the body.
+  const stub = renderOperationStub("getInvoice");
+  const bodyLines = stub
+    .split("\n")
+    .filter((l) => l.startsWith(" ") || l.startsWith("\t"));
+  assert.ok(bodyLines.length > 0, "the stub has an indented body");
+  for (const line of bodyLines) {
+    assert.ok(line.startsWith("\t"), `body line is tab-indented, not space-indented: ${line}`);
+  }
+  assert.match(
+    stub,
+    /app\.log\.warn\("operation not implemented", \{\n\t\toperationId: "getInvoice",\n\t\tmethod: input\.req\.method,\n\t\}\);/,
+  );
+  // Guard the same Biome-width defect class the reviewer flagged (nano-ide#454): the generated
+  // stub is linted by the scaffold's `operations/**/*.ts` include at Biome's default 80-column
+  // width (tab = 2 columns), so a single-line log call that overruns 80 makes `urban gen` emit a
+  // file `biome check` immediately reports as needing formatting. Assert every non-comment code
+  // line fits, so any future template change that reintroduces an over-wide line fails here.
+  for (const line of stub.split("\n")) {
+    if (line.trim().startsWith("//")) continue;
+    const leadingTabs = line.length - line.replace(/^\t+/, "").length;
+    const width = leadingTabs * 2 + (line.length - leadingTabs);
+    assert.ok(width <= 80, `generated code line exceeds Biome's 80-column width (${width}): ${line}`);
+  }
+  // Guard the PII/credential-leak defect class (nano-ide#454): the stub must reference a
+  // non-sensitive identifier, never serialize the whole validated `input` (which carries
+  // params/query/body/req) into the NDJSON log line.
+  assert.doesNotMatch(stub, /app\.log\.warn\([^)]*,\s*input\s*\}/);
+});
+
+test("operation stub logs a non-sensitive identifier, not the raw input payload", () => {
+  // Red/Green guard for the operation-stub log-leak: an unedited 501 handler must not emit the
+  // validated request body/params/query (potential credentials or PII) to structured logs.
+  const stub = renderOperationStub("createInvoice");
+  assert.doesNotMatch(stub, /,\s*input\s*\}\)/);
+  assert.match(stub, /method: input\.req\.method/);
+});
+
 test("planOperationScaffold plans one stub per declared operationId", () => {
   const plans = planOperationScaffold(doc);
   const byId = Object.fromEntries(plans.map((p) => [p.operationId, p.handlerPath]));

package/src/toolkit/scaffold/operations.ts

@@ -44,16 +44,21 @@ export function renderOperationStub(operationId: string, dir: string = DEFAULT_O
     `// (ADR 0059). This file is yours to edit — \`urban gen\` will never overwrite it. The\n` +
     `// generated controller (nano-generated/controller.ts) imports this default export and\n` +
     `// type-checks it against the spec, so the signature cannot drift. Implement the body below\n` +
-    `// (the validated \`{ req, params, query, body }\` input + the injected \`app\`) and delete the throw.\n` +
+    `// (the validated \`{ req, params, query, body }\` input + the injected \`app\`), replacing the\n` +
+    `// guard warn + throw.\n` +
     `import { NotImplemented } from "@nanobpm/urban";\n` +
     `import { defineOperation } from ${JSON.stringify(`${up}nano-generated/operations.ts`)};\n` +
     `\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. 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` +
+    `\t// \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
+    `\t// through the injected \`app\` API. Structured logs via \`app.log.info("…", { … })\` are\n` +
+    `\t// auto-tagged with this request's { method, path, operationId } (ADR 0061).\n` +
+    `\t// Return \`{ status?, headers?, body? }\` (or nothing → 204). Replace the two lines below.\n` +
+    `\tapp.log.warn("operation not implemented", {\n` +
+    `\t\toperationId: ${key},\n` +
+    `\t\tmethod: input.req.method,\n` +
+    `\t});\n` +
+    `\tthrow new NotImplemented(${key});\n` +
     `});\n`
   );
 }

package/src/toolkit/scaffold/workers.test.ts

@@ -7,7 +7,7 @@ import {
   type ScaffoldWorker,
 } from "./workers.ts";
 import type { ModelSource } from "../derivers/worker-io.ts";
-import { scaffoldWorkers } from "../scaffold.ts";
+import { detectJsonIndent, scaffoldWorkers } from "../scaffold.ts";
 import type { GenIO } from "../gen.ts";
 
 // A service task with a data-envelope in/out contract; `type` is the taskType, and the
@@ -53,6 +53,43 @@ test("untyped stub imports no generated types and uses bare AppJobHandler", () =
   assert.match(stub, /const handler: AppJobHandler = async \(job, app\) =>/);
 });
 
+test("stub is lint-clean under the scaffold config: tab-indented, both params referenced", () => {
+  // Guards the two ways `urban gen`'s stub used to fail a fresh scaffold's own `biome check`
+  // (nano-ide#451): space indentation (Biome defaults to tabs) and unused `job`/`app` params
+  // (correctness/noUnusedFunctionParameters). Body lines must be tab-indented and both params
+  // must be read before the author fills in the body.
+  const stub = renderWorkerStub("greet.hello", false, false);
+  const bodyLines = stub.split("\n").filter((l) => l.startsWith(" ") || l.startsWith("\t"));
+  assert.ok(bodyLines.length > 0, "the stub has an indented body");
+  for (const line of bodyLines) {
+    assert.ok(line.startsWith("\t"), `body line is tab-indented, not space-indented: ${line}`);
+  }
+  assert.match(stub, /app\.log\.warn\("worker not implemented", \{ jobKey: job\.jobKey \}\)/);
+});
+
+test("detectJsonIndent reuses tab/space width but clamps to JSON.stringify's 10-char cap", () => {
+  assert.equal(detectJsonIndent('{\n\t"a": 1\n}'), "\t");
+  assert.equal(detectJsonIndent('{\n  "a": 1\n}'), "  ");
+  assert.equal(detectJsonIndent("{}"), "\t", "no indentation falls back to a tab");
+  // JSON.stringify silently truncates a string `space` to 10 chars, so a wider space indent must
+  // be clamped rather than promising a fidelity the serializer cannot honor.
+  const wide = `{\n${" ".repeat(12)}"a": 1\n}`;
+  const indent = detectJsonIndent(wide);
+  assert.equal(indent, " ".repeat(10));
+  assert.equal(JSON.stringify({ a: 1 }, null, indent), JSON.stringify({ a: 1 }, null, wide.match(/\n( +)/)?.[1]));
+  // The 10-char cap is not space-only: an overlong *tab* indent must clamp too, or the rewrite
+  // would silently differ from an 11+-tab input (JSON.stringify truncates any string `space`).
+  const wideTabs = `{\n${"\t".repeat(12)}"a": 1\n}`;
+  const tabIndent = detectJsonIndent(wideTabs);
+  assert.equal(tabIndent, "\t".repeat(10));
+  assert.equal(JSON.stringify({ a: 1 }, null, tabIndent), JSON.stringify({ a: 1 }, null, wideTabs.match(/\n(\t+)/)?.[1]));
+  // Line-ending agnostic: the width must be detected regardless of terminator, or a space-indented
+  // Windows/old-Mac manifest would be rewritten at the tab fallback width instead of preserved.
+  assert.equal(detectJsonIndent('{\r\n  "a": 1\r\n}'), "  ", "CRLF space indent preserved");
+  assert.equal(detectJsonIndent('{\r  "a": 1\r}'), "  ", "bare-CR space indent preserved");
+  assert.equal(detectJsonIndent('{\n\r  "a": 1\n\r}'), "  ", "LFCR space indent preserved");
+});
+
 test("typed-out-only stub fills In with the open default", () => {
   const stub = renderWorkerStub("demo.out", false, true);
   assert.match(stub, /import type \{ WorkerOutputs \} from/);
@@ -183,6 +220,21 @@ test("scaffoldWorkers --write creates the stub and patches the manifest once", a
   assert.ok(io.files["/app/nano.app.json"].endsWith("\n"), "manifest ends with newline");
 });
 
+test("scaffoldWorkers preserves the manifest's own indentation when wiring (nano-ide#451)", async () => {
+  // `urban gen` used to reserialize nano.app.json with a hard-coded 2-space indent, clobbering
+  // the tab-indented scaffold and breaking its own `biome check`. The patch must round-trip the
+  // file's existing indentation instead.
+  for (const indent of ["\t", "  "]) {
+    const files = appFixture();
+    files["/app/nano.app.json"] = `${JSON.stringify(JSON.parse(files["/app/nano.app.json"]), null, indent)}\n`;
+    const io = memIO(files);
+    await scaffoldWorkers({ root: "/app", io, write: true });
+    const patched = io.files["/app/nano.app.json"];
+    const firstIndent = patched.match(/\n([ \t]+)\S/)?.[1];
+    assert.equal(firstIndent, indent, `indentation preserved (${JSON.stringify(indent)})`);
+  }
+});
+
 test("scaffoldWorkers never clobbers an existing stub (keeps it), still wires it", async () => {
   const files = appFixture();
   files["/app/workers/t-new/worker.ts"] = "// hand-edited, do not touch\n";

package/src/toolkit/scaffold/workers.ts

@@ -87,23 +87,28 @@ export function renderWorkerStub(
   else if (typedOut) generic = `<Record<string, unknown>, WorkerOutputs[${key}]>`;
 
   const varsNote = typedIn
-    ? `  // \`job.variables\` is typed as WorkerInputs[${key}].`
-    : `  // \`job.variables\` is an open Record<string, unknown> (no declared input type).`;
+    ? `\t// \`job.variables\` is typed as WorkerInputs[${key}].`
+    : `\t// \`job.variables\` is an open Record<string, unknown> (no declared input type).`;
 
+  // The stub arrives lint-clean under the scaffold's own Biome config: tab-indented, and
+  // referencing both `job` and `app` (via the warn line) so `noUnusedFunctionParameters`
+  // does not fire before the author has filled in the body.
   return (
     `// Handler stub for the \`${taskType}\` service task, scaffolded from the model (ADR 0056).\n` +
     `// This file is yours to edit — \`urban gen\` will never overwrite it. Implement the body\n` +
-    `// below (use \`app.data.table(...)\` for state) and delete the throw.\n` +
+    `// below (use \`app.data.table(...)\` for state), replacing the guard warn + throw so the\n` +
+    `// "worker not implemented" warning does not survive into a working handler.\n` +
     `import type { AppJobHandler } from "@nanobpm/urban/worker";\n` +
     generatedImport +
     `\n` +
     `const handler: AppJobHandler${generic} = async (job, app) => {\n` +
     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` +
+    `\t// Reach app state and services through the injected \`app\` API.\n` +
+    `\t// Structured logs: \`app.log.info("done", { … })\` — auto-tagged with this job's\n` +
+    `\t// { jobKey, jobType, processInstanceKey, elementId } (ADR 0061).\n` +
+    `\tapp.log.warn("worker not implemented", { jobKey: job.jobKey });\n` +
+    `\tthrow new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
     `};\n` +
     `\n` +
     `export default handler;\n`

package/src/toolkit/scaffold.ts

@@ -14,6 +14,27 @@ import {
 import { planOperationScaffold } from "./scaffold/operations.ts";
 import { parseSpec } from "../openapi/spec.ts";
 
+/**
+ * Detect the indentation of a JSON document from its first indented line, so a rewrite can
+ * reuse it (`"\t"` or an N-space string) instead of hard-coding one style. Falls back to a tab
+ * — the scaffold's Biome default — when the file is empty/single-line or uses no indentation.
+ *
+ * Any indent — spaces or tabs — is clamped to 10 characters because `JSON.stringify` silently
+ * truncates a string `space` argument to 10; returning a wider prefix would promise a fidelity the
+ * serializer cannot honor (e.g. an 11+-tab manifest would be rewritten at a different width than
+ * its input). Tab indentation (the scaffold default) and any realistic width (2/4 spaces) are
+ * unaffected.
+ */
+export function detectJsonIndent(json: string): string {
+  // Anchor on any line terminator, not just `\n`, so the width is detected regardless of the
+  // manifest's line endings: LF (`\n`), CRLF (`\r\n`, where `\n` already precedes the indent),
+  // bare-CR old-Mac (`\r`), and LFCR (`\n\r`) all resolve to the indentation that follows.
+  const m = json.match(/[\r\n]([ \t]+)\S/);
+  if (!m) return "\t";
+  const indent = m[1];
+  return indent.length > 10 ? indent.slice(0, 10) : indent;
+}
+
 /** The manifest fields the scaffolder reads. */
 interface ScaffoldManifest {
   types?: Record<string, unknown>;
@@ -61,7 +82,11 @@ export async function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRu
   const manifestFile = opts.manifestFile ?? "nano.app.json";
   const manifestPath = joinPath(root, manifestFile);
 
-  const manifest: ScaffoldManifest = JSON.parse(await io.readText(manifestPath));
+  const manifestRaw = await io.readText(manifestPath);
+  const manifest: ScaffoldManifest = JSON.parse(manifestRaw);
+  // Preserve the manifest's own indentation when we patch it back (default tab, matching the
+  // scaffold's Biome config), so wiring a worker never reformats the file out from under lint.
+  const manifestIndent = detectJsonIndent(manifestRaw);
   const models = await readModels(root, io, manifest);
   const declaredTypeIds = Object.keys(manifest.types ?? {});
 
@@ -105,7 +130,7 @@ export async function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRu
       ...manifest,
       workers: [...(manifest.workers ?? []), ...wired],
     };
-    await io.writeText(manifestPath, `${JSON.stringify(withWorkers, null, 2)}\n`);
+    await io.writeText(manifestPath, `${JSON.stringify(withWorkers, null, manifestIndent)}\n`);
     manifestPatched = true;
   }