@gr8ful/spf 0.1.7 → 0.2.1

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

@@ -14,37 +14,15 @@ import * as paths from "../../core/paths.js";
 import * as permissions from "../../core/permissions.js";
 import * as agentCc from "../../core/agent_cc.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: [] };

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() {
@@ -75,20 +92,76 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 // 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>;

package/dist/cli/commands/run.js

@@ -1,6 +1,7 @@
 /** Shared by both `spf <chain> "..."` and `spf run <chain> "..."` — same dispatch. */
 import * as paths from "../../core/paths.js";
 import { parseCli, resolvePrompt } from "../../core/utils.js";
+import { runChain } from "../../chains/index.js";
 const KNOWN_OPTIONS = ["config", "adw-id", "cwd", "agent", "base"];
 export function usageFor(chain) {
     return `usage: spf ${chain.name} "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id <id>] [--cwd <dir>]`;
@@ -17,11 +18,12 @@ export async function dispatchChain(chain, argv) {
         config_paths: paths.resolveConfigPaths(anchor, options["config"]).paths,
         adw_id: options["adw-id"] ?? null,
         cwd: anchor.cwd,
+        chain_name: chain.name,
     };
     const chainOptions = {};
     if (options["agent"] !== undefined)
         chainOptions["agent"] = options["agent"];
     if (options["base"] !== undefined)
         chainOptions["base"] = options["base"];
-    return chain.run(ctx, chainOptions);
+    return runChain(chain, ctx, chainOptions);
 }

package/dist/cli/commands/watch.js

@@ -15,7 +15,7 @@ import { GitHubProvider } from "../../core/issues/github_provider.js";
 import { JiraProvider } from "../../core/issues/jira_provider.js";
 import { BitbucketProvider } from "../../core/issues/bitbucket_provider.js";
 import { createWatchState, tick } from "../../core/watch.js";
-import { findChain } from "../../chains/index.js";
+import { findChain, runChain as runChainDef } from "../../chains/index.js";
 import { SfDb } from "../../ui/server/db.js";
 import { parseCli } from "../../core/utils.js";
 /**
@@ -184,8 +184,8 @@ export async function watchCommand(argv) {
     }
     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);
+        const ctx = { prompt: opts.prompt, config_paths: configPaths, adw_id: opts.adwId, cwd: opts.cwd, chain_name: chainDef.name };
+        const code = await runChainDef(chainDef, 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.`;

package/dist/cli/env_file.d.ts

@@ -0,0 +1,18 @@
+/** Parses simple `KEY=VALUE` lines; blank lines and `#` comments are ignored (and preserved verbatim on write). */
+export declare function readEnvFile(p: string): Map<string, string>;
+/** Redacts a secret for display: keeps the last 4 characters, masks the rest. Short values are fully masked. */
+export declare function maskSecret(value: string): string;
+export interface EnvUpsertResult {
+    added: string[];
+    updated: string[];
+    unchanged: string[];
+}
+/**
+ * Upsert `entries` into `<repoRoot>/.env`, preserving every existing line —
+ * comments, ordering, unrelated keys — verbatim. An existing key is
+ * rewritten in place (never duplicated); a new key is appended under a
+ * `# spf` header, matching `ensureGitignore`'s idempotent-append shape.
+ */
+export declare function upsertEnvFile(repoRoot: string, entries: Record<string, string>): EnvUpsertResult;
+/** Fills the `!.env.example` slot `.gitignore` already reserves — key names only, empty values, safe to commit. */
+export declare function writeEnvExample(repoRoot: string, keys: string[]): void;

package/dist/cli/env_file.js

@@ -0,0 +1,99 @@
+/**
+ * Idempotent `.env` upsert for `spf init`'s interview — the write-side
+ * counterpart of `process.loadEnvFile()` in `src/cli/index.ts:66`, which
+ * already loads `<repo_root>/.env` on every command. Modeled directly on
+ * `ensureGitignore` (`./gitignore.ts`): read, compute only what's missing or
+ * changed, log a one-line summary of key NAMES only — a secret value must
+ * never reach stdout, a log line, or a trace event.
+ */
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+const KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+function unquote(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length >= 2 && ((trimmed[0] === '"' && trimmed.endsWith('"')) || (trimmed[0] === "'" && trimmed.endsWith("'")))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function quoteIfNeeded(value) {
+    if (/[\s#"]/.test(value))
+        return `"${value.replace(/"/g, '\\"')}"`;
+    return value;
+}
+/** Parses simple `KEY=VALUE` lines; blank lines and `#` comments are ignored (and preserved verbatim on write). */
+export function readEnvFile(p) {
+    const values = new Map();
+    if (!existsSync(p))
+        return values;
+    for (const line of readFileSync(p, "utf-8").split("\n")) {
+        const match = KEY_LINE.exec(line.trim());
+        if (match)
+            values.set(match[1], unquote(match[2]));
+    }
+    return values;
+}
+/** Redacts a secret for display: keeps the last 4 characters, masks the rest. Short values are fully masked. */
+export function maskSecret(value) {
+    if (value.length <= 4)
+        return "•".repeat(Math.max(value.length, 1));
+    return `${"•".repeat(value.length - 4)}${value.slice(-4)}`;
+}
+/**
+ * Upsert `entries` into `<repoRoot>/.env`, preserving every existing line —
+ * comments, ordering, unrelated keys — verbatim. An existing key is
+ * rewritten in place (never duplicated); a new key is appended under a
+ * `# spf` header, matching `ensureGitignore`'s idempotent-append shape.
+ */
+export function upsertEnvFile(repoRoot, entries) {
+    const envPath = path.join(repoRoot, ".env");
+    const hadFile = existsSync(envPath);
+    const lines = hadFile ? readFileSync(envPath, "utf-8").split("\n") : [];
+    const result = { added: [], updated: [], unchanged: [] };
+    const remaining = new Map(Object.entries(entries));
+    const rewritten = lines.map((line) => {
+        const match = KEY_LINE.exec(line.trim());
+        if (!match || !remaining.has(match[1]))
+            return line;
+        const key = match[1];
+        const newValue = remaining.get(key);
+        remaining.delete(key);
+        if (unquote(match[2]) === newValue) {
+            result.unchanged.push(key);
+            return line;
+        }
+        result.updated.push(key);
+        return `${key}=${quoteIfNeeded(newValue)}`;
+    });
+    const newKeys = [...remaining.keys()];
+    if (newKeys.length > 0) {
+        result.added.push(...newKeys);
+        const body = hadFile ? rewritten.join("\n").replace(/\n*$/, "\n") + "\n" : "";
+        const appended = newKeys.map((key) => `${key}=${quoteIfNeeded(remaining.get(key))}`);
+        writeFileSync(envPath, `${body}# spf\n${appended.join("\n")}\n`);
+    }
+    else if (result.updated.length > 0) {
+        writeFileSync(envPath, rewritten.join("\n"));
+    }
+    if (!hadFile) {
+        try {
+            chmodSync(envPath, 0o600);
+        }
+        catch {
+            // best-effort — some filesystems (or Windows) don't support unix perms
+        }
+    }
+    if (result.added.length > 0 || result.updated.length > 0) {
+        console.log(`updated ${envPath} (added: ${result.added.join(", ") || "none"}; updated: ${result.updated.join(", ") || "none"})`);
+    }
+    return result;
+}
+/** Fills the `!.env.example` slot `.gitignore` already reserves — key names only, empty values, safe to commit. */
+export function writeEnvExample(repoRoot, keys) {
+    if (keys.length === 0)
+        return;
+    const examplePath = path.join(repoRoot, ".env.example");
+    const unique = [...new Set(keys)].sort();
+    writeFileSync(examplePath, `# spf — keys required by this repo's spf.config.yaml; fill in real values in .env (gitignored)\n${unique.map((k) => `${k}=`).join("\n")}\n`);
+    console.log(`wrote ${examplePath}`);
+}

package/dist/cli/index.js

@@ -27,7 +27,7 @@ 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] [--template <name>]    seed .spf/spf.config.yaml (from a packaged template, if named)
+  spf init [--force] [--yes] [--template <name>]  interview to seed .spf/spf.config.yaml + .env (--yes/--template skip the interview)
   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
@@ -90,7 +90,7 @@ export async function main() {
                 process.exitCode = listCommand();
                 return;
             case "init":
-                process.exitCode = initCommand(rest);
+                process.exitCode = await initCommand(rest);
                 return;
             case "install-skill":
                 process.exitCode = installSkillCommand(rest);

package/dist/cli/interview.d.ts

@@ -0,0 +1,24 @@
+import type { Asker } from "./ask.ts";
+export interface DetectedContext {
+    repoSlug?: string;
+    currentBranch: string;
+    gitEmail?: string;
+    gitName?: string;
+    scripts: Record<string, string>;
+    claudeOnPath: boolean;
+    /** Whatever's already in `.env` — shown masked so a re-run can offer "keep current" instead of asking blind. */
+    existingEnv: Map<string, string>;
+}
+export declare function gatherContext(repoRoot: string, existingEnv?: Map<string, string>): DetectedContext;
+export interface InterviewResult {
+    config: Record<string, unknown>;
+    env: Record<string, string>;
+    /** Key names only (no values) — written to a committable `.env.example`. */
+    envExampleKeys: string[];
+}
+/**
+ * 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 declare function runInterview(asker: Asker, ctx: DetectedContext): Promise<InterviewResult | null>;