@gr8ful/spf 0.1.7 → 0.3.0

package/dist/chains/steps.js

@@ -0,0 +1,299 @@
+/**
+ * Step primitives: named, reusable pieces of chain composition.
+ *
+ * Every chain used to be a hand-written module repeating the same prologue,
+ * the same `request` phase, and — where chains overlapped — byte-identical
+ * `plan`/`build`/test-fix/review-revise/commit phases. This file is that
+ * code, extracted once: a `Step` is one `run.phase(...)` call (or a small
+ * bounded group of them) lifted out verbatim and parameterized only where
+ * the chains genuinely differed.
+ *
+ * A Step reads and writes a shared `ChainState` — the local variables a
+ * hand-written chain would otherwise thread from one `run.phase` call to the
+ * next (the last envelope, the last quality result, whether the run is
+ * accepted). Composing a chain is then an ordered array of Steps.
+ *
+ * The loops (`fixLoop`, `reviseLoop`) own their bounded iteration and dynamic
+ * phase naming (`test_1`, `fix_1`, ...) INTERNALLY — a chain's step list is
+ * therefore always flat, with no loop or conditional syntax at the
+ * composition layer. That is what would make a future declarative (YAML)
+ * chain tractable: it would only ever need to name steps and pass them
+ * tuning params, never express control flow.
+ */
+import * as changesLib from "../core/changes.js";
+import * as gates from "../core/gates.js";
+import * as quality from "../core/quality.js";
+import * as agentsCfg from "../core/agents.js";
+import * as session from "../core/session.js";
+import { DOCUMENT_NOTES } from "../core/prompts.js";
+import { BuildOutput, DocumentOutput, GenericOutput, PlanOutput, ReviewOutput, ScoutOutput, makeAgentCall, makeChangeCapture, makePhaseParams, } from "../core/data_types.js";
+import { Run } from "../core/runner.js";
+function makeState(prompt, options) {
+    return { prompt, options, previous: null, quality: null, review: null, changeset: null, baseline: "", accepted: true, reason: "" };
+}
+function makeStep(fn, meta = {}) {
+    const step = fn;
+    step.requiredAgents = meta.requiredAgents;
+    step.requiredSuites = meta.requiredSuites;
+    step.label = meta.label;
+    return step;
+}
+// ── layer 1: the shared prologue ────────────────────────────────────────
+/** The identical loadConfig -> validate -> session.ensure prologue every chain repeated. */
+export function startRun(ctx, requiredAgents, requiredSuites) {
+    const cfg = agentsCfg.loadConfig(ctx.config_paths);
+    agentsCfg.validate(cfg, requiredAgents, requiredSuites, ctx.cwd);
+    return session.ensure(cfg, ctx.adw_id, ctx.cwd, ctx.chain_name);
+}
+/** Commit an envelope in its own author's words — the message-fallback four chains repeated. */
+export function commitEnvelope(run, ph, envelope) {
+    const message = envelope.commit_message || `spf(${run.adw_id}): ${envelope.summary}`;
+    ph.log({ sha: run.git.commitAll(message), message });
+}
+/** Log a change-capture result the same way every chain that captures one did. */
+export function logChangeset(ph, result) {
+    ph.log({
+        base: `${result.base.label} @ ${result.base.commit.slice(0, 7)}`,
+        reason: result.base.reason,
+        files: result.files.length + result.untracked.length,
+        lines: `+${result.insertions} -${result.deletions}`,
+        diff: result.diff_path,
+    });
+}
+// ── layer 2: step factories ──────────────────────────────────────────────
+/** The engineer(request) phase every chain opens with. */
+export function request(opts = {}) {
+    const fn = async (run, state) => {
+        if (opts.logBaseline)
+            state.baseline = run.git.rev("HEAD");
+        await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: opts.description ?? "Capture the incoming ask" }), async (ph) => {
+            const payload = { input: state.prompt };
+            if (opts.logBaseline)
+                payload.baseline = run.git.shortSha(state.baseline);
+            ph.log(payload);
+        });
+    };
+    return makeStep(fn, { label: "engineer(request)" });
+}
+/** One agent phase: prompt in, typed envelope out, `previous` is whatever the prior step left in state. */
+function agentStep(opts) {
+    const fn = async (run, state) => {
+        const envelope = await run.phase(makePhaseParams({ name: opts.name, kind: "agent", owner: opts.owner, description: opts.description, retries: opts.retries ?? 0 }), (ph) => ph.call(makeAgentCall({ output_type: opts.output_type, prompt: state.prompt, previous: state.previous, gates: opts.gates ?? [] })));
+        state.previous = envelope;
+    };
+    return makeStep(fn, { requiredAgents: [opts.owner], label: opts.label ?? opts.owner });
+}
+export function plan() {
+    return agentStep({
+        name: "plan",
+        owner: "planner",
+        output_type: PlanOutput,
+        description: "Turn the request into an implementable plan",
+        gates: [gates.artifactsExist, gates.filesNonEmpty],
+    });
+}
+/**
+ * `fromPlan` only changes the description — whether a plan() step precedes
+ * this one already decides whether `state.previous` is a plan or null, so
+ * there is nothing else for this flag to gate.
+ */
+export function build(opts = {}) {
+    const fromPlan = opts.fromPlan ?? true;
+    return agentStep({
+        name: "build",
+        owner: "builder",
+        output_type: BuildOutput,
+        description: fromPlan ? "Implement the plan exactly" : "Implement the request",
+        gates: [gates.diffMatchesClaims],
+        retries: opts.retries ?? 0,
+    });
+}
+export function scout() {
+    return agentStep({
+        name: "scout",
+        owner: "scout",
+        output_type: ScoutOutput,
+        description: "Find and report where things live — change nothing",
+        gates: [gates.artifactsExist],
+    });
+}
+/** The `prompt` chain's one step: --agent picks who, at run time and at requiredAgents-derivation time alike. */
+export function promptOnly() {
+    const fn = async (run, state) => {
+        const owner = state.options["agent"] ?? "builder";
+        const envelope = await run.phase(makePhaseParams({ name: "prompt", kind: "agent", owner, description: `Send the request straight to ${owner} and parse its envelope` }), (ph) => ph.call(makeAgentCall({ output_type: GenericOutput, prompt: state.prompt, previous: state.previous })));
+        state.previous = envelope;
+    };
+    return makeStep(fn, { requiredAgents: (options) => [options["agent"] ?? "builder"], label: "<agent>" });
+}
+/** One deterministic quality block, standalone — never throws; sets state.accepted for run.finish() to check. */
+export function qualityCheck(opts = { suite: "all" }) {
+    const fn = async (run, state) => {
+        await run.phase(makePhaseParams({
+            name: opts.suite === "all" ? "quality" : "test",
+            kind: "code",
+            owner: "quality",
+            description: opts.description ??
+                (opts.suite === "all" ? "Run the deterministic quality blocks" : "Run the suite — a known command, so code runs it and no agent has to rediscover it"),
+        }), async (ph) => {
+            const result = opts.suite === "all" ? quality.runQuality(run) : quality.runTests(run);
+            quality.record(ph, result);
+            state.quality = result;
+            state.accepted = result.passed;
+            state.reason = result.passed ? "" : `quality failed: ${result.failures.join("; ")}`;
+        });
+    };
+    return makeStep(fn, { requiredSuites: [opts.suite], label: opts.suite === "all" ? "code(quality)" : "code(test)" });
+}
+/**
+ * Bounded check -> fix loop: a known command finds the failure, the builder
+ * repairs it. Always guards the last iteration — a fix on the final attempt
+ * is never re-verified, so it is never spawned. Sets state.accepted/reason.
+ */
+export function fixLoop(opts = { suite: "test" }) {
+    const max = opts.max ?? 3;
+    const owner = opts.owner ?? "builder";
+    const stepName = opts.suite === "all" ? "verify" : "test";
+    const what = opts.suite === "all" ? "verification" : "tests";
+    const fn = async (run, state) => {
+        let result = null;
+        for (let i = 1; i <= max; i++) {
+            result = await run.phase(makePhaseParams({
+                name: `${stepName}_${i}`,
+                kind: "code",
+                owner: "quality",
+                description: opts.suite === "all"
+                    ? "Lint, typecheck, and build before testing"
+                    : "Run the suite — a known command, so code runs it and no agent has to rediscover it",
+            }), async (ph) => {
+                const r = opts.suite === "all" ? quality.runQuality(run) : quality.runTests(run);
+                quality.record(ph, r);
+                return r;
+            });
+            if (result.passed)
+                break;
+            if (i === max)
+                break; // never leave an unverified fix on the table
+            state.previous = await run.phase(makePhaseParams({ name: `fix_${i}`, kind: "agent", owner, retries: 1, description: "Repair what the suite reported, from its verbatim output" }), (ph) => ph.call(makeAgentCall({
+                output_type: BuildOutput,
+                prompt: state.prompt,
+                previous: quality.asEnvelope(result, what),
+                gates: [gates.diffMatchesClaims],
+            })));
+        }
+        state.quality = result;
+        state.accepted = result !== null && result.passed;
+        state.reason = state.accepted ? "" : `the suite still failed after ${max} fix attempt(s)`;
+    };
+    return makeStep(fn, {
+        requiredAgents: [owner],
+        requiredSuites: [opts.suite],
+        label: `code(${stepName}) [-> ${owner}(fix) -> code(${stepName}) ...] bounded`,
+    });
+}
+/** Bounded review -> revise loop. Sets state.accepted/reason from the final verdict. */
+export function reviseLoop(opts = {}) {
+    const max = opts.max ?? 3;
+    const fn = async (run, state) => {
+        let review = null;
+        for (let i = 1; i <= max; i++) {
+            review = await run.phase(makePhaseParams({ name: `review_${i}`, kind: "agent", owner: "reviewer", description: "Rule on every requirement in the spec, against the code on disk" }), (ph) => ph.call(makeAgentCall({ output_type: ReviewOutput, prompt: state.prompt, previous: state.previous, gates: [gates.artifactsExist, gates.verdictConsistent] })));
+            if (review.approved || i === max)
+                break;
+            state.previous = await run.phase(makePhaseParams({ name: `revise_${i}`, kind: "agent", owner: "builder", retries: 1, description: "Close every blocking finding the reviewer named" }), (ph) => ph.call(makeAgentCall({ output_type: BuildOutput, prompt: state.prompt, previous: review, gates: [gates.diffMatchesClaims] })));
+        }
+        state.review = review;
+        state.accepted = review !== null && review.approved;
+        state.reason = state.accepted ? "" : `the reviewer never approved after ${max} revision(s)`;
+    };
+    return makeStep(fn, { requiredAgents: ["reviewer", "builder"], label: "reviewer [-> builder(revise) -> reviewer ...] bounded" });
+}
+/** Commit the last agent step's envelope. `onlyIfAccepted` gates it on state.accepted (a preceding fixLoop/reviseLoop). */
+export function commit(opts = {}) {
+    const fn = async (run, state) => {
+        if (opts.onlyIfAccepted && !state.accepted)
+            return;
+        if (!state.previous)
+            throw new Error("commit() has nothing to commit — no preceding agent step produced an envelope");
+        await run.phase(makePhaseParams({
+            name: "commit",
+            kind: "code",
+            owner: "git",
+            description: opts.onlyIfAccepted
+                ? "Land the code only after the suite came back green"
+                : "Land the builder's changes, using the message it wrote",
+        }), async (ph) => commitEnvelope(run, ph, state.previous));
+    };
+    return makeStep(fn, { label: "git(commit)" });
+}
+/** Diff the working tree against a base ref — code, not judgement. `--base` (default "main") if opts.base is unset. */
+export function changes(opts = {}) {
+    const fn = async (run, state) => {
+        const base = opts.base ?? state.options["base"] ?? "main";
+        const changeset = await run.phase(makePhaseParams({ name: "changes", kind: "code", owner: "git", description: `Diff the working tree against ${base} — the change to be written up` }), async (ph) => {
+            const result = changesLib.capture(run, makeChangeCapture({ base }));
+            logChangeset(ph, result);
+            if (result.empty) {
+                throw new Error(`nothing changed since ${result.base.label} (${result.base.reason}) — documenting runs after a build. ` +
+                    `Build something first, or point --base at the ref the work should be measured from.`);
+            }
+            return result;
+        });
+        state.changeset = changeset;
+    };
+    return makeStep(fn, { label: "code(changes)" });
+}
+/** Write up the captured change. Requires a preceding changes() step. */
+export function document() {
+    const fn = async (run, state) => {
+        if (!state.changeset)
+            throw new Error("document() requires a preceding changes() step in the chain's step list");
+        const envelope = await run.phase(makePhaseParams({ name: "document", kind: "agent", owner: "documenter", retries: 1, description: "Turn the captured diff into a write-up an engineer can read" }), (ph) => ph.call(makeAgentCall({
+            output_type: DocumentOutput,
+            prompt: state.prompt,
+            previous: changesLib.asEnvelope(state.changeset, DOCUMENT_NOTES),
+            gates: [gates.artifactsExist, gates.filesNonEmpty],
+        })));
+        state.previous = envelope;
+    };
+    return makeStep(fn, { requiredAgents: ["documenter"], label: "documenter" });
+}
+// ── layer 3: derive ChainDefinition fields from a step list ─────────────
+export function deriveRequiredAgents(steps) {
+    const dynamicSteps = steps.filter((s) => typeof s.requiredAgents === "function");
+    const staticSteps = steps.filter((s) => Array.isArray(s.requiredAgents));
+    if (dynamicSteps.length === 0) {
+        return [...new Set(staticSteps.flatMap((s) => s.requiredAgents))];
+    }
+    return (options) => {
+        const set = new Set();
+        for (const s of staticSteps)
+            for (const a of s.requiredAgents)
+                set.add(a);
+        for (const s of dynamicSteps)
+            for (const a of s.requiredAgents(options))
+                set.add(a);
+        return [...set];
+    };
+}
+export function deriveRequiredSuites(steps) {
+    const set = new Set();
+    for (const s of steps)
+        for (const suite of s.requiredSuites ?? [])
+            set.add(suite);
+    return [...set];
+}
+/** A display string for `spf list` — derived so it can no longer drift from what actually runs. */
+export function derivePhases(steps) {
+    return steps.map((s) => s.label ?? "?").join(" -> ");
+}
+// ── the driver ────────────────────────────────────────────────────────────
+/** Run a chain's step list start to finish: prologue, every step in order, then run.finish(). */
+export async function runSteps(ctx, requiredAgents, requiredSuites, steps, options = {}) {
+    const run = startRun(ctx, requiredAgents, requiredSuites);
+    const state = makeState(ctx.prompt, options);
+    for (const step of steps) {
+        await step(run, state);
+    }
+    return run.finish(state.accepted, state.reason);
+}

