@nanobpm/nano-workforce 0.70.2 → 0.72.0

package/scripts/check-contracts.ts

@@ -0,0 +1,151 @@
+// check-contracts — CI gate for the shared contract registry (issue #227, ADR 0004).
+//
+// The registry (`app/contracts.ts`) is the single source of truth for cross-cutting contracts. This
+// gate enforces the invariants that make a duplicate/synonymous contract a BUILD failure rather than
+// a silent runtime fallback (the #223 / nano-ide #234 failure mode):
+//
+//   1. EVERY config-family env key read anywhere in the app (`process.env.NANO_*`, `CAMUNDA_*`,
+//      `NANOBPMN_BASE_URL`, `PR_REVIEW_PORT`) MUST be declared in the ONE typed schema
+//      `ENV_CONTRACTS`. An undeclared config key is a second, unregistered source of truth — fail.
+//      The scan recognises all three read patterns the app uses: dot-access (`process.env.KEY`),
+//      string-literal bracket-access (`process.env["KEY"]`), and the `envVar("KEY")` helper
+//      (`app/version.ts`) — a config key smuggled in through any of them must still be declared.
+//   2. NO rejected synonym (a name we deliberately retired, e.g. `NANO_PR_BASE_URL`) may appear in
+//      code. Its reappearance is the #223 phantom-fallback cascade — fail.
+//   3. The registry must reconcile against itself: no two entries are synonyms, no rejected synonym
+//      leaked back into the registry (`reconcileRegistry`).
+//
+// Scope note: the env-key scan targets the config family (below), NOT every env var — infra reads
+// like `NODE_ENV` are not app contracts. `GITHUB_TOKEN`/`CAMUNDA_TOKEN` ARE declared (as secrets) so
+// the schema documents them, but they need no fallback default.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { reconcileRegistry } from "../app/contractReconcile.ts";
+import { ENV_CONTRACTS, rejectedEnvSynonyms } from "../app/contracts.ts";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+// The directories that hold app code (mirrors the `lint` glob in package.json).
+const CODE_DIRS = ["app", "operations", "workers", "pages", "components", "scripts", "e2e"];
+const CODE_FILES = ["main.ts"];
+
+// The config-family env-key prefixes/names that MUST be declared in ENV_CONTRACTS. Anything matching
+// this and not declared is an unregistered config source of truth.
+//
+// A config key is read one of three ways in this app, and all three must be held to the registry
+// invariant — otherwise a key smuggled in via `envVar("…")` or bracket-access silently bypasses the
+// gate (the exact blind spot that let NANO_PR_WEBHOOK_SECRET / NANO_AGENTIC* go undeclared):
+//   - dot-access:                 process.env.KEY
+//   - string-literal bracket:     process.env["KEY"] / process.env['KEY']
+//   - the envVar() helper:        envVar("KEY")  (app/version.ts)
+const CONFIG_KEY_MATCHERS: readonly RegExp[] = [
+  /\bprocess\.env\.([A-Z][A-Z0-9_]*)\b/g,
+  /\bprocess\.env\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\]/g,
+  /\benvVar\(\s*["']([A-Z][A-Z0-9_]*)["']\s*\)/g,
+];
+const CONFIG_FAMILY = /^(NANO_|NANOBPMN_|CAMUNDA_|PR_REVIEW_)/;
+// `GITHUB_TOKEN` is the one production credential read outside the config families (app/service.ts,
+// operations/startPlanFanout.ts). It is declared in ENV_CONTRACTS; enforce that declaration here so a
+// future removal from the registry while code still reads it trips the gate (issue #227).
+export const EXPLICIT_CONFIG_KEYS = new Set(["PR_REVIEW_PORT", "GITHUB_TOKEN"]);
+
+/** Every env-key name read in `src` via any supported pattern (dot-access, string-literal
+ * bracket-access, or the `envVar("KEY")` helper). Order-preserving, with duplicates, so a caller can
+ * report each read site's key against the registry. */
+export function envKeyReads(src: string): string[] {
+  const keys: string[] = [];
+  for (const matcher of CONFIG_KEY_MATCHERS) {
+    for (const m of src.matchAll(matcher)) keys.push(m[1]);
+  }
+  return keys;
+}
+
+// The registry module declares the keys and (in comments/strings) names the rejected synonyms, this
+// checker's own doc comment shows the read patterns it scans for, and this checker's test embeds
+// literal `process.env[…]` / `envVar(…)` fixtures — all would self-trip the scan, so they are exempt.
+const EXEMPT_FILES = new Set([
+  "app/contracts.ts",
+  "scripts/check-contracts.ts",
+  "scripts/check-contracts.test.ts",
+]);
+
+function walk(dir: string, out: string[]): void {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      if (entry === "node_modules" || entry === "nano-generated" || entry.startsWith(".")) continue;
+      walk(full, out);
+    } else if ([".ts", ".mts", ".cts"].includes(extname(full))) {
+      out.push(full);
+    }
+  }
+}
+
+/** Path of `file` relative to ROOT, normalised to POSIX separators so it matches the POSIX-style
+ * `EXEMPT_FILES` entries on every platform (Windows `join` yields backslashes — issue #229 review). */
+export function toPosixRel(file: string, root: string = ROOT): string {
+  return file.slice(root.length + 1).replaceAll("\\", "/");
+}
+
+function collectFiles(): string[] {
+  const files: string[] = [];
+  for (const d of CODE_DIRS) {
+    const full = join(ROOT, d);
+    try {
+      if (statSync(full).isDirectory()) walk(full, files);
+    } catch {
+      /* dir may not exist in every checkout */
+    }
+  }
+  for (const f of CODE_FILES) {
+    const full = join(ROOT, f);
+    try {
+      if (statSync(full).isFile()) files.push(full);
+    } catch {
+      /* optional */
+    }
+  }
+  return files;
+}
+
+function main(): void {
+  const declared = new Set(Object.keys(ENV_CONTRACTS));
+  const rejected = rejectedEnvSynonyms();
+  const errors: string[] = [];
+
+  for (const file of collectFiles()) {
+    const rel = toPosixRel(file);
+    if (EXEMPT_FILES.has(rel)) continue;
+    const src = readFileSync(file, "utf8");
+    for (const key of envKeyReads(src)) {
+      if (rejected.has(key)) {
+        errors.push(
+          `  ${rel}: reads retired synonym '${key}' — reuse the canonical key '${rejected.get(key)}'. ` +
+            `A retired synonym must never come back as a silent fallback (issue #223).`,
+        );
+        continue;
+      }
+      if (!CONFIG_FAMILY.test(key) && !EXPLICIT_CONFIG_KEYS.has(key)) continue;
+      if (!declared.has(key)) {
+        errors.push(
+          `  ${rel}: reads config env key '${key}' that is NOT declared in ENV_CONTRACTS ` +
+            `(app/contracts.ts). Declare it in the ONE typed schema so it can't become a synonym.`,
+        );
+      }
+    }
+  }
+
+  for (const finding of reconcileRegistry()) {
+    errors.push(`  registry: [${finding.kind}] ${finding.detail}`);
+  }
+
+  if (errors.length > 0) {
+    console.error(`check-contracts: contract-registry violations:\n${errors.join("\n")}`);
+    process.exit(1);
+  }
+
+  console.log(`check-contracts: OK (${declared.size} declared env keys, registry reconciles clean).`);
+}
+
+if (import.meta.main) main();

