@gr8ful/spf 0.1.0

package/dist/cli/commands/install-skill.js

@@ -0,0 +1,122 @@
+/**
+ * `spf install-skill` — copy the packaged Claude Code skill (`assets/skill/`)
+ * into a target repo (or `~/.claude/skills/spf` with `--user`), on explicit
+ * request only. Nothing here ever runs unless a user asks for it.
+ *
+ * Idempotent via a manifest (`.spf-skill-version`: {package, version,
+ * files: {relpath: sha256}}) written at the skill root:
+ *   - unchanged file, unchanged source -> no-op
+ *   - unchanged file, source changed (version bump) -> upgraded in place
+ *   - user-edited file (its on-disk hash no longer matches what we last
+ *     installed) -> NEVER silently overwritten; the incoming version is
+ *     written to a `.new` sibling instead, unless --force
+ *   - a file present in the OLD manifest but absent from the current
+ *     package (renamed/removed cookbook) -> deleted, but only if it was
+ *     never edited; an edited stale file is left in place and reported
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import * as paths from "../../core/paths.js";
+import { parseCli } from "../../core/utils.js";
+const MANIFEST_NAME = ".spf-skill-version";
+function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function listFiles(root) {
+    return readdirSync(root, { recursive: true, encoding: "utf-8" })
+        .filter((entry) => statSync(path.join(root, entry)).isFile())
+        .sort();
+}
+function readManifest(manifestPath) {
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(manifestPath, "utf-8"));
+    }
+    catch {
+        return null; // corrupt/foreign file at this path — treat as "no manifest", never crash the install
+    }
+}
+function packageVersion() {
+    const pkg = JSON.parse(readFileSync(path.join(paths.PACKAGE_ROOT, "package.json"), "utf-8"));
+    return pkg.version;
+}
+export function installSkillCommand(argv) {
+    const { options, flags } = parseCli(argv, ["cwd", "target"], ["user", "force"]);
+    const destRoot = options["target"]
+        ? path.resolve(options["target"])
+        : flags["user"]
+            ? path.join(homedir(), ".claude", "skills", "spf")
+            : path.join(paths.resolveAnchor(options["cwd"]).repo_root, ".claude", "skills", "spf");
+    const srcRoot = path.join(paths.ASSETS_DIR, "skill");
+    const sourceFiles = listFiles(srcRoot);
+    const manifestPath = path.join(destRoot, MANIFEST_NAME);
+    const oldManifest = readManifest(manifestPath);
+    const version = packageVersion();
+    const finalFiles = {};
+    const report = [];
+    for (const relpath of sourceFiles) {
+        const srcPath = path.join(srcRoot, relpath);
+        const destPath = path.join(destRoot, relpath);
+        const sourceContent = readFileSync(srcPath);
+        const sourceHash = sha256(sourceContent);
+        const previousHash = oldManifest?.files[relpath];
+        if (!existsSync(destPath)) {
+            mkdirSync(path.dirname(destPath), { recursive: true });
+            writeFileSync(destPath, sourceContent);
+            finalFiles[relpath] = sourceHash;
+            report.push(`+ ${relpath}`);
+            continue;
+        }
+        const destHash = sha256(readFileSync(destPath));
+        if (destHash === sourceHash) {
+            finalFiles[relpath] = sourceHash;
+            continue; // already exactly right — true no-op
+        }
+        if (previousHash !== undefined && destHash === previousHash) {
+            writeFileSync(destPath, sourceContent); // untouched since our last install — safe to upgrade
+            finalFiles[relpath] = sourceHash;
+            report.push(`^ ${relpath} (upgraded)`);
+            continue;
+        }
+        if (flags["force"]) {
+            writeFileSync(destPath, sourceContent);
+            finalFiles[relpath] = sourceHash;
+            report.push(`! ${relpath} (forced over local edits)`);
+            continue;
+        }
+        writeFileSync(`${destPath}.new`, sourceContent);
+        finalFiles[relpath] = previousHash ?? destHash; // keep tracking what's actually on disk
+        report.push(`? ${relpath} (locally modified — wrote ${relpath}.new instead; --force to overwrite)`);
+    }
+    const sourceSet = new Set(sourceFiles);
+    for (const relpath of Object.keys(oldManifest?.files ?? {})) {
+        if (sourceSet.has(relpath))
+            continue;
+        const destPath = path.join(destRoot, relpath);
+        if (!existsSync(destPath))
+            continue;
+        const destHash = sha256(readFileSync(destPath));
+        if (destHash === oldManifest.files[relpath]) {
+            rmSync(destPath);
+            report.push(`- ${relpath} (removed — no longer shipped)`);
+        }
+        else {
+            report.push(`  ${relpath} (no longer shipped, but locally modified — left in place)`);
+        }
+    }
+    mkdirSync(destRoot, { recursive: true });
+    const manifest = { package: "@gr8ful/spf", version, files: finalFiles };
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    console.log(`spf install-skill: ${destRoot} (v${version})`);
+    if (report.length === 0) {
+        console.log("  already up to date");
+    }
+    else {
+        for (const line of report)
+            console.log(`  ${line}`);
+    }
+    return 0;
+}

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

@@ -0,0 +1 @@
+export declare function listCommand(): number;

package/dist/cli/commands/list.js

@@ -0,0 +1,13 @@
+import { CHAINS } from "../../chains/index.js";
+export function listCommand() {
+    const width = Math.max(...CHAINS.map((c) => c.name.length));
+    for (const chain of CHAINS) {
+        const agents = typeof chain.requiredAgents === "function" ? "(--agent picks who)" : chain.requiredAgents.join(", ") || "(none)";
+        console.log(`${chain.name.padEnd(width)}  ${chain.phases}`);
+        console.log(`${"".padEnd(width)}  ${chain.describe}`);
+        console.log(`${"".padEnd(width)}  agents: ${agents}${chain.requiredSuites.length ? `  ·  quality suites: ${chain.requiredSuites.join(", ")}` : ""}`);
+        console.log();
+    }
+    console.log(`spf <name> "<prompt>" [--config <path>] [--adw-id <id>] [--cwd <dir>]   (spf run <name> ... works identically)`);
+    return 0;
+}

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

@@ -0,0 +1 @@
+export declare function migrateCommand(argv: string[]): number;

package/dist/cli/commands/migrate.js

@@ -0,0 +1,167 @@
+/**
+ * `spf migrate` — move a repo stamped by the old skill-and-`bun run` design
+ * (an `adws/` tree) onto the global-CLI `.spf/` convention. Detects the
+ * stamped tree, then COPIES ONLY — nothing under `adws/` is ever deleted or
+ * modified, so a bad migration costs nothing to walk away from. Defaults to
+ * a dry run; pass `--apply` to actually write.
+ *
+ * What moves: the roster (rewritten onto `.spf/` paths, coding_agent: flue),
+ * the prompt files, the trace db (WAL-checkpointed first) and its sessions/
+ * directory as a strict sibling — the one invariant that must survive, or
+ * `spf ui`/the prompts endpoint 404 on every migrated session.
+ *
+ * What does NOT move, on purpose: `adws/adw_modules/*.ts` and any custom
+ * `adw_*.ts` chains. Hand-edited engine code has no automatic equivalent —
+ * the report points at `spf eject` for a copy of the current engine to
+ * reapply those edits onto. `harness_engineering/` entries are dropped for
+ * the same reason `agents.validate()` rejects them going forward: no Flue
+ * analogue exists.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, parseDocument } from "yaml";
+import { Database } from "../../core/sqlite.js";
+import * as paths from "../../core/paths.js";
+import { parseCli } from "../../core/utils.js";
+function copyDirRecursive(from, to) {
+    mkdirSync(to, { recursive: true });
+    for (const entry of readdirSync(from, { withFileTypes: true })) {
+        const srcPath = path.join(from, entry.name);
+        const destPath = path.join(to, entry.name);
+        if (entry.isDirectory())
+            copyDirRecursive(srcPath, destPath);
+        else if (entry.isFile()) {
+            mkdirSync(path.dirname(destPath), { recursive: true });
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+/** The last two path segments — the convention new agent refs use: "<agent>/<file>". */
+function shortRef(oldRef) {
+    const parts = oldRef.split("/").filter(Boolean);
+    return parts.slice(-2).join("/");
+}
+export function migrateCommand(argv) {
+    const { options, flags } = parseCli(argv, ["cwd"], ["apply", "force", "json"]);
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    const apply = Boolean(flags["apply"]);
+    const oldConfigPath = path.join(anchor.repo_root, "adws", "adw_sf_config", "spf.config.yaml");
+    if (!existsSync(oldConfigPath)) {
+        console.log(`no stamped adws/ tree found at ${anchor.repo_root} (looked for ${oldConfigPath}) — nothing to migrate`);
+        return 0;
+    }
+    const newSfDir = path.join(anchor.repo_root, ".spf");
+    const newConfigPath = path.join(newSfDir, "spf.config.yaml");
+    if (existsSync(newConfigPath) && !flags["force"]) {
+        console.error(`${newConfigPath} already exists — refusing to overwrite. Pass --force to proceed anyway.`);
+        return 1;
+    }
+    const oldText = readFileSync(oldConfigPath, "utf-8");
+    const oldConfig = parseYaml(oldText);
+    const doc = parseDocument(oldText);
+    const oldAdwsRoot = path.join(anchor.repo_root, "adws");
+    const resolveOld = (p) => path.resolve(oldAdwsRoot, "..", p); // old refs are "adws/..."-relative to repo_root
+    const actions = [];
+    const newDataDir = ".spf/data";
+    const newDbRel = ".spf/data/spf.db";
+    doc.setIn(["defaults", "data_dir"], newDataDir);
+    doc.setIn(["observability", "db"], newDbRel);
+    if (doc.getIn(["defaults", "coding_agent"]) !== undefined)
+        doc.setIn(["defaults", "coding_agent"], "flue");
+    const defaultsHarness = oldConfig?.defaults?.harness_engineering;
+    if (Array.isArray(defaultsHarness) && defaultsHarness.length > 0) {
+        actions.push({ kind: "note", detail: `defaults.harness_engineering (${defaultsHarness.join(", ")}) dropped — no Flue equivalent` });
+    }
+    doc.setIn(["defaults", "harness_engineering"], []);
+    // .spf/ is now the whole per-repo footprint; the old adws/ paths no longer exist.
+    doc.setIn(["defaults", "protected_files"], [".spf/", "spf.config.yaml"]);
+    const agents = Array.isArray(oldConfig?.agents) ? oldConfig.agents : [];
+    agents.forEach((agent, i) => {
+        const name = agent.name;
+        if (agent.coding_agent !== undefined)
+            doc.setIn(["agents", i, "coding_agent"], "flue");
+        const harness = agent.harness_engineering;
+        if (Array.isArray(harness) && harness.length > 0) {
+            actions.push({ kind: "note", detail: `${name}.harness_engineering (${harness.join(", ")}) dropped — no Flue equivalent` });
+        }
+        if (harness !== undefined)
+            doc.setIn(["agents", i, "harness_engineering"], []);
+        for (const slot of ["system", "user"]) {
+            const oldRef = agent?.prompt_engineering?.[slot];
+            if (!oldRef)
+                continue;
+            const srcPath = resolveOld(oldRef);
+            const newRef = shortRef(oldRef); // "<agent>/system.md" — resolves via .spf/prompt_engineering/<agent>/...
+            doc.setIn(["agents", i, "prompt_engineering", slot], newRef);
+            if (existsSync(srcPath)) {
+                actions.push({ kind: "copy-file", detail: `${path.relative(anchor.repo_root, srcPath)} -> .spf/prompt_engineering/${newRef}` });
+            }
+            else {
+                actions.push({ kind: "note", detail: `${name}.prompt_engineering.${slot} (${oldRef}) not found on disk — not copied` });
+            }
+        }
+    });
+    const oldDbPath = resolveOld(oldConfig?.observability?.db ?? "adws/adw_data/spf.db");
+    const oldSessionsDir = path.join(path.dirname(oldDbPath), "sessions");
+    if (existsSync(oldDbPath)) {
+        actions.push({ kind: "copy-file", detail: `${path.relative(anchor.repo_root, oldDbPath)} -> ${newDbRel} (WAL-checkpointed first)` });
+    }
+    else {
+        actions.push({ kind: "note", detail: `no trace db found at ${path.relative(anchor.repo_root, oldDbPath)} — nothing to carry over` });
+    }
+    if (existsSync(oldSessionsDir)) {
+        actions.push({ kind: "copy-dir", detail: `${path.relative(anchor.repo_root, oldSessionsDir)}/ -> .spf/data/sessions/ (must stay a sibling of spf.db)` });
+    }
+    actions.push({ kind: "write-config", detail: `.spf/spf.config.yaml (rewritten: data_dir, observability.db, prompt refs, coding_agent: flue)` });
+    const oldAdwFiles = existsSync(oldAdwsRoot)
+        ? readdirSync(oldAdwsRoot).filter((f) => f.startsWith("adw_") && f.endsWith(".ts"))
+        : [];
+    actions.push({
+        kind: "note",
+        detail: `adws/adw_modules/ and adws/${oldAdwFiles.length > 0 ? oldAdwFiles.join(", ") : "adw_*.ts"} were NOT migrated — ` +
+            `hand-edited engine code has no automatic equivalent. Run \`spf eject\` for an editable copy of the current ` +
+            `engine to reapply any customizations onto, then delete adws/ yourself once you've confirmed the migration.`,
+    });
+    if (flags["json"]) {
+        console.log(JSON.stringify({ apply, actions }, null, 2));
+    }
+    else {
+        console.log(apply ? `spf migrate --apply: ${anchor.repo_root}` : `spf migrate (dry run — pass --apply to write): ${anchor.repo_root}`);
+        for (const a of actions)
+            console.log(`  [${a.kind}] ${a.detail}`);
+    }
+    if (!apply)
+        return 0;
+    mkdirSync(newSfDir, { recursive: true });
+    mkdirSync(path.join(anchor.repo_root, ".spf", "data"), { recursive: true });
+    agents.forEach((agent) => {
+        for (const slot of ["system", "user"]) {
+            const oldRef = agent?.prompt_engineering?.[slot];
+            if (!oldRef)
+                continue;
+            const srcPath = resolveOld(oldRef);
+            if (!existsSync(srcPath))
+                continue;
+            const destPath = path.join(newSfDir, "prompt_engineering", shortRef(oldRef));
+            mkdirSync(path.dirname(destPath), { recursive: true });
+            copyFileSync(srcPath, destPath);
+        }
+    });
+    if (existsSync(oldDbPath)) {
+        try {
+            const db = new Database(oldDbPath);
+            db.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+            db.close();
+        }
+        catch (error) {
+            console.error(`warning: could not checkpoint ${oldDbPath} before copying (${error.message}) — copying as-is`);
+        }
+        copyFileSync(oldDbPath, path.join(anchor.repo_root, newDbRel));
+    }
+    if (existsSync(oldSessionsDir)) {
+        copyDirRecursive(oldSessionsDir, path.join(anchor.repo_root, ".spf", "data", "sessions"));
+    }
+    writeFileSync(newConfigPath, doc.toString());
+    console.log(`\ndone. Verify with: spf doctor && spf sessions`);
+    return 0;
+}

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

