@gr8ful/spf 0.1.6 → 0.2.1

package/dist/cli/interview.js

@@ -0,0 +1,330 @@
+/**
+ * The question flow behind `spf init`'s interactive interview. No filesystem
+ * writes happen here — `commands/init.ts` owns those, so this module stays
+ * unit-testable against a scripted `Asker` (see `src/test/interview.test.ts`)
+ * without touching disk beyond the read-only `DetectedContext` gather.
+ *
+ * Every section below mirrors an existing, already-shipped code path rather
+ * than inventing new vocabulary:
+ *   - coding agent          -> src/core/agent_cc.ts / agent_flue.ts, src/core/providers.ts
+ *   - quality checks        -> src/core/data_types.ts's QualityCheckSpecSchema
+ *   - watch ticket loop     -> src/cli/commands/watch.ts's resolveIssueProvider/resolveCodeHostProvider
+ *   - the pinned-roster fix -> assets/templates/ts-cc.spf.config.yaml, done by hand today
+ */
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { binaryOnPath } from "../core/utils.js";
+import { PROVIDER_ENV_KEYS } from "../core/providers.js";
+import { resolveModel } from "../core/agent_flue.js";
+import { ThinkingLevelSchema } from "../core/data_types.js";
+import { CHAINS } from "../chains/index.js";
+function gitConfigValue(repoRoot, key) {
+    const result = spawnSync("git", ["config", key], { cwd: repoRoot, encoding: "utf-8" });
+    const value = result.status === 0 ? result.stdout.trim() : "";
+    return value || undefined;
+}
+/** Parses the common GitHub/Bitbucket remote URL shapes (https and ssh) into "owner/name". Best-effort — an unparseable or missing remote just means no default to offer. */
+function parseRemoteSlug(url) {
+    if (!url)
+        return undefined;
+    const match = /(?:[/:])([^/:]+\/[^/]+?)(?:\.git)?$/.exec(url.trim());
+    return match ? match[1] : undefined;
+}
+function readScripts(repoRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf-8"));
+        return pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function gatherContext(repoRoot, existingEnv = new Map()) {
+    const remote = spawnSync("git", ["config", "--get", "remote.origin.url"], { cwd: repoRoot, encoding: "utf-8" });
+    const branch = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot, encoding: "utf-8" });
+    return {
+        repoSlug: parseRemoteSlug(remote.status === 0 ? remote.stdout.trim() : undefined),
+        currentBranch: branch.status === 0 && branch.stdout.trim() !== "HEAD" ? branch.stdout.trim() : "main",
+        gitEmail: gitConfigValue(repoRoot, "user.email"),
+        gitName: gitConfigValue(repoRoot, "user.name"),
+        scripts: readScripts(repoRoot),
+        claudeOnPath: binaryOnPath("claude"),
+        existingEnv,
+    };
+}
+const QUALITY_TIMEOUTS = { typecheck: 60, lint: 60, build: 120, test: 180 };
+function splitArgv(command) {
+    return command.trim().split(/\s+/).filter(Boolean);
+}
+/**
+ * Runs the interview and returns the config/env to write, or `null` if the
+ * user declines the final confirmation. Throws `InterviewAborted` (from
+ * `./ask.ts`) on Ctrl-C/EOF — the caller decides the exit code for that.
+ */
+export async function runInterview(asker, ctx) {
+    const defaults = {};
+    const agentOverrides = [];
+    const env = {};
+    const envExampleKeys = [];
+    const notes = [];
+    // ── 1. coding agent ────────────────────────────────────────────────────────
+    asker.heading("Coding agent");
+    const codingAgent = await asker.select("Which backend runs each agent?", [
+        { value: "claude_code", label: "claude_code — shells out to the `claude` CLI you already use", hint: "cc" },
+        { value: "flue", label: "flue — in-process, provider/model-id (openai, anthropic, openrouter, ...)" },
+    ], "claude_code");
+    defaults.coding_agent = codingAgent;
+    if (codingAgent === "claude_code") {
+        if (!ctx.claudeOnPath) {
+            asker.note("warning: `claude` was not found on PATH — install it (or set a launch command below) before running spf.");
+        }
+        const launchCommand = await asker.text("Launch command for the `claude` CLI (space-separated; SPF_CLAUDE_CMD)", { default: "claude" });
+        if (launchCommand !== "claude")
+            env["SPF_CLAUDE_CMD"] = launchCommand;
+        const model = await asker.select("Model (Claude Code's own vocabulary — not provider/model-id)", [
+            { value: "sonnet", label: "sonnet" },
+            { value: "opus", label: "opus" },
+            { value: "haiku", label: "haiku" },
+            { value: "custom", label: "custom — type an exact model name" },
+        ], "sonnet");
+        defaults.model = model === "custom" ? await asker.text("Exact model name") : model;
+        const auth = await asker.select("Authentication", [
+            { value: "login", label: "already logged in via `claude login`", hint: "writes nothing" },
+            { value: "key", label: "ANTHROPIC_API_KEY" },
+            { value: "endpoint", label: "custom endpoint (Ollama / Ollama Cloud / a proxy)" },
+        ], "login");
+        if (auth === "key") {
+            const current = ctx.existingEnv.get("ANTHROPIC_API_KEY");
+            const key = await asker.secret("ANTHROPIC_API_KEY", { current });
+            if (key)
+                env["ANTHROPIC_API_KEY"] = key;
+            envExampleKeys.push("ANTHROPIC_API_KEY");
+        }
+        else if (auth === "endpoint") {
+            const baseUrl = await asker.text("ANTHROPIC_BASE_URL", { default: "http://localhost:11434" });
+            env["ANTHROPIC_BASE_URL"] = baseUrl;
+            const token = await asker.secret("ANTHROPIC_AUTH_TOKEN", { current: ctx.existingEnv.get("ANTHROPIC_AUTH_TOKEN") });
+            env["ANTHROPIC_AUTH_TOKEN"] = token || "ollama";
+            envExampleKeys.push("ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN");
+            asker.note("spf doctor does not check these two — confirm the endpoint is reachable yourself.");
+        }
+        // The packaged roster pins planner/reviewer/documenter to their own
+        // Flue-style provider/model-id strings, which always win over
+        // defaults.model (agents.ts's back-fill only applies when an agent
+        // doesn't already set its own `model`). Left alone, switching the
+        // backend to claude_code sends those three straight to the `claude`
+        // CLI's `--model` flag as e.g. "fireworks/accounts/.../kimi-k3", which
+        // it cannot resolve. Override all three to the same model chosen above
+        // — exactly what assets/templates/ts-cc.spf.config.yaml does by hand.
+        for (const name of ["planner", "reviewer", "documenter"]) {
+            agentOverrides.push({ name, model: defaults.model });
+        }
+        notes.push("planner/reviewer/documenter pin their own model in the packaged roster and always win over defaults.model — overriding all three to match, since claude_code can't resolve their packaged Flue-style ids.");
+    }
+    else {
+        const provider = await asker.select("Provider", Object.keys(PROVIDER_ENV_KEYS).map((p) => ({ value: p, label: p })), "anthropic");
+        const modelId = await asker.text(`Model id (after "${provider}/")`, {
+            default: provider === "anthropic" ? "claude-sonnet-4-6" : "",
+            validate: (val) => (val.trim() ? null : "required"),
+        });
+        const model = `${provider}/${modelId}`;
+        try {
+            resolveModel(model);
+        }
+        catch (error) {
+            asker.note(`warning: ${error.message}`);
+        }
+        defaults.model = model;
+        const envKey = PROVIDER_ENV_KEYS[provider][0];
+        const key = await asker.secret(envKey, { current: ctx.existingEnv.get(envKey) });
+        if (key)
+            env[envKey] = key;
+        envExampleKeys.push(envKey);
+    }
+    // ── 2. quality checks ──────────────────────────────────────────────────────
+    asker.heading("Quality checks");
+    asker.note("a chain that gates on a suite (e.g. plan-build-test's `test`) fails loudly before anything runs if the suite is unconfigured.");
+    const checks = [];
+    const configuredNames = [];
+    for (const [checkName, operation, scriptGuess] of [
+        ["typecheck", "typecheck", "typecheck"],
+        ["lint", "lint", "lint"],
+        ["build", "build", "build"],
+        ["test", "build", "test"],
+    ]) {
+        const detectedScript = ctx.scripts[scriptGuess] ? `npm run ${scriptGuess}` : "";
+        const wantIt = await asker.confirm(`Add a "${checkName}" check?`, Boolean(detectedScript));
+        if (!wantIt)
+            continue;
+        const command = await asker.text(`  ${checkName} command`, { default: detectedScript || `npm run ${scriptGuess}` });
+        checks.push({ name: checkName, operation, argv: splitArgv(command), timeout_seconds: QUALITY_TIMEOUTS[checkName] });
+        configuredNames.push(checkName);
+    }
+    if (checks.length > 0) {
+        const suites = { all: configuredNames };
+        if (configuredNames.includes("test"))
+            suites.test = ["test"];
+        defaults["__quality__"] = { checks, suites };
+    }
+    // ── 3. watch ticket loop ────────────────────────────────────────────────────
+    asker.heading("Watch ticket loop (spf watch)");
+    const enableWatch = await asker.confirm("Enable spf watch (poll a tracker, run a chain per issue, open a PR)?", false);
+    let watch = null;
+    if (enableWatch) {
+        const issueProvider = await asker.select("Issue tracker", [
+            { value: "github", label: "GitHub Issues" },
+            { value: "jira", label: "Jira" },
+        ], "github");
+        const codeHost = await asker.select("Code host (where PRs open)", [
+            { value: "github", label: "GitHub" },
+            { value: "bitbucket", label: "Bitbucket" },
+        ], "github");
+        const repoHint = codeHost === "bitbucket" ? "workspace/repo_slug" : "owner/name";
+        const repo = await asker.text(`Repo (${repoHint})`, {
+            default: codeHost === "github" ? ctx.repoSlug ?? "" : "",
+            validate: (val) => (val.includes("/") && val.split("/").filter(Boolean).length === 2 ? null : `must be "${repoHint}"`),
+        });
+        const labelPrefix = await asker.text("Label prefix", { default: "spf" });
+        const baseBranch = await asker.text("Base branch", { default: ctx.currentBranch });
+        const chainChoices = CHAINS.map((c) => ({ value: c.name, label: c.name, hint: c.describe }));
+        const chain = await asker.select("Chain to run per issue", chainChoices, "plan-build-test");
+        watch = { issue_provider: issueProvider, code_host: codeHost, repo, label_prefix: labelPrefix, chain, base_branch: baseBranch };
+        if (issueProvider === "jira") {
+            const baseUrl = await asker.text("Jira base URL", {
+                default: "https://your-domain.atlassian.net",
+                validate: (val) => (/^https:\/\/.+/.test(val) ? null : "must start with https://"),
+            });
+            const projectKey = await asker.text("Jira project key", { validate: (val) => (val.trim() ? null : "required") });
+            watch.jira = { base_url: baseUrl.replace(/\/+$/, ""), project_key: projectKey.toUpperCase() };
+        }
+        const needsGithub = issueProvider === "github" || codeHost === "github";
+        if (needsGithub) {
+            asker.note('classic PAT, "repo" scope (private) or "public_repo" (public-only) — never "project".');
+            const token = await asker.secret("GITHUB_TOKEN", { current: ctx.existingEnv.get("GITHUB_TOKEN") });
+            if (token)
+                env["GITHUB_TOKEN"] = token;
+            envExampleKeys.push("GITHUB_TOKEN");
+        }
+        if (issueProvider === "jira") {
+            const email = await asker.text("JIRA_EMAIL", { default: ctx.gitEmail ?? "" });
+            if (email)
+                env["JIRA_EMAIL"] = email;
+            const token = await asker.secret("JIRA_API_TOKEN", { current: ctx.existingEnv.get("JIRA_API_TOKEN") });
+            if (token)
+                env["JIRA_API_TOKEN"] = token;
+            envExampleKeys.push("JIRA_EMAIL", "JIRA_API_TOKEN");
+            asker.note("id.atlassian.com -> Security -> API tokens");
+        }
+        if (codeHost === "bitbucket") {
+            const email = await asker.text("BITBUCKET_EMAIL", { default: ctx.gitEmail ?? "" });
+            if (email)
+                env["BITBUCKET_EMAIL"] = email;
+            const token = await asker.secret("BITBUCKET_API_TOKEN", { current: ctx.existingEnv.get("BITBUCKET_API_TOKEN") });
+            if (token)
+                env["BITBUCKET_API_TOKEN"] = token;
+            envExampleKeys.push("BITBUCKET_EMAIL", "BITBUCKET_API_TOKEN");
+            asker.note("Bitbucket app passwords are being removed — this needs an Atlassian API token instead.");
+        }
+    }
+    // ── 4. advanced (gated) ─────────────────────────────────────────────────────
+    const wantAdvanced = await asker.confirm("\nConfigure advanced settings (thinking level, tools, protected files, data dir, poll intervals, ...)?", false);
+    if (wantAdvanced) {
+        asker.heading("Advanced");
+        const thinkingChoices = ThinkingLevelSchema.options.map((o) => ({ value: o, label: o }));
+        const thinking = await asker.select("defaults.thinking", thinkingChoices, "medium");
+        if (thinking !== "medium")
+            defaults.thinking = thinking;
+        const dataDir = await asker.text("defaults.data_dir", { default: ".spf/data" });
+        if (dataDir !== ".spf/data")
+            defaults.data_dir = dataDir;
+        const protectedFiles = await asker.text("defaults.protected_files (comma-separated)", { default: ".spf/, spf.config.yaml" });
+        const protectedList = protectedFiles.split(",").map((s) => s.trim()).filter(Boolean);
+        if (protectedList.join(",") !== ".spf/,spf.config.yaml")
+            defaults.protected_files = protectedList;
+        const dbPath = await asker.text("observability.db", { default: ".spf/data/spf.db" });
+        const pollMs = await asker.text("observability.poll_ms", { default: "500" });
+        if (dbPath !== ".spf/data/spf.db" || pollMs !== "500") {
+            defaults["__observability__"] = { ...(dbPath !== ".spf/data/spf.db" ? { db: dbPath } : {}), ...(pollMs !== "500" ? { poll_ms: Number(pollMs) } : {}) };
+        }
+        if (watch) {
+            const watchPollMs = await asker.text("watch.poll_ms", { default: "60000" });
+            if (watchPollMs !== "60000")
+                watch.poll_ms = Number(watchPollMs);
+            const concurrency = await asker.text("watch.concurrency", { default: "2" });
+            if (concurrency !== "2")
+                watch.concurrency = Number(concurrency);
+        }
+        const engineerName = await asker.text("ENGINEER_NAME (falls back to `git config user.name`)", { default: ctx.gitName ?? "" });
+        if (engineerName && engineerName !== ctx.gitName)
+            env["ENGINEER_NAME"] = engineerName;
+        if (watch?.issue_provider === "jira") {
+            const debug = await asker.confirm("Enable SPF_JIRA_DEBUG (request/response logging)?", false);
+            if (debug)
+                env["SPF_JIRA_DEBUG"] = "1";
+        }
+    }
+    // ── 5. review + confirm ─────────────────────────────────────────────────────
+    const observability = defaults["__observability__"];
+    delete defaults["__observability__"];
+    const quality = defaults["__quality__"];
+    delete defaults["__quality__"];
+    const config = { defaults };
+    if (agentOverrides.length > 0)
+        config.agents = agentOverrides;
+    if (quality)
+        config.quality = quality;
+    if (watch)
+        config.watch = watch;
+    if (observability)
+        config.observability = observability;
+    // No schema validation here on purpose: `config.agents` overrides are
+    // intentionally PARTIAL (name + model only, no prompt_engineering) — valid
+    // only once merged by name into the packaged roster (agents.ts's
+    // mergeAgentLists), same as any hand-written override file. Validating
+    // this raw document against the full SFConfigSchema would flag every
+    // claude_code interview as broken. `commands/init.ts` runs the real
+    // merge-then-validate pipeline (agents.loadConfig + agents.validate,
+    // the same one `spf doctor` uses) after writing, and reports there.
+    asker.heading("Review");
+    console.log(renderPreview(config));
+    if (notes.length > 0) {
+        for (const n of notes)
+            asker.note(n);
+    }
+    if (Object.keys(env).length > 0) {
+        console.log("");
+        console.log(".env keys to write: " + Object.keys(env).join(", "));
+    }
+    const proceed = await asker.confirm("\nWrite .spf/spf.config.yaml and .env?", true);
+    if (!proceed)
+        return null;
+    return { config, env, envExampleKeys };
+}
+/** An array is worth recursing into only if it holds further objects (e.g. `agents:`, `quality.checks`) — an array of primitives (e.g. `argv: ["npm","run","test"]`) reads better printed inline than one bare, contentless line per entry. */
+function isArrayOfObjects(value) {
+    return Array.isArray(value) && value.some((item) => item && typeof item === "object");
+}
+function renderPreview(config) {
+    const lines = [];
+    const walk = (obj, indent) => {
+        for (const [key, value] of Object.entries(obj)) {
+            if (isArrayOfObjects(value)) {
+                lines.push(`${indent}${key}:`);
+                for (const item of value) {
+                    lines.push(`${indent}  -`);
+                    walk(item, indent + "    ");
+                }
+            }
+            else if (value && typeof value === "object" && !Array.isArray(value)) {
+                lines.push(`${indent}${key}:`);
+                walk(value, indent + "  ");
+            }
+            else {
+                lines.push(`${indent}${key}: ${JSON.stringify(value)}`);
+            }
+        }
+    };
+    walk(config, "");
+    return lines.join("\n");
+}