package/scripts/reconcile-contracts.test.ts

@@ -0,0 +1,38 @@
+// Coverage for the advisory-only reconcile pass's URL decoding (scripts/reconcile-contracts.ts, PR
+// #229). The pass is designed to NEVER fail the build. `fileUrlToPath` decodes NANO_APP_DB_URL, and a
+// literal `%` (or any malformed %-escape) makes `decodeURIComponent` throw — which would crash an
+// "advisory, never gate CI" script. Decoding is now best-effort, so a malformed URL degrades to the
+// raw path instead of throwing.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { fileUrlToPath } from "./reconcile-contracts.ts";
+
+test("fileUrlToPath: decodes a well-formed percent-escape", () => {
+  assertEquals(fileUrlToPath("file:./my%20app.db"), "./my app.db");
+});
+
+test("fileUrlToPath: a malformed percent-escape does not throw (best-effort)", () => {
+  // A bare `%` is not a valid escape; decodeURIComponent would throw. The pass must not crash — a
+  // successful call that returns the raw path proves the decode is best-effort.
+  assertEquals(fileUrlToPath("file:./100%done.db"), "./100%done.db");
+});
+
+test("fileUrlToPath: a non-file URL yields undefined", () => {
+  assertEquals(fileUrlToPath("postgres://localhost/db"), undefined);
+});
+
+test("fileUrlToPath: a malformed file:// URL yields undefined, never throws (PR #229)", () => {
+  // `new URL("file://…")` throws on a malformed authority/host. The advisory pass must degrade to
+  // undefined (best-effort: file simply not found) rather than crash a "never gate CI" script.
+  assertEquals(fileUrlToPath("file://%zz/bad host/db.sqlite"), undefined);
+});
+
+test("fileUrlToPath: strips a query/hash suffix on an opaque file: URL (PR #229)", () => {
+  // A valid SQLite-style URL carries connection params (`?mode=ro`). The opaque `file:` branch must
+  // drop the `?…`/`#…` suffix so the path resolves to a real on-disk file, else reconciliation is
+  // silently disabled by a path that never exists.
+  assertEquals(fileUrlToPath("file:./app.db?mode=ro"), "./app.db");
+  assertEquals(fileUrlToPath("file:./app.db#frag"), "./app.db");
+  assertEquals(fileUrlToPath("file:./app.db?mode=ro&cache=shared#x"), "./app.db");
+});
+

