ai-spec-dev 0.30.1 → 0.33.0

package/cli/commands/workspace.ts

@@ -0,0 +1,219 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { input, select, confirm } from "@inquirer/prompts";
+import {
+  WorkspaceLoader,
+  WorkspaceConfig,
+  RepoConfig,
+  WORKSPACE_CONFIG_FILE,
+  detectRepoType,
+} from "../../core/workspace-loader";
+
+export function registerWorkspace(program: Command): void {
+  const workspaceCmd = program
+    .command("workspace")
+    .description("Manage multi-repo workspace configuration");
+
+  // ── workspace init ──────────────────────────────────────────────────────────
+  workspaceCmd
+    .command("init")
+    .description(`Interactive workspace setup — creates ${WORKSPACE_CONFIG_FILE}`)
+    .action(async () => {
+      const currentDir = process.cwd();
+      const configPath = path.join(currentDir, WORKSPACE_CONFIG_FILE);
+
+      if (await fs.pathExists(configPath)) {
+        const overwrite = await confirm({
+          message: `${WORKSPACE_CONFIG_FILE} already exists. Overwrite?`,
+          default: false,
+        });
+        if (!overwrite) {
+          console.log(chalk.gray("  Cancelled."));
+          return;
+        }
+      }
+
+      console.log(chalk.blue("\n─── Workspace Setup ────────────────────────────"));
+
+      const workspaceName = await input({
+        message: "Workspace name:",
+        validate: (v) => v.trim().length > 0 || "Name cannot be empty",
+      });
+
+      const repos: RepoConfig[] = [];
+
+      const useAutoScan = await confirm({
+        message: "Auto-scan sibling directories for repos?",
+        default: true,
+      });
+
+      if (useAutoScan) {
+        const workspaceLoader = new WorkspaceLoader(currentDir);
+        const detected = await workspaceLoader.autoDetect();
+
+        if (detected.length === 0) {
+          console.log(chalk.yellow("  No recognizable repos found in sibling directories."));
+        } else {
+          console.log(chalk.cyan("\n  Detected repos:"));
+          for (const r of detected) {
+            console.log(chalk.gray(`    - ${r.name}: ${r.role} (${r.type}) at ${r.path}`));
+          }
+
+          const keepAll = await confirm({
+            message: `Include all ${detected.length} detected repo(s)?`,
+            default: true,
+          });
+
+          if (keepAll) {
+            repos.push(...detected);
+          } else {
+            for (const r of detected) {
+              const keep = await confirm({
+                message: `Include "${r.name}" (${r.role}, ${r.type})?`,
+                default: true,
+              });
+              if (keep) repos.push(r);
+            }
+          }
+          console.log(chalk.green(`  ✔ ${repos.length} repo(s) added from auto-scan.`));
+        }
+      }
+
+      const repoTypeChoices = [
+        { name: "node-express (Node.js/Express backend)", value: "node-express" },
+        { name: "node-koa (Node.js/Koa backend)", value: "node-koa" },
+        { name: "go (Go backend)", value: "go" },
+        { name: "python (Python backend)", value: "python" },
+        { name: "java (Java/Spring backend)", value: "java" },
+        { name: "rust (Rust backend)", value: "rust" },
+        { name: "php (PHP/Lumen/Laravel backend)", value: "php" },
+        { name: "react (React frontend)", value: "react" },
+        { name: "next (Next.js)", value: "next" },
+        { name: "vue (Vue frontend)", value: "vue" },
+        { name: "react-native (React Native mobile)", value: "react-native" },
+        { name: "unknown", value: "unknown" },
+      ];
+
+      let addMore = await confirm({
+        message: repos.length > 0 ? "Manually add more repos?" : "Add repos manually?",
+        default: repos.length === 0,
+      });
+
+      while (addMore) {
+        console.log(chalk.cyan(`\n  Adding repo #${repos.length + 1}`));
+
+        const repoName = await input({
+          message: "Repo name (e.g. api, web, app):",
+          validate: (v) => {
+            if (!v.trim()) return "Name cannot be empty";
+            if (repos.some((r) => r.name === v.trim())) return "Name already used";
+            return true;
+          },
+        });
+
+        const repoPath = await input({
+          message: `Relative path to "${repoName}" from here (default: ./${repoName}):`,
+          default: `./${repoName}`,
+        });
+
+        const absPath = path.resolve(currentDir, repoPath);
+        let detectedType = "unknown";
+        let detectedRole = "shared";
+
+        if (await fs.pathExists(absPath)) {
+          const { type, role } = await detectRepoType(absPath);
+          detectedType = type;
+          detectedRole = role;
+          console.log(chalk.gray(`    Auto-detected: type=${type}, role=${role}`));
+        } else {
+          console.log(chalk.yellow(`    Path "${absPath}" not found — type/role will be manual.`));
+        }
+
+        const repoType = await select({
+          message: `Repo type for "${repoName}":`,
+          choices: repoTypeChoices,
+          default: detectedType,
+        });
+
+        const repoRole = await select({
+          message: `Repo role for "${repoName}":`,
+          choices: [
+            { name: "backend", value: "backend" },
+            { name: "frontend", value: "frontend" },
+            { name: "mobile", value: "mobile" },
+            { name: "shared", value: "shared" },
+          ],
+          default: detectedRole,
+        });
+
+        repos.push({
+          name: repoName,
+          path: repoPath,
+          type: repoType as RepoConfig["type"],
+          role: repoRole as RepoConfig["role"],
+        });
+
+        console.log(chalk.green(`  ✔ Added: ${repoName} (${repoRole}, ${repoType})`));
+
+        addMore = await confirm({
+          message: "Add another repo?",
+          default: false,
+        });
+      }
+
+      const workspaceConfig: WorkspaceConfig = { name: workspaceName, repos };
+
+      console.log(chalk.cyan("\n  Workspace summary:"));
+      console.log(chalk.gray(`  Name: ${workspaceName}`));
+      for (const r of repos) {
+        console.log(chalk.gray(`  - ${r.name}: ${r.role} (${r.type}) at ${r.path}`));
+      }
+
+      const ok = await confirm({ message: `Save to ${WORKSPACE_CONFIG_FILE}?`, default: true });
+      if (!ok) {
+        console.log(chalk.gray("  Cancelled."));
+        return;
+      }
+
+      const loader = new WorkspaceLoader(currentDir);
+      const saved = await loader.save(workspaceConfig);
+      console.log(chalk.green(`\n  ✔ Workspace saved: ${saved}`));
+      console.log(chalk.gray(`  Run \`ai-spec create "your feature"\` — workspace mode will activate automatically.`));
+    });
+
+  // ── workspace status ────────────────────────────────────────────────────────
+  workspaceCmd
+    .command("status")
+    .description("Show current workspace configuration")
+    .action(async () => {
+      const currentDir = process.cwd();
+      const loader = new WorkspaceLoader(currentDir);
+      const config = await loader.load();
+
+      if (!config) {
+        console.log(chalk.yellow(`No ${WORKSPACE_CONFIG_FILE} found in ${currentDir}`));
+        console.log(chalk.gray("  Run `ai-spec workspace init` to create one."));
+        return;
+      }
+
+      console.log(chalk.bold(`\nWorkspace: ${config.name}`));
+      console.log(chalk.gray(`  Config: ${path.join(currentDir, WORKSPACE_CONFIG_FILE)}`));
+      console.log(chalk.gray(`  Repos (${config.repos.length}):\n`));
+
+      for (const repo of config.repos) {
+        const absPath = loader.resolveAbsPath(repo);
+        const exists = await fs.pathExists(absPath);
+        const status = exists ? chalk.green("found") : chalk.red("not found");
+
+        console.log(
+          `  ${chalk.bold(repo.name.padEnd(12))} ${repo.role.padEnd(10)} ${repo.type.padEnd(16)} ${status}`
+        );
+        console.log(chalk.gray(`    path: ${absPath}`));
+        if (repo.constitution) {
+          console.log(chalk.green(`    constitution: found`));
+        }
+      }
+    });
+}

