@gr8ful/spf 0.1.0

package/dist/cli/commands/watch.js

@@ -0,0 +1,210 @@
+/**
+ * `spf watch` — poll a `watch.repo` for issues labeled `<prefix>:ready`,
+ * run `watch.chain` against each in its own git worktree, open a PR, and
+ * track it through to merged/blocked. See `src/core/watch.ts` for the
+ * actual state machine; this file is just the wiring: config, the GitHub
+ * provider, the chain-dispatch callback, the lockfile, and the CLI loop.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import * as agents from "../../core/agents.js";
+import * as paths from "../../core/paths.js";
+import { isRepoAt, makeGit } from "../../core/git_helper.js";
+import { GitHubProvider } from "../../core/issues/github_provider.js";
+import { createWatchState, tick } from "../../core/watch.js";
+import { findChain } from "../../chains/index.js";
+import { SfDb } from "../../ui/server/db.js";
+import { parseCli } from "../../core/utils.js";
+/**
+ * Shared by `watch` and `watch init`: resolve config and build the
+ * provider, checking only what BOTH need — a supported provider, a
+ * non-empty `watch.repo`, and `GITHUB_TOKEN`. `watch`'s own extra checks
+ * (a real git repo, a registered chain) don't apply to seeding labels.
+ * Prints its own error and returns `null` on failure — the caller just
+ * needs to `return 1`.
+ */
+function resolveWatchProvider(cfg) {
+    if (cfg.watch.provider !== "github") {
+        console.error(`watch.provider ${JSON.stringify(cfg.watch.provider)} is not supported`);
+        return null;
+    }
+    if (!cfg.watch.repo.trim()) {
+        console.error(`watch.repo is not configured — add it to spf.config.yaml's watch: section, e.g. "owner/name"`);
+        return null;
+    }
+    const token = process.env["GITHUB_TOKEN"];
+    if (!token) {
+        console.error('GITHUB_TOKEN is not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo). See README.md\'s "GITHUB_TOKEN scope" section.');
+        return null;
+    }
+    return new GitHubProvider(cfg.watch.repo, cfg.watch.label_prefix, token);
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Stale-steal, like the reference implementation's daemon lock: a dead pid never blocks a restart. */
+function acquireLock(lockPath) {
+    if (existsSync(lockPath)) {
+        const pid = Number.parseInt(readFileSync(lockPath, "utf-8").trim(), 10);
+        if (Number.isInteger(pid) && isPidAlive(pid)) {
+            throw new Error(`another \`spf watch\` is already running (pid ${pid}) — lock at ${lockPath}`);
+        }
+    }
+    mkdirSync(path.dirname(lockPath), { recursive: true });
+    writeFileSync(lockPath, String(process.pid));
+}
+function releaseLock(lockPath) {
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // already gone — fine
+    }
+}
+/**
+ * `spf watch init` — idempotently seed the `<prefix>:*` labels the state
+ * machine needs, with sensible colors/descriptions. Doesn't touch git or
+ * run anything, so it skips watchCommand's repo/chain checks entirely —
+ * you can seed labels before ever wiring up a worktree-capable checkout.
+ */
+export async function watchInitCommand(argv) {
+    const { options } = parseCli(argv, ["cwd", "config"], []);
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    const cfg = agents.loadConfig(paths.resolveConfigPaths(anchor, options["config"]).paths);
+    const provider = resolveWatchProvider(cfg);
+    if (!provider)
+        return 1;
+    const result = await provider.ensureLabels();
+    console.log(`spf watch init: ${cfg.watch.repo} (label prefix "${cfg.watch.label_prefix}")`);
+    for (const name of result.created)
+        console.log(`  + ${name} (created)`);
+    for (const name of result.updated)
+        console.log(`  ~ ${name} (updated color/description)`);
+    for (const name of result.unchanged)
+        console.log(`  = ${name} (already correct)`);
+    return 0;
+}
+export async function watchCommand(argv) {
+    const { options, flags } = parseCli(argv, ["cwd", "config"], ["dry-run", "once"]);
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    const configPaths = paths.resolveConfigPaths(anchor, options["config"]).paths;
+    const cfg = agents.loadConfig(configPaths);
+    const provider = resolveWatchProvider(cfg);
+    if (!provider)
+        return 1;
+    if (!isRepoAt(anchor.repo_root)) {
+        console.error(`${anchor.repo_root} is not a git repository`);
+        return 1;
+    }
+    if (!findChain(cfg.watch.chain)) {
+        console.error(`watch.chain ${JSON.stringify(cfg.watch.chain)} is not a registered chain — run \`spf list\` to see every chain`);
+        return 1;
+    }
+    const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
+    const lockPath = path.join(dataPaths.data_dir, "watch.lock");
+    try {
+        acquireLock(lockPath);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const git = makeGit(anchor.repo_root);
+    const worktreesDir = path.join(homedir(), ".spf", "watch", path.basename(anchor.repo_root), "worktrees");
+    mkdirSync(worktreesDir, { recursive: true });
+    const runChain = async (opts) => {
+        const chainDef = findChain(cfg.watch.chain); // checked above
+        const ctx = { prompt: opts.prompt, config_paths: configPaths, adw_id: opts.adwId, cwd: opts.cwd };
+        const code = await chainDef.run(ctx);
+        if (code === 0)
+            return { accepted: true, adwId: opts.adwId, detail: "" };
+        let detail = `Chain "${cfg.watch.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`;
+        try {
+            const wtAnchor = paths.resolveAnchor(opts.cwd);
+            const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
+            const db = new SfDb(wtDataPaths.db_path);
+            const failed = db.phases(opts.adwId).find((p) => p.status === "fail");
+            if (failed)
+                detail += ` Phase "${failed.name}" failed: ${failed.error ?? "(no detail)"}`;
+        }
+        catch {
+            // best-effort — the generic message above still points at where to look
+        }
+        return { accepted: false, adwId: opts.adwId, detail };
+    };
+    const deps = {
+        provider,
+        git,
+        worktreeGit: makeGit,
+        labelPrefix: cfg.watch.label_prefix,
+        chain: cfg.watch.chain,
+        baseBranch: cfg.watch.base_branch,
+        concurrency: cfg.watch.concurrency,
+        worktreesDir,
+        dryRun: Boolean(flags["dry-run"]),
+        runChain,
+        log: (message) => console.log(message),
+    };
+    const state = createWatchState();
+    let stopping = false;
+    // `sleep()`'s pending setTimeout keeps running regardless of `stopping` —
+    // setting the flag alone doesn't wake it, which is exactly why Ctrl-C
+    // used to appear to do nothing for up to poll_ms (default 60s): the
+    // signal landed, but nothing was listening for it to cancel the wait.
+    let interrupt = null;
+    function interruptibleSleep(ms) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(resolve, ms);
+            interrupt = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+        });
+    }
+    let sigints = 0;
+    const stop = () => {
+        stopping = true;
+        interrupt?.();
+        sigints++;
+        if (sigints >= 2) {
+            console.error("\n[spf] watch     second interrupt — exiting immediately, without draining");
+            releaseLock(lockPath);
+            process.exit(130);
+        }
+        else {
+            console.error("\n[spf] watch     stopping after the current tick (press again to force-quit without draining)");
+        }
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    console.log(`[spf] watch     ${cfg.watch.repo}  label "${cfg.watch.label_prefix}:*"  chain "${cfg.watch.chain}"  concurrency ${cfg.watch.concurrency}${flags["dry-run"] ? "  (dry run)" : ""}`);
+    try {
+        for (;;) {
+            await tick(deps, state);
+            if (flags["once"] || stopping)
+                break;
+            await interruptibleSleep(cfg.watch.poll_ms);
+            if (stopping)
+                break;
+        }
+        while (state.inflight.size > 0) {
+            console.log(`[spf] watch     draining ${state.inflight.size} in-flight issue(s)...`);
+            await interruptibleSleep(1000);
+            if (stopping && sigints >= 2)
+                break; // stop() itself already exits on the 2nd signal; this is belt-and-suspenders
+        }
+        return 0;
+    }
+    finally {
+        process.off("SIGINT", stop);
+        process.off("SIGTERM", stop);
+        releaseLock(lockPath);
+    }
+}

