@nanobpm/nano-workforce 0.138.2 → 0.139.0

package/operations/dismissProposal.test.ts

@@ -0,0 +1,105 @@
+// Integration coverage for the POST /app/api/actions/delivery-graph/dismiss operation `dismissProposal`
+// (#520) — the OPERATOR-ONLY dismiss door. The cockpit's staged-proposals grid posts the `digest` of the
+// proposal the operator wants to discard as noise; this door loads that live `staged` proposal and flips
+// it to the terminal `dismissed` status, so it drops out of the staged list — exactly like
+// `superseded`/`expired`, but recording a deliberate operator discard. It launches nothing. These tests
+// drive the REAL door through `bootTestApp`'s api driver against the WASM engine: compile-to-stage, then
+// dismiss by digest, asserting the row leaves the staged list, an unknown digest is refused, and a
+// re-dismiss of an already-dismissed digest is idempotently refused (nothing changes, nothing launches).
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { after, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { deliveryGraphProposals, listStagedProposals } from "../app/deliveryGraphProposals.ts";
+import { deliveryGraphRuns } from "../app/deliveryGraphRun.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+const GITHUB_ENV: Record<string, string> = { NANO_PR_GITHUB_TRANSPORT: "token", GITHUB_TOKEN: "" };
+
+const HUMAN_ONLY = {
+  name: "manual gate",
+  nodes: [{ id: "ack", kind: "human", human: { prompt: "click done when the release is out" } }],
+};
+
+describe("dismissProposal — operator dismiss of a staged-proposal by digest", () => {
+  const dirs: string[] = [];
+  const apps: TestApp[] = [];
+  after(async () => {
+    for (const app of apps) await app.stop?.();
+    for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  });
+  const boot = async (): Promise<TestApp> => {
+    const d = mkdtempSync(join(tmpdir(), "nwf-dismiss-"));
+    dirs.push(d);
+    const app = await bootTestApp(APP_ROOT, { env: { ...GITHUB_ENV, NANO_APP_DB_URL: `file:${join(d, "app.db")}` } });
+    apps.push(app);
+    return app;
+  };
+
+  test("a missing/blank digest → 400 with a human error, nothing changed", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const res = await app.api.call<{ ok: boolean; error?: string }>("dismissProposal", { body: { digest: "  " } });
+    assert.equal(res.status, 400);
+    assert.equal(res.body.ok, false);
+    assert.ok(typeof res.body.error === "string" && res.body.error.length > 0);
+  });
+
+  test("an unknown / never-staged digest → 400, nothing changed", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const res = await app.api.call<{ ok: boolean; error?: string }>("dismissProposal", { body: { digest: "deadbeef0000" } });
+    assert.equal(res.status, 400);
+    assert.equal(res.body.ok, false);
+    assert.ok(/no staged proposal/.test(res.body.error ?? ""));
+  });
+
+  test("dismiss a staged proposal by digest → 200; the row leaves the staged list; nothing launches", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+
+    // Stage through the agent compile door — it returns a preview + digest and stages the proposal.
+    const staged = await api.call<{ status: string; digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    assert.equal(staged.status, 200);
+    const digest = staged.body.digest;
+    assert.equal((await deliveryGraphProposals(app.db).get(digest))?.status, "staged");
+    assert.equal((await listStagedProposals(app.db)).length, 1);
+
+    // The operator dismisses that digest.
+    const res = await api.call<{ ok: boolean; digest?: string }>("dismissProposal", { body: { digest } });
+    assert.equal(res.status, 200);
+    assert.equal(res.body.ok, true);
+    assert.equal(res.body.digest, digest);
+
+    // The proposal drops out of the staged list — it is now terminal (`dismissed`).
+    assert.equal((await deliveryGraphProposals(app.db).get(digest))?.status, "dismissed");
+    assert.equal((await listStagedProposals(app.db)).length, 0);
+    // Dismiss launches nothing — no runs exist.
+    await app.settle();
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+  });
+
+  test("re-dismissing an ALREADY-dismissed digest is idempotent → 400, state unchanged", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ status: string; digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    assert.equal(staged.status, 200);
+    const digest = staged.body.digest;
+
+    const first = await api.call<{ ok: boolean }>("dismissProposal", { body: { digest } });
+    assert.equal(first.status, 200);
+    assert.equal(first.body.ok, true);
+    assert.equal((await deliveryGraphProposals(app.db).get(digest))?.status, "dismissed");
+
+    // A second dismiss finds no LIVE staged proposal → clean 400; the row stays `dismissed` (unchanged).
+    const again = await api.call<{ ok: boolean; error?: string }>("dismissProposal", { body: { digest } });
+    assert.equal(again.status, 400);
+    assert.equal(again.body.ok, false);
+    assert.ok(/no staged proposal/.test(again.body.error ?? ""));
+    assert.equal((await deliveryGraphProposals(app.db).get(digest))?.status, "dismissed");
+  });
+});