package/cli/index.ts

@@ -73,6 +73,17 @@ import { SpecUpdater } from "../core/spec-updater";
 import { exportOpenApi } from "../core/openapi-exporter";
 import { generateRunId, RunLogger, setActiveLogger } from "../core/run-logger";
 import { RunSnapshot, setActiveSnapshot } from "../core/run-snapshot";
+import { computePromptHash } from "../core/prompt-hasher";
+import { runSelfEval, printSelfEval } from "../core/self-evaluator";
+import { loadRunLogs, buildTrendReport, printTrendReport } from "../core/run-trend";
+import {
+  assessDslRichness,
+  buildDslGapRefinementPrompt,
+  extractStructuralFindings,
+  buildStructuralAmendmentPrompt,
+  printDslGaps,
+  printStructuralFindings,
+} from "../core/dsl-feedback";
 
 // ─── Config File ──────────────────────────────────────────────────────────────
 
@@ -305,6 +316,11 @@ program
     });
     setActiveLogger(runLogger);
 
+    // Record prompt hash immediately — links this RunLog to the prompt version
+    // in use, enabling cross-run harnessScore comparisons (Harness Engineering).
+    const promptHash = computePromptHash();
+    runLogger.setPromptHash(promptHash);
+
     // ── Step 1: Context ───────────────────────────────────────────────────────
     console.log(chalk.blue("[1/6] Loading project context..."));
     runLogger.stageStart("context_load");