package/dist/cli/gitignore.d.ts

@@ -0,0 +1 @@
+export declare function ensureGitignore(repoRoot: string, entries: string[]): void;

package/dist/cli/gitignore.js

@@ -0,0 +1,14 @@
+/** Shared by `init` and `eject` — append missing entries to the repo's `.gitignore`, idempotently. */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+export function ensureGitignore(repoRoot, entries) {
+    const gitignorePath = path.join(repoRoot, ".gitignore");
+    const hadFile = existsSync(gitignorePath);
+    const existing = hadFile ? readFileSync(gitignorePath, "utf-8").split("\n") : [];
+    const missing = entries.filter((entry) => !existing.includes(entry));
+    if (missing.length === 0)
+        return;
+    const body = hadFile ? existing.join("\n").replace(/\n*$/, "\n") + "\n" : "";
+    writeFileSync(gitignorePath, `${body}# spf runtime\n${missing.join("\n")}\n`);
+    console.log(`updated ${gitignorePath} (added ${missing.join(", ")})`);
+}

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export declare function main(): Promise<void>;

package/dist/cli/index.js

@@ -0,0 +1,156 @@
+/**
+ * `spf` — the command surface. `spf <chain-name> "<prompt>"` and
+ * `spf run <chain-name> "<prompt>"` are identical; the bare form exists
+ * because typing the chain name IS choosing what to run, and that's the
+ * common case. Everything else is a named subcommand.
+ */
+import path from "node:path";
+import * as agentCc from "../core/agent_cc.js";
+import * as agentFlue from "../core/agent_flue.js";
+import * as paths from "../core/paths.js";
+import { findChain } from "../chains/index.js";
+import { dispatchChain, usageFor } from "./commands/run.js";
+import { listCommand } from "./commands/list.js";
+import { initCommand } from "./commands/init.js";
+import { installSkillCommand } from "./commands/install-skill.js";
+import { migrateCommand } from "./commands/migrate.js";
+import { ejectCommand } from "./commands/eject.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { sessionsCommand } from "./commands/sessions.js";
+import { phasesCommand } from "./commands/phases.js";
+import { eventsCommand } from "./commands/events.js";
+import { abortCommand } from "./commands/abort.js";
+import { uiCommand } from "./commands/ui.js";
+import { watchCommand, watchInitCommand } from "./commands/watch.js";
+import { versionCommand } from "./commands/version.js";
+const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
+
+  spf list                                  the chain registry — names, phases, what each needs
+  spf <chain> "<prompt>" [options]          run a chain (spf run <chain> ... works identically)
+  spf init [--force]                        seed .spf/spf.config.yaml in the current repo
+  spf install-skill [--user] [--force]      install the Claude Code skill (repo-local by default)
+  spf migrate [--apply] [--force]           move an old stamped adws/ tree onto .spf/ (dry run by default)
+  spf eject [--target <dir>] [--force]      copy the installed engine out for reference/hand-editing
+  spf doctor [--json]                       check everything that fails silently otherwise
+  spf ui [--port N] [--no-open] [--db path] open the trace visualizer
+  spf watch init                            idempotently seed the <prefix>:* labels watch.repo needs
+  spf watch [--dry-run] [--once]            poll watch.repo for labeled issues, run watch.chain on each
+  spf sessions [--limit N] [--json]         recent runs
+  spf phases <adw_id> [--json]              one run's phases
+  spf events <adw_id> [--follow] [--json]   one run's trace events
+  spf abort <adw_id>                        signal a run's process to stop
+  spf version                               print the installed version
+
+Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>]
+Run \`spf list\` to see every chain and what it needs.`;
+/** A raw scan for `--cwd`, ahead of any command-specific argv parsing — every command that takes it means the same thing by it. */
+function findCwdFlag(argv) {
+    const idx = argv.indexOf("--cwd");
+    return idx !== -1 ? argv[idx + 1] : undefined;
+}
+export async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    // `process.loadEnvFile()` with no argument reads from `process.cwd()` —
+    // the OS process's actual working directory, NOT spf's own `--cwd`
+    // option. Every other path in this codebase anchors to `--cwd` (that's
+    // the whole point of paths.resolveAnchor()); loading .env from the
+    // invoking shell's directory instead of the target repo's is exactly the
+    // anchor-mismatch bug that principle exists to close. Resolve the same
+    // way every command does, and load .env from the repo root it finds.
+    try {
+        const anchor = paths.resolveAnchor(findCwdFlag(rest));
+        process.loadEnvFile(path.join(anchor.repo_root, ".env"));
+    }
+    catch {
+        // no .env there — fine, nothing to load
+    }
+    if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+        console.log(HELP);
+        process.exitCode = 0;
+        return;
+    }
+    if (cmd === "version" || cmd === "--version" || cmd === "-v") {
+        process.exitCode = versionCommand();
+        return;
+    }
+    try {
+        switch (cmd) {
+            case "run": {
+                const [chainName, ...chainArgs] = rest;
+                const chain = chainName ? findChain(chainName) : undefined;
+                if (!chain) {
+                    console.error(`unknown chain: ${chainName ?? "(none given)"} — run \`spf list\` to see every chain`);
+                    process.exitCode = 1;
+                    return;
+                }
+                process.exitCode = await dispatchChain(chain, chainArgs);
+                return;
+            }
+            case "list":
+                process.exitCode = listCommand();
+                return;
+            case "init":
+                process.exitCode = initCommand(rest);
+                return;
+            case "install-skill":
+                process.exitCode = installSkillCommand(rest);
+                return;
+            case "migrate":
+                process.exitCode = migrateCommand(rest);
+                return;
+            case "eject":
+                process.exitCode = ejectCommand(rest);
+                return;
+            case "doctor":
+                process.exitCode = doctorCommand(rest);
+                return;
+            case "ui":
+                process.exitCode = await uiCommand(rest);
+                return;
+            case "watch": {
+                const [sub, ...watchArgs] = rest;
+                process.exitCode = sub === "init" ? await watchInitCommand(watchArgs) : await watchCommand(rest);
+                return;
+            }
+            case "sessions":
+                process.exitCode = sessionsCommand(rest);
+                return;
+            case "phases":
+                process.exitCode = phasesCommand(rest);
+                return;
+            case "events":
+                process.exitCode = await eventsCommand(rest);
+                return;
+            case "abort":
+                process.exitCode = abortCommand(rest);
+                return;
+            default: {
+                const chain = findChain(cmd);
+                if (!chain) {
+                    console.error(`unknown command or chain: ${cmd}\n`);
+                    console.error(HELP);
+                    process.exitCode = 1;
+                    return;
+                }
+                if (rest.length < 1) {
+                    console.error(usageFor(chain));
+                    process.exitCode = 1;
+                    return;
+                }
+                process.exitCode = await dispatchChain(chain, rest);
+                return;
+            }
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    }
+    finally {
+        // A no-op if this invocation never touched an agent (e.g. spf quality,
+        // spf list, spf doctor) — the Flue runtime only ever starts lazily, and
+        // agent_cc.ts's shutdown() just kills any still-running claude children.
+        await agentFlue.shutdown();
+        await agentCc.shutdown();
+    }
+}