package/operations/dismissProposal.ts

@@ -0,0 +1,53 @@
+// POST /app/api/actions/delivery-graph/dismiss → operationId `dismissProposal` (#520). The OPERATOR-ONLY
+// dismiss door: the cockpit's staged-proposals grid posts the `digest` of the proposal the operator
+// wants to discard as noise; this door loads that live `staged` proposal and flips it to the terminal
+// `dismissed` status (`markProposalDismissed`), so it drops out of the staged list — exactly like
+// `superseded`/`expired`, but recording a deliberate operator discard.
+//
+// It launches nothing (unlike dispatch) and is reachable only from the cockpit. Idempotent: a re-dismiss
+// of an already-terminal (dismissed / dispatched / superseded / expired) or unknown digest is a clean
+// 400 — the `getStagedProposal` liveness guard only resolves a live `staged` row, so a second dismiss
+// finds no live proposal and refuses without touching state. The guarded flip itself can also lose a race
+// (a dispatch/supersede/expiry lands between the liveness read and the write), in which case it changes 0
+// rows and this door routes the lost race to the same clean 400 rather than misreporting success.
+
+import { getStagedProposal, markProposalDismissed } from "../app/deliveryGraphProposals.ts";
+import type { DeliveryGraphTextResult } from "../nano-generated/api-io.d.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+export default defineOperation("dismissProposal", async ({ body }, app) => {
+  const digest = body && typeof body === "object" && "digest" in body && typeof body.digest === "string" ? body.digest.trim() : "";
+  if (digest === "") {
+    app.log.warn("dismiss-delivery-graph rejected: missing digest");
+    return { status: 400, body: { ok: false, error: "request body must carry a `digest` naming the staged proposal to dismiss" } };
+  }
+
+  // Load the live staged proposal for this digest — refuses an unknown or already-terminal (dismissed /
+  // dispatched / superseded / expired) digest cleanly. This is what makes the door idempotent: a second
+  // dismiss finds no live `staged` row and 400s without re-writing anything.
+  const proposal = await getStagedProposal(app.data, digest);
+  if (!proposal) {
+    app.log.warn("dismiss-delivery-graph rejected: no live staged proposal", { digest });
+    return {
+      status: 400,
+      body: { ok: false, error: `no staged proposal for digest ${digest} — it may already be dismissed, dispatched, superseded, or aged out` },
+    };
+  }
+
+  // Flip the live `staged` row to `dismissed`. This is a GUARDED UPDATE (`... WHERE status='staged'`), so a
+  // dispatch/supersede/expiry racing between the `getStagedProposal` read above and this write moves the row
+  // off `staged` and the flip legitimately changes 0 rows. In that lost-race case the dismiss did NOT happen,
+  // so we must not report success — fall through to the same clean 400 an already-terminal digest gets.
+  const dismissed = await markProposalDismissed(app.data, digest);
+  if (!dismissed) {
+    app.log.warn("dismiss-delivery-graph rejected: proposal left staged before dismiss landed", { digest });
+    return {
+      status: 400,
+      body: { ok: false, error: `no staged proposal for digest ${digest} — it may already be dismissed, dispatched, superseded, or aged out` },
+    };
+  }
+  app.log.info("dismiss-delivery-graph: proposal dismissed", { digest });
+
+  const outBody: DeliveryGraphTextResult = { ok: true, digest, message: `staged proposal ${digest} dismissed` };
+  return { status: 200, body: outBody };
+});

package/operations/getLibraryEntry.test.ts

