@gr8ful/spf 0.3.0 → 0.5.0

package/dist/test/watch.test.js

@@ -1,7 +1,21 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import path from "node:path";
-import { branchNameFor, claimNewWork, createWatchState, finishReviews, reconcileOrphans, tick } from "../core/watch.js";
+import { branchNameFor, claimNewWork, claimSpecs, createWatchState, finishReviews, reconcileOrphans, reconcileRefining, refineBranchNameFor, tick, } from "../core/watch.js";
+import { escapeForMarkup, formatReviewDigest, truncateDigest } from "../cli/commands/watch.js";
+/** A minimal, schema-shaped ReviewOutputT — only the fields formatReviewDigest reads. */
+function reviewOutput(overrides = {}) {
+    return {
+        status: "success",
+        summary: "",
+        artifacts: [],
+        notes_for_next_agent: "",
+        approved: false,
+        findings: [],
+        blocking: [],
+        ...overrides,
+    };
+}
 /** In-memory fake — exactly the seam `provider.ts` exists for. */
 class FakeProvider {
     entries = new Map();
@@ -21,19 +35,21 @@ class FakeProvider {
     async listInState(state) {
         return [...this.entries.values()].filter((e) => e.state === state).map((e) => e.issue);
     }
-    async claim(issue) {
+    async claim(issue, opts) {
         this.claimCalls.push(issue.id);
         const entry = this.entries.get(issue.id);
-        if (entry.state !== "ready")
+        const from = opts?.from ?? "ready";
+        const to = opts?.to ?? "working";
+        if (entry.state !== from)
             return false;
-        entry.state = "working";
+        entry.state = to;
         return true;
     }
     async transition(issue, to, detail) {
         this.entries.get(issue.id).state = to;
         this.transitions.push({ id: issue.id, to, detail });
     }
-    async comment() { }
+    async comment(_issue, _body) { }
     async readMarker(issue) {
         return this.entries.get(issue.id)?.marker ?? null;
     }
@@ -48,7 +64,7 @@ class FakeCodeHost {
     nextPrNumber = 1000;
     async openPr(opts) {
         const number = this.nextPrNumber++;
-        this.openedPrs.push({ title: opts.title, branch: opts.branch });
+        this.openedPrs.push({ title: opts.title, branch: opts.branch, body: opts.body });
         this.prs.set(number, { merged: false, state: "open", ciStatus: "pending" });
         return { number, branch: opts.branch, url: `https://example.invalid/pr/${number}` };
     }
@@ -91,6 +107,12 @@ function makeDeps(provider, codeHost, overrides = {}) {
         chain: "plan-build-test",
         baseBranch: "main",
         concurrency: 2,
+        // Off by default, like WatchRefineConfigSchema itself — a test that
+        // doesn't override these never touches the refine lane at all.
+        refineEnabled: false,
+        refineConcurrency: 1,
+        refineChain: "refine",
+        runRefine: async (opts) => ({ accepted: true, adwId: opts.adwId, detail: "", created: [] }),
         worktreesDir: "/tmp/spf-watch-test-worktrees",
         linkDataDir: () => { },
         dryRun: false,
@@ -382,6 +404,275 @@ test("reconcileOrphans: a routine orphan resume/retry notifies nothing — only
     await reconcileOrphans(makeDeps(provider, codeHost, { notify }), state);
     assert.deepEqual(events, []);
 });
+// ── the review digest threaded into the PR + pr_opened notification ────────
+test("claimNewWork: a reviewSummary from runChain lands in the PR body and the pr_opened event's detail/fields", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("60", "Add a /health endpoint");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        notify,
+        runChain: async (opts) => ({
+            accepted: true,
+            adwId: opts.adwId,
+            detail: "",
+            reviewRequired: true,
+            reviewSummary: "Reviewer verdict: changes requested.\nBlocking:\n- add a test",
+        }),
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.match(codeHost.openedPrs[0].body, /Automated by `spf watch`/);
+    assert.match(codeHost.openedPrs[0].body, /Reviewer verdict: changes requested\.\nBlocking:\n- add a test/);
+    const prOpened = events.find((e) => e.kind === "pr_opened");
+    assert.equal(prOpened.detail, "Reviewer verdict: changes requested.\nBlocking:\n- add a test");
+    assert.deepEqual(prOpened.fields.find(([k]) => k === "review"), ["review", "reviewed"]);
+});
+test("claimNewWork: a reviewer-required chain with no readable verdict says so, distinctly from no reviewer at all", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("61", "Add a /health endpoint");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        notify,
+        runChain: async (opts) => ({ accepted: true, adwId: opts.adwId, detail: "", reviewRequired: true }),
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.match(codeHost.openedPrs[0].body, /no verdict could be read back/);
+    const prOpened = events.find((e) => e.kind === "pr_opened");
+    assert.deepEqual(prOpened.fields.find(([k]) => k === "review"), ["review", "reviewer ran, no verdict"]);
+});
+test("claimNewWork: a chain with no reviewer step says nothing reviewed this change", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("62", "Add a /health endpoint");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    // makeDeps' default runChain returns neither reviewRequired nor reviewSummary.
+    const deps = makeDeps(provider, codeHost, { notify });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.match(codeHost.openedPrs[0].body, /Nothing reviewed this change — chain `plan-build-test` has no reviewer step\./);
+    const prOpened = events.find((e) => e.kind === "pr_opened");
+    assert.deepEqual(prOpened.fields.find(([k]) => k === "review"), ["review", "not reviewed"]);
+});
+// ── the refine lane ──────────────────────────────────────────────────────
+test("refineBranchNameFor: same sanitizer as branchNameFor, different prefix", () => {
+    assert.equal(refineBranchNameFor({ id: "9", title: "Team invitations spec", body: "", labels: [] }), "spf-refine/9-team-invitations-spec");
+});
+test("claimSpecs: a disabled refine lane never lists spec-ready issues or claims anything", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("100", "A spec", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    provider.listInState = async () => {
+        throw new Error("listInState should never be called when refineEnabled is false");
+    };
+    await claimSpecs(makeDeps(provider, codeHost, { refineEnabled: false }), state);
+    assert.equal(provider.claimCalls.length, 0);
+});
+test("claimSpecs: claims a spec-ready spec, publishes, and finishes it to done with a summary comment", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("101", "Team invitations", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const comments = [];
+    provider.comment = async (issue, body) => {
+        comments.push({ id: issue.id, body });
+    };
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        runRefine: async (opts) => ({
+            accepted: true,
+            adwId: opts.adwId,
+            detail: "",
+            created: [
+                { id: "200", title: "Owner invites by email", kind: "story", isLeaf: true },
+                { id: "199", title: "Invitations feature", kind: "feature", isLeaf: false },
+            ],
+        }),
+    });
+    await claimSpecs(deps, state);
+    await waitUntil(() => state.refining.size === 0);
+    assert.deepEqual(provider.claimCalls, ["101"]);
+    assert.deepEqual(provider.transitions.map((t) => t.to), ["done"]);
+    assert.equal(comments.length, 1);
+    assert.match(comments[0].body, /#200 \(story\): Owner invites by email/);
+    assert.deepEqual(provider.entries.get("101").marker?.refined, ["200", "199"]);
+});
+test("claimSpecs: never claims more than refineConcurrency in one tick, independent of the build lane's own budget", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("110", "one spec", "spec-ready");
+    provider.addIssue("111", "two spec", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        refineConcurrency: 1,
+        runRefine: () => new Promise(() => { }), // never resolves — keeps the claim "in flight" for this assertion
+    });
+    await claimSpecs(deps, state);
+    assert.equal(state.refining.size, 1);
+    assert.equal(provider.claimCalls.length, 1);
+});
+test("claimSpecs: dry-run claims no spec and never calls runRefine", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("120", "dry run spec", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    let called = false;
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        dryRun: true,
+        runRefine: async (opts) => {
+            called = true;
+            return { accepted: true, adwId: opts.adwId, detail: "", created: [] };
+        },
+    });
+    await claimSpecs(deps, state);
+    assert.equal(provider.claimCalls.length, 0);
+    assert.equal(called, false);
+    assert.equal(provider.entries.get("120").state, "spec-ready");
+});
+test("claimSpecs: a rejected refine chain blocks the spec with the failure detail, without publishing anything", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("130", "unrefinable spec", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        runRefine: async (opts) => ({ accepted: false, adwId: opts.adwId, detail: "refiner failed gates", created: [] }),
+    });
+    await claimSpecs(deps, state);
+    await waitUntil(() => state.refining.size === 0);
+    assert.deepEqual(provider.transitions, [{ id: "130", to: "blocked", detail: "refiner failed gates" }]);
+});
+test("claimSpecs: a re-claimed spec whose marker already lists published issues skips runRefine entirely", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("140", "already published", "spec-ready", { refined: ["300", "301"] });
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    let called = false;
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        runRefine: async (opts) => {
+            called = true;
+            return { accepted: true, adwId: opts.adwId, detail: "", created: [] };
+        },
+    });
+    await claimSpecs(deps, state);
+    await waitUntil(() => state.refining.size === 0);
+    assert.equal(called, false, "to-tickets itself has no idempotency guard — this is the one this lane adds");
+    assert.deepEqual(provider.transitions.map((t) => t.to), ["done"]);
+});
+test("reconcileRefining: a refining spec whose marker already lists published issues finishes it without re-running the refiner", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("150", "orphaned after publish", "refining", { refined: ["400"] });
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    await reconcileRefining(makeDeps(provider, codeHost, { refineEnabled: true }), state);
+    assert.deepEqual(provider.transitions, [{ id: "150", to: "done", detail: undefined }]);
+});
+test("reconcileRefining: a refining spec with no marker retries up to the cap, then blocks", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("151", "orphaned, no marker", "refining", null);
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const deps = makeDeps(provider, codeHost, { refineEnabled: true });
+    await reconcileRefining(deps, state); // attempt 1 -> spec-ready
+    assert.equal(provider.entries.get("151").state, "spec-ready");
+    provider.entries.get("151").state = "refining";
+    await reconcileRefining(deps, state); // attempt 2 -> spec-ready
+    assert.equal(provider.entries.get("151").state, "spec-ready");
+    provider.entries.get("151").state = "refining";
+    await reconcileRefining(deps, state); // attempt 3 exceeds MAX_ORPHAN_ATTEMPTS (2) -> blocked
+    assert.equal(provider.entries.get("151").state, "blocked");
+    assert.match(provider.transitions.at(-1)?.detail ?? "", /Gave up after 2 orphaned refine attempts/);
+});
+test("reconcileRefining: a disabled refine lane is a complete no-op", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("152", "should be ignored", "refining", null);
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    provider.listInState = async () => {
+        throw new Error("listInState should never be called when refineEnabled is false");
+    };
+    await reconcileRefining(makeDeps(provider, codeHost, { refineEnabled: false }), state);
+    assert.equal(provider.transitions.length, 0);
+});
+test("claim -> refine -> published fires issue_claimed then spec_refined, both info-level", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("160", "A spec", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        notify,
+        runRefine: async (opts) => ({ accepted: true, adwId: opts.adwId, detail: "", created: [{ id: "500", title: "A story", kind: "story", isLeaf: true }] }),
+    });
+    await claimSpecs(deps, state);
+    await waitUntil(() => state.refining.size === 0);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "spec_refined"]);
+    assert.ok(events.every((e) => e.level === "info"));
+});
+// ── escapeForMarkup / truncateDigest / formatReviewDigest ───────────────────
+// These three are what actually assembles the digest — the tests above only
+// exercise core/watch.ts's three-way reviewLine selection via a stubbed
+// runChain, so none of them ever call into these. Slack/GitHub markup
+// escaping is the one security-relevant behavior spec item B calls out by
+// name (a reviewer's findings are LLM-authored, hence untrusted), so it needs
+// direct coverage.
+test("escapeForMarkup: a Slack link-forgery attempt is neutralized, and & is escaped without double-escaping", () => {
+    const escaped = escapeForMarkup("<https://evil.example/|click here> & enjoy");
+    assert.equal(escaped, "&lt;https://evil.example/|click here&gt; &amp; enjoy");
+    assert.ok(!escaped.includes("<") && !escaped.includes(">"), "no raw angle bracket must survive — that's what prevents a forged Slack mrkdwn link");
+});
+test("formatReviewDigest: an approved review's met findings are the actual signal, and are surfaced (not silently dropped)", () => {
+    const review = reviewOutput({
+        approved: true,
+        findings: [
+            { requirement: "endpoint returns 200", met: true, evidence: "curl output attached" },
+            { requirement: "handles missing auth header", met: true, evidence: "" },
+            { requirement: "logs the request id", met: true, evidence: "trace shows request_id field" },
+        ],
+        blocking: [],
+    });
+    const digest = formatReviewDigest(review);
+    assert.match(digest, /^Reviewer verdict: approved\./);
+    assert.match(digest, /Verified 3 requirement\(s\):/);
+    assert.match(digest, /- endpoint returns 200 — curl output attached/);
+    assert.match(digest, /- handles missing auth header/);
+    assert.match(digest, /- logs the request id — trace shows request_id field/);
+});
+test("formatReviewDigest: blocking items and unmet findings are escaped before being joined in", () => {
+    const review = reviewOutput({
+        approved: false,
+        blocking: ["contains a <https://evil.example/|forged link> & needs fixing"],
+        findings: [{ requirement: "auth check <script>", met: false, evidence: "not implemented & untested" }],
+    });
+    const digest = formatReviewDigest(review);
+    assert.match(digest, /^Reviewer verdict: changes requested\./);
+    assert.match(digest, /- contains a &lt;https:\/\/evil\.example\/\|forged link&gt; &amp; needs fixing/);
+    assert.match(digest, /- auth check &lt;script&gt; — not implemented &amp; untested/);
+    assert.ok(!digest.includes("<script>") && !digest.includes("<https"), "raw markup from an unmet finding must not survive into the digest");
+});
+test("truncateDigest: a digest over the cap is cut at exactly the codepoint boundary, without splitting a surrogate pair", () => {
+    // An astral-plane emoji (2 UTF-16 code units, 1 codepoint) placed exactly
+    // at the 1200th codepoint — a naive `.slice(0, 1200)` on UTF-16 units would
+    // land mid-pair and emit a lone, invalid surrogate instead of the emoji.
+    const emoji = "\u{1F600}"; // grinning face, codepoint #1200
+    const filler = "a".repeat(1199); // codepoints #1-1199
+    const text = filler + emoji + "more text that must be cut off entirely";
+    const result = truncateDigest(text);
+    assert.equal(result, filler + emoji + "…", "must keep exactly 1200 whole codepoints (the emoji intact) then the ellipsis");
+    assert.ok(result.endsWith("…"), "a truncated digest must end with the ellipsis marker");
+    const short = "short digest, well under the cap";
+    assert.equal(truncateDigest(short), short, "text under the cap must pass through unchanged, with no ellipsis appended");
+});
 test("tick: a per-stage error is caught and fires exactly one watch_error", async () => {
     const provider = new FakeProvider();
     const codeHost = new FakeCodeHost();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",
@@ -18,10 +18,6 @@
     "README.md",
     "LICENSE"
   ],
-  "exports": {
-    ".": "./dist/index.js",
-    "./core": "./dist/core/index.js"
-  },
   "engines": {
     "node": ">=22.19.0"
   },
@@ -44,6 +40,7 @@
     "tag:patch": "node scripts/tag-release.js patch"
   },
   "dependencies": {
+    "@earendil-works/pi-ai": "0.83.0",
     "@flue/runtime": "2.0.3",
     "@hono/node-server": "^2.1.1",
     "@valibot/to-json-schema": "^1.7.1",
@@ -51,6 +48,9 @@
     "valibot": "^1.4.2",
     "yaml": "^2.5.1"
   },
+  "overrides": {
+    "@earendil-works/pi-ai": "0.83.0"
+  },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "lefthook": "^2.1.10",