@nanobpm/nano-workforce 0.90.0 → 0.92.0

package/operations/acknowledgeEpic.test.ts

@@ -0,0 +1,130 @@
+// Tests for the POST /app/api/actions/acknowledge-epic operation `acknowledgeEpic` (issue #298).
+// The nwf UI's "Dismiss" affordance for a RESOLVED epic — landed (`delivery=landed`) or
+// resolved-not-landed (`delivery=null`); only still-`converging` epics are rejected. It stamps
+// `acknowledged_at` via the plans gateway, which recomputes `list_bucket` to 'history' (and
+// `ack_open` to 0), dropping the resolved epic from Active into History. Unlike acknowledge-blocked
+// it completes NO user task (a resolved epic is not parked). The epic twin of acknowledge-done.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { plans } from "../app/plan.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./acknowledgeEpic.ts";
+
+// An in-memory data layer wired through the REAL plans gateway proxy, so the test exercises the
+// gateway's list_bucket/ack_open projection exactly as production does.
+function memApp(seed: any[]): { app: AppApi; rows: any[] } {
+  const stores: Record<string, any[]> = { plans: seed };
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+        return r ? 1 : 0;
+      },
+    };
+  }
+  const app = {
+    data: { table: (n: string, pk?: string) => tbl(n, pk) },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, rows: stores.plans };
+}
+
+async function call(app: AppApi, body: unknown) {
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+test("acknowledge-epic: stamps acknowledged_at and flips list_bucket to 'history' on a landed epic", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#1", status: "done", delivery: "landed", acknowledged_at: null }]);
+  // Seed the projection as the gateway would have on the last write (landed, unacknowledged → active).
+  await plans(app.data).update("o/r#1", { delivery: "landed" });
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 1);
+
+  const res = await call(app, { plan_key: "o/r#1" });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals(rows[0].list_bucket, "history");
+  assertEquals(rows[0].ack_open, 0);
+});
+
+test("acknowledge-epic: a still-converging epic is rejected (409) and stays Active", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#2", status: "done", delivery: "converging", acknowledged_at: null }]);
+  await plans(app.data).update("o/r#2", { delivery: "converging" });
+
+  const res = await call(app, { plan_key: "o/r#2" });
+
+  assertEquals(res.status, 409);
+  assertEquals(res.body.ok, false);
+  // Untouched: no premature acknowledged_at, still Active.
+  assertEquals(rows[0].acknowledged_at, null);
+  assertEquals(rows[0].list_bucket, "active");
+});
+
+test("acknowledge-epic: a resolved-not-landed epic (delivery=null) is accepted (200) and flips to History", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#2b", status: "done", delivery: null, acknowledged_at: null }]);
+  // Seed the projection as the gateway would have on the last write (resolved-not-landed, unacknowledged → active).
+  await plans(app.data).update("o/r#2b", { delivery: null });
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 1);
+
+  const res = await call(app, { plan_key: "o/r#2b" });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals(rows[0].list_bucket, "history");
+  assertEquals(rows[0].ack_open, 0);
+});
+
+test("acknowledge-epic: a live (dispatched) epic is rejected (409)", async () => {
+  const { app } = memApp([{ plan_key: "o/r#3", status: "dispatched", delivery: null, acknowledged_at: null }]);
+  const res = await call(app, { plan_key: "o/r#3" });
+  assertEquals(res.status, 409);
+});
+
+test("acknowledge-epic: a missing plan_key → 400", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, {});
+  assertEquals(res.status, 400);
+});
+
+test("acknowledge-epic: no matching epic → 404", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, { plan_key: "o/r#404" });
+  assertEquals(res.status, 404);
+});
+
+test("acknowledge-epic: idempotent — re-acknowledging a landed epic keeps it in History", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#5", status: "done", delivery: "landed", acknowledged_at: null }]);
+  await plans(app.data).update("o/r#5", { delivery: "landed" });
+
+  assertEquals((await call(app, { plan_key: "o/r#5" })).status, 200);
+  const firstStamp = rows[0].acknowledged_at;
+  assertEquals(rows[0].list_bucket, "history");
+
+  const res2 = await call(app, { plan_key: "o/r#5" });
+  assertEquals(res2.status, 200);
+  assertEquals(rows[0].list_bucket, "history");
+  // Re-stamped (a fresh timestamp) but still resolved.
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  void firstStamp;
+});