@@ -0,0 +1,75 @@
+// Tests for GET /app/api/delivery-graph/library/{id} → `getLibraryEntry` (issue #522, epic #519 S3).
+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 { buildLibraryEntryRow, saveLibraryEntry } from "../app/deliveryGraphLibrary.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./getLibraryEntry.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+const GRAPH = JSON.stringify({ name: "runbook", nodes: [] });
+
+async function withApp(fn: (app: AppApi, data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-dglibget-"));
+  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 });
+  }
+}
+
+const req = { headers: new Headers() } as any;
+async function call(app: AppApi, id: string) {
+  return (await handler({ req, params: { id }, query: {} } as any, app)) as any;
+}
+
+test("get-library-entry: a known id → 200 with the entry (including graph JSON)", async () => {
+  await withApp(async (app, data) => {
+    const saved = await saveLibraryEntry(data, buildLibraryEntryRow({ name: "runbook", graphJson: GRAPH, source: "composed" }));
+    const res = await call(app, saved.id);
+    assertEquals(res.status, 200);
+    assertEquals(res.body.id, saved.id);
+    assertEquals(res.body.name, "runbook");
+    assertEquals(res.body.graph, GRAPH);
+    assertEquals(res.body.source, "composed");
+  });
+});
+
+test("get-library-entry: an unknown id → 404", async () => {
+  await withApp(async (app) => {
+    const res = await call(app, "no-such-id");
+    assertEquals(res.status, 404);
+    assert(typeof res.body.error === "string");
+  });
+});
+
+// The optional shared-secret guard is enforced in the handler (not by OpenAPI `security`), mirroring
+// the other read doors. `SECRET` is captured at module import, so we cache-bust re-import the handler
+// with NANO_PR_WEBHOOK_SECRET set to exercise both the rejected (401) and authorized (200) paths
+// against a real booted data layer holding a known entry.
+test("get-library-entry: shared-secret guard — 401 without x-hook-secret, 200 with it", async () => {
+  await withApp(async (app, data) => {
+    const saved = await saveLibraryEntry(data, buildLibraryEntryRow({ name: "runbook", graphJson: GRAPH, source: "composed" }));
+    const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+    process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+    try {
+      const mod = await import(`./getLibraryEntry.ts?guard=${Date.now()}`);
+      const guarded = mod.default as (c: any, a: any) => Promise<any>;
+      const bad = await guarded({ req: { headers: new Headers() }, params: { id: saved.id }, query: {} } as any, app);
+      assertEquals(bad.status, 401);
+      const ok = await guarded({ req: { headers: new Headers({ "x-hook-secret": "s3cr3t" }) }, params: { id: saved.id }, query: {} } as any, app);
+      assertEquals(ok.status, 200);
+      assertEquals(ok.body.id, saved.id);
+    } finally {
+      if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+      else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+    }
+  });
+});

package/operations/getLibraryEntry.ts

@@ -0,0 +1,25 @@
+// GET /app/api/delivery-graph/library/{id} → operationId `getLibraryEntry` (issue #522, epic #519 S3).
+// Fetch one saved library entry by its `id`, including its full `graph` JSON (the S4 Reuse action loads
+// it into the compose textarea; the S6 export action downloads it). An unknown id is a clean 404.
+//
+// The optional shared-secret guard mirrors the other read doors (getLineage / listActivePrs /
+// listStagedProposals): when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the
+// x-hook-secret header; unset → open.
+
+import { getLibraryEntry, libraryEntryDto } from "../app/deliveryGraphLibrary.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getLibraryEntry", async ({ params, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getLibraryEntry rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const entry = await getLibraryEntry(app.data, params.id);
+  if (!entry) {
+    return { status: 404, body: { error: `no library entry for id ${params.id}` } };
+  }
+  return { status: 200, body: libraryEntryDto(entry) };
+});

package/operations/importToLibrary.test.ts

