ai-spec-dev 0.41.0 → 0.42.0

package/demo-frontend/.ai-spec-constitution.md

@@ -0,0 +1,95 @@
+# Project Constitution
+
+## 1. 架构规则 (Architecture Rules)
+- **组件分层架构**：页面/组件 → 自定义hooks → 服务层 → API客户端
+- **组件组织**：页面组件位于 `src/pages/`，可复用组件位于 `src/components/`
+- **业务逻辑分离**：所有API调用、数据转换和业务逻辑必须封装在自定义hooks或服务层中
+- **状态管理**：使用React Context或本地状态，禁止直接修改props
+- **类型安全**：所有组件props、API响应和状态必须明确定义TypeScript类型
+
+## 2. 命名规范 (Naming Conventions)
+- **文件命名**：
+  - 组件文件：PascalCase (`UserProfile.tsx`)
+  - Hook文件：camelCase，以`use`开头 (`useAuth.ts`)
+  - 工具/服务文件：camelCase (`apiService.ts`)
+  - 样式文件：与组件同名，使用CSS模块 (`UserProfile.module.css`)
+- **变量/函数**：
+  - 变量/函数：camelCase (`userData`, `fetchUserProfile`)
+  - 接口/类型：PascalCase (`UserData`, `ApiResponse`)
+  - 常量：UPPER_SNAKE_CASE (`API_BASE_URL`)
+- **组件命名**：PascalCase (`<UserProfile />`)
+- **路由路径**：kebab-case (`/user-profile`, `/admin/dashboard`)
+
+## 3. API 规范 (API Patterns)
+- **API客户端**：使用统一的axios实例配置，位于 `src/services/apiClient.ts`
+- **请求模式**：所有API调用必须封装在自定义hooks (`useApi`, `useFetch`) 或服务函数中
+- **响应结构**：
+  ```typescript
+  interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+    message?: string;
+    error?: string;
+    code?: number;
+  }
+  ```
+- **错误处理**：统一使用try-catch包装，错误通过状态返回而非抛出异常
+- **认证**：Token存储在localStorage，通过axios拦截器自动添加Authorization头
+- **路由组织**：
+  - 公开路由：无需认证 (`/login`, `/register`)
+  - 受保护路由：需要认证 (`/dashboard`, `/profile`)
+  - 管理员路由：需要特定角色 (`/admin/*`)
+
+## 4. 数据层规范 (Data Layer Rules)
+- **状态管理**：
+  - 全局状态：React Context + useReducer
+  - 本地组件状态：useState
+  - 服务端状态：React Query或自定义缓存hooks
+- **数据获取**：所有数据必须通过服务层获取，禁止组件直接调用fetch/axios
+- **类型定义**：所有API请求/响应必须定义在 `src/types/` 目录下
+- **数据转换**：在服务层进行API响应到前端模型的转换
+
+## 5. 错误处理规范 (Error Handling Patterns)
+- **全局错误边界**：App组件包裹ErrorBoundary
+- **API错误**：统一在服务层处理，返回标准化错误对象
+- **用户反馈**：通过Toast/Snackbar组件显示错误消息
+- **错误日志**：使用console.error记录，生产环境集成错误监控
+- **表单验证**：使用Formik或React Hook Form进行客户端验证
+
+## 6. 禁区 (Red Lines — Never Violate)
+- [ ] **禁止**在组件中直接进行API调用（必须通过hooks/服务层）
+- [ ] **禁止**使用`any`类型（必须明确定义或使用`unknown`）
+- [ ] **禁止**修改传入的props（遵循单向数据流）
+- [ ] **禁止**在组件中编写复杂业务逻辑（必须提取到hooks/服务层）
+- [ ] **禁止**使用内联样式（必须使用CSS模块或styled-components）
+- [ ] **禁止**提交未定义类型的代码
+- [ ] **禁止**直接访问process.env（必须通过配置模块）
+
+## 7. 测试规范 (Testing Rules)
+- **测试框架**：Vitest + React Testing Library
+- **测试文件位置**：与源文件同目录，使用`.test.tsx`或`.spec.tsx`后缀
+- **必须测试**：
+  - 所有自定义hooks
+  - 复杂业务逻辑函数
+  - 关键用户交互流程
+  - 组件渲染和状态变化
+- **测试结构**：Arrange-Act-Assert模式
+- **Mock策略**：API调用必须mock，使用MSW或手动mock
+- **覆盖率要求**：核心业务逻辑必须>80%
+
+## 8. 共享配置文件清单 (Shared Config Files — Append-Only)
+
+CRITICAL: The following files are **singleton config files** that already exist in the project.
+When any feature needs to add entries (translations, constants, routes, enums, etc.), they MUST be
+appended/merged into these existing files. **NEVER create a new parallel file.**
+
+- `src/constants/apiEndpoints.ts` — API端点配置 — **MODIFY ONLY, never recreate**
+- `src/types/api.d.ts` — API类型定义 — **MODIFY ONLY, never recreate**
+- `src/config/env.ts` — 环境变量配置 — **MODIFY ONLY, never recreate**
+- `src/utils/errorCodes.ts` — 错误码常量 — **MODIFY ONLY, never recreate**
+- `src/services/apiClient.ts` — Axios实例配置 — **MODIFY ONLY, never recreate**
+- `src/routes/index.tsx` — 路由配置 — **MODIFY ONLY, never recreate**
+- `src/hooks/index.ts` — 自定义hooks导出 — **MODIFY ONLY, never recreate**
+- `src/context/index.ts` — Context导出 — **MODIFY ONLY, never recreate**
+
+(No i18n/locale files detected — will be populated on first run)

