@gr8ful/spf 0.1.7 → 0.3.0

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

@@ -10,12 +10,13 @@ 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 { resolveNotifier } from "../../core/notify/notifier.js";
 import { isRepoAt, makeGit } from "../../core/git_helper.js";
 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";
 /**
@@ -161,6 +162,9 @@ export async function watchCommand(argv) {
     const git = makeGit(anchor.repo_root);
     const worktreesDir = path.join(homedir(), ".spf", "watch", path.basename(anchor.repo_root), "worktrees");
     mkdirSync(worktreesDir, { recursive: true });
+    // `null` when notifications are off/unconfigured — every call below is a
+    // no-op fallback to `console.error` in that case (see notify()`s default).
+    const notifier = resolveNotifier(cfg, { dryRun: Boolean(flags["dry-run"]) });
     /**
      * Without this, a claimed issue's chain resolves its session/trace data
      * relative to `cwd` (the worktree, not the main repo — see
@@ -184,8 +188,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.`;
@@ -216,6 +220,7 @@ export async function watchCommand(argv) {
         dryRun: Boolean(flags["dry-run"]),
         runChain,
         log: (message) => console.log(message),
+        notify: (event) => notifier?.send(event),
     };
     const state = createWatchState();
     let stopping = false;
@@ -250,6 +255,16 @@ export async function watchCommand(argv) {
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
     console.log(`[spf] watch     ${cfg.watch.issue_provider}+${cfg.watch.code_host}  ${cfg.watch.repo}  label "${cfg.watch.label_prefix}:*"  chain "${cfg.watch.chain}"  concurrency ${cfg.watch.concurrency}${flags["dry-run"] ? "  (dry run)" : ""}`);
+    deps.notify({
+        kind: "watch_started",
+        level: "info",
+        title: "watch started",
+        fields: [
+            ["repo", cfg.watch.repo],
+            ["label_prefix", cfg.watch.label_prefix],
+            ["chain", cfg.watch.chain],
+        ],
+    });
     try {
         for (;;) {
             await tick(deps, state);
@@ -268,6 +283,8 @@ export async function watchCommand(argv) {
         return 0;
     }
     finally {
+        deps.notify({ kind: "watch_stopped", level: "info", title: "watch stopped", fields: [["repo", cfg.watch.repo]] });
+        await notifier?.flush();
         process.off("SIGINT", stop);
         process.off("SIGTERM", stop);
         releaseLock(lockPath);

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

@@ -7,6 +7,7 @@
 import path from "node:path";
 import * as agentCc from "../core/agent_cc.js";
 import * as agentFlue from "../core/agent_flue.js";
+import * as notify from "../core/notify/notifier.js";
 import * as paths from "../core/paths.js";
 import { findChain } from "../chains/index.js";
 import { dispatchChain, usageFor } from "./commands/run.js";
@@ -27,7 +28,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 +91,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);
@@ -152,5 +153,8 @@ export async function main() {
         // agent_cc.ts's shutdown() just kills any still-running claude children.
         await agentFlue.shutdown();
         await agentCc.shutdown();
+        // A no-op if notifications are off/unconfigured — awaits any in-flight
+        // webhook POST so a fast-exiting command doesn't drop it mid-flight.
+        await notify.flushAll();
     }
 }

package/dist/cli/interview.d.ts

@@ -0,0 +1,26 @@
+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>;
+    /** The packaged roster's agent names (planner, builder, scout, reviewer, documenter today) — read from the built-in config so a 6th agent added there needs no interview change. */
+    rosterNames: 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>;