@gr8ful/spf 0.2.1 → 0.3.0

package/dist/test/interview.test.js

@@ -151,6 +151,124 @@ test("declining the final confirm returns null — nothing to write", async () =
     const result = await runInterview(asker, ctx);
     assert.equal(result, null);
 });
+test("notifications: declining the gate leaves config.notifications undefined", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: { "backend runs": "claude_code", "Model (Claude": "sonnet", Authentication: "login" },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Send notifications": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.notifications, undefined);
+});
+test("notifications: accepting collects the scope, a channel, and its webhook env key", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Notify on": "all",
+            Channel: "slack",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Send notifications": true,
+            "Add another channel": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { SLACK_WEBHOOK_URL: "https://hooks.slack.com/services/T000/B000/XXXX" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.notifications.events, "all");
+    assert.deepEqual(config.notifications.channels, [{ kind: "slack", webhook_url_env: "SLACK_WEBHOOK_URL" }]);
+    assert.equal(result.env.SLACK_WEBHOOK_URL, "https://hooks.slack.com/services/T000/B000/XXXX");
+    assert.ok(result.envExampleKeys.includes("SLACK_WEBHOOK_URL"));
+    // The written document must still merge and validate cleanly, same
+    // pipeline `spf doctor` runs.
+    const configPath = mergedConfigPath();
+    const { stringify } = await import("yaml");
+    writeFileSync(configPath, stringify(config));
+    const cfg = loadConfig([BUILTIN_CONFIG_PATH, configPath]);
+    assert.equal(cfg.notifications.events, "all");
+    assert.equal(cfg.notifications.channels[0].kind, "slack");
+});
+test("customize models per agent: declining keeps today's behavior — only the three pinned agents, all matching defaults.model", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: { "backend runs": "claude_code", "Model (Claude": "opus", Authentication: "login" },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Customize models per agent": false,
+            "Send notifications": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.deepEqual(config.agents.map((a) => a.name).sort(), ["documenter", "planner", "reviewer"]);
+    for (const a of config.agents)
+        assert.equal(a.model, "opus");
+});
+test("customize models per agent: accepting patches the pinned three and appends builder/scout", async () => {
+    const ctx = gatherContext(dir, new Map());
+    assert.deepEqual(ctx.rosterNames.slice().sort(), ["builder", "documenter", "planner", "reviewer", "scout"]);
+    const asker = createFakeAsker({
+        select: { "backend runs": "claude_code", "Model (Claude": "sonnet", Authentication: "login" },
+        text: {
+            "  planner": "opus",
+            "  builder": "sonnet",
+            "  scout": "haiku",
+            "  reviewer": "opus",
+            "  documenter": "sonnet",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Customize models per agent": true,
+            "Send notifications": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    const byName = Object.fromEntries(config.agents.map((a) => [a.name, a.model]));
+    assert.deepEqual(byName, { planner: "opus", reviewer: "opus", documenter: "sonnet", builder: "sonnet", scout: "haiku" });
+    const configPath = mergedConfigPath();
+    const { stringify } = await import("yaml");
+    writeFileSync(configPath, stringify(config));
+    const cfg = loadConfig([BUILTIN_CONFIG_PATH, configPath]);
+    validate(cfg, cfg.agents.map((a) => a.name), Object.keys(cfg.quality.suites), dir); // throws on any problem
+    assert.equal(cfg.agents.find((a) => a.name === "scout").model, "haiku");
+});
 test("an existing .env value is offered back as the default when a secret is left blank", async () => {
     const ctx = gatherContext(dir, new Map([["GITHUB_TOKEN", "ghp_existingvalue"]]));
     const asker = createFakeAsker({

package/dist/test/notify.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/notify.test.js

@@ -0,0 +1,174 @@
+/**
+ * The notifier: the `events` filter matrix, per-channel scope override, a
+ * real webhook POST against a local `node:http` receiver (not a `fetch`
+ * mock — proves the actual bytes on the wire), a rejecting channel never
+ * propagating, `flush()` actually awaiting pending sends, and an unset env
+ * var degrading to a warning instead of a crash.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import * as v from "valibot";
+import { Notifier, resolveNotifier, DEFAULT_NOTIFY_ENV_KEY } from "../core/notify/notifier.js";
+import { SFConfigSchema } from "../core/data_types.js";
+function baseConfig(overrides = {}) {
+    return v.parse(SFConfigSchema, { notifications: { events: "errors", channels: [], ...overrides } });
+}
+function infoEvent() {
+    return { kind: "run_started", level: "info", title: "run started", fields: [] };
+}
+function errorEvent() {
+    return { kind: "run_failed", level: "error", title: "run failed", fields: [] };
+}
+class RecordingChannel {
+    received = [];
+    label = "recording";
+    async send(event) {
+        this.received.push(event);
+    }
+}
+class RejectingChannel {
+    label = "rejecting";
+    async send() {
+        throw new Error("boom");
+    }
+}
+class BlockedChannel {
+    label = "blocked";
+    release;
+    gate = new Promise((resolve) => (this.release = resolve));
+    async send() {
+        await this.gate;
+    }
+}
+test("events: off never sends, regardless of level", () => {
+    const channel = new RecordingChannel();
+    const notifier = new Notifier([{ channel, scope: "off" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    notifier.send(errorEvent());
+    assert.deepEqual(channel.received, []);
+});
+test("events: errors sends only level=error", () => {
+    const channel = new RecordingChannel();
+    const notifier = new Notifier([{ channel, scope: "errors" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    notifier.send(errorEvent());
+    assert.equal(channel.received.length, 1);
+    assert.equal(channel.received[0].level, "error");
+});
+test("events: all sends both info and error", () => {
+    const channel = new RecordingChannel();
+    const notifier = new Notifier([{ channel, scope: "all" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    notifier.send(errorEvent());
+    assert.equal(channel.received.length, 2);
+});
+test("a per-channel scope overrides the top-level scope", () => {
+    const loud = new RecordingChannel();
+    const quiet = new RecordingChannel();
+    const notifier = new Notifier([
+        { channel: loud, scope: "all" },
+        { channel: quiet, scope: "errors" },
+    ], 1000, false, () => { });
+    notifier.send(infoEvent());
+    assert.equal(loud.received.length, 1);
+    assert.equal(quiet.received.length, 0);
+});
+test("dry-run logs and sends nothing to any channel", () => {
+    const channel = new RecordingChannel();
+    const logs = [];
+    const notifier = new Notifier([{ channel, scope: "all" }], 1000, true, (m) => logs.push(m));
+    notifier.send(infoEvent());
+    assert.deepEqual(channel.received, []);
+    assert.equal(logs.length, 1);
+    assert.match(logs[0], /would notify/);
+});
+test("a rejecting channel logs one line and never throws or blocks other channels", async () => {
+    const rejecting = new RejectingChannel();
+    const ok = new RecordingChannel();
+    const logs = [];
+    const notifier = new Notifier([
+        { channel: rejecting, scope: "all" },
+        { channel: ok, scope: "all" },
+    ], 1000, false, (m) => logs.push(m));
+    assert.doesNotThrow(() => notifier.send(infoEvent()));
+    await notifier.flush();
+    assert.equal(ok.received.length, 1);
+    assert.equal(logs.length, 1);
+    assert.match(logs[0], /rejecting notification failed: boom/);
+});
+test("flush() actually awaits pending sends before returning", async () => {
+    const blocked = new BlockedChannel();
+    const notifier = new Notifier([{ channel: blocked, scope: "all" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    let flushed = false;
+    const flushPromise = notifier.flush().then(() => {
+        flushed = true;
+    });
+    await new Promise((r) => setTimeout(r, 20));
+    assert.equal(flushed, false, "flush must not resolve before the pending send does");
+    blocked.release();
+    await flushPromise;
+    assert.equal(flushed, true);
+});
+test("resolveNotifier returns null when events is off", () => {
+    const cfg = baseConfig({ events: "off", channels: [{ kind: "webhook", webhook_url_env: "SPF_TEST_WEBHOOK" }] });
+    assert.equal(resolveNotifier(cfg), null);
+});
+test("resolveNotifier returns null when no channels are configured", () => {
+    const cfg = baseConfig({ events: "all", channels: [] });
+    assert.equal(resolveNotifier(cfg), null);
+});
+test("resolveNotifier skips a channel whose env var is unset, with one warning naming the key — never throws", () => {
+    delete process.env["SPF_TEST_WEBHOOK_UNSET"];
+    const cfg = baseConfig({ events: "all", channels: [{ kind: "webhook", webhook_url_env: "SPF_TEST_WEBHOOK_UNSET" }] });
+    const logs = [];
+    const notifier = resolveNotifier(cfg, { log: (m) => logs.push(m) });
+    assert.equal(notifier, null);
+    assert.equal(logs.length, 1);
+    assert.match(logs[0], /SPF_TEST_WEBHOOK_UNSET is not set/);
+});
+test("resolveNotifier falls back to the kind's default env key when webhook_url_env is empty", () => {
+    process.env["SLACK_WEBHOOK_URL"] = "http://127.0.0.1:1/unused";
+    try {
+        const cfg = baseConfig({ events: "all", channels: [{ kind: "slack" }] });
+        const notifier = resolveNotifier(cfg);
+        assert.notEqual(notifier, null);
+        assert.equal(DEFAULT_NOTIFY_ENV_KEY["slack"], "SLACK_WEBHOOK_URL");
+    }
+    finally {
+        delete process.env["SLACK_WEBHOOK_URL"];
+    }
+});
+test("a webhook channel posts the real NotifyEvent JSON over the wire to a local receiver", async () => {
+    let receivedBody = "";
+    let receivedContentType = "";
+    const server = createServer((req, res) => {
+        receivedContentType = req.headers["content-type"] ?? "";
+        let body = "";
+        req.on("data", (chunk) => (body += chunk));
+        req.on("end", () => {
+            receivedBody = body;
+            res.writeHead(200);
+            res.end("ok");
+        });
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = server.address().port;
+    const envKey = "SPF_TEST_WEBHOOK_LIVE";
+    process.env[envKey] = `http://127.0.0.1:${port}/hook`;
+    try {
+        const cfg = baseConfig({ events: "all", channels: [{ kind: "webhook", webhook_url_env: envKey }] });
+        const notifier = resolveNotifier(cfg);
+        assert.notEqual(notifier, null);
+        const event = { kind: "issue_claimed", level: "info", title: "issue 42 claimed", fields: [["issue", "42"]] };
+        notifier.send(event);
+        await notifier.flush();
+        assert.equal(receivedContentType, "application/json");
+        assert.deepEqual(JSON.parse(receivedBody), event);
+    }
+    finally {
+        delete process.env[envKey];
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+});

package/dist/test/watch.test.js

@@ -1,7 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import path from "node:path";
-import { branchNameFor, claimNewWork, createWatchState, finishReviews, reconcileOrphans } from "../core/watch.js";
+import { branchNameFor, claimNewWork, createWatchState, finishReviews, reconcileOrphans, tick } from "../core/watch.js";
 /** In-memory fake — exactly the seam `provider.ts` exists for. */
 class FakeProvider {
     entries = new Map();
@@ -96,9 +96,15 @@ function makeDeps(provider, codeHost, overrides = {}) {
         dryRun: false,
         runChain: async () => ({ accepted: true, adwId: "issue-1", detail: "" }),
         log: () => { },
+        notify: () => { },
         ...overrides,
     };
 }
+/** Collects every `deps.notify(...)` call, for asserting kinds/levels without a real channel. */
+function collectNotifications() {
+    const events = [];
+    return { events, notify: (event) => events.push(event) };
+}
 async function waitUntil(predicate, timeoutMs = 2000) {
     const start = Date.now();
     while (!predicate()) {
@@ -281,3 +287,110 @@ test("finishReviews: a still-open PR leaves the issue in review", async () => {
     assert.equal(provider.transitions.length, 0);
     assert.equal(provider.entries.get("42").state, "review");
 });
+// ── notifications ────────────────────────────────────────────────────────────
+test("claim -> PR opened -> merged fires issue_claimed, pr_opened, then issue_done (all info-level)", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("50", "Add a /health endpoint");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, { notify });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "pr_opened"]);
+    assert.ok(events.every((e) => e.level === "info"));
+    codeHost.prs.set(1000, { merged: true, state: "closed", ciStatus: "success" });
+    await finishReviews(deps);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "pr_opened", "issue_done"]);
+    assert.equal(events.at(-1).level, "info");
+});
+test("a rejected chain run fires issue_blocked at error level", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("51", "Flaky feature");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        notify,
+        runChain: async () => ({ accepted: false, adwId: "issue-51", detail: "build-test failed" }),
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    const blocked = events.filter((e) => e.kind === "issue_blocked");
+    assert.equal(blocked.length, 1);
+    assert.equal(blocked[0].level, "error");
+    assert.equal(blocked[0].detail, "build-test failed");
+});
+test("an accepted run with nothing committed fires issue_blocked", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("52", "No-op request");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, { notify, worktreeGit: () => fakeGit({ diffFiles: () => [] }) });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "issue_blocked"]);
+    assert.match(events[1].detail ?? "", /no committed changes/);
+});
+test("an exception mid-runIssue fires watch_error at error level", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("53", "Explodes");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        notify,
+        runChain: async () => {
+            throw new Error("kaboom");
+        },
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    const errors = events.filter((e) => e.kind === "watch_error");
+    assert.equal(errors.length, 1);
+    assert.equal(errors[0].level, "error");
+    assert.match(errors[0].detail ?? "", /kaboom/);
+});
+test("finishReviews: a closed-without-merging PR fires issue_blocked", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("54", "rejected", "review", { pr: 700, branch: "spf-watch/54-x" });
+    const codeHost = new FakeCodeHost();
+    codeHost.prs.set(700, { merged: false, state: "closed", ciStatus: "failure" });
+    const { events, notify } = collectNotifications();
+    await finishReviews(makeDeps(provider, codeHost, { notify }));
+    assert.deepEqual(events.map((e) => e.kind), ["issue_blocked"]);
+    assert.equal(events[0].level, "error");
+});
+test("reconcileOrphans: giving up past the retry cap fires issue_blocked", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("55", "orphaned, no marker", "working", { attempt: 2 }); // one more push exceeds MAX_ORPHAN_ATTEMPTS (2)
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    await reconcileOrphans(makeDeps(provider, codeHost, { notify }), state);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_blocked"]);
+    assert.match(events[0].detail ?? "", /Gave up after 2 orphaned attempts/);
+});
+test("reconcileOrphans: a routine orphan resume/retry notifies nothing — only the terminal give-up does", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("56", "orphaned, resumable", "working", { pr: 800, branch: "spf-watch/56-x" });
+    const codeHost = new FakeCodeHost();
+    codeHost.prs.set(800, { merged: false, state: "open", ciStatus: "pending" });
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    await reconcileOrphans(makeDeps(provider, codeHost, { notify }), state);
+    assert.deepEqual(events, []);
+});
+test("tick: a per-stage error is caught and fires exactly one watch_error", async () => {
+    const provider = new FakeProvider();
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    provider.listEligible = async () => {
+        throw new Error("listEligible exploded");
+    };
+    await tick(makeDeps(provider, codeHost, { notify }), state);
+    assert.deepEqual(events.map((e) => e.kind), ["watch_error"]);
+    assert.match(events[0].detail ?? "", /listEligible exploded/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",