@nanobpm/urban 0.51.0 → 0.53.0

package/src/toolkit/derivers/system-brief.ts

@@ -0,0 +1,210 @@
+// Deriver: BPMN models + manifest → `system-brief.md` / `system-brief.json`, the app's
+// *institutional-memory* brief (ADR 0060). Where `worker-io.ts` emits worker *types* and
+// `meta.ts` emits a *typed accessor*, this deriver folds the SAME scanned structure into
+// agent- and human-readable **system context**: the app's processes, its service-task call
+// graph, the decisions it encodes, and the ownership / "why" carried on
+// the model as reserved `nano:meta` keys. It reuses the sibling scanners (single parse rule
+// per vocabulary) and is pure (models in, artifacts out) so `urban gen --check` keeps it
+// honest — the brief can never rot the way a hand-written README does (ADR 0060 §1).
+//
+// Wired into `runGen` (gen.ts) as a standard artifact and served at runtime via `/app/agent`
+// (agent.ts, ADR 0060 §2): the shape, scanners, fold, and both emitters are real and tested.
+
+import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { GENERATED_DIR } from "../artifact.ts";
+import { byModelPath, type ModelSource, scanModelWorkers, type WorkerIo } from "./worker-io.ts";
+import { scanModelMeta } from "./meta.ts";
+
+/** Basenames of the two emitted artifacts. */
+export const SYSTEM_BRIEF_MD = "system-brief.md";
+export const SYSTEM_BRIEF_JSON = "system-brief.json";
+
+/** Reserved `nano:meta` keys the brief recognises as ownership / provenance context (ADR 0060
+ * §1). All optional and additive — absence degrades the brief to structure-only. `adr` may be
+ * declared more than once (repeated `nano:meta`, matching the existing scan) to reference
+ * multiple ADRs; the scan collects them into `adrs[]`. */
+export interface Ownership {
+  owner?: string;
+  team?: string;
+  slack?: string;
+  runbook?: string;
+  since?: string;
+  adrs: string[];
+}
+
+/** One decision the app encodes: a `businessRuleTask` with a `zeebe:calledDecision`. */
+export interface DecisionRef {
+  process?: string;
+  elementId?: string;
+  decisionId: string;
+}
+
+/** The derived, machine-readable system model — the payload of `system-brief.json` and the
+ * input the runtime injects as session context / the retro plane consumes (ADR 0060 §3). */
+export interface SystemBrief {
+  /** App id/name from the manifest, if provided. */
+  app?: string;
+  /** Every process id the models declare, in scan order. */
+  processes: string[];
+  /** Service-task call graph: each worker binding (task type + in/out envelope + process). The
+   * dependency edges are implicit — a process depends on the task types its service tasks invoke. */
+  workers: WorkerIo[];
+  /** Decisions (`businessRuleTask` → DMN) the models encode. */
+  decisions: DecisionRef[];
+  /** Ownership / provenance folded from reserved `nano:meta` keys. */
+  ownership: Ownership;
+}
+
+function attr(tag: string, name: string): string | undefined {
+  const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+  return m ? m[1] : undefined;
+}
+
+function processId(xml: string): string | undefined {
+  const m = xml.match(/<bpmn:process\b[^>]*>/);
+  return m ? attr(m[0], "id") : undefined;
+}
+
+/** Scan one BPMN document for `businessRuleTask` → `zeebe:calledDecision` decision refs, in
+ * document order, tagged with the enclosing process (mirrors `scanModelWorkers`' shape). */
+export function scanModelDecisions(xml: string): DecisionRef[] {
+  const proc = processId(xml);
+  const out: DecisionRef[] = [];
+  const blockRe = /<bpmn:businessRuleTask\b([^>]*)>([\s\S]*?)<\/bpmn:businessRuleTask>/g;
+  let m: RegExpExecArray | null;
+  while ((m = blockRe.exec(xml)) !== null) {
+    const elementId = attr(`<x ${m[1]}>`, "id");
+    const cd = m[2].match(/<zeebe:calledDecision\b[^>]*>/);
+    if (!cd) continue;
+    const decisionId = attr(cd[0], "decisionId");
+    if (!decisionId) continue;
+    out.push({ process: proc, elementId, decisionId });
+  }
+  return out;
+}
+
+/** Reserved single-valued ownership keys → their `Ownership` field. */
+const OWNERSHIP_KEYS: Record<string, Exclude<keyof Ownership, "adrs">> = {
+  owner: "owner",
+  team: "team",
+  slack: "slack",
+  runbook: "runbook",
+  since: "since",
+};
+
+/** Fold the models' reserved `nano:meta` entries into `Ownership`. Single-valued keys take the
+ * last (scan-order) write, matching `foldMeta`; `adr` is multi-valued and accumulates. */
+export function foldOwnership(models: ModelSource[]): Ownership {
+  const own: Ownership = { adrs: [] };
+  for (const model of [...models].sort(byModelPath)) {
+    for (const { key, value } of scanModelMeta(model.xml)) {
+      const k = key.trim().toLowerCase();
+      if (k === "adr") {
+        if (value && !own.adrs.includes(value)) own.adrs.push(value);
+      } else if (Object.hasOwn(OWNERSHIP_KEYS, k)) {
+        own[OWNERSHIP_KEYS[k]] = value ?? "";
+      }
+    }
+  }
+  return own;
+}
+
+/** Fold all models + manifest into the machine-readable `SystemBrief`. Deterministic: models
+ * are scanned in path order. */
+export function buildSystemBrief(models: ModelSource[], app?: string): SystemBrief {
+  const sorted = [...models].sort(byModelPath);
+  const workers: WorkerIo[] = [];
+  const decisions: DecisionRef[] = [];
+  const processes: string[] = [];
+  for (const model of sorted) {
+    const proc = processId(model.xml);
+    if (proc && !processes.includes(proc)) processes.push(proc);
+    workers.push(...scanModelWorkers(model.xml));
+    decisions.push(...scanModelDecisions(model.xml));
+  }
+  return { app, processes, workers, decisions, ownership: foldOwnership(models) };
+}
+
+/** Escape a Markdown table cell: neutralise `|` and newlines, which would otherwise break the
+ * table. Ownership values come from model-authored `nano:meta`, so this both keeps rendering
+ * honest and blunts Markdown/prompt injection into the agent-facing brief. Backticks are left
+ * intact — the emitter deliberately wraps ids in code spans. */
+function mdCell(s: string): string {
+  return s.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+function mdTable(headers: string[], rows: string[][]): string {
+  if (rows.length === 0) return "_none_\n";
+  const head = `| ${headers.join(" | ")} |\n| ${headers.map(() => "---").join(" | ")} |\n`;
+  return head + rows.map((r) => `| ${r.map((c) => mdCell(c || "")).join(" | ")} |`).join("\n") + "\n";
+}
+
+/** Emit the agent- and human-readable `system-brief.md` from the machine model. Compact by
+ * design (call graph + owners, not model XML) to keep the per-session prompt budget small
+ * (ADR 0060 §3 / open question 1). */
+export function emitSystemBriefMd(b: SystemBrief): string {
+  const o = b.ownership;
+  let m = `# ${b.app ?? "App"} — system brief\n\n`;
+  m += "_Auto-derived from the process models (ADR 0060). Do not edit — regenerated by " +
+    "`urban gen`; drift fails `urban gen --check`._\n\n";
+
+  m += "## Ownership\n\n";
+  const ownRows = [
+    ["Owner", o.owner ?? ""],
+    ["Team", o.team ?? ""],
+    ["Slack", o.slack ?? ""],
+    ["Runbook", o.runbook ?? ""],
+    ["Since", o.since ?? ""],
+    ["ADRs", o.adrs.join(", ")],
+  ].filter((r) => r[1]);
+  m += ownRows.length ? mdTable(["Field", "Value"], ownRows) : "_No ownership metadata declared " +
+    "(add reserved `nano:meta` keys: owner, team, slack, runbook, adr, since)._\n";
+  m += "\n";
+
+  m += "## Processes\n\n";
+  m += b.processes.length ? b.processes.map((p) => `- \`${p}\``).join("\n") + "\n" : "_none_\n";
+  m += "\n";
+
+  m += "## Service-task call graph (dependency edges)\n\n";
+  m += mdTable(
+    ["Process", "Task type (dependency)", "In", "Out"],
+    b.workers.map((w) => [
+      w.process ? `\`${w.process}\`` : "",
+      `\`${w.taskType}\``,
+      w.in ? `\`${w.in}\`` : "",
+      w.out ? `\`${w.out}\`` : "",
+    ]),
+  );
+  m += "\n";
+
+  m += "## Decisions (DMN)\n\n";
+  m += mdTable(
+    ["Process", "Element", "Decision"],
+    b.decisions.map((d) => [
+      d.process ? `\`${d.process}\`` : "",
+      d.elementId ? `\`${d.elementId}\`` : "",
+      `\`${d.decisionId}\``,
+    ]),
+  );
+  return m;
+}
+
+/**
+ * Derive `nano-generated/system-brief.md` + `system-brief.json` from BPMN models (ADR 0060 §1).
+ * Pure and deterministic (path-ordered scan), so it is a drop-in drift-checkable artifact like
+ * its sibling derivers.
+ */
+export function deriveSystemBrief(models: ModelSource[], app?: string): DerivedArtifact[] {
+  const brief = buildSystemBrief(models, app);
+  return [
+    { path: `${GENERATED_DIR}/${SYSTEM_BRIEF_MD}`, content: emitSystemBriefMd(brief) },
+    { path: `${GENERATED_DIR}/${SYSTEM_BRIEF_JSON}`, content: JSON.stringify(brief, null, 2) + "\n" },
+  ];
+}
+
+/** The `Deriver` binding, peer to `worker-io` / `meta`, for wiring into `gen.ts`. */
+export const systemBriefDeriver: Deriver<{ models: ModelSource[]; app?: string }> = {
+  id: "system-brief",
+  describe: "App institutional-memory brief (processes, call graph, decisions, ownership) — ADR 0060",
+  derive: ({ models, app }) => deriveSystemBrief(models, app),
+};

package/src/toolkit/gen.test.ts

@@ -74,7 +74,7 @@ function fixture(): Record<string, string> {
   };
 }
 