package/dist/cli/ask.d.ts

@@ -0,0 +1,27 @@
+export interface SelectChoice<T extends string> {
+    value: T;
+    label?: string;
+    hint?: string;
+}
+export interface Asker {
+    text(label: string, opts?: {
+        default?: string;
+        validate?: (value: string) => string | null;
+    }): Promise<string>;
+    select<T extends string>(label: string, choices: SelectChoice<T>[], dflt: T): Promise<T>;
+    confirm(label: string, dflt: boolean): Promise<boolean>;
+    /** Echo-suppressed. `current` (if any) is shown masked; an empty answer keeps it and resolves to `""`. */
+    secret(label: string, opts?: {
+        current?: string;
+    }): Promise<string>;
+    note(text: string): void;
+    heading(text: string): void;
+    close(): void;
+}
+/** `stdin.isTTY` is what actually matters (the interview reads it) — `stdout.isTTY` alone, this repo's only prior TTY check (`src/ui/server/serve.ts:88`), would let a piped-in `spf init` hang waiting on input that will never arrive. */
+export declare function isInteractive(): boolean;
+/** Thrown when the user interrupts (Ctrl-C) or stdin closes (EOF) mid-interview. `initCommand` catches this and exits 130, writing nothing. */
+export declare class InterviewAborted extends Error {
+    constructor();
+}
+export declare function createAsker(): Asker;

