ai-spec-dev 0.25.0 → 0.28.1

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run:*)",
+      "Bash(python3 -c \":*)",
+      "Bash(grep -E \"^./\\\\w+/|^./\\\\w+\\\\.ts$\")",
+      "Bash(wc -l core/*.ts prompts/*.ts)"
+    ]
+  }
+}

package/README.md

@@ -2,12 +2,9 @@
 
 > AI 驱动的功能开发编排工具 — 从一句话需求到可运行代码的完整流水线，支持单 Repo 及多 Repo 跨端联动
 
-[![Version](https://img.shields.io/badge/version-0.25.0-blue)](https://github.com/hzhongzhong/ai-spec)
-[![Author](https://img.shields.io/badge/author-hzhongzhong-green)](https://github.com/hzhongzhong)
-
 **单 Repo 模式：**
 ```
-需求描述 → 项目宪法 → 项目感知 → Spec+Tasks → 交互式润色(Diff预览) → Spec质量预评估 → Approval Gate → DSL提取+校验 → Git 隔离 → 代码生成(同层并行) → TDD测试(--tdd) / 测试骨架 → 错误反馈自动修复 → 2-pass 代码审查 → 经验积累(宪法§9)
+需求描述 → 项目宪法 → 项目感知 → Spec+Tasks → 交互式润色(Diff预览) → Spec质量预评估 → Approval Gate → DSL提取+校验 → Git 隔离 → 代码生成(同层并行) → TDD测试(--tdd) / 测试骨架 → 错误反馈自动修复 → 3-pass 代码审查 → 经验积累(宪法§9)
 ```
 
 **多 Repo 模式（工作区）：**
@@ -94,9 +91,16 @@ ai-spec create "给用户模块增加登录功能"
         [cycle 2/2] Running tests: npm test
         ✔ Tests passed.
         ✔ All checks passed after 2 cycle(s).
-[9/9]   Automated code review (file-based)...
+[9/9]   Automated code review (3-pass: architecture + implementation + impact/complexity)...
+        Pass 1/3: Architecture review...
+        Pass 2/3: Implementation review...
+        Pass 3/3: Impact & complexity assessment...
+        🌊 影响等级: 中  🧮 复杂度等级: 低
 ─── Knowledge Memory ─────────────────────────────
         ✔ 2 lesson(s) appended to constitution (§9).
+  Run ID: 20260326-143022-ab3f in 94.3s · 8 files written
+  Log   : .ai-spec-logs/20260326-143022-ab3f.json
+  To undo changes: ai-spec restore 20260326-143022-ab3f
 ```
 
 ---
@@ -153,7 +157,8 @@ ai-spec update [change]     增量更新：修改现有 Spec → 重提取 DSL
 ai-spec learn [lesson]      零摩擦知识注入：直接将工程决策或教训写入宪法 §9（无需运行 review）
 ai-spec export              DSL → OpenAPI 3.1.0 YAML/JSON（可导入 Postman / Swagger UI / openapi-generator）
 ai-spec mock                从 DSL 生成 Mock Server / 前端 Proxy 配置 / MSW Handlers（联调利器）
-ai-spec review [file]       对当前 git diff 运行 2-pass AI 代码审查（架构层 + 实现层），并打印评分趋势
+ai-spec review [file]       对当前 git diff 运行 3-pass AI 代码审查（架构层 + 实现层 + 影响面/复杂度），并打印评分趋势
+ai-spec restore <runId>     回滚指定 run 修改的所有文件至原始状态（配合 Run ID 使用）
 ai-spec model               交互式切换 AI provider / model，写入 .ai-spec.json
 ai-spec config              查看 / 修改 / 重置项目级配置
 ai-spec workspace init      初始化多 Repo 工作区（生成 .ai-spec-workspace.json）

package/RELEASE_LOG.md

@@ -2,6 +2,108 @@
 
 ---
 
+## [0.28.0] 2026-03-26 — 三 Pass 代码审查（影响面评估 + 代码复杂度评估）
+
+### 新增内容
+
+**Feature — Review Pass 3：影响面评估 + 代码复杂度评估**
+- 文件：`prompts/codegen.prompt.ts`（新增 `reviewImpactComplexitySystemPrompt`）、`core/reviewer.ts`（两 Pass 升级为三 Pass）
+- 原有两 Pass 不变；新增第三 Pass 专注于两个前两 Pass 刻意跳过的维度：
+
+  **影响面评估 (Impact Assessment)**
+  - 直接影响文件列表
+  - 间接影响范围（哪些模块/消费方/下游服务受影响）
+  - 破坏性变更检测（接口签名变更、Schema 变更、配置变更、导出重命名）
+  - 影响等级：低 / 中 / 高（附理由）
+
+  **代码复杂度评估 (Complexity Assessment)**
+  - 认知复杂度热点（最难理解的 1-3 个函数，说明为什么复杂）
+  - 耦合度分析（依赖注入 vs 硬编码、循环依赖风险）
+  - 可维护性风险（魔法数字、业务逻辑藏在生命周期钩子里、隐式时序耦合）
+  - 复杂度等级：低 / 中 / 高（附理由）
+
+- `ReviewHistoryEntry` 新增 `impactLevel` 和 `complexityLevel` 字段，历史记录持久化到 `.ai-spec-reviews.json`
+- CLI banner 更新为 `3-pass: architecture + implementation + impact/complexity`
+
+---
+
+## [0.27.0] 2026-03-26 — 三项工业化底座（Provider 可靠性、文件快照回滚、RunId 结构化日志）
+
+### 新增内容
+
+**Feature #1 — Provider 统一可靠性封装**
+- 新文件：`core/provider-utils.ts`
+- 新增 `withReliability(fn, opts)` 包装器，覆盖所有 provider 的 `generate()` 调用（Gemini、Claude、OpenAI-compatible、MiMo）
+- 能力：超时（默认 90s）+ 自动重试（2 次，退避 2s/6s）+ 结构化错误分类（`auth` / `rate_limit` / `timeout` / `network` / `provider`）
+- Auth 错误（401/403）不重试，避免无效消耗；限流（429）和网络抖动均自动重试并打印黄色警告
+
+**Feature #2 — 文件写入快照与一键回滚**
+- 新文件：`core/run-snapshot.ts`
+- 每次 `create` 运行前，自动备份将被覆盖的文件到 `.ai-spec-backup/<runId>/`
+- 新增命令：`ai-spec restore <runId>`，将本次运行修改的所有文件恢复到原始状态
+- 涵盖 codegen 写入（`code-generator.ts`）和错误修复写入（`error-feedback.ts`）两个落盘点
+- 纯新建文件不备份（无需恢复）；同一文件多次写入只备份一次（保留原始版本）
+
+**Feature #3 — RunId + 结构化执行日志**
+- 新文件：`core/run-logger.ts`
+- 每次运行生成唯一 RunId（格式：`YYYYMMDD-HHMMSS-xxxx`），打印在 banner 下方
+- 执行阶段、写入文件、错误信息实时写入 `.ai-spec-logs/<runId>.json`
+- 运行结束时打印摘要：RunId + 耗时 + 写入文件数 + 错误数 + 日志路径
+- 有文件被修改时自动提示：`To undo changes: ai-spec restore <runId>`
+
+---
+
+## [0.26.0] 2026-03-26 — 三项稳定性修复（多仓库 review、并行 batch 容错、tasks JSON 损坏）
+
+### 修复内容
+
+**Fix #1 — 多仓库模式代码审查 git diff 为空**
+- 文件：`cli/index.ts` → `runSingleRepoPipelineInWorkspace`
+- 问题：`reviewer.reviewCode()` 内部调用 `execSync("git diff")`，运行在 `process.cwd()`（CLI 启动目录）而非当前 repo 的 `workingDir`（可能是 worktree 路径），导致 diff 为空或错误，审查结果没有意义。
+- 修复：在 `reviewCode` 调用前后加 `process.chdir(workingDir)` / `process.chdir(originalDir)`，与单仓库模式保持一致。
+
+**Fix #2 — 并行 batch 单任务抛异常导致整层崩溃**
+- 文件：`core/code-generator.ts` → `runApiModeWithTasks` batch 执行循环
+- 问题：`Promise.all(batchResultPromises)` 中任意一个 `executeTask` 抛出未捕获异常（磁盘满、mkdir 失败、provider 超时），整个 `Promise.all` 立即 reject，该层剩余所有任务都被丢弃，没有任何降级处理。
+- 修复：每个 `executeTask` 调用后追加 `.catch((err) => ...)` 返回失败结果对象，确保单任务失败只影响自身，不中断同批次其他任务。
+
+**Fix #3 — `loadTasksForSpec` 遇到损坏的 JSON 文件直接崩溃**
+- 文件：`core/task-generator.ts` → `loadTasksForSpec`
+- 问题：如果上次运行中途中断导致 `*-tasks.json` 是不完整的 JSON，`fs.readJson()` 抛出 parse 错误，没有任何 try-catch 包裹，用户看到的是裸 JS 异常而非友好提示。
+- 修复：加 try-catch，catch 块打印"Tasks file corrupt，请重新运行 `ai-spec tasks`"并返回 `null`（触发重新生成），不再崩溃。
+
+---
+
+## [0.25.0] 2026-03-26 — 三项上下文提取修复（HTTP import、分页示例、工具崩溃误判）
+
+### 修复内容
+
+**Fix #1 — HTTP import 幻觉防护失效**
+- 文件：`core/frontend-context-loader.ts` → `httpImportRegex`
+- 问题：旧正则只匹配 `axios`、`ky`、`@/` 开头的路径。使用 `import request from '@/utils/request'` 等自定义封装的项目（极其常见）提取结果为 `undefined`，AI 会自由发挥 import 路径。
+- 修复：扩展匹配范围：
+  - 所有项目别名：`@/`、`~/`、`#/`、`@@/`
+  - 包含 http/request/fetch/client/api 关键词的相对路径
+  - 完整 HTTP 库列表：axios、ky、ky-universal、undici、node-fetch、cross-fetch、got、superagent、alova、openapi-fetch
+  - 排除 `import type` 语句（它们不是运行时 import）
+
+**Fix #2 — 分页示例提取正则永远不匹配**
+- 文件：`core/frontend-context-loader.ts` → 分页提取块
+- 问题：
+  1. 接口正则用 `[^}]*` 匹配接口体，遇到嵌套对象 `{ field: { ... } }` 立即截断
+  2. 函数正则用 `\n\}` 匹配闭合括号，但缩进的 `  }` 永远不匹配
+  3. 只处理 `export function`，遗漏了现代代码中更常见的 `export const x = () =>` 写法
+- 修复：完全重写为**逐行 + 括号深度计数器**的两步提取法：
+  - Step 1：找到带分页字段（pageIndex/pageSize/page/…）的接口，用深度计数捕获完整块（支持嵌套对象）
+  - Step 2：找到引用该接口的导出函数（同时支持 `export function` 和 `export const = () =>`），同样用深度计数捕获函数体
+
+**Fix #3 — `isToolCrash` 把用户代码错误当工具崩溃**
+- 文件：`core/error-feedback.ts`
+- 问题：旧判断条件是"输出包含 ReferenceError/TypeError 且包含 node_modules"。TypeScript 的自动修复测试运行时，测试框架的 stack trace 中也会包含 node_modules，导致用户自己代码里的 ReferenceError 被误判为工具崩溃跳过。
+- 修复：改为精确判断：必须同时满足（1）存在未捕获 JS 错误，且（2）stack trace 中有 `at … node_modules/…` 帧——即错误起源于工具二进制本身，而不仅仅是"输出中某处出现了 node_modules"。
+
+---
+
 ## [0.24.0] 2026-03-25 — 四项质量修复（lesson 计数、export default、impliesRegistration、依赖拓扑排序）
 
 ### 修复内容

package/cli/index.ts

@@ -72,6 +72,8 @@ import {
 } from "../core/mock-server-generator";
 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";
 
 // ─── Config File ──────────────────────────────────────────────────────────────
 
@@ -293,6 +295,17 @@ program
       codegenModel: codegenModelName,
     });
 
+    // ── Run tracking ──────────────────────────────────────────────────────────────
+    const runId = generateRunId();
+    console.log(chalk.gray(`  Run ID: ${runId}`));
+    const runSnapshot = new RunSnapshot(currentDir, runId);
+    setActiveSnapshot(runSnapshot);
+    const runLogger = new RunLogger(currentDir, runId, {
+      provider: specProviderName,
+      model: specModelName,
+    });
+    setActiveLogger(runLogger);
+
     // ── Step 1: Context ───────────────────────────────────────────────────────
     console.log(chalk.blue("[1/6] Loading project context..."));
     const loader = new ContextLoader(currentDir);
@@ -606,7 +619,7 @@ program
     // ── Step 9: Code Review ───────────────────────────────────────────────────
     let reviewResult = "";
     if (!opts.skipReview) {
-      console.log(chalk.blue("\n[9/9] Automated code review (2-pass: architecture + implementation)..."));
+      console.log(chalk.blue("\n[9/9] Automated code review (3-pass: architecture + implementation + impact/complexity)..."));
       const reviewer = new CodeReviewer(specProvider, currentDir);
       const savedSpec = await fs.readFile(specFile, "utf-8");
 
@@ -629,6 +642,7 @@ program
     }
 
     // ── Done ──────────────────────────────────────────────────────────────────
+    runLogger.finish();
     console.log(chalk.bold.green("\n✔ All done!"));
     console.log(chalk.gray(`  Spec        : ${specFile}`));
     if (savedDslFile) console.log(chalk.gray(`  DSL         : ${savedDslFile}`));
@@ -639,6 +653,10 @@ program
     if (workingDir !== currentDir) {
       console.log(chalk.gray(`  Run \`cd ${workingDir}\` to enter the worktree.`));
     }
+    runLogger.printSummary();
+    if (runSnapshot.fileCount > 0) {
+      console.log(chalk.gray(`  To undo changes: ai-spec restore ${runId}`));
+    }
   });
 
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -1252,7 +1270,16 @@ async function runSingleRepoPipelineInWorkspace(opts: {
     console.log(chalk.blue(`  [${repoName}] Running code review...`));
     try {
       const reviewer = new CodeReviewer(specProvider);
-      const reviewResult = await reviewer.reviewCode(finalSpec);
+      // git diff must run in the repo's working directory (may be a worktree),
+      // not in wherever the CLI was invoked from.
+      const originalDir = process.cwd();
+      let reviewResult: string;
+      try {
+        process.chdir(workingDir);
+        reviewResult = await reviewer.reviewCode(finalSpec);
+      } finally {
+        process.chdir(originalDir);
+      }
       await accumulateReviewKnowledge(specProvider, repoAbsPath, reviewResult);
       console.log(chalk.green(`    Code review complete.`));
     } catch (err) {
@@ -2127,6 +2154,27 @@ program
     }
   });
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: restore
+// ═══════════════════════════════════════════════════════════════════════════════
+
+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.`));
+    }
+  });
+
 // Show welcome screen when invoked with no arguments
 if (process.argv.length <= 2) {
   (async () => {

package/core/code-generator.ts

@@ -8,6 +8,8 @@ import { getCodeGenSystemPrompt } from "../prompts/codegen.prompt";
 import { SpecTask, loadTasksForSpec, updateTaskStatus } from "./task-generator";
 import { loadDslForSpec, buildDslContextSection } from "./dsl-extractor";
 import { loadFrontendContext, buildFrontendContextSection } from "./frontend-context-loader";
+import { getActiveSnapshot } from "./run-snapshot";
+import { getActiveLogger } from "./run-logger";
 
 // ─── Shared Config Helper ───────────────────────────────────────────────────
 
@@ -720,7 +722,15 @@ Output ONLY a valid JSON array:
 
       for (const batch of taskBatches) {
         const batchIsParallel = batch.length > 1;
-        const batchResultPromises = batch.map((task) => executeTask(task, batchIsParallel));
+        // Wrap each task in .catch() so a single unexpected failure (disk full,
+        // provider timeout, mkdir error) degrades gracefully instead of rejecting
+        // the entire Promise.all and aborting all sibling tasks in the batch.
+        const batchResultPromises = batch.map((task) =>
+          executeTask(task, batchIsParallel).catch((err): TaskResult => {
+            console.log(chalk.yellow(`  ⚠ ${task.id} threw unexpectedly: ${(err as Error).message}`));
+            return { task, files: [], createdFiles: [], success: 0, total: 0, impliesRegistration: false };
+          })
+        );
         const batchResults = await Promise.all(batchResultPromises);
         layerResults.push(...batchResults);
         // Update cache after each batch so the next batch sees the exports.
@@ -838,8 +848,10 @@ ${existingContent || "Output only the complete file content."}`;
       try {
         const raw = await this.provider.generate(codePrompt, systemPrompt);
         const fileContent = stripCodeFences(raw);
+        await getActiveSnapshot()?.snapshotFile(fullPath);
         await fs.ensureDir(path.dirname(fullPath));
         await fs.writeFile(fullPath, fileContent, "utf-8");
+        getActiveLogger()?.fileWritten(item.file);
         console.log(`${prefix}${existingContent ? chalk.yellow("~") : chalk.green("+")} ${chalk.bold(item.file)} ${chalk.green("✔")}`);
         successCount++;
         writtenFiles.push(item.file);

package/core/error-feedback.ts

@@ -6,6 +6,7 @@ import { AIProvider } from "./spec-generator";
 import { getCodeGenSystemPrompt } from "../prompts/codegen.prompt";
 import { SpecDSL } from "./dsl-types";
 import { buildDslContextSection } from "./dsl-extractor";
+import { getActiveSnapshot } from "./run-snapshot";
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -242,6 +243,7 @@ Output ONLY the complete fixed file content. No markdown fences, no explanations
     try {
       const raw = await provider.generate(prompt, getCodeGenSystemPrompt());
       const fixed = raw.replace(/^```\w*\n?/gm, "").replace(/\n?```$/gm, "").trim();
+      await getActiveSnapshot()?.snapshotFile(fullPath);
       await fs.writeFile(fullPath, fixed, "utf-8");
       results.push({ fixed: true, file, explanation: `Fixed ${fileErrors.length} error(s)` });
       console.log(chalk.green(`  ✔ Auto-fixed: ${file}`));
@@ -300,13 +302,22 @@ export async function runErrorFeedback(
       console.log(chalk.gray(`\n  [cycle ${cycle}/${maxCycles}] Type-check: ${buildCmd}`));
       const buildResult = runCommand(buildCmd, workingDir);
       if (!buildResult.success) {
-        // Detect tool crash (ReferenceError / TypeError inside node_modules) —
-        // this means the type-check tool itself is broken (e.g. vue-tsc version
-        // incompatibility), NOT a user code error. Skip silently instead of
-        // feeding garbage into the auto-fix loop.
-        const isToolCrash =
-          /ReferenceError:|TypeError:|SyntaxError:/.test(buildResult.output) &&
-          buildResult.output.includes("node_modules");
+        // Detect tool crash — the type-check binary itself threw an unhandled
+        // exception (e.g. vue-tsc / tsc version incompatibility).
+        //
+        // Two conditions must BOTH be true:
+        //   1. The output contains an uncaught JS error (ReferenceError, TypeError, …)
+        //   2. The stack trace has at least one frame inside node_modules,
+        //      meaning the crash originated in the tool binary, not user code.
+        //
+        // TypeScript compilation errors from user code are formatted as
+        //   "src/foo.ts:10:5 - error TS2345: …"
+        // and do NOT produce "at …" stack frames, so they are never misclassified.
+        const hasUncaughtError = /ReferenceError:|TypeError:|SyntaxError:/.test(buildResult.output);
+        const hasToolStackFrame = buildResult.output
+          .split("\n")
+          .some((l) => l.trim().startsWith("at ") && l.includes("node_modules"));
+        const isToolCrash = hasUncaughtError && hasToolStackFrame;
         if (isToolCrash) {
           console.log(chalk.yellow(`  ⚠ Type-check tool crashed (possible version incompatibility). Skipping.`));
           console.log(chalk.gray(`    Tip: run \`${buildCmd}\` manually to investigate.`));

package/core/frontend-context-loader.ts

@@ -299,10 +299,16 @@ export async function loadFrontendContext(
       }
     }
 
-    // Extract the exact HTTP client import line from an existing API file
+    // Extract the exact HTTP client import line from an existing API file.
     // e.g. "import request from '@/utils/http'" or "import axios from 'axios'"
     // This is ground truth — prevents the AI from inventing a different import path.
-    const httpImportRegex = /^import\s+(?:\w+|\{[^}]+\})\s+from\s+['"](@\/[^'"]+|axios|ky)['"]/m;
+    //
+    // Matches (in priority order):
+    //   1. Project alias imports: @/, ~/, #/, @@/ (common in Vite/webpack projects)
+    //   2. Named HTTP libraries: axios, ky, undici, node-fetch, etc.
+    //   3. Relative imports whose path contains http-utility keywords
+    const httpImportRegex =
+      /^import(?!\s+type)\s+(?:[\w*]+|\{[^}]+\})\s+from\s+['"]((?:@{1,2}|~|#)[/\\][^'"]+|\.{1,2}\/[^'"]*(?:http|request|fetch|client|api)[^'"]*|axios|ky(?:-universal)?|undici|node-fetch|cross-fetch|got|superagent|alova|openapi-fetch)['"]/im;
     for (const relPath of ctx.existingApiFiles.slice(0, 5)) {
       try {
         const content = await fs.readFile(path.join(projectRoot, relPath), "utf-8");
@@ -316,36 +322,78 @@ export async function loadFrontendContext(
       }
     }
 
-    // Pagination pattern extraction — find a real paginated list function from the existing codebase.
-    // Scans API files for interfaces/params that contain pagination field names,
-    // then extracts the matching function as ground truth for the AI to copy.
+    // Pagination pattern extraction — line-based scan for robustness.
+    //
+    // Two-step approach:
+    //   1. Find an interface/type whose name suggests a request/query shape AND
+    //      whose body contains at least one pagination field name.
+    //      Uses line-by-line scanning with a brace-depth counter so nested
+    //      objects inside the interface don't confuse the closing-brace match.
+    //   2. Find the first exported function (regular or arrow) that references
+    //      that interface type, then capture its body the same way.
+    //
+    // Handles both `export function` and `export const x = (...) =>` styles.
     const paginationFieldNames = ["pageIndex", "pageSize", "pageNum", "current", "page", "size", "offset", "limit"];
-    const paginationInterfaceRegex = new RegExp(
-      `(?:interface|type)\\s+(\\w*(?:Params|Query|Request|Filter|Page)\\w*)\\s*\\{[^}]*\\b(?:${paginationFieldNames.join("|")})\\b[^}]*\\}`,
-      "s"
-    );
-    const apiExportFnRegex = /export\s+(?:async\s+)?function\s+\w+\s*\([^)]*\)[^{]*\{[\s\S]*?\n\}/g;
+
     for (const relPath of ctx.existingApiFiles) {
-      // Skip type-only and index files
       if (/types?\.ts$|index\.ts$/.test(relPath)) continue;
       try {
         const content = await fs.readFile(path.join(projectRoot, relPath), "utf-8");
-        // Only process files that have pagination field names at all
         if (!paginationFieldNames.some((f) => content.includes(f))) continue;
-        // Check this file has an interface with pagination fields
-        const interfaceMatch = content.match(paginationInterfaceRegex);
-        if (!interfaceMatch) continue;
-        // Find the first exported function that uses this interface
-        const interfaceName = interfaceMatch[1];
-        const fnRegex = new RegExp(
-          `export\\s+(?:async\\s+)?function\\s+\\w+\\s*\\(\\s*\\w+\\s*:\\s*${interfaceName}[^)]*\\)[\\s\\S]*?\\n\\}`,
-          ""
-        );
-        const fnMatch = content.match(fnRegex);
-        if (fnMatch) {
-          ctx.paginationExample = `// From ${relPath}\n${interfaceMatch[0]}\n\n${fnMatch[0]}`;
+
+        const lines = content.split("\n");
+
+        // ── Step 1: locate a pagination interface/type ──────────────────────
+        let interfaceName = "";
+        let interfaceBlock = "";
+
+        for (let i = 0; i < lines.length; i++) {
+          const m = lines[i].match(/(?:interface|type)\s+(\w*(?:Params|Query|Request|Filter|Page)\w*)\s*[={<]/);
+          if (!m) continue;
+
+          // Capture the full block via brace-depth counter
+          const blockLines: string[] = [];
+          let depth = 0;
+          for (let j = i; j < Math.min(i + 40, lines.length); j++) {
+            blockLines.push(lines[j]);
+            depth += (lines[j].match(/\{/g) ?? []).length;
+            depth -= (lines[j].match(/\}/g) ?? []).length;
+            if (depth === 0 && j > i) break;
+          }
+
+          const blockText = blockLines.join("\n");
+          // Only use interfaces that actually contain a pagination field
+          if (!paginationFieldNames.some((f) => new RegExp(`\\b${f}\\b`).test(blockText))) continue;
+
+          interfaceName = m[1];
+          interfaceBlock = blockText;
+          break;
+        }
+
+        if (!interfaceName) continue;
+
+        // ── Step 2: find an exported function that uses this interface ───────
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i];
+          // Match both `export function` and `export const x = (`
+          if (!/export\s+(async\s+)?(function|const)/.test(line)) continue;
+          if (!line.includes(interfaceName)) continue;
+
+          // Capture function body with brace-depth counter (max 30 lines)
+          const fnLines: string[] = [];
+          let depth = 0;
+          for (let j = i; j < Math.min(i + 30, lines.length); j++) {
+            fnLines.push(lines[j]);
+            depth += (lines[j].match(/\{/g) ?? []).length;
+            depth -= (lines[j].match(/\}/g) ?? []).length;
+            if (depth === 0 && j > i) break;
+          }
+
+          ctx.paginationExample = `// From ${relPath}\n${interfaceBlock}\n\n${fnLines.join("\n")}`;
           break;
         }
+
+        if (ctx.paginationExample) break;
       } catch {
         // skip
       }

package/core/provider-utils.ts

@@ -0,0 +1,90 @@
+import chalk from "chalk";
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+// ─── Error Classification ──────────────────────────────────────────────────────
+
+export type ProviderErrorKind = "auth" | "rate_limit" | "timeout" | "network" | "provider";
+
+export class ProviderError extends Error {
+  constructor(
+    message: string,
+    public readonly kind: ProviderErrorKind,
+    public readonly originalError?: unknown
+  ) {
+    super(message);
+    this.name = "ProviderError";
+  }
+}
+
+function classifyError(err: unknown, label: string): ProviderError {
+  const e = err as Error & { status?: number; code?: string; response?: { status?: number } };
+  const status = e.status ?? e.response?.status;
+
+  if (status === 401 || status === 403)
+    return new ProviderError(`Auth error — check your API key (${label})`, "auth", err);
+  if (status === 429)
+    return new ProviderError(`Rate limit hit (${label}) — try again later or switch provider`, "rate_limit", err);
+  if ((e as Error & { _timeout?: boolean })._timeout || e.message?.toLowerCase().includes("timed out"))
+    return new ProviderError(`Request timed out (${label})`, "timeout", err);
+  if (e.code === "ECONNRESET" || e.code === "ENOTFOUND" || e.code === "ECONNREFUSED")
+    return new ProviderError(`Network error — check connection/proxy (${label}): ${e.message}`, "network", err);
+  return new ProviderError(`Provider error (${label}): ${e.message}`, "provider", err);
+}
+
+function isRetryable(err: unknown): boolean {
+  const e = err as Error & { status?: number; code?: string; response?: { status?: number } };
+  const status = e.status ?? e.response?.status;
+  if (status === 401 || status === 403) return false; // wrong key — retrying won't help
+  if (status === 429 || (status !== undefined && status >= 500)) return true;
+  if (e.code === "ECONNRESET" || e.code === "ENOTFOUND" || e.code === "ECONNREFUSED") return true;
+  if (e.message?.toLowerCase().includes("timed out")) return true;
+  return true; // unknown errors: retry once
+}
+
+// ─── Reliability Wrapper ───────────────────────────────────────────────────────
+
+/**
+ * Wrap any async AI provider call with:
+ *   - Configurable timeout (default 90s)
+ *   - Automatic retry with exponential backoff (default 2 retries)
+ *   - Structured error classification (auth / rate_limit / timeout / network / provider)
+ */
+export async function withReliability<T>(
+  fn: () => Promise<T>,
+  opts?: {
+    retries?: number;
+    timeoutMs?: number;
+    label?: string;
+    onRetry?: (attempt: number, err: unknown) => void;
+  }
+): Promise<T> {
+  const { retries = 2, timeoutMs = 90_000, label = "AI call", onRetry } = opts ?? {};
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await Promise.race([
+        fn(),
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () => reject(Object.assign(new Error(`timed out after ${timeoutMs / 1000}s`), { _timeout: true })),
+            timeoutMs
+          )
+        ),
+      ]);
+    } catch (err) {
+      if (!isRetryable(err) || attempt === retries) {
+        throw classifyError(err, label);
+      }
+      const waitMs = attempt === 0 ? 2_000 : 6_000;
+      console.warn(
+        chalk.yellow(`  ⚠ ${label} failed (attempt ${attempt + 1}/${retries + 1}), retrying in ${waitMs / 1000}s`) +
+          chalk.gray(` — ${(err as Error).message}`)
+      );
+      onRetry?.(attempt + 1, err);
+      await sleep(waitMs);
+    }
+  }
+  /* istanbul ignore next */
+  throw new Error("unreachable");
+}