ai-spec-dev 0.30.1 → 0.33.0

package/cli/commands/logs.ts

@@ -0,0 +1,106 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { loadRunLogs } from "../../core/run-trend";
+
+export function registerLogs(program: Command): void {
+  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`));
+    });
+}

package/cli/commands/model.ts

@@ -0,0 +1,156 @@
+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 {
+  DEFAULT_MODELS,
+  ENV_KEY_MAP,
+  PROVIDER_CATALOG,
+} from "../../core/spec-generator";
+import { AiSpecConfig, CONFIG_FILE, loadConfig } from "../utils";
+
+export function registerModel(program: Command): void {
+  program
+    .command("model")
+    .description("Interactively switch the active AI provider/model and save to .ai-spec.json")
+    .option("--list", "List all available providers and models")
+    .action(async (opts) => {
+      const currentDir = process.cwd();
+      const configPath = path.join(currentDir, CONFIG_FILE);
+
+      // ── --list ──────────────────────────────────────────────────────────────
+      if (opts.list) {
+        console.log(chalk.bold("\nAvailable providers & models:\n"));
+        for (const [key, meta] of Object.entries(PROVIDER_CATALOG)) {
+          console.log(
+            `  ${chalk.bold.cyan(key.padEnd(10))} ${chalk.white(meta.displayName)}`
+          );
+          console.log(chalk.gray(`             ${meta.description}`));
+          console.log(
+            chalk.gray(
+              `             env: ${meta.envKey}  |  models: ${meta.models.join(", ")}`
+            )
+          );
+          console.log();
+        }
+        return;
+      }
+
+      const existing: AiSpecConfig = await loadConfig(currentDir);
+
+      console.log(chalk.blue("\n─── Model Switcher ─────────────────────────────"));
+      if (Object.keys(existing).length > 0) {
+        console.log(
+          chalk.gray(
+            `  Current: spec=${existing.provider ?? "gemini"}/${existing.model ?? DEFAULT_MODELS[existing.provider ?? "gemini"]}` +
+              (existing.codegenProvider
+                ? `  codegen=${existing.codegenProvider}/${existing.codegenModel ?? ""}`
+                : "")
+          )
+        );
+      }
+      console.log();
+
+      const target = await select({
+        message: "Configure model for:",
+        choices: [
+          { name: "Spec generation  (used for spec writing & refinement)", value: "spec" },
+          { name: "Code generation  (used when --codegen api is active)", value: "codegen" },
+          { name: "Both             (same provider/model for all tasks)", value: "both" },
+        ],
+      });
+
+      async function pickProviderAndModel(label: string): Promise<{ provider: string; model: string }> {
+        const providerKey = await select({
+          message: `${label} — select provider:`,
+          choices: Object.entries(PROVIDER_CATALOG).map(([key, meta]) => ({
+            name: `${meta.displayName.padEnd(22)} ${chalk.gray(meta.description)}`,
+            value: key,
+            short: meta.displayName,
+          })),
+        });
+
+        const meta = PROVIDER_CATALOG[providerKey];
+        const modelChoices = [
+          ...meta.models.map((m) => ({ name: m, value: m })),
+          { name: chalk.italic("✎  Enter custom model name..."), value: "__custom__" },
+        ];
+
+        let chosenModel = await select({
+          message: `${label} — select model (${meta.displayName}):`,
+          choices: modelChoices,
+        });
+
+        if (chosenModel === "__custom__") {
+          chosenModel = await input({
+            message: "Enter model name:",
+            validate: (v) => v.trim().length > 0 || "Model name cannot be empty",
+          });
+        }
+
+        return { provider: providerKey, model: chosenModel };
+      }
+
+      const updated: AiSpecConfig = { ...existing };
+
+      if (target === "spec" || target === "both") {
+        const { provider, model } = await pickProviderAndModel("Spec");
+        updated.provider = provider;
+        updated.model = model;
+      }
+
+      if (target === "codegen" || target === "both") {
+        if (target === "both") {
+          updated.codegenProvider = updated.provider;
+          updated.codegenModel = updated.model;
+        } else {
+          const { provider, model } = await pickProviderAndModel("Codegen");
+          updated.codegenProvider = provider;
+          updated.codegenModel = model;
+        }
+
+        const effectiveCodegenProvider = updated.codegenProvider ?? updated.provider ?? "gemini";
+        if (effectiveCodegenProvider !== "claude") {
+          if (!updated.codegen || updated.codegen === "claude-code") {
+            updated.codegen = "api";
+            console.log(
+              chalk.yellow(
+                `\n  ⚠  provider "${effectiveCodegenProvider}" 不支持 "claude-code" 模式。`
+              )
+            );
+            console.log(chalk.gray(`  已自动将 codegen 模式设为 "api"。`));
+          }
+        }
+      }
+
+      console.log(chalk.blue("\n  Preview:"));
+      console.log(chalk.gray(`    spec    → ${updated.provider}/${updated.model}`));
+      if (updated.codegenProvider) {
+        console.log(
+          chalk.gray(
+            `    codegen → ${updated.codegenProvider}/${updated.codegenModel}  (mode: ${updated.codegen ?? "claude-code"})`
+          )
+        );
+      }
+
+      const ok = await confirm({ message: "Save to .ai-spec.json?", default: true });
+      if (!ok) {
+        console.log(chalk.gray("  Cancelled."));
+        return;
+      }
+
+      await fs.writeJson(configPath, updated, { spaces: 2 });
+      console.log(chalk.green(`\n  ✔ Saved to ${configPath}`));
+
+      const providerToCheck = updated.provider ?? "gemini";
+      const envKey = ENV_KEY_MAP[providerToCheck];
+      if (envKey && !process.env[envKey]) {
+        console.log(
+          chalk.yellow(
+            `  ⚠  Remember to set ${envKey} in your environment or .env file.`
+          )
+        );
+      }
+    });
+}

package/cli/commands/restore.ts

@@ -0,0 +1,22 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { RunSnapshot } from "../../core/run-snapshot";
+
+export function registerRestore(program: Command): void {
+  program
+    .command("restore")
+    .description("Restore files modified by a previous run")
+    .argument("<runId>", "Run ID shown at the end of a create / generate run")
+    .action(async (runId: string) => {
+      const currentDir = process.cwd();
+      const snapshot = new RunSnapshot(currentDir, runId);
+      console.log(chalk.blue(`Restoring run: ${runId}...`));
+      const restored = await snapshot.restore();
+      if (restored.length === 0) {
+        console.log(chalk.yellow("  No backup found for this run ID."));
+      } else {
+        restored.forEach((f) => console.log(chalk.green(`  ✔ restored: ${f}`)));
+        console.log(chalk.bold.green(`\n✔ ${restored.length} file(s) restored.`));
+      }
+    });
+}

package/cli/commands/review.ts

@@ -0,0 +1,63 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { createProvider, DEFAULT_MODELS, SUPPORTED_PROVIDERS } from "../../core/spec-generator";
+import { CodeReviewer } from "../../core/reviewer";
+import { loadConfig, resolveApiKey } from "../utils";
+
+export function registerReview(program: Command): void {
+  program
+    .command("review")
+    .description("Run AI code review on current git diff against a spec")
+    .argument("[specFile]", "Path to spec file (auto-detects latest in specs/ if omitted)")
+    .option(
+      "--provider <name>",
+      `AI provider (${SUPPORTED_PROVIDERS.join("|")})`,
+      undefined
+    )
+    .option("--model <name>", "Model name")
+    .option("-k, --key <apiKey>", "API key")
+    .action(async (specFile: string | undefined, opts) => {
+      const currentDir = process.cwd();
+      const config = await loadConfig(currentDir);
+
+      const providerName = opts.provider || config.provider || "gemini";
+      const modelName = opts.model || config.model || DEFAULT_MODELS[providerName];
+      const apiKey = await resolveApiKey(providerName, opts.key);
+
+      const provider = createProvider(providerName, apiKey, modelName);
+      const reviewer = new CodeReviewer(provider, currentDir);
+
+      let specContent = "";
+      let resolvedSpecFile: string | undefined;
+
+      if (specFile && (await fs.pathExists(specFile))) {
+        specContent = await fs.readFile(specFile, "utf-8");
+        resolvedSpecFile = specFile;
+        console.log(chalk.gray(`Using spec: ${specFile}`));
+      } else {
+        // Auto-detect the latest spec in specs/
+        const specsDir = path.join(currentDir, "specs");
+        if (await fs.pathExists(specsDir)) {
+          const files = (await fs.readdir(specsDir))
+            .filter((f) => f.endsWith(".md"))
+            .sort()
+            .reverse();
+          if (files.length > 0) {
+            const latest = path.join(specsDir, files[0]);
+            specContent = await fs.readFile(latest, "utf-8");
+            resolvedSpecFile = latest;
+            console.log(chalk.gray(`Auto-detected spec: specs/${files[0]}`));
+          }
+        }
+      }
+
+      if (!specContent) {
+        console.log(chalk.yellow("No spec file found. Running review without spec context."));
+      }
+
+      await reviewer.reviewCode(specContent, resolvedSpecFile);
+      await reviewer.printScoreTrend();
+    });
+}

package/cli/commands/trend.ts

@@ -0,0 +1,36 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { loadRunLogs, buildTrendReport, printTrendReport } from "../../core/run-trend";
+
+export function registerTrend(program: Command): void {
+  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);
+    });
+}

package/cli/commands/update.ts

@@ -0,0 +1,178 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { input } from "@inquirer/prompts";
+import { createProvider, DEFAULT_MODELS, SUPPORTED_PROVIDERS } from "../../core/spec-generator";
+import { ContextLoader } from "../../core/context-loader";
+import { CodeGenerator } from "../../core/code-generator";
+import { CodeReviewer } from "../../core/reviewer";
+import { SpecUpdater } from "../../core/spec-updater";
+import { accumulateReviewKnowledge } from "../../core/knowledge-memory";
+import { generateRunId, RunLogger, setActiveLogger } from "../../core/run-logger";
+import { RunSnapshot, setActiveSnapshot } from "../../core/run-snapshot";
+import { detectRepoType } from "../../core/workspace-loader";
+import { getCodeGenSystemPrompt } from "../../prompts/codegen.prompt";
+import { loadConfig, resolveApiKey } from "../utils";
+
+export function registerUpdate(program: Command): void {
+  program
+    .command("update")
+    .description("Update an existing spec with a change request, re-extract DSL, and identify affected files")
+    .argument("[change]", "Change description (prompted if omitted)")
+    .option("--provider <name>", `AI provider (${SUPPORTED_PROVIDERS.join("|")})`, undefined)
+    .option("--model <name>", "Model name")
+    .option("-k, --key <apiKey>", "API key")
+    .option("--spec <path>", "Path to the existing spec file (auto-detected if omitted)")
+    .option("--codegen", "Regenerate affected files automatically after updating spec")
+    .option("--codegen-provider <name>", "Provider for code generation")
+    .option("--codegen-model <name>", "Model for code generation")
+    .option("--codegen-key <key>", "API key for code generation")
+    .option("--skip-affected", "Skip identifying affected files")
+    .action(async (change: string | undefined, opts) => {
+      const currentDir = process.cwd();
+      const config = await loadConfig(currentDir);
+
+      if (!change) {
+        change = await input({
+          message: "Describe the change you want to make:",
+          validate: (v) => v.trim().length > 0 || "Change description cannot be empty",
+        });
+      }
+
+      const providerName = opts.provider || config.provider || "gemini";
+      const modelName = opts.model || config.model || DEFAULT_MODELS[providerName];
+      const apiKey = await resolveApiKey(providerName, opts.key);
+      const provider = createProvider(providerName, apiKey, modelName);
+
+      console.log(chalk.blue("\n─── ai-spec update ─────────────────────────────"));
+      console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
+
+      const updateRunId = generateRunId();
+      const updateSnapshot = new RunSnapshot(currentDir, updateRunId);
+      setActiveSnapshot(updateSnapshot);
+      const updateLogger = new RunLogger(currentDir, updateRunId, { provider: providerName, model: modelName });
+      setActiveLogger(updateLogger);
+      console.log(chalk.gray(`  Run ID: ${updateRunId}`));
+
+      let specPath: string | null = opts.spec ?? null;
+      if (!specPath) {
+        const specsDir = path.join(currentDir, "specs");
+        const latest = await SpecUpdater.findLatestSpec(specsDir);
+        if (!latest) {
+          console.error(chalk.red("  No spec files found in specs/. Run `ai-spec create` first or use --spec <path>."));
+          process.exit(1);
+        }
+        specPath = latest.filePath;
+        console.log(chalk.gray(`  Using spec: ${path.relative(currentDir, specPath)} (v${latest.version})`));
+      }
+
+      console.log(chalk.gray("  Loading project context..."));
+      const loader = new ContextLoader(currentDir);
+      const context = await loader.loadProjectContext();
+      if (context.constitution && context.constitution.length > 6000) {
+        console.log(chalk.yellow(`  ⚠ Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
+      }
+
+      const { type: repoType } = await detectRepoType(currentDir);
+
+      const updater = new SpecUpdater(provider);
+      let result;
+      try {
+        result = await updater.update(change!, specPath, currentDir, context, {
+          skipAffectedFiles: opts.skipAffected,
+          repoType,
+        });
+      } catch (err) {
+        console.error(chalk.red(`  Update failed: ${(err as Error).message}`));
+        process.exit(1);
+      }
+
+      console.log(chalk.green(`\n  ✔ Spec updated → v${result.newVersion}: ${path.relative(currentDir, result.newSpecPath)}`));
+      if (result.newDslPath) {
+        console.log(chalk.green(`  ✔ DSL updated: ${path.relative(currentDir, result.newDslPath)}`));
+      }
+
+      if (result.affectedFiles.length > 0) {
+        console.log(chalk.cyan("\n  Affected files:"));
+        for (const f of result.affectedFiles) {
+          const icon = f.action === "create" ? chalk.green("+") : chalk.yellow("~");
+          console.log(`    ${icon} ${f.file}: ${chalk.gray(f.description)}`);
+        }
+      }
+
+      if (opts.codegen && result.affectedFiles.length > 0) {
+        const codegenProviderName = opts.codegenProvider || config.codegenProvider || providerName;
+        const codegenModelName = opts.codegenModel || config.codegenModel || DEFAULT_MODELS[codegenProviderName];
+        const codegenApiKey = opts.codegenKey ?? (codegenProviderName === providerName ? apiKey : await resolveApiKey(codegenProviderName, opts.codegenKey));
+        const codegenProvider = createProvider(codegenProviderName, codegenApiKey, codegenModelName);
+
+        console.log(chalk.blue("\n  Regenerating affected files..."));
+        new CodeGenerator(codegenProvider, "api");
+
+        const specContent = await fs.readFile(result.newSpecPath, "utf-8");
+        const constitutionSection = context.constitution
+          ? `\n=== Project Constitution (MUST follow) ===\n${context.constitution}\n`
+          : "";
+        const dslSection = result.updatedDsl
+          ? `\n=== DSL Context ===\n${JSON.stringify(result.updatedDsl, null, 2).slice(0, 3000)}\n`
+          : "";
+
+        updateLogger.stageStart("update_codegen");
+        for (const affected of result.affectedFiles) {
+          const fullPath = path.join(currentDir, affected.file);
+          let existing = "";
+          try { existing = await fs.readFile(fullPath, "utf-8"); } catch { /* new file */ }
+
+          const codePrompt = `Apply this change to the file.
+
+Change: ${change}
+File: ${affected.file}
+Purpose: ${affected.description}
+
+=== Feature Spec (updated) ===
+${specContent}
+${constitutionSection}${dslSection}
+=== ${existing ? "Current File (return the FULL updated content)" : "New File"} ===
+${existing || "Create from scratch."}`;
+
+          process.stdout.write(`  ${existing ? chalk.yellow("~") : chalk.green("+")} ${affected.file}... `);
+          try {
+            const raw = await codegenProvider.generate(codePrompt, getCodeGenSystemPrompt(repoType));
+            const content = raw.replace(/^```\w*\n?/gm, "").replace(/\n?```$/gm, "").trim();
+            await fs.ensureDir(path.dirname(fullPath));
+            await updateSnapshot.snapshotFile(fullPath);
+            await fs.writeFile(fullPath, content, "utf-8");
+            updateLogger.fileWritten(affected.file);
+            console.log(chalk.green("✔"));
+          } catch (err) {
+            updateLogger.stageFail("update_codegen", `${affected.file}: ${(err as Error).message}`);
+            console.log(chalk.red(`✘ ${(err as Error).message}`));
+          }
+        }
+        updateLogger.stageEnd("update_codegen", { filesUpdated: result.affectedFiles.length });
+
+        const updatedSpecContent = await fs.readFile(result.newSpecPath, "utf-8").catch(() => "");
+        if (updatedSpecContent) {
+          const updateReviewer = new CodeReviewer(provider, currentDir);
+          const reviewResult = await updateReviewer.reviewCode(updatedSpecContent, result.newSpecPath).catch(() => "");
+          if (reviewResult && reviewResult !== "No changes") {
+            await accumulateReviewKnowledge(provider, currentDir, reviewResult);
+          }
+        }
+      }
+
+      updateLogger.finish();
+      updateLogger.printSummary();
+      if (updateSnapshot.fileCount > 0) {
+        console.log(chalk.gray(`  To undo changes: ai-spec restore ${updateRunId}`));
+      }
+
+      if (!opts.codegen && result.affectedFiles.length > 0) {
+        console.log(chalk.blue("\n  Next steps:"));
+        console.log(chalk.gray(`  • Re-run with --codegen to regenerate affected files automatically`));
+        console.log(chalk.gray(`  • Or update files manually based on the affected files list above`));
+        console.log(chalk.gray(`  • Run \`ai-spec mock\` to refresh the mock server with the new DSL`));
+      }
+    });
+}