@@ -0,0 +1 @@
+export declare function phasesCommand(argv: string[]): number;

package/dist/cli/commands/phases.js

@@ -0,0 +1,25 @@
+import { parseCli } from "../../core/utils.js";
+import { openTrace } from "./trace.js";
+export function phasesCommand(argv) {
+    const { positionals, options, flags } = parseCli(argv, ["cwd", "config"], ["json"]);
+    if (positionals.length < 1) {
+        console.error("usage: spf phases <adw_id> [--cwd <dir>] [--config <path>] [--json]");
+        return 1;
+    }
+    const adwId = positionals[0];
+    const { db } = openTrace(options);
+    const rows = db.phases(adwId);
+    if (flags["json"]) {
+        console.log(JSON.stringify(rows, null, 2));
+        return 0;
+    }
+    if (rows.length === 0) {
+        console.log(`no phases recorded for ${adwId}`);
+        return 1;
+    }
+    for (const p of rows) {
+        const marker = p.status === "success" ? "✓" : p.status === "fail" ? "✗" : "…";
+        console.log(`${String(p.seq).padStart(2, "0")} ${marker} ${(p.name ?? "").padEnd(20)} ${(p.kind ?? "").padEnd(9)} ${(p.owner ?? "").padEnd(12)} ${p.error ?? ""}`);
+    }
+    return 0;
+}

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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,27 @@
+/** 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";
+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>]`;
+}
+export async function dispatchChain(chain, argv) {
+    const { positionals, options } = parseCli(argv, KNOWN_OPTIONS);
+    if (positionals.length < 1) {
+        console.error(usageFor(chain));
+        return 1;
+    }
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    const ctx = {
+        prompt: resolvePrompt(positionals[0]),
+        config_paths: paths.resolveConfigPaths(anchor, options["config"]).paths,
+        adw_id: options["adw-id"] ?? null,
+        cwd: anchor.cwd,
+    };
+    const chainOptions = {};
+    if (options["agent"] !== undefined)
+        chainOptions["agent"] = options["agent"];
+    if (options["base"] !== undefined)
+        chainOptions["base"] = options["base"];
+    return chain.run(ctx, chainOptions);
+}

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

@@ -0,0 +1 @@
+export declare function sessionsCommand(argv: string[]): number;

package/dist/cli/commands/sessions.js

@@ -0,0 +1,20 @@
+import { parseCli } from "../../core/utils.js";
+import { openTrace } from "./trace.js";
+export function sessionsCommand(argv) {
+    const { options, flags } = parseCli(argv, ["cwd", "config", "limit"], ["json"]);
+    const { db } = openTrace(options);
+    const limit = options["limit"] ? Number.parseInt(options["limit"], 10) : 20;
+    const rows = db.sessions(limit);
+    if (flags["json"]) {
+        console.log(JSON.stringify(rows, null, 2));
+        return 0;
+    }
+    if (rows.length === 0) {
+        console.log("no sessions yet");
+        return 0;
+    }
+    for (const s of rows) {
+        console.log(`${s.adw_id}  ${(s.status ?? "").padEnd(8)}  ${s.started_at}  ${(s.request ?? "").slice(0, 60)}`);
+    }
+    return 0;
+}

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

@@ -0,0 +1,8 @@
+import * as paths from "../../core/paths.ts";
+import { SfDb } from "../../ui/server/db.ts";
+export interface TraceHandle {
+    db: SfDb;
+    anchor: paths.RepoAnchor;
+    dataDir: string;
+}
+export declare function openTrace(options: Record<string, string>): TraceHandle;

package/dist/cli/commands/trace.js

@@ -0,0 +1,10 @@
+/** Shared by sessions/phases/events/abort — resolve the workspace and open its trace db. */
+import * as agents from "../../core/agents.js";
+import * as paths from "../../core/paths.js";
+import { SfDb } from "../../ui/server/db.js";
+export function openTrace(options) {
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    const cfg = agents.loadConfig(paths.resolveConfigPaths(anchor, options["config"]).paths);
+    const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
+    return { db: new SfDb(dataPaths.db_path), anchor, dataDir: dataPaths.data_dir };
+}

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

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