@@ -517,6 +533,60 @@ program
       }
     }
 
+    // ── Loop 1: DSL Gap Feedback ──────────────────────────────────────────────
+    // Runs only in interactive mode (not --auto / --fast / --skip-dsl).
+    // Checks for common completeness gaps in the freshly-extracted DSL and
+    // offers a targeted spec refinement AI call to fill them before codegen.
+    // Zero extra AI calls unless the user explicitly opts in.
+    if (extractedDsl && !opts.auto && !opts.fast && !opts.skipDsl) {
+      const dslGaps = assessDslRichness(extractedDsl);
+
+      if (dslGaps.length > 0) {
+        printDslGaps(dslGaps);
+        runLogger.stageStart("dsl_gap_feedback", { gapCount: dslGaps.length, gaps: dslGaps.map((g) => g.code) });
+
+        const refineChoice = await select({
+          message: "How would you like to proceed?",
+          choices: [
+            { name: "🔧  Refine spec (AI fills the gaps, then re-extract DSL)", value: "refine" },
+            { name: "⏭   Skip — proceed with the current DSL", value: "skip" },
+          ],
+        });
+
+        if (refineChoice === "refine") {
+          console.log(chalk.blue("  Refining spec to fill DSL gaps..."));
+          try {
+            const refinedSpec = await specProvider.generate(
+              buildDslGapRefinementPrompt(finalSpec, dslGaps),
+              "You are a Senior Tech Lead doing a targeted spec revision. Output only the complete revised Markdown spec."
+            );
+            finalSpec = refinedSpec;
+            console.log(chalk.green("  ✔ Spec refined."));
+
+            // Re-extract DSL from the improved spec
+            console.log(chalk.blue("  Re-extracting DSL from refined spec..."));
+            const isFrontend2 = isFrontendDeps(context.dependencies);
+            const reExtractor = new DslExtractor(specProvider);
+            const reExtractedDsl = await reExtractor.extract(finalSpec, { auto: true, isFrontend: isFrontend2 });
+            if (reExtractedDsl) {
+              extractedDsl = reExtractedDsl;
+              console.log(chalk.green(`  ✔ DSL re-extracted: ${extractedDsl.endpoints.length} endpoint(s), ${extractedDsl.models.length} model(s).`));
+              runLogger.stageEnd("dsl_gap_feedback", { action: "refined", endpoints: extractedDsl.endpoints.length, models: extractedDsl.models.length });
+            } else {
+              console.log(chalk.yellow("  ⚠ Re-extraction failed — keeping original DSL."));
+              runLogger.stageEnd("dsl_gap_feedback", { action: "refined_but_reextract_failed" });
+            }
+          } catch (err) {
+            console.log(chalk.yellow(`  ⚠ Spec refinement failed: ${(err as Error).message} — keeping original DSL.`));
+            runLogger.stageEnd("dsl_gap_feedback", { action: "refinement_error", error: (err as Error).message });
+          }
+        } else {
+          runLogger.stageEnd("dsl_gap_feedback", { action: "skipped" });
+          console.log(chalk.gray("  Continuing with current DSL."));
+        }
+      }
+    }
+
     // ── Step 4: Git Worktree ──────────────────────────────────────────────────
     // Frontend projects (React / Vue / Next / React-Native) work directly on a
     // feature branch — no worktree needed. node_modules is not copied into