package/dist/cli/ask.js

@@ -0,0 +1,125 @@
+/**
+ * Zero-dependency interactive prompt primitives for `spf init`'s interview.
+ *
+ * No prompting library exists anywhere in this repo, and the project keeps a
+ * deliberately thin dependency list (`@flue/runtime`, `hono`, `valibot`,
+ * `yaml`) — this builds directly on `node:readline/promises` rather than
+ * adding one. `Asker` is an interface, not a class, so a test can supply a
+ * scripted fake instead of driving a real TTY — the same seam this repo
+ * already uses for `IssueProvider`/`CodeHostProvider` (see
+ * `src/test/watch.test.ts`'s `FakeProvider`).
+ */
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+import { paint } from "../core/console.js";
+/** `stdin.isTTY` is what actually matters (the interview reads it) — `stdout.isTTY` alone, this repo's only prior TTY check (`src/ui/server/serve.ts:88`), would let a piped-in `spf init` hang waiting on input that will never arrive. */
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY) && !process.env["CI"];
+}
+/** Thrown when the user interrupts (Ctrl-C) or stdin closes (EOF) mid-interview. `initCommand` catches this and exits 130, writing nothing. */
+export class InterviewAborted extends Error {
+    constructor() {
+        super("interview interrupted");
+    }
+}
+class MutableWritable extends Writable {
+    muted = false;
+    _write(chunk, _encoding, callback) {
+        if (!this.muted)
+            process.stdout.write(chunk);
+        callback();
+    }
+}
+export function createAsker() {
+    const muteableOut = new MutableWritable();
+    const rl = createInterface({ input: process.stdin, output: muteableOut, terminal: true });
+    let aborted = false;
+    rl.on("SIGINT", () => {
+        aborted = true;
+        rl.close();
+    });
+    async function raw(prompt) {
+        if (aborted)
+            throw new InterviewAborted();
+        try {
+            const answer = await rl.question(prompt);
+            return answer.trim();
+        }
+        catch {
+            // readline rejects `question()` if the interface is closed underneath it (EOF/SIGINT mid-prompt).
+            throw new InterviewAborted();
+        }
+    }
+    return {
+        async text(label, opts) {
+            const suffix = opts?.default ? paint("dim", ` [${opts.default}]`) : "";
+            while (true) {
+                const answer = await raw(`${label}${suffix}: `);
+                const value = answer || opts?.default || "";
+                const problem = opts?.validate?.(value);
+                if (problem) {
+                    console.log(paint("red", `  ${problem}`));
+                    continue;
+                }
+                return value;
+            }
+        },
+        async select(label, choices, dflt) {
+            console.log(label);
+            for (const c of choices) {
+                const marker = c.value === dflt ? paint("bold", "*") : " ";
+                const hint = c.hint ? paint("dim", ` — ${c.hint}`) : "";
+                console.log(`  ${marker} ${c.label ?? c.value}${hint}`);
+            }
+            const valid = new Set(choices.map((c) => c.value));
+            while (true) {
+                const answer = await raw(paint("dim", `choose [${dflt}]: `));
+                if (!answer)
+                    return dflt;
+                if (valid.has(answer))
+                    return answer;
+                console.log(paint("red", `  not one of: ${[...valid].join(", ")}`));
+            }
+        },
+        async confirm(label, dflt) {
+            const hint = dflt ? "Y/n" : "y/N";
+            const answer = (await raw(`${label} ${paint("dim", `[${hint}]`)}: `)).toLowerCase();
+            if (!answer)
+                return dflt;
+            return answer === "y" || answer === "yes";
+        },
+        async secret(label, opts) {
+            const maskedCurrent = opts?.current ? paint("dim", ` [keep current: ${maskForPrompt(opts.current)}]`) : "";
+            // The "  > " marker is written unmuted, before muting starts — otherwise
+            // it vanishes along with the (correctly) suppressed keystroke echo,
+            // and an empty line reads as a hang rather than a waiting prompt.
+            console.log(`${label}${maskedCurrent}`);
+            process.stdout.write("  > ");
+            muteableOut.muted = true;
+            let answer;
+            try {
+                answer = await raw("");
+            }
+            finally {
+                muteableOut.muted = false;
+                process.stdout.write("\n"); // the newline the muted output swallowed
+            }
+            return answer;
+        },
+        note(text) {
+            console.log(paint("dim", `  ${text}`));
+        },
+        heading(text) {
+            console.log("");
+            console.log(paint("bold cyan", `── ${text} ──`));
+        },
+        close() {
+            rl.close();
+        },
+    };
+}
+function maskForPrompt(value) {
+    if (value.length <= 4)
+        return "•".repeat(value.length);
+    return `${"•".repeat(Math.max(0, value.length - 4))}${value.slice(-4)}`;
+}