package/dist/cli/commands/ui.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+import * as agents from "../../core/agents.js";
+import * as paths from "../../core/paths.js";
+import { parseCli } from "../../core/utils.js";
+import { runUi } from "../../ui/server/serve.js";
+export async function uiCommand(argv) {
+    const { options, flags } = parseCli(argv, ["cwd", "config", "db", "port"], ["no-open"]);
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    let dbPath;
+    if (options["db"]) {
+        dbPath = path.resolve(anchor.cwd, options["db"]);
+    }
+    else {
+        const cfg = agents.loadConfig(paths.resolveConfigPaths(anchor, options["config"]).paths);
+        dbPath = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db).db_path;
+    }
+    try {
+        const handle = await runUi({
+            dbPath,
+            webDir: paths.WEB_DIR,
+            port: options["port"] ? Number.parseInt(options["port"], 10) : undefined,
+            open: !flags["no-open"],
+        });
+        console.log(`[spf] ui        ${handle.url}`);
+        console.log(`[spf] db        ${dbPath}`);
+        // runUi() already registers SIGINT/SIGTERM handlers that exit the
+        // process; just keep this call from returning until then.
+        await new Promise(() => { });
+        return 0;
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+}

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

@@ -0,0 +1 @@
+export declare function versionCommand(): number;

package/dist/cli/commands/version.js

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { PACKAGE_ROOT } from "../../core/paths.js";
+export function versionCommand() {
+    const pkg = JSON.parse(readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf-8"));
+    console.log(`${pkg.name} ${pkg.version}`);
+    return 0;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * `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 declare function watchInitCommand(argv: string[]): Promise<number>;
+export declare function watchCommand(argv: string[]): Promise<number>;