package/operations/acknowledgeEpic.ts

@@ -0,0 +1,63 @@
+// POST /app/api/actions/acknowledge-epic → operationId `acknowledgeEpic` (issue #298).
+// The nwf UI's "Dismiss" affordance for a RESOLVED epic: an operator dismisses a `done` epic whose
+// fan-out has finished (all slice PRs reached a terminal state — whether all merged/landed or
+// resolved-not-landed) directly from the Epic / Overview pages so it drops out of the Active epic list
+// into History. It is the epic twin of `acknowledgeDone` (the feature-run tick-off) — a resolved epic
+// is NOT parked at a user task, so this op completes no user task and touches no engine/ledger: it
+// simply stamps `acknowledged_at` on the `plans` row via the plans gateway.
+//
+// The gateway (app/plan.ts) recomputes `list_bucket`/`ack_open` on that write — a landed, now-
+// acknowledged epic flips `list_bucket` to 'history' and `ack_open` to 0 — so this op NEVER hand-sets
+// a derived projection. Keyed on the row's `plan_key`. Idempotent-safe: re-acknowledging re-stamps
+// the timestamp and keeps the row in History.
+//
+// It rejects (409) an epic that is NOT yet resolved — i.e. anything the `epicIsAcknowledgeable`
+// guard refuses: a non-`done` status (`planning`/`dispatched`), or `done` but still `converging`. A
+// resolved epic is acknowledgeable whether all slices merged (`delivery=landed`) or it resolved-not-
+// landed (`delivery=null`); only a still-live or still-converging epic is refused, so those stay
+// visible in Active and can never pre-seed the tick-off.
+
+import { epicIsAcknowledgeable } from "../app/delivery.ts";
+import { plans } from "../app/plan.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("acknowledgeEpic", async ({ body }, app) => {
+  if (!body || typeof body !== "object") {
+    app.log.warn("acknowledge-epic rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "plan_key is required" } };
+  }
+
+  const planKey = str(body.plan_key);
+  if (!planKey) return { status: 400, body: { ok: false, error: "plan_key is required" } };
+
+  const table = plans(app.data);
+  const plan = await table.get(planKey);
+  if (!plan) {
+    app.log.warn("acknowledge-epic: no such plan", { planKey });
+    return { status: 404, body: { ok: false, error: "no such epic" } };
+  }
+
+  // Guard: only a RESOLVED epic (`status=done` and no longer `converging`) carries the Dismiss
+  // affordance. Acknowledging a live/converging epic would pre-seed `acknowledged_at`, so the moment
+  // it later resolved `deriveEpicBucket` would drop it straight into History, skipping the operator
+  // tick-off this op exists to require — and a converging epic must stay visible while its slices land.
+  if (!epicIsAcknowledgeable(plan.status, plan.delivery ?? null)) {
+    app.log.warn("acknowledge-epic rejected: epic is not resolved", {
+      planKey,
+      status: plan.status,
+      delivery: plan.delivery ?? null,
+    });
+    return { status: 409, body: { ok: false, error: "epic is not resolved" } };
+  }
+
+  // Stamp the dismissal. The gateway recomputes `list_bucket` (→ 'history') and `ack_open` (→ 0) from
+  // the merged row, so we never hand-set them here. Idempotent: re-acknowledging re-stamps and stays
+  // in History.
+  const now = new Date().toISOString();
+  await table.update(planKey, { acknowledged_at: now, updated_at: now });
+
+  app.log.info("operator dismissed resolved epic", { planKey });
+  return { status: 200, body: { ok: true, message: "acknowledged" } };
+});