package/demo-frontend/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "demo-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "axios": "^1.7.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "vite": "^5.4.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "vitest": "^2.1.0"
+  }
+}

package/demo-frontend/src/App.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+
+function App() {
+  return (
+    <div>
+      <h1>Bookmark Manager</h1>
+      <p>Coming soon...</p>
+    </div>
+  );
+}
+
+export default App;

package/demo-frontend/src/main.tsx

@@ -0,0 +1,9 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

package/demo-frontend/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/dist/cli/index.js

@@ -147,6 +147,100 @@ CRITICAL \u2014 \u5386\u53F2\u6559\u8BAD\u5E94\u7528\uFF08Accumulated Lessons\uF
   }
 });
 
+// core/cli-ui.ts
+function startSpinner(text) {
+  const isTTY = process.stderr.isTTY;
+  let frame = 0;
+  let currentText = text;
+  let stopped = false;
+  function render() {
+    if (stopped) return;
+    const symbol = import_chalk.default.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length]);
+    if (isTTY) {
+      process.stderr.write(`\r  ${symbol} ${currentText}${" ".repeat(10)}`);
+    }
+    frame++;
+  }
+  if (!isTTY) {
+    process.stderr.write(`  \u2026 ${currentText}
+`);
+  }
+  const timer = setInterval(render, 80);
+  render();
+  return {
+    update(newText) {
+      currentText = newText;
+    },
+    stop(finalText) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      if (isTTY) {
+        process.stderr.write(`\r${" ".repeat(currentText.length + 20)}\r`);
+      }
+      if (finalText) {
+        process.stderr.write(`  ${finalText}
+`);
+      }
+    },
+    succeed(successText) {
+      this.stop(import_chalk.default.green(`\u2714 ${successText}`));
+    },
+    fail(failText) {
+      this.stop(import_chalk.default.red(`\u2718 ${failText}`));
+    }
+  };
+}
+async function retryCountdown(opts) {
+  const { attempt, maxAttempts, waitMs, errorMessage, label } = opts;
+  const isTTY = process.stderr.isTTY;
+  const shortErr = errorMessage.length > 120 ? errorMessage.slice(0, 117) + "..." : errorMessage;
+  process.stderr.write("\n");
+  process.stderr.write(import_chalk.default.yellow(`  \u250C\u2500 Retry ${attempt}/${maxAttempts} `) + import_chalk.default.gray(`[${label}]`) + import_chalk.default.yellow(` ${"\u2500".repeat(Math.max(1, 40 - label.length))}
+`));
+  process.stderr.write(import_chalk.default.yellow(`  \u2502 `) + import_chalk.default.white(shortErr) + "\n");
+  process.stderr.write(import_chalk.default.yellow(`  \u2502 `) + import_chalk.default.gray(`Waiting before retry...`) + "\n");
+  const totalSeconds = Math.ceil(waitMs / 1e3);
+  for (let s = totalSeconds; s > 0; s--) {
+    const bar = import_chalk.default.green("\u2588".repeat(totalSeconds - s)) + import_chalk.default.gray("\u2591".repeat(s));
+    const line = import_chalk.default.yellow(`  \u2502 `) + `${bar} ${import_chalk.default.bold.white(`${s}s`)}`;
+    if (isTTY) {
+      process.stderr.write(`\r${line}${" ".repeat(10)}`);
+    }
+    await new Promise((r) => setTimeout(r, 1e3));
+  }
+  if (isTTY) {
+    process.stderr.write(`\r${" ".repeat(70)}\r`);
+  }
+  process.stderr.write(import_chalk.default.yellow(`  \u2514\u2500 `) + import_chalk.default.cyan(`Retrying now...`) + "\n\n");
+}
+function startStage(stageKey, label) {
+  const icon = STAGE_ICONS[stageKey] ?? "\u25B8";
+  return startSpinner(`${icon}  ${label}`);
+}
+var import_chalk, SPINNER_FRAMES, STAGE_ICONS;
+var init_cli_ui = __esm({
+  "core/cli-ui.ts"() {
+    "use strict";
+    import_chalk = __toESM(require("chalk"));
+    SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+    STAGE_ICONS = {
+      context_load: "\u{1F4C2}",
+      design_dialogue: "\u{1F4AC}",
+      spec_gen: "\u{1F4DD}",
+      spec_refine: "\u270F\uFE0F ",
+      spec_assess: "\u{1F4CA}",
+      dsl_extract: "\u{1F517}",
+      dsl_gap_feedback: "\u{1F50D}",
+      codegen: "\u2699\uFE0F ",
+      test_gen: "\u{1F9EA}",
+      error_feedback: "\u{1F527}",
+      review: "\u{1F50E}",
+      self_eval: "\u{1F4C8}"
+    };
+  }
+});
+
 // core/provider-utils.ts
 function classifyError(err, label) {
   const e = err;
@@ -223,21 +317,23 @@ async function withReliability(fn, opts) {
         throw classifyError(err, label);
       }
       const waitMs = attempt === 0 ? 2e3 : 6e3;
-      console.warn(
-        import_chalk.default.yellow(`  \u26A0 ${label} failed (attempt ${attempt + 1}/${retries + 1}), retrying in ${waitMs / 1e3}s`) + import_chalk.default.gray(` \u2014 ${err.message}`)
-      );
       onRetry?.(attempt + 1, err);
-      await sleep(waitMs);
+      await retryCountdown({
+        attempt: attempt + 1,
+        maxAttempts: retries + 1,
+        waitMs,
+        errorMessage: err.message ?? String(err),
+        label
+      });
     }
   }
   throw new Error("unreachable");
 }