package/dist/core/agent_cc.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Claude Code coding agent interface — a second backend alongside
+ * `agent_flue.ts` (`coding_agent: claude_code` in config), for running
+ * agents on the `claude` CLI instead of Flue. Subprocess-based, on purpose:
+ * the official SDK's own platform-specific optional dependency is 300MB+
+ * per platform, on top of the `claude` CLI itself (which anyone using this
+ * backend needs installed anyway) — shelling out costs SPF zero new
+ * dependencies, the same trade the pre-Flue `agent_pi.ts` made for `pi`.
+ *
+ * Every flag below was verified against a REAL local run of this exact
+ * machine's `claude` CLI (v2.1.237) before being written — not assumed from
+ * the SDK's docs, which describe a related but separately-versioned
+ * product. Findings that shaped this file:
+ *
+ *  - `--json-schema` is real, and structured output arrives as a BUILT-IN
+ *    tool call named `StructuredOutput` (visible in the `system/init`
+ *    message's `tools` list the moment `--json-schema` is passed) — no
+ *    custom tool registration needed, unlike Flue's injected `sf_report`.
+ *    The final `result` message's `structured_output` field carries the
+ *    validated object directly.
+ *  - `--strict-mcp-config` (with no `--mcp-config` given) is REQUIRED, not
+ *    optional: without it, a spawned `claude` process inherits this
+ *    machine's entire user-level MCP server configuration (GitHub, Slack,
+ *    Google Drive, whatever the operator has configured globally) — a real
+ *    capability leak into what's supposed to be a `tools:`-bounded headless
+ *    agent. `--tools ""` alone does NOT strip these; confirmed by a live
+ *    run showing `mcp__github__*`/`mcp__claude_ai_*` tools still listed in
+ *    `system/init` without it, and gone with it.
+ *  - `--resume <uuid>` genuinely continues context (confirmed: a follow-up
+ *    call answered from a file read in the FIRST call, never re-reading it)
+ *    — the same continuity Flue's `init(agent, {id})` gives, so the
+ *    same-session-correction design carries over unchanged.
+ *  - The result message's `total_cost_usd` has no per-component breakdown
+ *    (unlike Flue/pi-ai's `cost.{input,output,cacheRead,cacheWrite}`) — it's
+ *    folded into `UsageBreakdown` under `total_cost` only, honestly, rather
+ *    than fabricating a split CC doesn't provide.
+ */
+import type { AgentRequest, AgentResult } from "./data_types.ts";
+/** One line of `claude -p --output-format stream-json` output, loosely typed — see the module doc comment for what's actually verified. */
+export type CcStreamMessage = Record<string, any>;
+/**
+ * Folds a `tool_use` content block (on an `assistant` message) + its
+ * matching `tool_result` block (on a LATER `user` message, linked by
+ * `tool_use_id`) into one record — the same shape
+ * `agent_flue.ToolCallTracker` produces, so `agents.ts`'s `eventForwarder`
+ * needs no backend-specific branching downstream of picking which tracker
+ * to use. `StructuredOutput` calls fold through here too, deliberately
+ * unfiltered — Flue's `sf_report` tool shows up as an ordinary `tool_call`
+ * event for the same reason, and that's useful trace information, not noise.
+ */
+export declare class CcToolCallTracker {
+    private open;
+    observe(message: CcStreamMessage): Record<string, any> | null;
+    private finish;
+}
+export declare function isKnownToolName(name: string): boolean;
+/** Kill any still-running `claude` children — call once, at process exit. Safe if none are running. */
+export declare function shutdown(): Promise<void>;
+/**
+ * Run one `claude -p` turn against `request.session_id` (a UUID minted by
+ * `agents.ts`'s `agentSessionId()` for a fresh session, or carried over from
+ * `agent_map.json` for a rejoin) — `--session-id` on first contact,
+ * `--resume` when `request.resume` says this session already exists. CC has
+ * no single create-or-continue flag the way Flue's `init(id)` is, which is
+ * exactly why `AgentRequest.resume` exists — see its doc comment in
+ * `data_types.ts`.
+ *
+ * `onEvent` receives each parsed stream-json line UNFOLDED, exactly as
+ * `agent_flue.run()` forwards raw `ConversationStreamChunk`s — folding into
+ * one record per tool call is `eventForwarder`'s job (`agents.ts`), via
+ * this module's `CcToolCallTracker`. Folding here too would fold twice.
+ */
+export declare function run(request: AgentRequest, onEvent?: (message: CcStreamMessage) => void, onSpawn?: (pid: number) => void, onExit?: (pid: number) => void): Promise<AgentResult>;
+/** CC requires a real UUID for `--session-id`/`--resume` — `agents.ts`'s `agentSessionId()` calls this to mint a fresh one for a claude_code agent's first contact. */
+export declare function newSessionId(): string;