package/scripts/reconcile-contracts.ts

@@ -0,0 +1,104 @@
+// npm run reconcile:contracts — the contract reconciliation pass runner (issue #227, ADR 0004).
+//
+// A sibling to the L2 retro: read the whole blackboard (`agentic_blackboard`) plus the durable
+// contract registry (`app/contracts.ts`) and report synonyms / contradictions / mock-vs-real skew.
+// Advisory by design — it PRINTS a report (an escalation / merge candidate) and exits 0, so it can
+// run periodically without gating CI. The registry-only, mechanically-enforceable half is the hard
+// gate `scripts/check-contracts.ts`; this pass adds the blackboard-vs-registry view.
+//
+// It reads the app sqlite datasource (NANO_APP_DB_URL, default `file:./app.db`) directly through
+// node:sqlite. If the datasource or the blackboard table is absent, it still runs the static
+// registry reconciliation.
+
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { BLACKBOARD_TABLE } from "@nanobpm/agentic/blackboard";
+import {
+  type ContractSignal,
+  formatReconciliationReport,
+  reconcileContracts,
+} from "../app/contractReconcile.ts";
+import type { ContractCategory } from "../app/contracts.ts";
+
+function safeDecodeURIComponent(s: string): string {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    // Advisory-only pass: a malformed %-escape in NANO_APP_DB_URL must never fail the build. Fall
+    // back to the raw segment so reconciliation still runs (worst case: the file simply isn't found).
+    return s;
+  }
+}
+
+export function fileUrlToPath(u: string): string | undefined {
+  if (!u.startsWith("file:")) return undefined;
+  if (u.startsWith("file://")) {
+    let pathname: string;
+    try {
+      pathname = new URL(u).pathname;
+    } catch {
+      // Advisory-only pass: a malformed file:// URL must never fail the build. Give up on this
+      // input (worst case the file simply isn't found) rather than throwing out of reconciliation.
+      return undefined;
+    }
+    const p = safeDecodeURIComponent(pathname);
+    return /^\/[A-Za-z]:/.test(p) ? p.slice(1) : p;
+  }
+  // Opaque `file:` form (no authority) — the `new URL().pathname` branch above already drops any
+  // query/hash, but here we hold the raw remainder, so strip a `?…`/`#…` suffix ourselves. A valid
+  // SQLite-style URL like `file:./app.db?mode=ro` must resolve to `./app.db`, not `./app.db?mode=ro`
+  // (which never exists on disk and would silently disable blackboard reconciliation).
+  const raw = u.slice("file:".length).replace(/[?#].*$/, "");
+  const p = safeDecodeURIComponent(raw);
+  return /^\/[A-Za-z]:/.test(p) ? p.slice(1) : p;
+}
+
+function parseRef(dedupeKey: string | null): { category?: ContractCategory; name?: string } {
+  if (!dedupeKey) return {};
+  const idx = dedupeKey.indexOf(":");
+  if (idx <= 0) return {};
+  const category = dedupeKey.slice(0, idx).trim();
+  const name = dedupeKey.slice(idx + 1).trim();
+  if (!name) return {};
+  if (category === "env" || category === "wire" || category === "type" || category === "capability-url") {
+    return { category, name };
+  }
+  return {};
+}
+
+function loadSignals(): ContractSignal[] {
+  const url = process.env.NANO_APP_DB_URL ?? "file:./app.db";
+  const path = fileUrlToPath(url);
+  if (!path || !existsSync(path)) return [];
+  let db: DatabaseSync;
+  try {
+    db = new DatabaseSync(path, { readOnly: true });
+  } catch {
+    // Advisory-only pass: opening the db can still fail (permission, invalid/corrupt file) even
+    // though the path exists. Degrade to no signals — reconcile the registry alone — rather than
+    // crash a script that must never gate CI.
+    return [];
+  }
+  try {
+    // biome-ignore lint/plugin: external node:sqlite row shape at the DB boundary — the column list is fixed by the SELECT above.
+    const rows = db
+      .prepare(
+        `SELECT author_task, body, dedupe_key FROM ${BLACKBOARD_TABLE} WHERE kind = 'contract' ORDER BY id ASC`,
+      )
+      .all() as { author_task: string; body: string; dedupe_key: string | null }[];
+    return rows.map((r) => ({ authorTask: r.author_task, body: r.body, ...parseRef(r.dedupe_key) }));
+  } catch {
+    // No blackboard table (bare/unmigrated db) — reconcile the registry alone.
+    return [];
+  } finally {
+    db.close();
+  }
+}
+
+function main(): void {
+  const report = reconcileContracts(loadSignals());
+  console.log(formatReconciliationReport(report));
+  // Advisory: never fail the build. The hard, registry-only gate is `npm run check:contracts`.
+}
+
+if (import.meta.main) main();