@@ -0,0 +1,195 @@
+// Tests for POST /app/api/actions/delivery-graph/library/import → `importToLibrary` (issue #524, epic
+// #519 S5). Covers the three required paths: a valid file → 200, saved with source=imported; a file that
+// is not valid JSON → 400, nothing saved; a valid-JSON but UNCOMPILABLE graph → 400 with path-qualified
+// errors, nothing saved. Exercised against the REAL SQLite data layer so the migration + store
+// round-trip is validated, not modelled — mirroring saveToLibrary.test.ts.
+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 handler from "./importToLibrary.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-dglibimport-"));
+  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) {
+  // A real empty `Headers` (not `{}`) so the door's shared-secret guard — which reads
+  // `req.headers.get("x-hook-secret")` whenever NANO_PR_WEBHOOK_SECRET is configured — is safe to
+  // dereference here too, not only in the guard-specific test below.
+  return (await handler({ req: { headers: new Headers() } as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+const GOOD = JSON.stringify({
+  name: "imported-runbook",
+  nodes: [
+    { id: "a", kind: "agent", agent: { jobType: "senior:feature" } },
+    { id: "b", kind: "human", human: { prompt: "do X" } },
+  ],
+  edges: [{ from: "a", to: "b" }],
+});
+
+test("import-to-library: a valid file → 200, saved with source=imported, name from the graph", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { graphJson: GOOD });
+    assertEquals(res.status, 200);
+    assertEquals(res.body.ok, true);
+    assertEquals(res.body.entry.source, "imported");
+    assertEquals(res.body.entry.name, "imported-runbook");
+    assert(res.body.entry.id.startsWith("imported-runbook-"));
+    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))?.source, "imported");
+  });
+});
+
+test("import-to-library: an explicit name overrides the graph's own name", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { graphJson: GOOD, name: "My Import", description: "from disk" });
+    assertEquals(res.status, 200);
+    assertEquals(res.body.entry.name, "My Import");
+    assertEquals(res.body.entry.description, "from disk");
+    assert(res.body.entry.id.startsWith("my-import-"));
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 1);
+  });
+});
+
+// The `nameOverride ?? ingress.name` fallback: a graph with NO own name must still import when an
+// explicit override supplies one (the complement of the unnamed-with-no-override → 400 case below).
+test("import-to-library: an unnamed graph imports when an explicit override supplies the name", async () => {
+  await withApp(async (app, data) => {
+    const unnamed = JSON.stringify({
+      nodes: [{ id: "a", kind: "human", human: { prompt: "do X" } }],
+      edges: [],
+    });
+    const res = await call(app, { graphJson: unnamed, name: "Named By Override", description: "from disk" });
+    assertEquals(res.status, 200);
+    assertEquals(res.body.ok, true);
+    assertEquals(res.body.entry.name, "Named By Override");
+    assertEquals(res.body.entry.source, "imported");
+    assert(res.body.entry.id.startsWith("named-by-override-"));
+    // Persisted exactly one row, readable back with source=imported.
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 1);
+    assertEquals((await deliveryGraphLibrary(data).get(res.body.entry.id))?.source, "imported");
+  });
+});
+
+test("import-to-library: a file that isn't valid JSON → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { 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("import-to-library: an empty file → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { graphJson: "   " });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+// This is a MUTATING library door, so it carries the same optional shared-secret guard as the
+// get/delete/save library doors. `SECRET` is captured at module import, so we cache-bust re-import the
+// handler with NANO_PR_WEBHOOK_SECRET set to exercise both the rejected (401 — nothing persisted) path
+// and the authorized (200) path against a real booted data layer.
+test("import-to-library: shared-secret guard — 401 without x-hook-secret (no import), 200 with it", 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(`./importToLibrary.ts?guard=${Date.now()}`);
+      const guarded = mod.default as (c: any, a: any) => Promise<any>;
+      const bad = await guarded({ req: { headers: new Headers() }, params: {}, query: {}, body: { graphJson: GOOD } } as any, app);
+      assertEquals(bad.status, 401);
+      // The rejected request must not have persisted anything.
+      assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+      const ok = await guarded({ req: { headers: new Headers({ "x-hook-secret": "s3cr3t" }) }, params: {}, query: {}, body: { graphJson: GOOD } } as any, app);
+      assertEquals(ok.status, 200);
+      assertEquals(ok.body.entry.source, "imported");
+      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;
+    }
+  });
+});
+
+test("import-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, { graphJson: uncompilable });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(Array.isArray(res.body.errors) && res.body.errors.length > 0);
+    assert(
+      res.body.errors.every(
+        (e: { path: string; message: string }) => typeof e.path === "string" && e.path.trim().length > 0,
+      ),
+    );
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+// Regression for PR #533 review (operations/importToLibrary.ts): because `graphJson` is a STRING at
+// the request boundary, the runtime's OpenAPI `DeliveryGraph` shape gate never ran on the parsed
+// object, so a malformed NESTED value the semantic validator does not re-enumerate (here
+// `nodes[0].human.prompt: 42`) could return 200 and persist a contract-violating typed field. The
+// reused shape gate now rejects it at the door with a path-qualified error and persists nothing.
+test("import-to-library: a nested-shape violation (human.prompt not a string) → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    const malformed = JSON.stringify({
+      name: "malformed",
+      // biome-ignore lint/suspicious/noExplicitAny: deliberately violating the DeliveryGraph shape.
+      nodes: [{ id: "h", kind: "human", human: { prompt: 42 } } as any],
+    });
+    const res = await call(app, { graphJson: malformed });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assert(Array.isArray(res.body.errors) && res.body.errors.length > 0);
+    assert(
+      res.body.errors.some((e: { path: string; message: string }) => e.path.includes("nodes[0]/human/prompt")),
+      "the 400 must carry a path-qualified error at the offending nested field",
+    );
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});
+
+test("import-to-library: an unnamed graph with no override → 400, nothing persisted", async () => {
+  await withApp(async (app, data) => {
+    // A graph with no `name` cannot derive a library id and no override was supplied.
+    const unnamed = JSON.stringify({
+      nodes: [{ id: "a", kind: "human", human: { prompt: "do X" } }],
+      edges: [],
+    });
+    const res = await call(app, { graphJson: unnamed });
+    assertEquals(res.status, 400);
+    assertEquals(res.body.ok, false);
+    assertEquals((await deliveryGraphLibrary(data).all()).length, 0);
+  });
+});