@@ -625,14 +695,16 @@ program
     // ── Step 8: Error Feedback Loop ───────────────────────────────────────────
     // In TDD mode, the error feedback loop is the primary driver:
     // it runs tests, collects failures, and fixes implementation until tests pass.
+    let compilePassed = false;
     if (opts.skipErrorFeedback) {
       console.log(chalk.gray("[8/9] Skipping error feedback (--skip-error-feedback)."));
+      compilePassed = true; // treat skip as neutral pass for self-eval
     } else {
       if (opts.tdd) {
         console.log(chalk.cyan("[8/9] TDD mode — error feedback loop driving implementation to pass tests..."));
       }
       runLogger.stageStart("error_feedback");
-      await runErrorFeedback(codegenProvider, workingDir, extractedDsl, {
+      compilePassed = await runErrorFeedback(codegenProvider, workingDir, extractedDsl, {
         maxCycles: opts.tdd ? 3 : 2,  // TDD gets one extra cycle
       });
       runLogger.stageEnd("error_feedback");
@@ -665,6 +737,96 @@ program
       await accumulateReviewKnowledge(specProvider, currentDir, reviewResult);
     }
 
+    // ── Loop 2: Review → DSL Structural Feedback ─────────────────────────────
+    // Runs only in interactive mode when a review was produced.
+    // Classifies Pass 1 (architecture) findings as design-level vs implementation-
+    // level issues. Design issues belong in the Spec/DSL — not just in §9.
+    // If found: offer to amend the spec → re-extract DSL → overwrite saved DSL file.
+    // The user can then run `ai-spec update --codegen` to regenerate affected files.
+    if (reviewResult && !opts.skipReview && !opts.auto && extractedDsl && savedDslFile) {
+      const structuralFindings = extractStructuralFindings(reviewResult);
+
+      if (structuralFindings.length > 0) {
+        printStructuralFindings(structuralFindings);
+        runLogger.stageStart("review_dsl_feedback", { findingCount: structuralFindings.length, categories: structuralFindings.map((f) => f.category) });
+
+        const savedSpecContent = await fs.readFile(specFile, "utf-8");
+
+        const patchChoice = await select({
+          message: "These are design issues in the Spec/DSL. How would you like to handle them?",
+          choices: [
+            { name: "🔧  Amend spec + update DSL (AI fixes the design issues, no regen yet)", value: "amend" },
+            { name: "📝  Note in §9 only (already done — no DSL change)", value: "note" },
+            { name: "⏭   Skip", value: "skip" },
+          ],
+        });
+
+        if (patchChoice === "amend") {
+          console.log(chalk.blue("  Amending spec to address structural findings..."));
+          try {
+            const amendedSpec = await specProvider.generate(
+              buildStructuralAmendmentPrompt(savedSpecContent, structuralFindings),
+              "You are a Senior Tech Lead doing a targeted spec correction. Output only the complete revised Markdown spec."
+            );
+
+            // Snapshot spec + DSL before overwriting so `ai-spec restore <runId>` works
+            await runSnapshot.snapshotFile(specFile);
+            if (savedDslFile) await runSnapshot.snapshotFile(savedDslFile);
+
+            // Overwrite the saved spec file with the amendment
+            await fs.writeFile(specFile, amendedSpec, "utf-8");
+            console.log(chalk.green(`  ✔ Spec updated: ${specFile}`));
+
+            // Re-extract DSL from the amended spec
+            console.log(chalk.blue("  Re-extracting DSL from amended spec..."));
+            const isFrontend3 = isFrontendDeps(context.dependencies);
+            const amendExtractor = new DslExtractor(specProvider);
+            const amendedDsl = await amendExtractor.extract(amendedSpec, { auto: true, isFrontend: isFrontend3 });
+            if (amendedDsl) {
+              // Overwrite saved DSL file
+              const dslWriter = new DslExtractor(specProvider);
+              const newDslPath = await dslWriter.saveDsl(amendedDsl, specFile);
+              extractedDsl = amendedDsl;
+              console.log(chalk.green(`  ✔ DSL updated: ${newDslPath}`));
+              console.log(chalk.cyan(
+                `\n  Next step: run ${chalk.white("ai-spec update --codegen")} to regenerate files affected by the DSL change.`
+              ));
+              runLogger.stageEnd("review_dsl_feedback", {
+                action: "amended",
+                endpoints: amendedDsl.endpoints.length,
+                models: amendedDsl.models.length,
+              });
+            } else {
+              console.log(chalk.yellow("  ⚠ DSL re-extraction failed — spec was updated but DSL file unchanged."));
+              runLogger.stageEnd("review_dsl_feedback", { action: "amended_spec_only" });
+            }
+          } catch (err) {
+            console.log(chalk.yellow(`  ⚠ Spec amendment failed: ${(err as Error).message}`));
+            runLogger.stageEnd("review_dsl_feedback", { action: "amendment_error", error: (err as Error).message });
+          }
+        } else {
+          runLogger.stageEnd("review_dsl_feedback", { action: patchChoice });
+          if (patchChoice === "note") {
+            console.log(chalk.gray("  Structural findings retained in §9. DSL unchanged."));
+          }
+        }
+      }
+    }
+
+    // ── Step 10: Harness Self-Evaluation ──────────────────────────────────────
+    // Zero AI calls — deterministic scoring from file-system state + review text.
+    // Records harnessScore + promptHash in RunLog for cross-run trend analysis.
+    runLogger.stageStart("self_eval");
+    const selfEvalResult = runSelfEval({
+      dsl: extractedDsl,
+      generatedFiles,
+      compilePassed,
+      reviewText: reviewResult,
+      promptHash,
+      logger: runLogger,
+    });
+    printSelfEval(selfEvalResult);
+
     // ── Done ──────────────────────────────────────────────────────────────────
     runLogger.finish();
     console.log(chalk.bold.green("\n✔ All done!"));
@@ -2230,4 +2392,142 @@ program
     }
   });
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: trend
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("trend")
+  .description("Show harness score trend across past create runs")
+  .option("--last <n>", "Number of recent scored runs to show (default: 15)", "15")
+  .option("--prompt <hash>", "Filter to a specific prompt hash (prefix match)")
+  .option("--json", "Output raw JSON instead of formatted table")
+  .action(async (opts: { last: string; prompt?: string; json?: boolean }) => {
+    const currentDir = process.cwd();
+    const last = parseInt(opts.last, 10) || 15;
+
+    const logs = await loadRunLogs(currentDir);
+    if (logs.length === 0) {
+      console.log(chalk.yellow(
+        "\n  No run logs found. Run `ai-spec create` at least once to start tracking.\n"
+      ));
+      return;
+    }
+
+    const report = buildTrendReport(logs, {
+      last,
+      promptFilter: opts.prompt,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+
+    printTrendReport(report, currentDir);
+  });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: logs
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("logs")
+  .description("List recent run logs with stage timing")
+  .argument("[runId]", "Show detailed stage breakdown for a specific run ID")
+  .option("--last <n>", "Number of runs to list (default: 10)", "10")
+  .action(async (runId: string | undefined, opts: { last: string }) => {
+    const currentDir = process.cwd();
+    const logDir = path.join(currentDir, ".ai-spec-logs");
+
+    if (!(await fs.pathExists(logDir))) {
+      console.log(chalk.yellow("\n  No run logs found (.ai-spec-logs/ does not exist).\n"));
+      return;
+    }
+
+    if (runId) {
+      // ── Detail view for a single run ──────────────────────────────────────
+      const logPath = path.join(logDir, `${runId}.json`);
+      if (!(await fs.pathExists(logPath))) {
+        console.log(chalk.red(`\n  Run not found: ${runId}\n`));
+        return;
+      }
+      const log = await fs.readJson(logPath);
+
+      console.log(chalk.cyan(`\n─── Run: ${log.runId} ─────────────────────────────────`));
+      console.log(chalk.gray(`  Started : ${log.startedAt}`));
+      if (log.endedAt) console.log(chalk.gray(`  Ended   : ${log.endedAt}`));
+      if (log.totalDurationMs !== undefined)
+        console.log(chalk.gray(`  Duration: ${(log.totalDurationMs / 1000).toFixed(1)}s`));
+      if (log.provider) console.log(chalk.gray(`  Provider: ${log.provider} / ${log.model ?? "?"}`));
+      if (log.promptHash) console.log(chalk.gray(`  Prompt  : ${log.promptHash}`));
+      if (log.harnessScore !== undefined)
+        console.log(chalk.white(`  Score   : ${log.harnessScore}/10`));
+      if (log.filesWritten?.length)
+        console.log(chalk.gray(`  Files   : ${log.filesWritten.length} written`));
+      if (log.errors?.length)
+        console.log(chalk.yellow(`  Errors  : ${log.errors.length}`));
+
+      if (log.entries?.length) {
+        console.log(chalk.bold("\n  Stages:\n"));
+        const doneEvents = (log.entries as Array<{ event: string; data?: Record<string, unknown>; ts: string }>)
+          .filter((e) => e.event.endsWith(":done") || e.event.endsWith(":failed"));
+
+        for (const entry of doneEvents) {
+          const isOk  = entry.event.endsWith(":done");
+          const stage = entry.event.replace(/:done$|:failed$/, "");
+          const dur   = entry.data?.durationMs
+            ? chalk.gray(` ${(Number(entry.data.durationMs) / 1000).toFixed(1)}s`)
+            : "";
+          const mark  = isOk ? chalk.green("✔") : chalk.red("✘");
+          console.log(`    ${mark}  ${stage.padEnd(20)}${dur}`);
+        }
+      }
+      console.log(chalk.cyan("─".repeat(52)));
+      return;
+    }
+
+    // ── List view ─────────────────────────────────────────────────────────────
+    const logs = await loadRunLogs(currentDir);
+    const last  = parseInt(opts.last, 10) || 10;
+    const shown = logs.slice(0, last);
+
+    if (shown.length === 0) {
+      console.log(chalk.yellow("\n  No run logs found.\n"));
+      return;
+    }
+
+    console.log(chalk.cyan("\n─── Run Logs ────────────────────────────────────────────────"));
+    console.log(chalk.gray(
+      "\n  " +
+      "Run ID                  ".padEnd(26) +
+      "Date      " +
+      "Score ".padStart(6) +
+      "  Files  Dur\n"
+    ));
+
+    for (const log of shown) {
+      const date  = log.startedAt.slice(0, 10);
+      const score = log.harnessScore !== undefined
+        ? (log.harnessScore >= 8 ? chalk.green : log.harnessScore >= 6 ? chalk.yellow : chalk.red)(
+            log.harnessScore.toFixed(1).padStart(5)
+          )
+        : chalk.gray("    —");
+      const files = String(log.filesWritten?.length ?? 0).padStart(5);
+      const dur   = log.totalDurationMs !== undefined
+        ? chalk.gray((log.totalDurationMs / 1000).toFixed(0) + "s")
+        : chalk.gray("—");
+      const errMark = (log.errors?.length ?? 0) > 0
+        ? chalk.yellow(` ⚠${log.errors.length}`)
+        : "";
+
+      console.log(`  ${chalk.white(log.runId.padEnd(25))} ${chalk.gray(date)} ${score}  ${chalk.gray(files)}  ${dur}${errMark}`);
+    }
+
+    console.log(chalk.gray(`\n  Showing ${shown.length} of ${logs.length} run(s)  ·  logs: .ai-spec-logs/`));
+    console.log(chalk.cyan("─".repeat(63)));
+    console.log(chalk.gray(`  Tip: ai-spec logs <runId>   to see stage breakdown`));
+    console.log(chalk.gray(`       ai-spec trend          to see score trend by prompt version\n`));
+  });
+
 program.parse();

package/cli/utils.ts

@@ -0,0 +1,83 @@
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { input, select } from "@inquirer/prompts";
+import { CodeGenMode } from "../core/code-generator";
+import { ENV_KEY_MAP } from "../core/spec-generator";
+import { getSavedKey, saveKey, KEY_STORE_FILE } from "../core/key-store";
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+export interface AiSpecConfig {
+  provider?: string;
+  model?: string;
+  codegen?: CodeGenMode;
+  codegenProvider?: string;
+  codegenModel?: string;
+  /** Minimum overall spec score (1-10) required to pass Approval Gate. 0 = disabled (default). */
+  minSpecScore?: number;
+}
+
+export const CONFIG_FILE = ".ai-spec.json";
+
+export async function loadConfig(dir: string): Promise<AiSpecConfig> {
+  const p = path.join(dir, CONFIG_FILE);
+  if (await fs.pathExists(p)) {
+    return fs.readJson(p);
+  }
+  return {};
+}
+
+// ─── API Key Resolution ───────────────────────────────────────────────────────
+
+export async function resolveApiKey(
+  providerName: string,
+  cliKey?: string
+): Promise<string> {
+  if (cliKey) return cliKey;
+
+  const envVar = ENV_KEY_MAP[providerName];
+  if (envVar && process.env[envVar]) return process.env[envVar]!;
+
+  const savedKey = await getSavedKey(providerName);
+  if (savedKey) {
+    const masked = savedKey.slice(0, 6) + "..." + savedKey.slice(-4);
+    const choice = await select({
+      message: `${providerName} API key (saved: ${masked}):`,
+      choices: [
+        { name: "Use saved key", value: "reuse" },
+        { name: "Enter a new key", value: "new" },
+      ],
+    });
+    if (choice === "reuse") return savedKey;
+  }
+
+  const newKey = await input({
+    message: `Enter your ${providerName} API key${envVar ? ` (or set ${envVar} env var)` : ""}:`,
+    validate: (v) => v.trim().length > 0 || "API key cannot be empty",
+  });
+  await saveKey(providerName, newKey.trim());
+  console.log(chalk.gray(`  Key saved to ${KEY_STORE_FILE}`));
+  return newKey.trim();
+}
+
+// ─── Banner ───────────────────────────────────────────────────────────────────
+
+export function printBanner(opts: {
+  specProvider: string;
+  specModel: string;
+  codegenMode: string;
+  codegenProvider: string;
+  codegenModel: string;
+}) {
+  console.log(chalk.blue("\n" + "─".repeat(52)));
+  console.log(chalk.bold("  ai-spec — AI-driven Development Orchestrator"));
+  console.log(chalk.blue("─".repeat(52)));
+  console.log(chalk.gray(`  Spec    : ${opts.specProvider} / ${opts.specModel}`));
+  console.log(
+    chalk.gray(
+      `  Codegen : ${opts.codegenMode} (${opts.codegenProvider} / ${opts.codegenModel})`
+    )
+  );
+  console.log(chalk.blue("─".repeat(52) + "\n"));
+}