-test("runGen writes migrations, the worker index, the meta accessor, and the message map", async () => {
+test("runGen writes migrations, the worker index, the meta accessor, the message map, and the system brief", async () => {
   const io = memIO(fixture());
   const res = await runGen({ root: "/app", io });
   const paths = res.artifacts.map((a) => a.path).sort();
@@ -83,6 +83,8 @@ test("runGen writes migrations, the worker index, the meta accessor, and the mes
     "nano-generated/domain-rows.d.ts",
     "nano-generated/message-io.d.ts",
     "nano-generated/meta.ts",
+    "nano-generated/system-brief.json",
+    "nano-generated/system-brief.md",
     "nano-generated/worker-io.d.ts",
   ]);
   assert.ok(io.files["/app/nano-generated/app.schema.sql"].includes("CREATE TABLE"));
@@ -91,6 +93,27 @@ test("runGen writes migrations, the worker index, the meta accessor, and the mes
   assert.ok(io.files["/app/nano-generated/message-io.d.ts"].includes("export type MessageName"));
   assert.ok(io.files["/app/nano-generated/domain-rows.d.ts"].includes('"greetings": Greetings;'));
   assert.ok(io.files["/app/nano-generated/domain-rows.d.ts"].includes('"greeting": {'));
+  // The system brief threads the app id from the manifest and folds the process + call graph.
+  assert.ok(io.files["/app/nano-generated/system-brief.md"].includes("# demo — system brief"));
+  assert.ok(io.files["/app/nano-generated/system-brief.md"].includes("demo.do"));
+  const brief = JSON.parse(io.files["/app/nano-generated/system-brief.json"]);
+  assert.equal(brief.app, "demo");
+  assert.deepEqual(brief.processes, ["p"]);
+  assert.equal(brief.workers[0].taskType, "demo.do");
+});
+
+test("the system brief is drift-checked and swept like its sibling artifacts", async () => {
+  const io = memIO(fixture());
+  await runGen({ root: "/app", io });
+  // Drift gate owns the brief: a hand-edit is reported by --check.
+  io.files["/app/nano-generated/system-brief.json"] = "{ tampered: true }";
+  const check = await runGen({ root: "/app", io, check: true });
+  assert.ok(check.drift.includes("nano-generated/system-brief.json"), "brief drift is reported");
+  // Stale sweep owns the brief: a renamed-away brief artifact is removed on the next write.
+  io.files["/app/nano-generated/system-brief.old.md"] = "# stale brief";
+  const res = await runGen({ root: "/app", io });
+  assert.ok(res.swept.includes("nano-generated/system-brief.old.md"), "stale brief swept");
+  assert.ok("/app/nano-generated/system-brief.md" in io.files, "fresh brief kept");
 });
 
 test("gen --check reports no drift right after a write", async () => {
@@ -345,13 +368,14 @@ test("readModels: a models block without processes suppresses the resources/ con
   const io = memIO({
     "/app/resources/a.bpmn": "<bpmn:definitions/>",
     "/app/resources/sub/b.bpmn": "<bpmn:definitions/>",
+    "/app/resources/sub/deeper/c.bpmn": "<bpmn:definitions/>",
   });
-  // No models block at all → convention scans resources/ (shallow, one level deep).
+  // No models block at all → convention scans resources/ recursively (issue #231).
   const byConvention = await readModels("/app", io, {});
   assert.deepEqual(
     byConvention.map((m) => m.path).sort(),
-    ["resources/a.bpmn", "resources/sub/b.bpmn"],
-    "with no models block, gen discovers under resources/ by convention",
+    ["resources/a.bpmn", "resources/sub/b.bpmn", "resources/sub/deeper/c.bpmn"],
+    "with no models block, gen discovers under resources/ recursively by convention",
   );
   // A declared models block (even one that resolves to zero process files) is an explicit override:
   // the convention scan must be skipped entirely, matching runtime deployModels.

package/src/toolkit/gen.ts

@@ -12,6 +12,7 @@ import { deriveMeta } from "./derivers/meta.ts";
 import { deriveMessageBindings } from "./derivers/messages.ts";
 import { resolveShapes, scanModelShapes } from "./derivers/shapes.ts";
 import { deriveApi } from "./derivers/api.ts";
+import { deriveSystemBrief } from "./derivers/system-brief.ts";
 import { parseSpec, sharedRequestBodySchemas } from "../openapi/spec.ts";
 import { deriveModels, type DerivedModels, type ModelError, MODEL_PROVENANCE } from "./models.ts";
 
@@ -106,31 +107,32 @@ export async function expandPattern(root: string, io: GenIO, pattern: string): P
 }
 
 /** The deploy-by-convention directory (ADR 0062): when the manifest declares no `models`, both the
- *  runtime deploy and this codegen scan discover deployables/models under it — shallow, one level
- *  deep (`resources/*` and `resources/<subdir>/*`). Deploy-only by convention. */
+ *  runtime deploy and this codegen scan discover deployables/models under it — **recursively**,
+ *  every file at any depth (issue #231). Deploy-only by convention. */
 export const RESOURCES_DIR = "resources";
 
 /** Model file extensions the `nano:shape`/code-first scan reads by convention (BPMN + DMN). */
 const MODEL_EXTS = [".bpmn", ".dmn"];
 
 /**
- * Discover model files under `resources/` by convention — shallow, one level deep (`resources/*`
- * and `resources/<subdir>/*`), never deeper — mirroring the runtime deploy walk so the codegen scan
- * and the deploy see the same set. Returns root-relative paths, sorted. Descending one level needs
+ * Discover model files under `resources/` by convention — **recursively**, every `.bpmn`/`.dmn`
+ * under `resources/` at any depth (issue #231) — mirroring the runtime deploy walk so the codegen
+ * scan and the deploy see the same set. Returns root-relative paths, sorted. Descending needs
  * `io.listSubdirs`; without it only the files directly under `resources/` are scanned.
  */
 export async function discoverResourceModels(root: string, io: GenIO): Promise<string[]> {
   const isModel = (n: string): boolean => MODEL_EXTS.some((e) => n.endsWith(e));
   const out: string[] = [];
-  for (const n of await io.listDir(join(root, RESOURCES_DIR))) {
-    if (isModel(n)) out.push(`${RESOURCES_DIR}/${n}`);
-  }
-  const subdirs = io.listSubdirs ? await io.listSubdirs(join(root, RESOURCES_DIR)) : [];
-  for (const sub of subdirs.slice().sort()) {
-    for (const n of await io.listDir(join(root, `${RESOURCES_DIR}/${sub}`))) {
-      if (isModel(n)) out.push(`${RESOURCES_DIR}/${sub}/${n}`);
+  const walk = async (rel: string): Promise<void> => {
+    for (const n of await io.listDir(join(root, rel))) {
+      if (isModel(n)) out.push(`${rel}/${n}`);
     }
-  }
+    const subdirs = io.listSubdirs ? await io.listSubdirs(join(root, rel)) : [];
+    for (const sub of subdirs.slice().sort()) {
+      await walk(`${rel}/${sub}`);
+    }
+  };
+  await walk(RESOURCES_DIR);
   return out.sort();
 }
 
@@ -233,6 +235,11 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
       artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
       artifacts.push(...deriveMeta(models));
       artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
+      // Institutional-memory brief (ADR 0060): fold the same scanned model structure into the
+      // app's agent/human-readable system brief. Flows through `artifacts` like its siblings, so
+      // the `nano-generated/` stale sweep and the `urban gen --check` drift gate own the two new
+      // artifacts (system-brief.md / .json) with no extra bookkeeping.
+      artifacts.push(...deriveSystemBrief(models, manifest.id));
       // Surface genuine data-envelope conflicts: a taskType whose variants disagree on a field's
       // TYPE. The emitted contract is the union of the variants (sound for a shared handler), so a
       // type clash would silently widen to `A | B` — warn instead so the author unifies the envelope.

package/src/toolkit/index.ts

@@ -110,6 +110,18 @@ export {
   API_CONTROLLER_TS,
 } from "./derivers/api.ts";
 
+export {
+  buildSystemBrief,
+  deriveSystemBrief,
+  emitSystemBriefMd,
+  foldOwnership,
+  scanModelDecisions,
+  systemBriefDeriver,
+  SYSTEM_BRIEF_JSON,
+  SYSTEM_BRIEF_MD,
+} from "./derivers/system-brief.ts";
+export type { DecisionRef, Ownership, SystemBrief } from "./derivers/system-brief.ts";
+
 // The OpenAPI machinery the deriver + runtime share (ADR 0058).
 export {
   collectOperations,
@@ -139,6 +151,7 @@ import { workerIoDeriver } from "./derivers/worker-io.ts";
 import { metaDeriver } from "./derivers/meta.ts";
 import { messagesDeriver } from "./derivers/messages.ts";
 import { apiDeriver } from "./derivers/api.ts";
+import { systemBriefDeriver } from "./derivers/system-brief.ts";
 export const DERIVERS = [
   migrationsDeriver,
   domainDeriver,
@@ -146,6 +159,7 @@ export const DERIVERS = [
   metaDeriver,
   messagesDeriver,
   apiDeriver,
+  systemBriefDeriver,
 ] as const;
 
 // Gen orchestrator + IO

package/src/toolkit/models.ts

@@ -21,9 +21,10 @@ import { isRecord } from "../runtime/core/guards.ts";
 export const DEFAULT_WORKFLOW_PATTERNS = ["workflows/*.ts"];
 
 /** Default output dir for derived models when the manifest declares no `models.processes`: under
- * the deploy-by-convention `resources/` tree (ADR 0062), one level deep, so a derived model lands
- * exactly where the convention deploy + codegen scan look for it. When `models.processes` IS set,
- * `processesOutDir` derives the dir from that glob instead (the model-first override). */
+ * the deploy-by-convention `resources/` tree (ADR 0062), so a derived model lands where the
+ * convention deploy + codegen scan (which walk `resources/` recursively) look for it. When
+ * `models.processes` IS set, `processesOutDir` derives the dir from that glob instead (the
+ * model-first override). */
 export const PROCESSES_DIR = "resources/processes";
 
 /** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the