package/operations/importToLibrary.ts

@@ -0,0 +1,62 @@
+// POST /app/api/actions/delivery-graph/library/import → operationId `importToLibrary` (issue #524, epic
+// #519 S5). Import a delivery graph into the reusable LIBRARY from a filesystem FILE. The compose
+// App-View's `<input type=file accept=.json>` reads the chosen file's text client-side and POSTs it here
+// as the raw `graphJson` string.
+//
+// Like `saveToLibrary` (#522), every import validates the graph through the SAME `parseAndCompileText`
+// pipeline the preview/stage doors use, so an uncompilable graph can NEVER be persisted — a file that is
+// not valid JSON, or a graph that fails to compile, is a clean 400 (carrying the path-qualified compile
+// `errors`) and NOTHING is written. The persisted entry is tagged `source: imported`. Its name defaults
+// to the imported graph's own `name`; an explicit `name` in the body overrides it (an unnamed graph with
+// no override is a clean 400 — the library id is name-derived, so a name is required).
+//
+// This is a MUTATING library door, so — like the get/delete library doors — it carries the optional
+// shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret
+// header (the compose client sends it for same-origin requests); unset → open. Without this, a configured
+// deployment would let an unauthenticated caller upsert persistent library entries. (The `save` door is
+// the deliberate exception — it is also reached by a declarative page row action that cannot carry the
+// header, so it is unguarded; see `saveToLibrary.ts`.)
+
+import { buildLibraryEntryRow, libraryEntryDto, saveLibraryEntry } from "../app/deliveryGraphLibrary.ts";
+import { parseAndCompileText } from "../app/deliveryGraphTextIngress.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("importToLibrary", async ({ body, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("import-to-library rejected: missing/invalid shared secret");
+    return { status: 401, body: { ok: false, error: "unauthorized" } };
+  }
+  const graphJson = body && typeof body.graphJson === "string" ? body.graphJson : "";
+  if (graphJson.trim() === "") {
+    app.log.warn("import-to-library rejected: empty file");
+    return { status: 400, body: { ok: false, error: "the imported file was empty — select a delivery-graph `.json` file" } };
+  }
+  const description = body && typeof body.description === "string" ? body.description : undefined;
+  const nameOverride = body && typeof body.name === "string" && body.name.trim() !== "" ? body.name.trim() : undefined;
+
+  // Validate/compile — a file that is not valid JSON, or a graph that fails validation, is a clean 400
+  // with path-qualified errors and nothing is persisted (an uncompilable graph can never enter the library).
+  const ingress = await parseAndCompileText({ graphJson });
+  if (!ingress.ok) {
+    app.log.warn("import-to-library rejected: graph failed validation", { message: ingress.body.error });
+    return { status: 400, body: ingress.body };
+  }
+
+  // The library id is name-derived, so a name is required. It defaults to the imported graph's own
+  // compiled `name`; an explicit override wins. An unnamed graph with no override is a clean 400.
+  const name = nameOverride ?? ingress.name ?? "";
+  if (name.trim() === "") {
+    app.log.warn("import-to-library rejected: imported graph has no name and none was provided");
+    return { status: 400, body: { ok: false, error: "the imported graph has no `name` — add one to the file, or supply a name" } };
+  }
+
+  const saved = await saveLibraryEntry(
+    app.data,
+    buildLibraryEntryRow({ name, description, graphJson: JSON.stringify(ingress.graph), source: "imported" }),
+  );
+  app.log.info("import-to-library saved", { id: saved.id, name: saved.name, source: "imported" });
+  return { status: 200, body: { ok: true, entry: libraryEntryDto(saved) } };
+});