package/dist/cli/commands/doctor.js

@@ -13,38 +13,17 @@ import * as agents from "../../core/agents.js";
 import * as paths from "../../core/paths.js";
 import * as permissions from "../../core/permissions.js";
 import * as agentCc from "../../core/agent_cc.js";
+import { DEFAULT_NOTIFY_ENV_KEY } from "../../core/notify/notifier.js";
 import { isKnownToolName as isKnownFlueToolName, resolveModel } from "../../core/agent_flue.js";
-import { parseCli } from "../../core/utils.js";
+import { binaryOnPath, parseCli } from "../../core/utils.js";
+import { PROVIDER_ENV_KEYS } from "../../core/providers.js";
 import { isRepoAt } from "../../core/git_helper.js";
 import { findChain } from "../../chains/index.js";
-// Common providers' env var conventions — public knowledge (pi-ai's own
-// resolution table is internal, unexported, and not something to reach into
-// for this). Missing from this table just means "unknown provider, skipped
-// the key check" — never a false failure.
-const PROVIDER_ENV_KEYS = {
-    anthropic: ["ANTHROPIC_API_KEY"],
-    openai: ["OPENAI_API_KEY"],
-    google: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
-    openrouter: ["OPENROUTER_API_KEY"],
-    fireworks: ["FIREWORKS_API_KEY"],
-    groq: ["GROQ_API_KEY"],
-    mistral: ["MISTRAL_API_KEY"],
-    xai: ["XAI_API_KEY"],
-    deepseek: ["DEEPSEEK_API_KEY"],
-    together: ["TOGETHER_API_KEY"],
-    cerebras: ["CEREBRAS_API_KEY"],
-};
 function check(report, name, ok, detail) {
     report.checks.push({ name, ok, detail });
     if (!ok)
         report.ok = false;
 }