-var import_chalk, sleep, ProviderError;
+var ProviderError;
 var init_provider_utils = __esm({
   "core/provider-utils.ts"() {
     "use strict";
-    import_chalk = __toESM(require("chalk"));
-    sleep = (ms2) => new Promise((r) => setTimeout(r, ms2));
+    init_cli_ui();
     ProviderError = class extends Error {
       constructor(message, kind, originalError) {
         super(message);
@@ -6711,6 +6807,7 @@ function printTaskProgress(completed, total, task, mode) {
 }
 
 // core/code-generator.ts
+init_cli_ui();
 var CodeGenerator = class {
   constructor(provider, mode = "claude-code") {
     this.provider = provider;
@@ -7159,6 +7256,7 @@ ${spec}
 ${constitutionSection}
 === ${existingContent ? "Existing content (modify and return the complete file)" : "Create this file from scratch"} ===
 ${existingContent || "Output only the complete file content."}`;
+      const fileSpinner = startSpinner(`${prefix}Generating ${import_chalk9.default.bold(item.file)}...`);
       try {
         const raw = await this.provider.generate(codePrompt, systemPrompt);
         const fileContent = stripCodeFences(raw);
@@ -7166,11 +7264,11 @@ ${existingContent || "Output only the complete file content."}`;
         await fs12.ensureDir(path11.dirname(fullPath));
         await fs12.writeFile(fullPath, fileContent, "utf-8");
         getActiveLogger()?.fileWritten(item.file);
-        console.log(`${prefix}${existingContent ? import_chalk9.default.yellow("~") : import_chalk9.default.green("+")} ${import_chalk9.default.bold(item.file)} ${import_chalk9.default.green("\u2714")}`);
+        fileSpinner.succeed(`${existingContent ? import_chalk9.default.yellow("~") : import_chalk9.default.green("+")} ${import_chalk9.default.bold(item.file)}`);
         successCount++;
         writtenFiles.push(item.file);
       } catch (err) {
-        console.log(`${prefix}${import_chalk9.default.red("\u2718")} ${import_chalk9.default.bold(item.file)} \u2014 ${import_chalk9.default.red(err.message)}`);
+        fileSpinner.fail(`${import_chalk9.default.bold(item.file)} \u2014 ${err.message}`);
       }
     }
     if (!taskLabel) {
@@ -8196,6 +8294,7 @@ var import_chalk15 = __toESM(require("chalk"));
 var import_child_process5 = require("child_process");
 var fs18 = __toESM(require("fs-extra"));
 var path17 = __toESM(require("path"));
+init_cli_ui();
 var MAX_COMMAND_OUTPUT_CHARS = 5e4;
 var MAX_FIX_FILE_CHARS = 6e4;
 function runCommand(cmd, cwd) {
@@ -8387,16 +8486,17 @@ ${errorSummary}
 ${fileContent}
 
 Output ONLY the complete fixed file content. No markdown fences, no explanations.`;
+    const fixSpinner = startSpinner(`Fixing ${import_chalk15.default.bold(file)} (${fileErrors.length} error(s))...`);
     try {
       const raw = await provider.generate(prompt, getCodeGenSystemPrompt());
       const fixed = raw.replace(/^```\w*\n?/gm, "").replace(/\n?```$/gm, "").trim();
       await getActiveSnapshot()?.snapshotFile(fullPath);
       await fs18.writeFile(fullPath, fixed, "utf-8");
       results.push({ fixed: true, file, explanation: `Fixed ${fileErrors.length} error(s)` });
-      console.log(import_chalk15.default.green(`  \u2714 Auto-fixed: ${file}`));
+      fixSpinner.succeed(`Auto-fixed: ${file}`);
     } catch (err) {
       results.push({ fixed: false, file, explanation: `AI fix failed: ${err.message}` });
-      console.log(import_chalk15.default.yellow(`  \u26A0 Could not auto-fix: ${file}`));
+      fixSpinner.fail(`Could not auto-fix: ${file}`);
     }
   }
   return results;
@@ -11272,6 +11372,7 @@ async function listVcrRecordings(workingDir) {
 }
 
 // cli/pipeline/single-repo.ts
+init_cli_ui();
 async function runSingleRepoPipeline(idea, opts, currentDir, config2) {
   const specProviderName = opts.provider || config2.provider || "gemini";
   const specModelName = opts.model || config2.model || DEFAULT_MODELS[specProviderName];
@@ -11334,7 +11435,7 @@ async function runSingleRepoPipeline(idea, opts, currentDir, config2) {
       console.log(import_chalk25.default.yellow(`  \u26A0 Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
     }
   } else {
-    console.log(import_chalk25.default.yellow("  Constitution : not found \u2014 auto-generating..."));
+    const constitutionSpinner = startSpinner("Constitution not found \u2014 auto-generating...");
     try {
       const constitutionGen = new ConstitutionGenerator(
         createProvider(specProviderName, specApiKey, specModelName)
@@ -11342,9 +11443,9 @@ async function runSingleRepoPipeline(idea, opts, currentDir, config2) {
       const constitutionContent = await constitutionGen.generate(currentDir);
       await constitutionGen.saveConstitution(currentDir, constitutionContent);
       context.constitution = constitutionContent;
-      console.log(import_chalk25.default.green(`  Constitution : \u2714 generated and saved (.ai-spec-constitution.md)`));
+      constitutionSpinner.succeed("Constitution generated and saved (.ai-spec-constitution.md)");
     } catch (err) {
-      console.log(import_chalk25.default.yellow(`  Constitution : \u26A0 auto-generation failed (${err.message}), continuing without it.`));
+      constitutionSpinner.fail(`Constitution auto-generation failed (${err.message}), continuing without it.`);
     }
   }
   let architectureDecision;
@@ -11375,17 +11476,18 @@ async function runSingleRepoPipeline(idea, opts, currentDir, config2) {
   let initialSpec;
   let initialTasks = [];
   runLogger.stageStart("spec_gen", { provider: specProviderName, model: specModelName });
+  const specSpinner = startStage("spec_gen", `Generating spec with ${specProviderName}/${specModelName}...`);
   try {
     if (opts.skipTasks) {
       const { SpecGenerator: SpecGenerator2 } = await Promise.resolve().then(() => (init_spec_generator(), spec_generator_exports));
       const generator = new SpecGenerator2(specProvider);
       initialSpec = await generator.generateSpec(idea, context, architectureDecision);
-      console.log(import_chalk25.default.green("  \u2714 Spec generated."));
+      specSpinner.succeed("Spec generated.");
     } else {
       const result = await generateSpecWithTasks(specProvider, idea, context, architectureDecision);
       initialSpec = result.spec;
       initialTasks = result.tasks;
-      console.log(import_chalk25.default.green(`  \u2714 Spec generated.`));
+      specSpinner.succeed("Spec generated.");
       if (initialTasks.length > 0) {
         console.log(import_chalk25.default.green(`  \u2714 ${initialTasks.length} tasks generated (combined call).`));
       } else {
@@ -11394,8 +11496,8 @@ async function runSingleRepoPipeline(idea, opts, currentDir, config2) {
     }
     runLogger.stageEnd("spec_gen", { taskCount: initialTasks.length });
   } catch (err) {
+    specSpinner.fail(`Spec generation failed: ${err.message}`);
     runLogger.stageFail("spec_gen", err.message);
-    console.error(import_chalk25.default.red("  \u2718 Spec generation failed:"), err);
     process.exit(1);
   }
   let finalSpec;
@@ -11417,7 +11519,9 @@ async function runSingleRepoPipeline(idea, opts, currentDir, config2) {
       console.log(import_chalk25.default.blue("\n[3.4/6] Spec quality assessment..."));
     }
     runLogger.stageStart("spec_assess");
+    const assessSpinner = startStage("spec_assess", "Evaluating spec quality...");
     const assessment = await assessSpec(specProvider, finalSpec, context.constitution ?? void 0);
+    assessSpinner.stop();
     if (assessment) {
       runLogger.stageEnd("spec_assess", { overallScore: assessment.overallScore });
       if (!opts.auto) printSpecAssessment(assessment);
@@ -11509,21 +11613,24 @@ async function runSingleRepoPipeline(idea, opts, currentDir, config2) {
     console.log(import_chalk25.default.blue("\n[DSL] Extracting structured DSL from spec..."));
     console.log(import_chalk25.default.gray(`  Provider: ${specProviderName}/${specModelName}`));
     runLogger.stageStart("dsl_extract");
+    const dslSpinner = startStage("dsl_extract", "Extracting DSL from spec...");
     try {
       const isFrontend = isFrontendDeps(context.dependencies);
-      if (isFrontend) console.log(import_chalk25.default.gray("  Frontend project detected \u2014 using ComponentSpec extractor"));
+      if (isFrontend) {
+        dslSpinner.update("\u{1F517}  Extracting DSL (frontend ComponentSpec mode)...");
+      }
       const dslExtractor = new DslExtractor(specProvider);
       extractedDsl = await dslExtractor.extract(finalSpec, { auto: opts.auto, isFrontend });
       if (extractedDsl) {
         runLogger.stageEnd("dsl_extract", { endpoints: extractedDsl.endpoints?.length ?? 0, models: extractedDsl.models?.length ?? 0 });
-        console.log(import_chalk25.default.green("  \u2714 DSL extracted and validated."));
+        dslSpinner.succeed("DSL extracted and validated.");
       } else {
         runLogger.stageEnd("dsl_extract", { skipped: true });
-        console.log(import_chalk25.default.yellow("  \u26A0 DSL skipped \u2014 codegen will use Spec + Tasks only."));
+        dslSpinner.fail("DSL skipped \u2014 codegen will use Spec + Tasks only.");
       }
     } catch (err) {
       runLogger.stageFail("dsl_extract", err.message);
-      console.log(import_chalk25.default.yellow(`  \u26A0 DSL extraction error: ${err.message} \u2014 continuing without DSL.`));
+      dslSpinner.fail(`DSL extraction error: ${err.message} \u2014 continuing without DSL.`);
     }
   }
   if (extractedDsl && !opts.auto && !opts.fast && !opts.skipDsl) {
@@ -11698,6 +11805,7 @@ async function runSingleRepoPipeline(idea, opts, currentDir, config2) {
   if (!opts.skipReview) {
     console.log(import_chalk25.default.blue("\n[9/9] Automated code review (3-pass: architecture + implementation + impact/complexity)..."));
     runLogger.stageStart("review");
+    const reviewSpinner = startStage("review", "Running 3-pass code review...");
     const reviewer = new CodeReviewer(specProvider, workingDir);
     const savedSpec = await fs25.readFile(specFile, "utf-8");
     if (codegenMode === "api" && generatedFiles.length > 0) {
@@ -11705,6 +11813,7 @@ async function runSingleRepoPipeline(idea, opts, currentDir, config2) {
     } else {
       reviewResult = await reviewer.reviewCode(savedSpec, specFile);
     }
+    reviewSpinner.succeed("Code review complete.");
     runLogger.stageEnd("review");
     const complianceScore = extractComplianceScore(reviewResult);
     const missingCount = extractMissingCount(reviewResult);