package/operations/listLibrary.test.ts

@@ -0,0 +1,79 @@
+// Tests for GET /app/api/delivery-graph/library → `listLibrary` (issue #522, epic #519 S3). The read
+// behind the Library App-View: every saved entry, newest first, carrying its full graph JSON.
+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 { buildLibraryEntryRow, saveLibraryEntry } from "../app/deliveryGraphLibrary.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./listLibrary.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+const GRAPH = JSON.stringify({ name: "runbook", nodes: [] });
+
+async function withApp(fn: (app: AppApi, data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-dgliblist-"));
+  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 });
+  }
+}
+
+const req = { headers: new Headers() } as any;
+async function call(app: AppApi) {
+  return (await handler({ req, params: {}, query: {} } as any, app)) as any;
+}
+
+test("list-library: empty → count 0", async () => {
+  await withApp(async (app) => {
+    const res = await call(app);
+    assertEquals(res.status, 200);
+    assertEquals(res.body.count, 0);
+    assertEquals(res.body.entries.length, 0);
+  });
+});
+
+test("list-library: saved entries returned newest-first with their graph JSON", async () => {
+  await withApp(async (app, data) => {
+    await saveLibraryEntry(data, buildLibraryEntryRow({ name: "older", graphJson: GRAPH, source: "composed", createdAt: "2024-01-01T00:00:00.000Z" }));
+    await saveLibraryEntry(data, buildLibraryEntryRow({ name: "newer", graphJson: GRAPH, source: "imported", createdAt: "2024-06-01T00:00:00.000Z" }));
+    const res = await call(app);
+    assertEquals(res.status, 200);
+    assertEquals(res.body.count, 2);
+    assertEquals(res.body.entries[0].name, "newer");
+    assertEquals(res.body.entries[1].name, "older");
+    assertEquals(res.body.entries[0].graph, GRAPH);
+    assertEquals(res.body.entries[0].createdAt, "2024-06-01T00:00:00.000Z");
+    assert(typeof res.body.entries[0].updatedAt === "string");
+  });
+});
+
+// The optional shared-secret guard is enforced in the handler (not by OpenAPI `security`), mirroring
+// the other read doors (getLineage / listActivePrs / listStagedProposals). `SECRET` is captured at
+// module import, so we cache-bust re-import the handler with NANO_PR_WEBHOOK_SECRET set to exercise
+// both the rejected (401) and authorized (200) paths against a real booted data layer.
+test("list-library: shared-secret guard — 401 without x-hook-secret, 200 with it", async () => {
+  await withApp(async (app) => {
+    const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+    process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+    try {
+      const mod = await import(`./listLibrary.ts?guard=${Date.now()}`);
+      const guarded = mod.default as (c: any, a: any) => Promise<any>;
+      const bad = await guarded({ req: { headers: new Headers() }, params: {}, query: {} } as any, app);
+      assertEquals(bad.status, 401);
+      const ok = await guarded({ req: { headers: new Headers({ "x-hook-secret": "s3cr3t" }) }, params: {}, query: {} } as any, app);
+      assertEquals(ok.status, 200);
+      assert(Array.isArray(ok.body.entries));
+    } finally {
+      if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+      else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+    }
+  });
+});

package/operations/listLibrary.ts

@@ -0,0 +1,24 @@
+// GET /app/api/delivery-graph/library → operationId `listLibrary` (issue #522, epic #519 S3). The read
+// behind the Library App-View (S4/#523): every saved library entry, newest first, with its full
+// `graph` JSON so the export affordance (S6/#525) can build a client-side download straight from the
+// list payload.
+//
+// The optional shared-secret guard mirrors the other read doors (getLineage / listActivePrs /
+// listStagedProposals): when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the
+// x-hook-secret header; unset → open.
+
+import { libraryEntryDto, listLibraryEntries } from "../app/deliveryGraphLibrary.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("listLibrary", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listLibrary rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const rows = await listLibraryEntries(app.data);
+  const entries = rows.map(libraryEntryDto);
+  return { status: 200, body: { count: entries.length, entries } };
+});