package/dist/core/issues/jira_provider.d.ts

@@ -45,6 +45,15 @@ export declare class JiraProvider implements IssueProvider {
     /** Jira labels are freeform strings, not a seedable registry — report what's used, create nothing. */
     ensureLabels(): Promise<EnsureLabelsResult>;
     private toIssue;
+    /**
+     * POST with the JQL in the JSON body, NOT a GET with `jql` as a query
+     * param: this endpoint's own real-world behavior (confirmed by multiple
+     * independent bug reports against it, not just this project's own
+     * testing) is to silently ignore query-string parameters and return an
+     * empty `issues` array with a 200 OK — no error, nothing to catch. A
+     * `spf watch` that builds this as a GET query string would run cleanly
+     * forever without ever claiming a single issue.
+     */
     private searchByLabel;
     listEligible(): Promise<Issue[]>;
     /**

package/dist/core/issues/jira_provider.js

@@ -36,6 +36,9 @@ export class JiraProvider {
         return `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`;
     }
     async jira(path, init) {
+        const debug = Boolean(process.env["SPF_JIRA_DEBUG"]);
+        if (debug)
+            console.error(`[jira debug] ${init?.method ?? "GET"} ${this.baseUrl}${path} body=${init?.body ?? "(none)"}`);
         const response = await fetch(`${this.baseUrl}${path}`, {
             ...init,
             headers: {
@@ -51,7 +54,10 @@ export class JiraProvider {
         }
         if (response.status === 204)
             return undefined;
-        return (await response.json());
+        const text = await response.text();
+        if (debug)
+            console.error(`[jira debug] -> ${response.status} ${text.slice(0, 2000)}`);
+        return text ? JSON.parse(text) : undefined;
     }
     label(state) {
         return `${this.labelPrefix}:${state}`;
@@ -68,9 +74,21 @@ export class JiraProvider {
             labels: raw.fields.labels,
         };
     }
+    /**
+     * POST with the JQL in the JSON body, NOT a GET with `jql` as a query
+     * param: this endpoint's own real-world behavior (confirmed by multiple
+     * independent bug reports against it, not just this project's own
+     * testing) is to silently ignore query-string parameters and return an
+     * empty `issues` array with a 200 OK — no error, nothing to catch. A
+     * `spf watch` that builds this as a GET query string would run cleanly
+     * forever without ever claiming a single issue.
+     */
     async searchByLabel(label) {
         const jql = `project = ${JSON.stringify(this.projectKey)} AND labels = ${JSON.stringify(label)}`;
-        const result = await this.jira(`/rest/api/3/search/jql?jql=${encodeURIComponent(jql)}&maxResults=100&fields=summary,description,labels`);
+        const result = await this.jira("/rest/api/3/search/jql", {
+            method: "POST",
+            body: JSON.stringify({ jql, maxResults: 100, fields: ["summary", "description", "labels"] }),
+        });
         return result.issues.map((i) => this.toIssue(i));
     }
     async listEligible() {

package/dist/core/prompts.d.ts

@@ -1,4 +1,6 @@
 /** Prompt rendering: load system/user refs from config, replace {{placeholders}}. */
+/** Shared instructions for any documenter call fed a change.asEnvelope() capture. */
+export declare const DOCUMENT_NOTES = "Read diff_path in full before writing. Document only what the diff shows, then copy the write-up into app_docs/ as your task describes.";
 export declare function render(templatePath: string, variables: Record<string, string>): string;
 /** Save the exact prompt sent, before execution — the audit copy. */
 export declare function save(directory: string, name: string, content: string): string;

package/dist/core/prompts.js

@@ -1,6 +1,8 @@
 /** Prompt rendering: load system/user refs from config, replace {{placeholders}}. */
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
+/** Shared instructions for any documenter call fed a change.asEnvelope() capture. */
+export const DOCUMENT_NOTES = "Read diff_path in full before writing. Document only what the diff shows, then copy the write-up into app_docs/ as your task describes.";
 export function render(templatePath, variables) {
     let text = readFileSync(templatePath, "utf-8");
     for (const [key, value] of Object.entries(variables)) {

package/dist/core/providers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Common Flue 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.
+ *
+ * Shared by `spf doctor` (checks whichever key the configured model's
+ * provider prefix implies) and the `spf init` interview (asks for the key up
+ * front, keyed off the provider the user picked) — one table, so the two
+ * can never drift apart on what a provider needs.
+ */
+export declare const PROVIDER_ENV_KEYS: Record<string, string[]>;

package/dist/core/providers.js

@@ -0,0 +1,24 @@
+/**
+ * Common Flue 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.
+ *
+ * Shared by `spf doctor` (checks whichever key the configured model's
+ * provider prefix implies) and the `spf init` interview (asks for the key up
+ * front, keyed off the provider the user picked) — one table, so the two
+ * can never drift apart on what a provider needs.
+ */
+export 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"],
+};

package/dist/core/quality.d.ts

@@ -53,6 +53,15 @@ export declare function runSuite(run: RunLike, suiteName: string): QualityResult
 export declare function runTests(run: RunLike): QualityResult;
 /** Every configured check, across every configured suite's union — the `all` suite. */
 export declare function runQuality(run: RunLike): QualityResult;
+/**
+ * Log a deterministic block's verdict — the same shape every chain uses.
+ *
+ * Every quality/test phase in every chain reported this same summary by
+ * hand; one copy here instead of one per chain.
+ */
+export declare function record(ph: {
+    log: (payload: Record<string, unknown>) => void;
+}, result: QualityResult): void;
 /**
  * Wrap a deterministic result so an agent can be handed it directly.
  *

package/dist/core/quality.js

@@ -170,6 +170,16 @@ export function runTests(run) {
 export function runQuality(run) {
     return runSuite(run, "all");
 }
+/**
+ * Log a deterministic block's verdict — the same shape every chain uses.
+ *
+ * Every quality/test phase in every chain reported this same summary by
+ * hand; one copy here instead of one per chain.
+ */
+export function record(ph, result) {
+    const passed = result.checks.filter((c) => c.passed).length;
+    ph.log({ passed: result.passed, checks: `${passed}/${result.checks.length}`, artifacts: result.artifacts.join(", ") });
+}
 /**
  * Wrap a deterministic result so an agent can be handed it directly.
  *

package/dist/core/session.d.ts

@@ -12,5 +12,10 @@ import type { SFConfig } from "./data_types.ts";
  * process happened to start; it is an explicit decision, threaded down from
  * the CLI/chain context. Defaults to `process.cwd()` only for direct callers
  * (tests, scratch scripts) that have no anchor of their own to pass.
+ *
+ * `chainName` is the CLI name (`"plan-build-test"`, not a module basename) —
+ * every chain is a composed step list now, not its own file, so there is no
+ * longer a `process.argv[1]` basename that means anything. Direct callers
+ * that have no chain of their own fall back to `"adw"`.
  */
-export declare function ensure(cfg: SFConfig, adwId?: string | null, cwd?: string): Run;
+export declare function ensure(cfg: SFConfig, adwId?: string | null, cwd?: string, chainName?: string): Run;

package/dist/core/session.js

@@ -33,8 +33,13 @@ function finalizeWhenKilled(run) {
  * process happened to start; it is an explicit decision, threaded down from
  * the CLI/chain context. Defaults to `process.cwd()` only for direct callers
  * (tests, scratch scripts) that have no anchor of their own to pass.
+ *
+ * `chainName` is the CLI name (`"plan-build-test"`, not a module basename) —
+ * every chain is a composed step list now, not its own file, so there is no
+ * longer a `process.argv[1]` basename that means anything. Direct callers
+ * that have no chain of their own fall back to `"adw"`.
  */
-export function ensure(cfg, adwId, cwd) {
+export function ensure(cfg, adwId, cwd, chainName) {
     const id = adwId || newId(8);
     const anchor = paths.resolveAnchor(cwd);
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
@@ -49,8 +54,7 @@ export function ensure(cfg, adwId, cwd) {
         dataDir: dataPaths.data_dir,
     });
     const scriptPath = process.argv[1] || "adw";
-    const adwName = path.basename(scriptPath, path.extname(scriptPath));
-    tracer.sessionStart(id, run.engineer, adwName);
+    tracer.sessionStart(id, run.engineer, chainName || "adw");
     // This process is the run. Record it before any phase opens, so a run that
     // hangs in its first agent call is still killable by adw_id.
     tracer.processStart(id, "adw", "", process.pid ?? -1, [path.basename(scriptPath), ...process.argv.slice(2)].join(" "));

package/dist/core/tracer.js

@@ -12,7 +12,7 @@ import { newId, nowIso } from "./utils.js";
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS sessions (
   adw_id        TEXT PRIMARY KEY,
-  adw_name      TEXT,                -- ADW script(s) run, e.g. "adw_plan + adw_build_test"
+  adw_name      TEXT,                -- chain(s) run, e.g. "plan + build-test"
   request       TEXT,
   status        TEXT,
   engineer      TEXT,

package/dist/core/utils.d.ts

@@ -1,8 +1,10 @@
 /**
  * Small shared helpers. Anything bigger belongs in its own module.
  *
- * Bun loads .env files automatically for anything run with `bun run`/`bun`,
- * so there is no load_dotenv() call to make here — that parity is free.
+ * `.env` loading lives in cli/index.ts's `main()`, via Node's built-in
+ * `process.loadEnvFile()` — anchored to the resolved repo root, not
+ * `process.cwd()`. Not here: this module has no anchor of its own to load
+ * relative to.
  */
 import path from "node:path";
 /**
@@ -22,6 +24,8 @@ export declare function nowIso(): string;
 export declare function ensureDir(dirPath: string): string;
 /** CLI prompt arg: a file path resolves to its contents, else inline text. */
 export declare function resolvePrompt(arg: string): string;
+/** True when `bin` resolves on PATH (or exists, if given as an absolute/relative path). Shared by `spf doctor` and the `spf init` interview so both agree on what's installed. */
+export declare function binaryOnPath(bin: string): boolean;
 export declare function engineerName(): string;
 /**
  * Minimal `--flag value` / `--bare-flag` CLI parsing — the CLI only ever

package/dist/core/utils.js

@@ -1,8 +1,10 @@
 /**
  * Small shared helpers. Anything bigger belongs in its own module.
  *
- * Bun loads .env files automatically for anything run with `bun run`/`bun`,
- * so there is no load_dotenv() call to make here — that parity is free.
+ * `.env` loading lives in cli/index.ts's `main()`, via Node's built-in
+ * `process.loadEnvFile()` — anchored to the resolved repo root, not
+ * `process.cwd()`. Not here: this module has no anchor of its own to load
+ * relative to.
  */
 import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
@@ -50,6 +52,13 @@ export function resolvePrompt(arg) {
     }
     return arg;
 }
+/** True when `bin` resolves on PATH (or exists, if given as an absolute/relative path). Shared by `spf doctor` and the `spf init` interview so both agree on what's installed. */
+export 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 engineerName() {
     const name = (process.env.ENGINEER_NAME || "").trim();
     if (name)

package/dist/core/watch.d.ts

@@ -17,6 +17,18 @@ export interface WatchDeps {
     baseBranch: string;
     concurrency: number;
     worktreesDir: string;
+    /**
+     * Symlink (or otherwise wire up) `<worktreePath>/.spf/data` to the MAIN
+     * repo's own persistent data_dir, called once per worktree right after
+     * it's created. Without this, a chain run's session/trace data resolves
+     * relative to `cwd` (the worktree — see ChainContext's doc comment) and
+     * lands in a fresh, throwaway `.spf/data` that `cleanupWorktree` deletes
+     * along with the rest of the worktree once the issue finishes: no trace
+     * in `spf ui`, and no trace anywhere at all after cleanup. Injected (not
+     * called directly) so watch.ts's own tests never touch the real
+     * filesystem for it.
+     */
+    linkDataDir: (worktreePath: string) => void;
     dryRun: boolean;
     runChain: (opts: {
         prompt: string;

package/dist/core/watch.js

@@ -129,8 +129,19 @@ async function runIssue(deps, issue) {
     const worktreePath = worktreePathFor(deps, issue);
     const adwId = `issue-${issue.id}`;
     try {
+        // Both worktreePath and branch are fully deterministic from issue.id —
+        // the only way either could already exist is a previous spf watch
+        // attempt for THIS issue that never reached its own cleanup (killed
+        // mid-run, crashed, machine restart). `git worktree add -b` refuses
+        // outright if the branch already exists ("fatal: a branch named '...'
+        // already exists"), which without this would permanently block the
+        // issue from ever being claimed again — it'd fail this same way on
+        // every single retry. Safe to clear unconditionally: worktreeRemove/
+        // deleteLocalBranch are both no-ops if there's nothing to remove.
+        cleanupWorktree(deps, { worktree: worktreePath, branch });
         deps.git.fetch("origin", deps.baseBranch);
         deps.git.worktreeAdd(worktreePath, branch, `origin/${deps.baseBranch}`);
+        deps.linkDataDir(worktreePath);
         await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, attempt: 0 });
         const prompt = `${issue.title}\n\n${issue.body}`.trim();
         const result = await deps.runChain({ prompt, cwd: worktreePath, adwId });

package/dist/test/chains.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Regression net for the chain registry. Chains used to each be a hand-written
+ * module; now every one but `simple-sdlc` is a `steps` list whose
+ * `phases`/`requiredAgents`/`requiredSuites` are DERIVED (see
+ * `chains/steps.ts`'s `derivePhases`/`deriveRequiredAgents`/
+ * `deriveRequiredSuites`). These tests pin what that derivation produces
+ * today, so a step-factory change that silently alters a chain's shape (an
+ * agent dropped from `requiredAgents`, a suite no longer required, a phase
+ * missing from the display string) fails here instead of only showing up as
+ * a `spf list` diff nobody happened to read.
+ */
+export {};