stoa-mcp 0.1.0

package/dist/cli.js

@@ -0,0 +1,1135 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { readFile, writeFile, mkdir, access } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, readFileSync, constants } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { refinePipeline } from "./core/refine.js";
+import { computeSpecScore } from "./core/spec-score.js";
+import { initProject, loadConfig } from "./storage/project.js";
+import { listGuardrails, addGuardrail, showGuardrail, removeGuardrail, } from "./guardrails/loader.js";
+import { refinePipeline as refineGuardrail } from "./guardrails/refine.js";
+import { refinePipeline as refineRole } from "./storage/roles-refine.js";
+import { toSlug, resolveSlug } from "./utils/slug.js";
+import { readMoodboard, writeSpecFiles, writeRefineMeta, listSpecs, showSpec } from "./storage/index.js";
+import { listRoles, addRole, showRole, removeRole, loadRole, } from "./storage/roles.js";
+import { listScenarios, showScenarios, addScenario, removeScenario, } from "./storage/scenarios.js";
+import { generateScenarios } from "./storage/scenarios-refine.js";
+import { resolveSpecName, snapshotSpecFiles } from "./utils/spec-helpers.js";
+import { runReviewLoop } from "./cli/review-loop.js";
+import { composePrompt, runBuild, parseSubtasks, promptSubtaskChoice } from "./cli/build.js";
+import { runVerify } from "./cli/verify.js";
+import { detectChanges } from "./storage/change-detection.js";
+import { promptAndRerun } from "./tools/rerefine.js";
+import { scanProject } from "./storage/project-scan.js";
+import { syncMoodboard } from "./storage/moodboard-sync.js";
+import { describeMoodboard } from "./storage/moodboard-describe.js";
+import { runSpecScenarios } from "./cli/scenarios-runner.js";
+import { spawn } from "node:child_process";
+// ── Constants ─────────────────────────────────────────────────────────
+const STAGE_NAMES = ["clarify", "structure", "score", "harden", "finalize"];
+const STAGE_NAME_TO_NUMBER = {
+    clarify: 1,
+    structure: 2,
+    score: 3,
+    harden: 4,
+    finalize: 5,
+};
+const STAGE_DISPLAY_NAMES = {
+    1: "Problem Statement",
+    2: "Acceptance Criteria",
+    3: "Constraints",
+    4: "Decomposition",
+    5: "Evaluation Design",
+};
+const GLOBAL_CONFIG_DIR = join(homedir(), ".stoa");
+const GLOBAL_CONFIG_PATH = join(GLOBAL_CONFIG_DIR, "config.json");
+// ── Helpers ───────────────────────────────────────────────────────────
+function writeln(text = "") {
+    process.stdout.write(text + "\n");
+}
+function colorScore(score) {
+    if (score >= 4)
+        return chalk.green(`${score}`);
+    if (score >= 3)
+        return chalk.yellow(`${score}`);
+    return chalk.red(`${score}`);
+}
+function printScoreBadge(score) {
+    const label = `  Spec Score: ${colorScore(score)} / 5  `;
+    const rawLabel = `  Spec Score: ${score} / 5  `;
+    const width = rawLabel.length;
+    const top = "┌" + "─".repeat(width) + "┐";
+    const bottom = "└" + "─".repeat(width) + "┘";
+    writeln();
+    writeln(top);
+    writeln("│" + label + "│");
+    writeln(bottom);
+}
+function printStageHeader(index, total, stage) {
+    const line = "─".repeat(37);
+    writeln();
+    writeln(line);
+    writeln(chalk.bold(`Stage ${index} / ${total} — ${STAGE_DISPLAY_NAMES[stage] ?? `Stage ${stage}`}`));
+    writeln(line);
+}
+function formatStageOutput(output) {
+    if (output == null)
+        return "(no output)";
+    if (typeof output === "string") {
+        // Detect JSON array strings (e.g. Stage 2 acceptance criteria)
+        const trimmed = output.trim();
+        if (trimmed.startsWith("[")) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
+                    return parsed.map((item, i) => `${i + 1}. ${item}`).join("\n");
+                }
+            }
+            catch {
+                // Not valid JSON — fall through
+            }
+        }
+        return output;
+    }
+    if (Array.isArray(output) && output.every((item) => typeof item === "string")) {
+        return output.map((item, i) => `${i + 1}. ${item}`).join("\n");
+    }
+    return JSON.stringify(output, null, 2);
+}
+async function readConfig() {
+    try {
+        const raw = await readFile(GLOBAL_CONFIG_PATH, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+async function writeConfig(config) {
+    if (!existsSync(GLOBAL_CONFIG_DIR)) {
+        await mkdir(GLOBAL_CONFIG_DIR, { recursive: true });
+    }
+    await writeFile(GLOBAL_CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+function maskApiKey(value) {
+    if (value.length <= 4)
+        return value;
+    return value.slice(0, 3) + "..." + value.slice(-4);
+}
+function copyToClipboard(text) {
+    try {
+        const child = spawn("pbcopy", { stdio: ["pipe", "ignore", "ignore"] });
+        child.stdin.write(text);
+        child.stdin.end();
+    }
+    catch {
+        // Clipboard unavailable — skip silently
+    }
+}
+async function printPostRefineOutput(slug, specScore) {
+    const specsDir = join(process.cwd(), ".stoa", "specs");
+    const descPath = join(specsDir, slug, "01-problem-statement.md");
+    const scenariosPath = join(specsDir, slug, "05-evaluation-design.md");
+    // Copy Stage 1 to clipboard
+    let copiedToClipboard = false;
+    try {
+        const descContent = await readFile(descPath, "utf-8");
+        copyToClipboard(descContent);
+        copiedToClipboard = true;
+    }
+    catch {
+        // description file missing — skip
+    }
+    // Check if scenarios exist
+    let hasScenarios = false;
+    try {
+        const scenariosContent = await readFile(scenariosPath, "utf-8");
+        hasScenarios = scenariosContent.trim().length > 0;
+    }
+    catch {
+        // no scenarios file
+    }
+    writeln();
+    writeln(chalk.cyan(`Spec saved to .stoa/specs/${slug}/`));
+    printScoreBadge(specScore);
+    if (copiedToClipboard) {
+        writeln();
+        writeln(chalk.green("→ Stage 1 description copied to clipboard"));
+        writeln(chalk.dim("  Paste into Lovable, Bolt, v0, or any AI tool"));
+    }
+    writeln();
+    writeln(chalk.green("→ Build prompt for Claude Code:"));
+    writeln(chalk.dim(`  Read the spec in .stoa/specs/${slug}/ and build it. Follow all constraints and subtasks.`));
+    if (hasScenarios) {
+        writeln();
+        writeln(chalk.green(`→ Scenarios saved. Run: ${chalk.white(`stoa scenarios run ${slug}`)}`));
+    }
+}
+function resolveStages(stagesArg) {
+    const names = stagesArg.split(",").map((s) => s.trim());
+    return names.map((name) => {
+        const num = STAGE_NAME_TO_NUMBER[name];
+        if (!num) {
+            const valid = STAGE_NAMES.join(", ");
+            process.stderr.write(chalk.red(`Unknown stage: "${name}". Valid stages: ${valid}`) + "\n");
+            process.exit(1);
+        }
+        return num;
+    });
+}
+// ── Read version from package.json ────────────────────────────────────
+const __pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+const pkg = JSON.parse(readFileSync(__pkgPath, "utf-8"));
+// ── Program ───────────────────────────────────────────────────────────
+const program = new Command();
+program
+    .name("stoa")
+    .description("Stoa — spec refinement CLI")
+    .version(pkg.version);
+// ── stoa refine ───────────────────────────────────────────────────────
+program
+    .command("refine")
+    .description("Run the spec refinement pipeline on a task description")
+    .argument("<description>", "Task description to refine")
+    .option("--stages <stages>", "Comma-separated stage names to run (e.g. clarify,structure)")
+    .option("--role <role>", "Role context for the pipeline (e.g. 'Backend Dev')")
+    .option("--mode <mode>", "Execution mode (clipboard|api|claude-code)")
+    .action(async (description, opts) => {
+    const validModes = ["clipboard", "api", "claude-code"];
+    if (opts.mode && !validModes.includes(opts.mode)) {
+        process.stderr.write(chalk.red(`Invalid mode: "${opts.mode}". Valid modes: ${validModes.join(", ")}`) + "\n");
+        process.exit(1);
+    }
+    const stageNumbers = opts.stages ? resolveStages(opts.stages) : undefined;
+    const totalStages = stageNumbers ? stageNumbers.length : 5;
+    let stageIndex = 0;
+    // Load guardrails
+    const guardrailItems = listGuardrails();
+    const guardrails = guardrailItems.map((g) => g.title);
+    // Resolve role
+    let roleName = opts.role;
+    if (!roleName) {
+        try {
+            const config = await loadConfig();
+            roleName = config.defaultRole;
+        }
+        catch (err) {
+            if (err instanceof SyntaxError) {
+                process.stderr.write(chalk.red("Error: .stoa/config.json contains invalid JSON — fix or delete the file.") + "\n");
+                process.exit(1);
+            }
+            // File not found — roleName stays undefined
+        }
+    }
+    let roleContent;
+    if (roleName) {
+        try {
+            roleContent = loadRole(toSlug(roleName));
+        }
+        catch {
+            const rolePath = `.stoa/roles/${toSlug(roleName)}.md`;
+            process.stderr.write(chalk.red(`Error: Role file not found: ${rolePath}`) + "\n");
+            process.exit(1);
+        }
+    }
+    // Build prompt options
+    const promptOptions = {
+        ...(guardrails.length > 0 ? { guardrails } : {}),
+        ...(roleContent ? { role: roleContent } : {}),
+    };
+    const hasPromptOptions = guardrails.length > 0 || roleContent;
+    // Sync moodboard tokens before loading (ensures tokens.json is up to date)
+    try {
+        syncMoodboard(process.cwd());
+    }
+    catch {
+        // Non-critical — notes.md may not exist
+    }
+    // Load moodboard design context (optional — continue without it on error)
+    let moodboard;
+    try {
+        const result = await readMoodboard(process.cwd());
+        if (result) {
+            moodboard = result;
+        }
+    }
+    catch {
+        // Non-critical — proceed without design context
+    }
+    // Scan project for context (optional — continue without it on error)
+    let projectCtx;
+    try {
+        projectCtx = scanProject(process.cwd());
+    }
+    catch {
+        // Non-critical — proceed without project context
+    }
+    const executionMode = opts.mode;
+    // In clipboard mode, skip spinner
+    if (executionMode === "clipboard") {
+        const stagesToRun = stageNumbers ?? [1, 2, 3, 4, 5];
+        try {
+            const result = await refinePipeline({
+                title: description,
+                description,
+                role: opts.role,
+                guardrails,
+                moodboard,
+                projectCtx,
+                promptOptions: hasPromptOptions ? promptOptions : undefined,
+            }, {
+                executionMode: "clipboard",
+                stages: stageNumbers,
+                onStageComplete: (stage, stageResult) => {
+                    stageIndex++;
+                    printStageHeader(stageIndex, totalStages, stage);
+                    writeln(formatStageOutput(stageResult.output || stageResult.rawResponse));
+                },
+            });
+            // Write spec files
+            const specsDir = join(process.cwd(), ".stoa", "specs");
+            const slug = await resolveSlug(specsDir, toSlug(description));
+            const stagesRun = {};
+            for (const sr of result.stages) {
+                stagesRun[sr.stage] = sr.rawResponse;
+            }
+            await writeSpecFiles(specsDir, slug, stagesRun);
+            await writeRefineMeta(specsDir, slug, result.stages.map((s) => s.stage), result.executionMode, pkg.version);
+            await printPostRefineOutput(slug, result.finalSpecScore);
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+            process.exit(1);
+        }
+        return;
+    }
+    const spinner = ora({ text: "", color: "cyan" });
+    const stagesToRun = stageNumbers ?? [1, 2, 3, 4, 5];
+    spinner.start(`Running stage: ${STAGE_DISPLAY_NAMES[stagesToRun[0]]}...`);
+    try {
+        const result = await refinePipeline({
+            title: description,
+            description,
+            role: opts.role,
+            guardrails,
+            moodboard,
+            projectCtx,
+            promptOptions: hasPromptOptions ? promptOptions : undefined,
+        }, {
+            ...(executionMode ? { executionMode } : {}),
+            stages: stageNumbers,
+            onStageComplete: (stage, stageResult) => {
+                spinner.stop();
+                stageIndex++;
+                printStageHeader(stageIndex, totalStages, stage);
+                writeln(formatStageOutput(stageResult.output || stageResult.rawResponse));
+                // Start spinner for next stage if there are more
+                if (stageIndex < totalStages) {
+                    const nextStage = stagesToRun[stageIndex];
+                    spinner.start(`Running stage: ${STAGE_DISPLAY_NAMES[nextStage]}...`);
+                }
+            },
+        });
+        // Write spec files
+        const specsDir = join(process.cwd(), ".stoa", "specs");
+        const slug = await resolveSlug(specsDir, toSlug(description));
+        const stagesRun = {};
+        for (const sr of result.stages) {
+            stagesRun[sr.stage] = sr.rawResponse;
+        }
+        await writeSpecFiles(specsDir, slug, stagesRun);
+        await writeRefineMeta(specsDir, slug, result.stages.map((s) => s.stage), result.executionMode, pkg.version);
+        await printPostRefineOutput(slug, result.finalSpecScore);
+    }
+    catch (err) {
+        spinner.fail(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// ── stoa score ────────────────────────────────────────────────────────
+program
+    .command("score")
+    .description("Score a task description without running the full pipeline")
+    .argument("<description>", "Task description to score")
+    .action((description) => {
+    const result = computeSpecScore({
+        hasDescription: description.length > 0,
+        descriptionLength: description.length,
+        wasRefined: false,
+        hasAcceptanceCriteria: false,
+        hasGuardrails: false,
+        hasRole: false,
+        hasScenarios: false,
+        hasSubtasks: false,
+    });
+    writeln(`Level: ${chalk.bold(result.level)}`);
+    printScoreBadge(result.score);
+    if (result.missing.length > 0) {
+        writeln();
+        writeln(chalk.dim("Missing:"));
+        for (const item of result.missing) {
+            writeln(chalk.dim(`  - ${item}`));
+        }
+    }
+});
+// ── stoa specs ────────────────────────────────────────────────────────
+const specsCmd = program
+    .command("specs")
+    .description("Manage saved specs (.stoa/specs/)");
+specsCmd
+    .command("list")
+    .description("List all saved specs with date")
+    .action(async () => {
+    const specsDir = join(process.cwd(), ".stoa", "specs");
+    const specs = await listSpecs(specsDir);
+    if (specs.length === 0) {
+        writeln(chalk.dim("No specs found. Run stoa refine <task> first."));
+        return;
+    }
+    for (const spec of specs) {
+        const dateStr = spec.date.toISOString().slice(0, 10);
+        writeln(`${chalk.white(spec.name)}  ${chalk.dim(dateStr)}  ${chalk.dim(`${spec.stages} stage(s)`)}`);
+    }
+});
+specsCmd
+    .command("show")
+    .description("Show a saved spec's content")
+    .argument("<name>", "Spec name (slug)")
+    .action(async (name) => {
+    const specsDir = join(process.cwd(), ".stoa", "specs");
+    try {
+        const content = await showSpec(specsDir, name);
+        process.stdout.write(content);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+// ── stoa config ───────────────────────────────────────────────────────
+const configCmd = program
+    .command("config")
+    .description("Manage global Stoa configuration (~/.stoa/config.json)");
+configCmd
+    .command("set")
+    .description("Set a configuration value")
+    .argument("<key>", "Configuration key")
+    .argument("<value>", "Configuration value")
+    .action(async (key, value) => {
+    const config = await readConfig();
+    config[key] = value;
+    await writeConfig(config);
+    writeln(chalk.green(`Set ${key}`));
+});
+configCmd
+    .command("get")
+    .description("Get a configuration value")
+    .argument("<key>", "Configuration key")
+    .action(async (key) => {
+    const config = await readConfig();
+    const value = config[key];
+    if (value === undefined) {
+        writeln(chalk.dim(`(not set)`));
+        return;
+    }
+    if (key.toLowerCase().endsWith("api_key")) {
+        writeln(maskApiKey(value));
+    }
+    else {
+        writeln(value);
+    }
+});
+// ── stoa edit ─────────────────────────────────────────────────────────
+const EDITABLE_FILES = {
+    moodboard: ".stoa/moodboard/notes.md",
+    context: ".stoa/context.md",
+    lessons: ".stoa/lessons.md",
+};
+program
+    .command("edit")
+    .description("Open a .stoa/ file in your editor")
+    .argument("<file>", `File to edit (${Object.keys(EDITABLE_FILES).join(", ")})`)
+    .action((file) => {
+    const relativePath = EDITABLE_FILES[file];
+    if (!relativePath) {
+        process.stderr.write(chalk.red(`Unknown file: "${file}". Valid: ${Object.keys(EDITABLE_FILES).join(", ")}`) + "\n");
+        process.exit(1);
+    }
+    const fullPath = join(process.cwd(), relativePath);
+    if (!existsSync(fullPath)) {
+        process.stderr.write(chalk.red(`File not found: ${relativePath}. Run 'stoa init' first.`) + "\n");
+        process.exit(1);
+    }
+    const editor = process.env.EDITOR || "nano";
+    const child = spawn(editor, [fullPath], { stdio: "inherit" });
+    child.on("exit", (code) => {
+        process.exit(code ?? 0);
+    });
+});
+// ── stoa init ─────────────────────────────────────────────────────────
+program
+    .command("init")
+    .description("Initialize a .stoa/ directory in the current working directory")
+    .option("--name <name>", "Project name (defaults to current directory name)")
+    .option("--type <type>", "Project type", "generic")
+    .option("--no-templates", "Skip copying starter templates")
+    .action(async (opts) => {
+    const name = opts.name ?? basename(process.cwd());
+    const created = await initProject(name, opts.type, !opts.templates);
+    if (!created) {
+        process.exit(1);
+    }
+    writeln(chalk.green("Created .stoa/ with:"));
+    if (opts.templates) {
+        writeln(chalk.green("  5 guardrails"));
+        writeln(chalk.green("  3 roles (Builder, Fixer, Planner)"));
+    }
+    writeln(chalk.green("  moodboard/notes.md — design direction"));
+    writeln(chalk.green("  context.md — brand voice, dependencies, conventions"));
+    writeln(chalk.green("  lessons.md — project memory (grows automatically)"));
+    writeln();
+    writeln("Edit moodboard/notes.md and context.md, then run 'stoa refine \"your idea\"'");
+});
+// ── stoa guardrails ──────────────────────────────────────────────────
+const guardrailsCmd = program
+    .command("guardrails")
+    .description("Manage project guardrails (.stoa/guardrails/)");
+guardrailsCmd
+    .command("list")
+    .description("List all guardrails")
+    .action(() => {
+    const items = listGuardrails();
+    if (items.length === 0) {
+        writeln(chalk.dim("No guardrails found."));
+        return;
+    }
+    for (const item of items) {
+        writeln(`${item.slug}: ${item.title}`);
+    }
+});
+guardrailsCmd
+    .command("add")
+    .description("Add a new guardrail")
+    .argument("<title>", "Guardrail title")
+    .action((title) => {
+    try {
+        addGuardrail(title);
+        writeln(chalk.green(`Added: ${toSlug(title)}`));
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+guardrailsCmd
+    .command("show")
+    .description("Show a guardrail's content")
+    .argument("<slug>", "Guardrail slug")
+    .action((slug) => {
+    try {
+        const content = showGuardrail(slug);
+        process.stdout.write(content);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+guardrailsCmd
+    .command("remove")
+    .description("Remove a guardrail")
+    .argument("<slug>", "Guardrail slug")
+    .action(async (slug) => {
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`Remove ${slug}? (y/N) `, (answer) => {
+        rl.close();
+        if (answer.toLowerCase() !== "y") {
+            return;
+        }
+        try {
+            removeGuardrail(slug);
+            writeln(chalk.green(`Removed: ${slug}`));
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+            process.exit(1);
+        }
+    });
+});
+guardrailsCmd
+    .command("refine")
+    .description("Refine a guardrail through a 3-stage pipeline (clarify → verify → examples)")
+    .argument("<name>", "Guardrail slug name")
+    .option("--mode <mode>", "Execution mode (clipboard|api|claude-code)", "clipboard")
+    .action(async (name, opts) => {
+    const validModes = ["clipboard", "api", "claude-code"];
+    if (!validModes.includes(opts.mode)) {
+        process.stderr.write(chalk.red(`Invalid mode: "${opts.mode}". Valid modes: ${validModes.join(", ")}`) + "\n");
+        process.exit(1);
+    }
+    const mode = opts.mode;
+    if (mode === "clipboard") {
+        try {
+            const result = await refineGuardrail({
+                name,
+                mode,
+                onStageComplete: (i, label, output) => {
+                    const line = "─".repeat(40);
+                    writeln(`\n${line}`);
+                    writeln(chalk.bold(label));
+                    writeln(line);
+                    writeln(output);
+                },
+            });
+            // result.prompts are printed via onStageComplete
+            void result;
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+            process.exit(1);
+        }
+        return;
+    }
+    // api or claude-code mode
+    const spinner = ora({ text: "", color: "cyan" });
+    spinner.start("Stage 1: Clarify & Tighten...");
+    try {
+        await refineGuardrail({
+            name,
+            mode,
+            onStageComplete: (i, label) => {
+                spinner.succeed(label);
+                if (i < 2) {
+                    const nextLabels = [
+                        "Stage 2: Add Verification...",
+                        "Stage 3: Add Examples...",
+                    ];
+                    spinner.start(nextLabels[i]);
+                }
+            },
+        });
+        writeln(chalk.green(`\nUpdated: .stoa/guardrails/${name}.md`));
+    }
+    catch (err) {
+        spinner.fail(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// ── stoa export ───────────────────────────────────────────────────────
+program
+    .command("export")
+    .description("Export configuration in a specific format")
+    .argument("<format>", "Export format (e.g. claude-md)")
+    .action(async (format) => {
+    if (format !== "claude-md") {
+        process.stderr.write(chalk.red(`Unknown export format: "${format}". Supported: claude-md`) + "\n");
+        process.exit(1);
+    }
+    // Try local config first, then global
+    let config = {};
+    const localPath = join(process.cwd(), ".stoa", "config.json");
+    try {
+        const raw = await readFile(localPath, "utf-8");
+        config = JSON.parse(raw);
+    }
+    catch {
+        try {
+            const raw = await readFile(GLOBAL_CONFIG_PATH, "utf-8");
+            config = JSON.parse(raw);
+        }
+        catch {
+            // empty config
+        }
+    }
+    const lines = [
+        "# Stoa Configuration",
+        "",
+    ];
+    if (config.stages) {
+        lines.push("## Pipeline Stages");
+        lines.push("");
+        const stages = config.stages;
+        for (const stage of stages) {
+            lines.push(`- ${stage}`);
+        }
+        lines.push("");
+    }
+    // Include any other config keys
+    for (const [key, value] of Object.entries(config)) {
+        if (key === "stages")
+            continue;
+        if (typeof key === "string" && key.toLowerCase().endsWith("api_key"))
+            continue;
+        lines.push(`## ${key}`);
+        lines.push("");
+        lines.push(typeof value === "string" ? value : JSON.stringify(value, null, 2));
+        lines.push("");
+    }
+    // Read guardrails if present
+    const guardrailsDir = join(process.cwd(), ".stoa", "guardrails");
+    if (existsSync(guardrailsDir)) {
+        const { readdir } = await import("node:fs/promises");
+        const files = await readdir(guardrailsDir);
+        const mdFiles = files.filter((f) => f.endsWith(".md")).sort();
+        if (mdFiles.length > 0) {
+            lines.push("## Guardrails");
+            lines.push("");
+            for (const file of mdFiles) {
+                const content = await readFile(join(guardrailsDir, file), "utf-8");
+                lines.push(content);
+                lines.push("");
+            }
+        }
+    }
+    process.stdout.write(lines.join("\n"));
+});
+// ── stoa roles ───────────────────────────────────────────────────────
+const rolesCmd = program
+    .command("roles")
+    .description("Manage project roles (.stoa/roles/)");
+rolesCmd
+    .command("list")
+    .description("List all roles")
+    .action(() => {
+    const slugs = listRoles();
+    for (const slug of slugs) {
+        writeln(slug);
+    }
+});
+rolesCmd
+    .command("add")
+    .description("Add a new role")
+    .argument("<displayName>", "Role display name")
+    .action((displayName) => {
+    try {
+        addRole(displayName);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+rolesCmd
+    .command("show")
+    .description("Show a role's content")
+    .argument("<slug>", "Role slug")
+    .action((slug) => {
+    try {
+        const content = showRole(slug);
+        process.stdout.write(content);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+rolesCmd
+    .command("remove")
+    .description("Remove a role")
+    .argument("<slug>", "Role slug")
+    .action((slug) => {
+    try {
+        removeRole(slug);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+rolesCmd
+    .command("refine")
+    .description("Refine a role through a 3-stage pipeline (sharpen → boundaries → guardrails)")
+    .argument("<name>", "Role slug name")
+    .option("--mode <mode>", "Execution mode (clipboard|api|claude-code)", "clipboard")
+    .action(async (name, opts) => {
+    const validModes = ["clipboard", "api", "claude-code"];
+    if (!validModes.includes(opts.mode)) {
+        process.stderr.write(chalk.red(`Invalid mode: "${opts.mode}". Valid modes: ${validModes.join(", ")}`) + "\n");
+        process.exit(1);
+    }
+    const mode = opts.mode;
+    if (mode === "clipboard") {
+        try {
+            const result = await refineRole({
+                name,
+                mode,
+                onStageComplete: (i, label, output) => {
+                    const line = "─".repeat(40);
+                    writeln(`\n${line}`);
+                    writeln(chalk.bold(label));
+                    writeln(line);
+                    writeln(output);
+                },
+            });
+            void result;
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+            process.exit(1);
+        }
+        return;
+    }
+    // api or claude-code mode
+    const spinner = ora({ text: "", color: "cyan" });
+    spinner.start("Stage 1: Sharpen Identity...");
+    try {
+        const result = await refineRole({
+            name,
+            mode,
+            onStageComplete: (i, label, output) => {
+                spinner.succeed(label);
+                if (i === 0) {
+                    spinner.start("Stage 2: Define Boundaries...");
+                }
+                else if (i === 1) {
+                    writeln(chalk.green(`\nUpdated: .stoa/roles/${name}.md`));
+                    spinner.start("Stage 3: Suggest Guardrails...");
+                }
+                else if (i === 2) {
+                    // Stage 3: print guardrail suggestions to terminal only
+                    const line = "─".repeat(40);
+                    writeln(`\n${line}`);
+                    writeln(chalk.bold("Suggested Guardrails (review & create manually):"));
+                    writeln(line);
+                    writeln(output);
+                }
+            },
+        });
+        void result;
+    }
+    catch (err) {
+        spinner.fail(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// ── stoa scenarios ───────────────────────────────────────────────────
+const scenariosCmd = program
+    .command("scenarios")
+    .description("Manage project scenarios (.stoa/scenarios/)");
+scenariosCmd
+    .command("list")
+    .description("List all scenarios for a task")
+    .argument("<name>", "Scenario set name")
+    .action((name) => {
+    const scenarios = listScenarios(name);
+    for (let i = 0; i < scenarios.length; i++) {
+        writeln(`[${i}] title: ${scenarios[i].title}`);
+    }
+});
+scenariosCmd
+    .command("show")
+    .description("Show scenarios with details")
+    .argument("<name>", "Scenario set name")
+    .action((name) => {
+    try {
+        const scenarios = showScenarios(name);
+        for (let i = 0; i < scenarios.length; i++) {
+            writeln(`[${i}] GIVEN: ${scenarios[i].given}`);
+            writeln(`    EXPECTED: ${scenarios[i].expected}`);
+        }
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+scenariosCmd
+    .command("add")
+    .description("Add a scenario")
+    .argument("<name>", "Scenario set name")
+    .requiredOption("--title <string>", "Scenario title")
+    .requiredOption("--given <string>", "Given condition")
+    .requiredOption("--expected <string>", "Expected outcome")
+    .action((name, opts) => {
+    addScenario(name, { title: opts.title, given: opts.given, expected: opts.expected });
+});
+scenariosCmd
+    .command("remove")
+    .description("Remove a scenario by index")
+    .argument("<name>", "Scenario set name")
+    .requiredOption("--index <number>", "Index to remove", parseInt)
+    .action((name, opts) => {
+    try {
+        removeScenario(name, opts.index);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+scenariosCmd
+    .command("run")
+    .description("Interactively walk through scenarios for a spec")
+    .argument("[specName]", "Spec name (defaults to most recent)")
+    .action(async (specNameArg) => {
+    try {
+        await runSpecScenarios(specNameArg);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+scenariosCmd
+    .command("generate")
+    .description("Generate structured scenarios from a task spec (.stoa/specs/<taskName>.json)")
+    .argument("<taskName>", "Task name (matches spec filename)")
+    .option("--mode <mode>", "Execution mode (api|clipboard|cli)", "clipboard")
+    .action(async (taskName, opts) => {
+    const validModes = ["api", "clipboard", "cli"];
+    if (!validModes.includes(opts.mode)) {
+        process.stderr.write(chalk.red(`Invalid mode: "${opts.mode}". Valid modes: ${validModes.join(", ")}`) + "\n");
+        process.exit(1);
+    }
+    await generateScenarios(taskName, opts.mode);
+});
+// ── stoa moodboard ──────────────────────────────────────────────────
+const moodboardCmd = program
+    .command("moodboard")
+    .description("Manage project moodboard (.stoa/moodboard/)");
+moodboardCmd
+    .command("sync")
+    .description("Parse notes.md and generate tokens.json")
+    .action(() => {
+    try {
+        const tokens = syncMoodboard(process.cwd());
+        writeln(chalk.green("Generated .stoa/moodboard/tokens.json"));
+        writeln();
+        const entries = Object.entries(tokens);
+        if (entries.length === 0) {
+            writeln(chalk.dim("No values found. Add content to .stoa/moodboard/notes.md first."));
+        }
+        else {
+            writeln("Extracted:");
+            for (const [key, value] of entries) {
+                if (typeof value === "string") {
+                    writeln(`  ${key}: ${value}`);
+                }
+                else if (value && typeof value === "object") {
+                    const count = Object.keys(value).length;
+                    writeln(`  ${key}: ${count} value(s)`);
+                }
+            }
+        }
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+moodboardCmd
+    .command("describe")
+    .description("AI-extract design system from screenshots in moodboard/")
+    .option("--mode <mode>", "Execution mode (api|claude-code|clipboard)")
+    .option("--overwrite", "Overwrite notes.md without prompting")
+    .action(async (opts) => {
+    const validModes = ["api", "claude-code", "clipboard"];
+    if (opts.mode && !validModes.includes(opts.mode)) {
+        process.stderr.write(chalk.red(`Invalid mode: "${opts.mode}". Valid: ${validModes.join(", ")}`) + "\n");
+        process.exit(1);
+    }
+    // Auto-detect mode if not specified
+    let mode;
+    if (opts.mode) {
+        mode = opts.mode;
+    }
+    else if (process.env.ANTHROPIC_API_KEY) {
+        mode = "api";
+    }
+    else {
+        mode = "clipboard";
+    }
+    const spinner = mode === "api" ? ora({ text: "Analyzing screenshots...", color: "cyan" }) : null;
+    try {
+        if (spinner)
+            spinner.start();
+        const result = await describeMoodboard(process.cwd(), {
+            mode,
+            overwrite: opts.overwrite,
+            apiKey: process.env.ANTHROPIC_API_KEY,
+            onConfirm: async () => {
+                if (spinner)
+                    spinner.stop();
+                const { createInterface } = await import("node:readline");
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                return new Promise((resolve) => {
+                    rl.question("notes.md has content. Overwrite? [y/N] ", (answer) => {
+                        rl.close();
+                        const yes = answer.trim().toLowerCase() === "y";
+                        if (yes && spinner)
+                            spinner.start();
+                        resolve(yes);
+                    });
+                });
+            },
+        });
+        if (spinner)
+            spinner.stop();
+        if (result.written) {
+            writeln(chalk.green(`Extracted design system from ${result.imageCount} image(s).`));
+            writeln(chalk.green("Updated notes.md and tokens.json."));
+        }
+        else {
+            writeln(result.output);
+        }
+    }
+    catch (err) {
+        if (spinner)
+            spinner.fail();
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+// ── stoa review ──────────────────────────────────────────────────────
+program
+    .command("review")
+    .description("Review a refined spec interactively, then optionally re-run affected stages")
+    .argument("[specName]", "Spec name (defaults to most recent)")
+    .action(async (specNameArg) => {
+    let specName;
+    try {
+        specName = await resolveSpecName(specNameArg);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+    const specDir = join(process.cwd(), ".stoa", "specs", specName);
+    // 1. Capture snapshot
+    const snapshot = await snapshotSpecFiles(specDir);
+    // 2. Run interactive review loop
+    await runReviewLoop(specDir);
+    // 3. Detect changes made during review
+    const affectedStages = await detectChanges(specDir, snapshot);
+    // 4. Prompt user about re-running affected stages
+    const success = await promptAndRerun(affectedStages, specDir);
+    if (success) {
+        // 5. Write .approved marker
+        const approvedPath = join(specDir, ".approved");
+        await writeFile(approvedPath, new Date().toISOString(), "utf-8");
+        writeln(chalk.green(`Approved: ${specName}`));
+    }
+    else {
+        process.stderr.write(chalk.red(`Review failed for spec "${specName}". Spec was not approved.`) + "\n");
+        process.exit(1);
+    }
+});
+// ── stoa build ───────────────────────────────────────────────────────
+program
+    .command("build")
+    .description("Launch a build from an approved spec")
+    .argument("[specName]", "Spec name to build (defaults to most recent approved spec)")
+    .option("--fix <number>", "Apply a fix spec before building (reads .stoa/specs/<name>/fixes/fix-<NNN>.md)")
+    .action(async (specNameArg, opts) => {
+    let specName;
+    try {
+        specName = await resolveSpecName(specNameArg);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+    const approvedPath = join(process.cwd(), ".stoa", "specs", specName, ".approved");
+    try {
+        await access(approvedPath, constants.F_OK);
+    }
+    catch {
+        process.stderr.write(chalk.red(`Error: Spec "${specName}" has not been reviewed. Run \`stoa review ${specName}\` first.`) + "\n");
+        process.exit(1);
+    }
+    // Handle --fix N: read the fix file and use it as the prompt
+    let fixPrompt;
+    if (opts.fix) {
+        const fixNum = parseInt(opts.fix, 10);
+        const padded = String(fixNum).padStart(3, "0");
+        const fixPath = join(process.cwd(), ".stoa", "specs", specName, "fixes", `fix-${padded}.md`);
+        if (!existsSync(fixPath)) {
+            process.stderr.write(chalk.red(`Error: Fix file not found: .stoa/specs/${specName}/fixes/fix-${padded}.md`) + "\n");
+            process.exit(1);
+        }
+        fixPrompt = readFileSync(fixPath, "utf-8");
+        writeln(chalk.cyan(`Applying fix ${fixNum} for spec: ${chalk.white(specName)}`));
+    }
+    const config = await loadConfig();
+    const role = config.defaultRole ?? "builder";
+    writeln(chalk.cyan(`Building from spec: ${chalk.white(specName)}`));
+    writeln(chalk.dim(`Role: ${role}`));
+    const basePrompt = composePrompt(specName, { role });
+    // If --fix, append fix content to the prompt
+    const prompt = fixPrompt
+        ? basePrompt + "\n\n# Fix Spec\n" + fixPrompt
+        : basePrompt;
+    // Check for subtasks in the spec
+    const subtasksPath = join(process.cwd(), ".stoa", "specs", specName, "04-decomposition.md");
+    const subtasksContent = existsSync(subtasksPath) ? readFileSync(subtasksPath, "utf-8") : "";
+    const subtasks = parseSubtasks(subtasksContent);
+    try {
+        if (fixPrompt || subtasks.length === 0) {
+            // --fix mode or no subtasks: single build
+            await runBuild(specName, prompt);
+        }
+        else {
+            writeln(chalk.cyan(`\nFound ${subtasks.length} subtask(s):`));
+            for (const st of subtasks) {
+                writeln(chalk.dim(`  ${st.index}. ${st.text.split("\n")[0]}`));
+            }
+            writeln("");
+            const choice = await promptSubtaskChoice(subtasks);
+            if (choice === "q") {
+                process.exit(0);
+            }
+            else if (choice === "all") {
+                for (const st of subtasks) {
+                    writeln(chalk.cyan(`\n── Subtask ${st.index}/${subtasks.length} ──\n`));
+                    await runBuild(specName, prompt + `\n\n# Current Subtask\n${st.text}`);
+                }
+            }
+            else {
+                const num = parseInt(choice, 10);
+                const picked = subtasks.find((s) => s.index === num);
+                if (!picked) {
+                    process.stderr.write(chalk.red(`Invalid choice: "${choice}". Expected all, 1-${subtasks.length}, or q.\n`));
+                    process.exit(1);
+                }
+                writeln(chalk.cyan(`\n── Subtask ${picked.index} ──\n`));
+                await runBuild(specName, prompt + `\n\n# Current Subtask\n${picked.text}`);
+            }
+        }
+        // If --fix mode, run verify automatically after build completes
+        if (fixPrompt) {
+            writeln(chalk.cyan("\nRunning verification..."));
+            await runVerify(specName);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.code === "ENOENT") {
+            process.exit(1);
+        }
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
+// ── stoa verify ─────────────────────────────────────────────────────
+program
+    .command("verify")
+    .description("Interactively verify scenarios for a spec")
+    .argument("[specName]", "Spec name to verify (defaults to most recent spec)")
+    .action(async (specNameArg) => {
+    let specName;
+    try {
+        specName = await resolveSpecName(specNameArg);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+    await runVerify(specName);
+});
+// ── Parse ─────────────────────────────────────────────────────────────
+program.parse();
+//# sourceMappingURL=cli.js.map