@nanobpm/nano-workforce 0.138.2 → 0.139.0

package/operations/saveToLibrary.test.ts

@@ -0,0 +1,225 @@
+// Tests for POST /app/api/actions/delivery-graph/library/save → `saveToLibrary` (issue #522, epic #519
+// S3). Covers the three required paths: save-from-raw-JSON (`source: composed`), save-from-digest
+// (reuse a staged proposal's stored graph, `source: from-staged`), and validation-reject (an
+// uncompilable graph → clean 400, nothing persisted). Exercised against the REAL SQLite data layer so
+// the migration + store round-trip is validated, not modelled.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi, DataLayer } from "@nanobpm/urban";
+import { bootTestApp } from "@nanobpm/urban-testkit";
+import { deliveryGraphLibrary } from "../app/deliveryGraphLibrary.ts";
+import { noopLog } from "../test/log.ts";
+import stageHandler from "./stageDeliveryGraph.ts";
+import handler from "./saveToLibrary.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+async function withApp(fn: (app: AppApi, data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-dglibsave-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    const edge = { data: app.db, log: noopLog() } as unknown as AppApi;
+    await fn(edge, app.db);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+async function call(app: AppApi, body: unknown) {
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+async function stage(app: AppApi, graphJson: string) {
+  return (await stageHandler({ req: {} as any, params: {}, query: {}, body: { graphJson } } as any, app)) as any;
+}
+
+const GOOD = JSON.stringify({
+  name: "runbook",
+  nodes: [
+    { id: "a", kind: "agent", agent: { jobType: "senior:feature" } },
+    { id: "b", kind: "human", human: { prompt: "do X" } },
+  ],
+  edges: [{ from: "a", to: "b" }],
+});
+
+test("save-to-library: a raw graph JSON → 200, saved with source=composed, id derived from name", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { name: "My Runbook", description: "a note", graphJson: GOOD });
+    assertEquals(res.status, 200);
+    assertEquals(res.body.ok, true);
+    assert(res.body.entry.id.startsWith("my-runbook-"));
+    assertEquals(res.body.entry.name, "My Runbook");
+    assertEquals(res.body.entry.description, "a note");
+    assertEquals(res.body.entry.source, "composed");
+    assert(typeof res.body.entry.graph === "string" && res.body.entry.graph.length > 0);
+    // Persisted exactly one row.
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 1);
+    assertEquals((await deliveryGraphLibrary(data).get(res.body.entry.id))?.name, "My Runbook");
+  });
+});
+
+test("save-to-library: from a staged proposal digest → 200, reuses the stored graph, source=from-staged", async () => {
+  await withApp(async (app, data) => {
+    const staged = await stage(app, GOOD);
+    assertEquals(staged.status, 200);
+    const digest = staged.body.digest;
+    const res = await call(app, { name: "Saved From Staged", digest });
+    assertEquals(res.status, 200);
+    assertEquals(res.body.ok, true);
+    assertEquals(res.body.entry.source, "from-staged");
+    // The reused graph compiles to the SAME digest the proposal carried.
+    const proposal = await (await import("../app/deliveryGraphProposals.ts")).deliveryGraphProposals(data).get(digest);
+    assert(proposal !== undefined);
+    // The saved entry reuses the proposal's stored graph verbatim (the digest path), not a recompile:
+    // both the response payload and the persisted row carry exactly the proposal's `graph`.
+    assertEquals(res.body.entry.graph, proposal.graph);
+    assertEquals((await deliveryGraphLibrary(data).get(res.body.entry.id))?.graph, proposal.graph);
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 1);
+  });
+});
+
+test("save-to-library: from a dispatched proposal digest → 200, source=from-dispatched", async () => {
+  await withApp(async (app, data) => {
+    const staged = await stage(app, GOOD);
+    assertEquals(staged.status, 200);
+    const digest = staged.body.digest;
+    const { markProposalDispatched } = await import("../app/deliveryGraphProposals.ts");
+    await markProposalDispatched(data, digest);
+    const res = await call(app, { name: "Saved From Dispatched", digest });
+    assertEquals(res.status, 200);
+    assertEquals(res.body.ok, true);
+    assertEquals(res.body.entry.source, "from-dispatched");
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 1);
+  });
+});
+
+test("save-to-library: a superseded proposal digest → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    const staged = await stage(app, GOOD);
+    assertEquals(staged.status, 200);
+    const digest = staged.body.digest;
+    const proposals = (await import("../app/deliveryGraphProposals.ts")).deliveryGraphProposals(data);
+    await proposals.update(digest, { status: "superseded" });
+    assertEquals((await proposals.get(digest))?.status, "superseded");
+    const res = await call(app, { name: "Saved From Superseded", digest });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(typeof res.body.error === "string" && res.body.error.includes("not a live staged/dispatched proposal"));
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+test("save-to-library: an expired proposal digest → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    const staged = await stage(app, GOOD);
+    assertEquals(staged.status, 200);
+    const digest = staged.body.digest;
+    const { markProposalExpired } = await import("../app/deliveryGraphProposals.ts");
+    await markProposalExpired(data, digest);
+    const res = await call(app, { name: "Saved From Expired", digest });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(typeof res.body.error === "string" && res.body.error.includes("not a live staged/dispatched proposal"));
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+test("save-to-library: a staged-but-TTL-expired proposal digest → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    const staged = await stage(app, GOOD);
+    assertEquals(staged.status, 200);
+    const digest = staged.body.digest;
+    // Force the row's TTL horizon into the past while leaving status=`staged`.
+    await (await import("../app/deliveryGraphProposals.ts"))
+      .deliveryGraphProposals(data)
+      .update(digest, { expires_at: new Date(Date.now() - 60_000).toISOString() });
+    const res = await call(app, { name: "Saved From Stale Staged", digest });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(typeof res.body.error === "string" && res.body.error.includes("not a live staged/dispatched proposal"));
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+test("save-to-library: an unknown digest → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { name: "ghost", digest: "deadbeef0000" });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(typeof res.body.error === "string" && res.body.error.includes("no stored graph"));
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+test("save-to-library: not-valid-JSON graph → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { name: "bad", graphJson: "{ not json" });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(typeof res.body.error === "string" && res.body.error.includes("not valid JSON"));
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+test("save-to-library: a valid-JSON but UNCOMPILABLE graph → 400 with path-qualified errors, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    // A structurally-invalid graph (edge references a node that does not exist) fails compilation.
+    const uncompilable = JSON.stringify({
+      name: "broken",
+      nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature" } }],
+      edges: [{ from: "a", to: "missing" }],
+    });
+    const res = await call(app, { name: "broken", graphJson: uncompilable });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(Array.isArray(res.body.errors) && res.body.errors.length > 0);
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+test("save-to-library: a blank name → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { name: "   ", graphJson: GOOD });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+test("save-to-library: providing BOTH graphJson and digest → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { name: "conflict", graphJson: GOOD, digest: "deadbeef0000" });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+// Regression (PR #533 review): this door is INTENTIONALLY UNGUARDED, unlike the get/delete/import
+// library doors — it is also invoked by a DECLARATIVE page row action ("Save to library" on the
+// In-flight/History grid) that structurally cannot attach an `x-hook-secret` header. So even when
+// NANO_PR_WEBHOOK_SECRET is configured, a save WITHOUT the header must still succeed (a header guard
+// would 401 the door's own UI). We cache-bust re-import the handler with the secret set to prove it
+// ignores the header entirely.
+test("save-to-library: stays open even when NANO_PR_WEBHOOK_SECRET is set (no header guard)", async () => {
+  await withApp(async (app, data) => {
+    const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+    process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+    try {
+      const mod = await import(`./saveToLibrary.ts?guard=${Date.now()}`);
+      const reloaded = mod.default as (c: any, a: any) => Promise<any>;
+      // No x-hook-secret header, yet the save is accepted and persisted.
+      const res = await reloaded({ req: { headers: new Headers() }, params: {}, query: {}, body: { name: "unguarded", graphJson: GOOD } } as any, app);
+      assertEquals(res.status, 200);
+      assertEquals(res.body.entry.source, "composed");
+      assertEquals((await deliveryGraphLibrary(data).all()).length, 1);
+    } finally {
+      if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+      else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+    }
+  });
+});

package/operations/saveToLibrary.ts

@@ -0,0 +1,89 @@
+// POST /app/api/actions/delivery-graph/library/save → operationId `saveToLibrary` (issue #522, epic
+// #519 S3). Persist a delivery graph to the reusable LIBRARY — the durable base S4/S5/S6 build on. The
+// request carries the entry `name` (its slug + short-hash derive the stable library id, so re-saving
+// the same name upserts) plus EITHER a raw `graphJson` STRING (compiled from scratch, `source:
+// composed`) OR the `digest` of an existing staged/dispatched proposal whose ALREADY-STORED graph is
+// reused (`source: from-staged` / `from-dispatched`).
+//
+// Every save validates the graph through the SAME `parseAndCompileText` pipeline the preview/stage
+// doors use, so an uncompilable graph can NEVER be persisted — a bad JSON string or a graph that fails
+// validation is a clean 400 and nothing is written. Mirrors the proposals store/door pattern so the S3
+// API surface is familiar to the S4/S5/S6 slices.
+//
+// This library door is INTENTIONALLY UNGUARDED, unlike the get/delete/import library doors that carry
+// the optional NANO_PR_WEBHOOK_SECRET / x-hook-secret guard. Save is the one library door also reached
+// by a DECLARATIVE page-runtime row action — the "Save to library" action on the In-flight/History grid
+// (`pages/delivery-graphs.page.json`), which posts only `{path, body}` and structurally CANNOT attach a
+// custom `x-hook-secret` header (that affordance is the external `@nanobpm/urban` page runtime's, not
+// ours). A header guard here would therefore make the door unreachable by its own UI (a hard 401 on
+// every dispatched-row Save whenever a secret is configured). The imperative composer/library mounts
+// reach the other doors and can send the header; this door cannot require one until the page runtime
+// grows a supported way for declarative actions to authenticate. See PR #533 review.
+
+import {
+  buildLibraryEntryRow,
+  type DeliveryLibrarySource,
+  libraryEntryDto,
+  saveLibraryEntry,
+} from "../app/deliveryGraphLibrary.ts";
+import { deliveryGraphProposals, isProposalExpired } from "../app/deliveryGraphProposals.ts";
+import { parseAndCompileText } from "../app/deliveryGraphTextIngress.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+export default defineOperation("saveToLibrary", async ({ body }, app) => {
+  const name = body && typeof body.name === "string" ? body.name.trim() : "";
+  if (name === "") {
+    app.log.warn("save-to-library rejected: missing name");
+    return { status: 400, body: { ok: false, error: "request body must carry a non-blank `name` for the library entry" } };
+  }
+  const description = body && typeof body.description === "string" ? body.description : undefined;
+
+  const digest = body && typeof body.digest === "string" && body.digest.trim() !== "" ? body.digest.trim() : undefined;
+  const graphJson = body && typeof body.graphJson === "string" && body.graphJson.trim() !== "" ? body.graphJson : undefined;
+  if (digest && graphJson) {
+    app.log.warn("save-to-library rejected: both digest and graphJson", { name });
+    return { status: 400, body: { ok: false, error: "provide EITHER `graphJson` (a raw graph) OR `digest` (an existing proposal), not both" } };
+  }
+
+  // Resolve the graph text + its provenance. From a digest: reuse the proposal's already-stored graph
+  // (still re-validated below, so a corrupt stored graph is refused). From raw JSON: compile from scratch.
+  let sourceGraphJson: string;
+  let source: DeliveryLibrarySource;
+  if (digest) {
+    const proposal = await deliveryGraphProposals(app.data).get(digest);
+    if (!proposal) {
+      app.log.warn("save-to-library rejected: unknown digest", { digest });
+      return { status: 400, body: { ok: false, error: `no stored graph for digest ${digest} — stage or dispatch it first, or save a raw graph` } };
+    }
+    // Only a LIVE staged (not aged out of its TTL) or dispatched proposal may seed the library — a
+    // superseded/expired/stale-staged digest is not a canonical graph, and reusing it would both persist a
+    // retired graph and mis-label it `source: from-staged`.
+    const isLiveStaged = proposal.status === "staged" && !isProposalExpired(proposal.expires_at);
+    if (!isLiveStaged && proposal.status !== "dispatched") {
+      app.log.warn("save-to-library rejected: digest not live staged/dispatched", { digest, status: proposal.status });
+      return { status: 400, body: { ok: false, error: `digest ${digest} is not a live staged/dispatched proposal (status ${proposal.status}) — stage or dispatch it first, or save a raw graph` } };
+    }
+    sourceGraphJson = proposal.graph;
+    source = proposal.status === "dispatched" ? "from-dispatched" : "from-staged";
+  } else if (graphJson) {
+    sourceGraphJson = graphJson;
+    source = "composed";
+  } else {
+    app.log.warn("save-to-library rejected: no graph source", { name });
+    return { status: 400, body: { ok: false, error: "request body must carry either `graphJson` (a raw graph) or `digest` (an existing proposal)" } };
+  }
+
+  // Validate/compile — an uncompilable graph can never enter the library (nothing is persisted here).
+  const ingress = await parseAndCompileText({ graphJson: sourceGraphJson });
+  if (!ingress.ok) {
+    app.log.warn("save-to-library rejected: graph failed validation", { name, source, message: ingress.body.error });
+    return { status: 400, body: ingress.body };
+  }
+
+  const saved = await saveLibraryEntry(
+    app.data,
+    buildLibraryEntryRow({ name, description, graphJson: JSON.stringify(ingress.graph), source }),
+  );
+  app.log.info("save-to-library saved", { id: saved.id, name: saved.name, source });
+  return { status: 200, body: { ok: true, entry: libraryEntryDto(saved) } };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.138.2",
+  "version": "0.139.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/delivery-graphs/delivery-graphs.css

@@ -170,6 +170,39 @@
   color: #8aa0b8;
 }
 
+/* The filesystem Import control (issue #524): a <label class="btn"> wrapping a visually-hidden native
+   <input type=file>, so the file picker reads as a button consistent with the other actions. The label
+   dims while its input is disabled (busy) via :has(), mirroring .btn:disabled. */
+.dg .dg-import {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+
+.dg .dg-import-input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  border: 0;
+}
+
+.dg .dg-import:has(.dg-import-input:disabled) {
+  opacity: 0.5;
+  cursor: default;
+}
+
+/* The native <input type=file> is visually hidden (clipped to 1×1), which also clips its browser
+   focus ring, so surface a visible keyboard focus indicator on the wrapping label instead — keyboard
+   users can tab to Import and see where focus landed. */
+.dg .dg-import:has(.dg-import-input:focus-visible) {
+  outline: 2px solid #58a6ff;
+  outline-offset: 2px;
+}
+
 .dg .status {
   font-size: 12.5px;
   color: #8aa0b8;

package/pages/delivery-graphs/embed.html

@@ -25,6 +25,7 @@
       mountDeliveryGraphs(cfg.host ?? document.getElementById("delivery-graphs-root"), {
         previewUrl: cfg.previewUrl,
         stageUrl: cfg.stageUrl,
+        importUrl: cfg.importUrl,
         hookSecret: cfg.hookSecret,
       });
     </script>

package/pages/delivery-graphs/library-embed.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Delivery graphs — library (reuse · delete) (App View embed)</title>
+    <link rel="stylesheet" href="./delivery-graphs.css" />
+    <style>
+      html, body { margin: 0; height: 100%; background: #0b0f14; }
+    </style>
+  </head>
+  <body>
+    <!--
+      Console App-View embed (ADR 0057, issue #523). The console loads this document into its App-View
+      surface and hands it a host element; we mount the SAME reusable-library list (Reuse + Delete) via
+      the SAME ./library.mount.js as the standalone shell — only the host and the injected endpoint
+      config differ, so the view renders identically. When the console injects endpoint config via
+      `window.__NANO_APP_VIEW__`, it wins.
+    -->
+    <main id="delivery-graphs-library-root"></main>
+    <script type="module">
+      import { mountDeliveryGraphLibrary } from "./library.mount.js";
+
+      const cfg = window.__NANO_APP_VIEW__ ?? {};
+      mountDeliveryGraphLibrary(cfg.host ?? document.getElementById("delivery-graphs-library-root"), {
+        libraryUrl: cfg.libraryUrl,
+        hookSecret: cfg.hookSecret,
+      });
+    </script>
+  </body>
+</html>

package/pages/delivery-graphs/library-standalone.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>Delivery graphs — library (reuse · delete)</title>
+    <link rel="stylesheet" href="./delivery-graphs.css" />
+    <style>
+      html, body { margin: 0; height: 100%; background: #0b0f14; }
+    </style>
+  </head>
+  <body>
+    <!--
+      Standalone shell (phone / direct link). Loads the SAME ./library.mount.js the console App-View
+      embed uses, so the standalone and embedded views render identically. Endpoints default to the
+      current origin; override the list endpoint via ?library=. For a secured deployment, pass the guard
+      secret via the URL fragment #secret= (sent as x-hook-secret) — NOT the query string, so it never
+      leaks via server access logs, browser history, or the Referer header. The fragment is stripped
+      from the address bar immediately after it is read. Note: "Reuse" fills the compose App-View, which
+      only exists in the console — standalone it reports that instead of failing silently.
+    -->
+    <main id="delivery-graphs-library-root"></main>
+    <script type="module">
+      import { mountDeliveryGraphLibrary } from "./library.mount.js";
+
+      const params = new URLSearchParams(location.search);
+      const secrets = new URLSearchParams(location.hash.slice(1));
+      const hookSecret = secrets.get("secret") ?? undefined;
+      if (location.hash) {
+        history.replaceState(null, "", location.pathname + location.search);
+      }
+      mountDeliveryGraphLibrary(document.getElementById("delivery-graphs-library-root"), {
+        libraryUrl: params.get("library") ?? undefined,
+        hookSecret,
+      });
+    </script>
+  </body>
+</html>