-function binaryOnPath(bin) {
-    if (path.isAbsolute(bin) || bin.includes("/"))
-        return existsSync(bin);
-    const result = spawnSync(process.platform === "win32" ? "where" : "which", [bin], { encoding: "utf-8" });
-    return result.status === 0;
-}
 export function doctorCommand(argv) {
     const { options, flags } = parseCli(argv, ["cwd", "config"], ["json"]);
     const report = { ok: true, checks: [] };
@@ -165,6 +144,17 @@ export function doctorCommand(argv) {
         }
         check(report, "watch.chain", Boolean(findChain(cfg.watch.chain)), findChain(cfg.watch.chain) ? cfg.watch.chain : `"${cfg.watch.chain}" is not a registered chain`);
     }
+    if (cfg.notifications.events !== "off") {
+        check(report, "notifications.events", true, cfg.notifications.events);
+        if (cfg.notifications.channels.length === 0) {
+            check(report, "notifications.channels", false, `notifications.events is ${JSON.stringify(cfg.notifications.events)} but no channels are configured`);
+        }
+        for (const ch of cfg.notifications.channels) {
+            const envKey = ch.webhook_url_env || DEFAULT_NOTIFY_ENV_KEY[ch.kind];
+            const label = ch.name ? `${ch.kind} (${ch.name})` : ch.kind;
+            check(report, `notifications: ${label}`, Boolean(process.env[envKey]), process.env[envKey] ? `${envKey} set` : `${envKey} is not set`);
+        }
+    }
     return finish(report, flags["json"]);
 }
 function finish(report, json) {

package/dist/cli/commands/init.d.ts

@@ -1 +1 @@
-export declare function initCommand(argv: string[]): number;
+export declare function initCommand(argv: string[]): Promise<number>;

package/dist/cli/commands/init.js

@@ -1,10 +1,27 @@
-/** `spf init` — seed a `.spf/` override directory. Everything else is inherited from the packaged defaults. */
+/**
+ * `spf init` — seed a `.spf/` override directory. Everything else is
+ * inherited from the packaged defaults.
+ *
+ * On a TTY (and without `--template`/`--yes`), this runs an interview
+ * instead of writing the all-comments starter file: it asks which coding
+ * agent, model/provider, quality checks, and (if wanted) `spf watch`
+ * tracker/host to use, collects the secrets those answers imply, and
+ * appends them to `.env` (already auto-loaded by every command — see
+ * `src/cli/index.ts`). Piped input, `--yes`, or `--template <name>` all
+ * fall through to the original non-interactive behavior unchanged — a
+ * scripted `spf init` must never hang waiting on stdin.
+ */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { stringify } from "yaml";
 import * as paths from "../../core/paths.js";
+import * as agents from "../../core/agents.js";
 import { ensureGitignore } from "../gitignore.js";
 import { parseCli } from "../../core/utils.js";
 import { paint } from "../../core/console.js";
+import { createAsker, isInteractive, InterviewAborted } from "../ask.js";
+import { gatherContext, runInterview } from "../interview.js";
+import { readEnvFile, upsertEnvFile, writeEnvExample } from "../env_file.js";
 const TEMPLATE_SUFFIX = ".spf.config.yaml";
 /** Every template's short name (e.g. "ts-cc"), derived from disk rather than hand-maintained — never drifts from what's actually packaged. */
 function listTemplates() {
@@ -69,26 +86,96 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
+
+# Uncomment to push notifications for unattended work — spf watch's daemon
+# lifecycle, and every chain run (spf <chain> / spf run, including watch's
+# own per-issue runs). Interactive commands (doctor, list, sessions, ...)
+# never notify — you're already looking at the terminal for those. events:
+# "errors" sends only failures/blocked issues; "all" adds every milestone
+# (run started, issue claimed, PR opened, ...). The URL is a secret and
+# lives only in .env — never in this file. See README.md's "Notifications"
+# section for how to get each webhook URL.
+# notifications:
+#   events: errors            # off (default) | errors | all
+#   channels:
+#     - kind: slack            # slack | teams | webhook
+#       webhook_url_env: SLACK_WEBHOOK_URL   # default for slack; TEAMS_WEBHOOK_URL / SPF_WEBHOOK_URL for the others
 `;
 // .spf/spf.config.yaml and .spf/prompt_engineering/ stay tracked — they're
 // shared project config, same as package.json. Only runtime/generated
 // content is ignored: session traces (data/), a hand-editable engine copy
 // (engine/, from `spf eject`), and secrets (.env).
 const GITIGNORE_ENTRIES = [".spf/data/", ".spf/engine/", ".env"];
-export function initCommand(argv) {
-    const { options, flags } = parseCli(argv, ["cwd", "template"], ["force"]);
+const GENERATED_HEADER = `# .spf/spf.config.yaml — written by \`spf init\`'s interview, merged ON TOP of
+# spf's packaged built-in defaults. Only what you changed is here; run
+# \`spf doctor\` any time to see what's actually in effect for this repo, and
+# where each value came from. Secrets this config implies live in .env
+# (gitignored) — .env.example lists the key names only.
+`;
+export async function initCommand(argv) {
+    const { options, flags } = parseCli(argv, ["cwd", "template"], ["force", "yes"]);
     const anchor = paths.resolveAnchor(options["cwd"]);
     const sfDir = path.join(anchor.repo_root, ".spf");
     mkdirSync(sfDir, { recursive: true });
     const configPath = path.join(sfDir, "spf.config.yaml");
-    if (existsSync(configPath) && !flags["force"]) {
-        console.log(`${configPath} already exists — leaving it alone (--force to overwrite)`);
+    const templateName = options["template"];
+    const interactive = !templateName && !flags["yes"] && isInteractive();
+    if (!interactive) {
+        if (existsSync(configPath) && !flags["force"]) {
+            console.log(`${configPath} already exists — leaving it alone (--force to overwrite)`);
+        }
+        else {
+            const content = templateName ? loadTemplate(templateName) : STARTER_CONFIG;
+            writeFileSync(configPath, content);
+            console.log(`wrote ${configPath}${templateName ? ` (from template "${templateName}")` : ""}`);
+        }
     }
     else {
-        const templateName = options["template"];
-        const content = templateName ? loadTemplate(templateName) : STARTER_CONFIG;
-        writeFileSync(configPath, content);
-        console.log(`wrote ${configPath}${templateName ? ` (from template "${templateName}")` : ""}`);
+        const asker = createAsker();
+        try {
+            if (existsSync(configPath) && !flags["force"]) {
+                const overwrite = await asker.confirm(`${configPath} already exists — overwrite it?`, false);
+                if (!overwrite) {
+                    console.log("leaving the existing config alone (--force to skip this prompt)");
+                    asker.close();
+                    ensureGitignore(anchor.repo_root, GITIGNORE_ENTRIES);
+                    return 0;
+                }
+            }
+            const envPath = path.join(anchor.repo_root, ".env");
+            const ctx = gatherContext(anchor.repo_root, readEnvFile(envPath));
+            const result = await runInterview(asker, ctx);
+            asker.close();
+            if (!result) {
+                console.log("init cancelled — nothing written");
+                return 1;
+            }
+            writeFileSync(configPath, GENERATED_HEADER + stringify(result.config));
+            console.log(`wrote ${configPath}`);
+            if (Object.keys(result.env).length > 0)
+                upsertEnvFile(anchor.repo_root, result.env);
+            writeEnvExample(anchor.repo_root, result.envExampleKeys);
+            // The same merge-then-validate pipeline `spf doctor` runs — catches a
+            // bad answer (e.g. a suite naming an unconfigured check) right after
+            // writing, not at the user's first real chain run. Non-fatal: the
+            // config is already written either way, and `spf doctor` gives the
+            // full picture.
+            try {
+                const cfg = agents.loadConfig([paths.BUILTIN_CONFIG_PATH, configPath]);
+                agents.validate(cfg, cfg.agents.map((a) => a.name), Object.keys(cfg.quality.suites), anchor.cwd);
+            }
+            catch (error) {
+                console.log(paint("yellow", `warning: ${error.message}\nrun \`spf doctor\` for the full picture.`));
+            }
+        }
+        catch (error) {
+            asker.close();
+            if (error instanceof InterviewAborted) {
+                console.log("\ninit interrupted — nothing written");
+                return 130;
+            }
+            throw error;
+        }
     }
     ensureGitignore(anchor.repo_root, GITIGNORE_ENTRIES);
     const templates = listTemplates();

package/dist/cli/commands/run.d.ts

@@ -1,3 +1,3 @@
-import type { ChainDefinition } from "../../chains/index.ts";
+import { type ChainDefinition } from "../../chains/index.ts";
 export declare function usageFor(chain: ChainDefinition): string;
 export declare function dispatchChain(chain: ChainDefinition, argv: string[]): Promise<number>;