failproofai 0.0.2-beta.7 → 0.0.2-beta.9

package/.next/standalone/docs/zh/testing.mdx

@@ -0,0 +1,260 @@
+---
+title: 测试
+description: "单元测试、端到端测试与测试辅助工具"
+icon: flask-vial
+---
+
+failproofai 包含两套测试套件：**单元测试**（快速、使用 mock）和**端到端测试**（真实子进程调用）。
+
+---
+
+## 运行测试
+
+```bash
+# 单次运行所有单元测试
+bun run test:run
+
+# 以监视模式运行单元测试
+bun run test
+
+# 运行端到端测试（需要配置环境，详见下文）
+bun run test:e2e
+
+# 仅进行类型检查，不构建
+bunx tsc --noEmit
+
+# 代码检查
+bun run lint
+```
+
+---
+
+## 单元测试
+
+单元测试位于 `__tests__/` 目录，使用 [Vitest](https://vitest.dev) 和 `happy-dom`。
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # 每个内置策略的逻辑测试
+    hooks-config.test.ts          # 配置加载与作用域合并
+    policy-evaluator.test.ts      # 参数注入与评估顺序
+    custom-hooks-registry.test.ts # globalThis 注册表的增删查
+    custom-hooks-loader.test.ts   # ESM 加载器、传递性导入、错误处理
+    manager.test.ts               # 安装/移除/列出操作
+  components/
+    sessions-list.test.tsx        # 会话列表组件
+    project-list.test.tsx         # 项目列表组件
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### 编写策略单元测试
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## 端到端测试
+
+端到端测试将真实的 `failproofai` 二进制文件作为子进程调用，通过 stdin 传入 JSON payload，并对 stdout 输出和退出码进行断言。这能够测试 Claude Code 所使用的完整集成路径。
+
+### 环境配置
+
+端到端测试直接从仓库源码运行二进制文件。在首次运行前，需要构建自定义 hook 文件从 `'failproofai'` 导入时所使用的 CJS 包：
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+然后运行测试：
+
+```bash
+bun run test:e2e
+```
+
+每当修改公共 hook API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts` 或 `src/hooks/policy-types.ts`）后，请重新构建 `dist/`。
+
+### 端到端测试结构
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # 启动二进制进程，传入 payload JSON，捕获退出码 + stdout + stderr
+    fixture-env.ts      # 为每个测试创建包含配置文件的隔离临时目录
+    payloads.ts         # 符合 Claude 格式的各事件类型 payload 工厂函数
+  hooks/
+    builtin-policies.e2e.test.ts   # 每个内置策略的真实子进程测试
+    custom-hooks.e2e.test.ts       # 自定义 hook 的加载与评估
+    config-scopes.e2e.test.ts      # 跨项目/本地/全局的配置合并
+    policy-params.e2e.test.ts      # 各参数化策略的参数注入
+```
+
+### 使用端到端测试辅助工具
+
+**`FixtureEnv`** - 每个测试的隔离环境：
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - 临时目录；作为 payload.cwd 传入以加载 .failproofai/policies-config.json
+// env.home   - 隔离的 home 目录；不会读取真实的 ~/.failproofai
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` 会自动注册 `afterEach` 清理回调。
+
+**`runHook`** - 调用二进制文件：
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** - 现成的 payload 工厂函数：
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### 编写端到端测试
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // allow → 空 stdout
+  });
+});
+```
+
+### 端到端响应格式
+
+| 决策 | 退出码 | stdout |
+|----------|-----------|--------|
+| `PreToolUse` 拒绝 | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` 拒绝 | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| 指令（非 Stop） | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop 指令 | `2` | stdout 为空；原因输出至 stderr |
+| 允许 | `0` | 空字符串 |
+
+### Vitest 配置
+
+端到端测试使用 `vitest.config.e2e.mts`，配置如下：
+
+- `environment: "node"` - 无需浏览器全局变量
+- `pool: "forks"` - 真正的进程隔离（测试会派生子进程）
+- `testTimeout: 20_000` - 每个测试 20 秒超时（含二进制启动和 hook 评估时间）
+
+使用 `forks` 池至关重要：基于线程的 worker 共享 `globalThis`，可能干扰需要派生子进程的测试。基于进程的 forks 模式可避免此问题。
+
+---
+
+## 持续集成
+
+在合并前，必须通过完整的 CI 运行（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）。端到端测试套件作为独立的 CI 任务并行运行。
+
+完整的合并前检查清单请参阅 [Contributing](../CONTRIBUTING.md)。

package/.next/standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.2-beta.7",
+  "version": "0.0.2-beta.9",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs"
@@ -32,7 +32,12 @@
     "preuninstall": "node scripts/preuninstall.mjs",
     "prepare": "bun run build",
     "test:e2e": "vitest run --config vitest.config.e2e.mts",
-    "test:e2e:watch": "vitest --config vitest.config.e2e.mts"
+    "test:e2e:watch": "vitest --config vitest.config.e2e.mts",
+    "translate": "bun scripts/translate-docs/cli.ts",
+    "translate:readme": "bun scripts/translate-docs/cli.ts --readme-only",
+    "translate:docs": "bun scripts/translate-docs/cli.ts --docs-only",
+    "translate:dry-run": "bun scripts/translate-docs/cli.ts --dry-run",
+    "translate:validate": "bun scripts/translate-docs/cli.ts --validate"
   },
   "keywords": [
     "claude",
@@ -85,6 +90,7 @@
     "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.1.18",
     "typescript": "^6.0.2",
+    "@anthropic-ai/sdk": "^0.39.0",
     "vitest": "^4.0.18"
   },
   "dependencies": {

package/.next/standalone/scripts/translate-docs/cache.ts

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CacheEntry, TranslationCache } from "./types";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CACHE_FILE = join(__dirname, ".translation-cache.json");
+
+export function contentHash(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+export function readCache(): TranslationCache {
+  if (!existsSync(CACHE_FILE)) {
+    return { sourceHash: "", lastUpdated: "", translations: {} };
+  }
+  try {
+    return JSON.parse(readFileSync(CACHE_FILE, "utf-8"));
+  } catch {
+    return { sourceHash: "", lastUpdated: "", translations: {} };
+  }
+}
+
+export function writeCache(cache: TranslationCache): void {
+  cache.lastUpdated = new Date().toISOString();
+  writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2));
+}
+
+export function getCacheKey(sourcePath: string, lang: string): string {
+  return `${sourcePath}::${lang}`;
+}
+
+export function isCached(
+  cache: TranslationCache,
+  sourcePath: string,
+  lang: string,
+  sourceContent: string,
+): boolean {
+  const key = getCacheKey(sourcePath, lang);
+  const entry = cache.translations[key];
+  if (!entry) return false;
+  return entry.sourceHash === contentHash(sourceContent);
+}
+
+export function setCacheEntry(
+  cache: TranslationCache,
+  sourcePath: string,
+  lang: string,
+  sourceContent: string,
+  inputTokens: number,
+  outputTokens: number,
+): void {
+  const key = getCacheKey(sourcePath, lang);
+  cache.translations[key] = {
+    sourceHash: contentHash(sourceContent),
+    targetLang: lang,
+    translatedAt: new Date().toISOString(),
+    inputTokens,
+    outputTokens,
+  };
+}

package/.next/standalone/scripts/translate-docs/cli.ts

@@ -0,0 +1,357 @@
+#!/usr/bin/env bun
+import { parseArgs } from "node:util";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LANGUAGES, getLanguagesByTier, getLanguageByCode, getModelForTier } from "./config";
+import { getEnglishMdxPages, translateMdxPage } from "./mdx-translator";
+import { translateReadme } from "./readme-translator";
+import { updateDocsJson, readDocsConfig } from "./mintlify-nav";
+import { readCache, writeCache, isCached, setCacheEntry } from "./cache";
+import type { TranslationResult } from "./types";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DOCS_DIR = join(__dirname, "..", "..", "docs");
+
+const { values: args } = parseArgs({
+  options: {
+    languages: { type: "string", short: "l" },
+    tier: { type: "string", short: "t" },
+    pages: { type: "string", short: "p" },
+    "readme-only": { type: "boolean", default: false },
+    "docs-only": { type: "boolean", default: false },
+    "dry-run": { type: "boolean", default: false },
+    force: { type: "boolean", short: "f", default: false },
+    "update-nav": { type: "boolean", default: false },
+    validate: { type: "boolean", default: false },
+    model: { type: "string", short: "m" },
+    help: { type: "boolean", short: "h", default: false },
+  },
+  strict: true,
+});
+
+if (args.help) {
+  console.log(`
+Usage: bun scripts/translate-docs/cli.ts [options]
+
+Options:
+  -l, --languages <codes>  Comma-separated language codes (e.g. zh,ja,es)
+  -t, --tier <n>           Translate all languages up to tier n (1, 2, or 3)
+  -p, --pages <files>      Comma-separated page names to translate
+      --readme-only        Only translate the README
+      --docs-only          Only translate Mintlify docs
+      --dry-run            Show what would be translated without calling the API
+  -f, --force              Ignore cache, re-translate everything
+      --update-nav         Regenerate docs.json navigation after translation
+      --validate           Check all nav references resolve to files
+  -m, --model <model>      Claude model override (default: Sonnet for Tier 1, Haiku for Tier 2/3)
+  -h, --help               Show this help
+
+Environment:
+  ANTHROPIC_API_KEY        Required for translation (not needed for --dry-run or --validate)
+
+Examples:
+  bun scripts/translate-docs/cli.ts --tier 1              # Translate Tier 1 languages
+  bun scripts/translate-docs/cli.ts -l zh,ja --docs-only  # Translate Chinese + Japanese docs only
+  bun scripts/translate-docs/cli.ts --dry-run --tier 3    # Preview all translations
+  bun scripts/translate-docs/cli.ts --validate            # Check nav references
+  bun scripts/translate-docs/cli.ts --update-nav          # Regenerate docs.json
+`);
+  process.exit(0);
+}
+
+function resolveLanguages(): string[] {
+  if (args.languages) {
+    const codes = args.languages.split(",").map((c) => c.trim());
+    for (const code of codes) {
+      if (!getLanguageByCode(code)) {
+        console.error(`Unknown language code: ${code}`);
+        console.error(`Available: ${LANGUAGES.map((l) => l.code).join(", ")}`);
+        process.exit(1);
+      }
+    }
+    return codes;
+  }
+  const tier = args.tier ? parseInt(args.tier, 10) : 1;
+  if (tier < 1 || tier > 3) {
+    console.error("Tier must be 1, 2, or 3");
+    process.exit(1);
+  }
+  return getLanguagesByTier(tier).map((l) => l.code);
+}
+
+async function validateNavReferences(): Promise<boolean> {
+  const config = readDocsConfig();
+  const nav = config.navigation as Record<string, unknown>;
+  let valid = true;
+  let total = 0;
+  let missing = 0;
+
+  const languages = (nav.languages || []) as Array<{
+    language: string;
+    tabs: Array<{ groups: Array<{ pages: string[] }> }>;
+  }>;
+
+  if (languages.length === 0) {
+    // Flat tabs structure (not yet migrated to languages)
+    const tabs = (nav.tabs || []) as Array<{
+      groups: Array<{ pages: string[] }>;
+    }>;
+    for (const tab of tabs) {
+      for (const group of tab.groups) {
+        for (const page of group.pages) {
+          total++;
+          const filePath = join(DOCS_DIR, `${page}.mdx`);
+          if (!existsSync(filePath)) {
+            console.error(`  MISSING: ${page} -> ${filePath}`);
+            missing++;
+            valid = false;
+          }
+        }
+      }
+    }
+  } else {
+    for (const langEntry of languages) {
+      for (const tab of langEntry.tabs) {
+        for (const group of tab.groups) {
+          for (const page of group.pages) {
+            total++;
+            const filePath = join(DOCS_DIR, `${page}.mdx`);
+            if (!existsSync(filePath)) {
+              console.error(`  MISSING [${langEntry.language}]: ${page} -> ${filePath}`);
+              missing++;
+              valid = false;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (valid) {
+    console.log(`All ${total} page references are valid.`);
+  } else {
+    console.error(`\n${missing} of ${total} page references are missing.`);
+  }
+
+  return valid;
+}
+
+async function main() {
+  // Validate mode
+  if (args.validate) {
+    const valid = await validateNavReferences();
+    process.exit(valid ? 0 : 1);
+  }
+
+  // Update nav mode
+  if (args["update-nav"]) {
+    const langCodes = resolveLanguages();
+    console.log(`Updating docs.json with languages: ${langCodes.join(", ")}`);
+    updateDocsJson(langCodes);
+    console.log("docs.json updated.");
+    return;
+  }
+
+  const langCodes = resolveLanguages();
+  const isDryRun = args["dry-run"];
+  const isForce = args.force;
+  const modelOverride = args.model;
+
+  /** Resolve the model for a language: CLI override wins, otherwise tier-based default. */
+  function resolveModel(lang: string): string {
+    if (modelOverride) return modelOverride;
+    const langConfig = getLanguageByCode(lang);
+    return getModelForTier(langConfig?.tier ?? 1);
+  }
+
+  console.log(
+    `${isDryRun ? "[DRY RUN] " : ""}Translating into: ${langCodes.join(", ")}`,
+  );
+  if (!modelOverride) {
+    console.log(`Models: Tier 1 -> ${getModelForTier(1)}, Tier 2/3 -> ${getModelForTier(2)}`);
+  } else {
+    console.log(`Model override: ${modelOverride}`);
+  }
+
+  const results: TranslationResult[] = [];
+  const errors: Array<{ lang: string; source: string; error: string }> = [];
+
+  // Read cache once upfront — filter unchanged files before starting work
+  const cache = readCache();
+
+  // Concurrency limiter to avoid overwhelming the Anthropic API
+  const MAX_CONCURRENT = 10;
+  async function runWithConcurrency<T>(tasks: (() => Promise<T>)[]): Promise<T[]> {
+    const results: T[] = [];
+    let i = 0;
+    async function next(): Promise<void> {
+      while (i < tasks.length) {
+        const idx = i++;
+        results[idx] = await tasks[idx]();
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENT, tasks.length) }, () => next()));
+    return results;
+  }
+
+  // Translate docs
+  if (!args["readme-only"]) {
+    const pages = getEnglishMdxPages();
+    const filteredPages = args.pages
+      ? pages.filter((p) => {
+          const rel = relative(DOCS_DIR, p).replace(".mdx", "");
+          return args.pages!.split(",").some((f) => rel.includes(f.trim()));
+        })
+      : pages;
+
+    // Read each page once and reuse across languages
+    const pageContents = new Map<string, string>();
+    for (const page of filteredPages) {
+      pageContents.set(page, readFileSync(page, "utf-8"));
+    }
+
+    // Split into cached (skip) and uncached (need translation) upfront
+    type PageTask = { page: string; relPath: string; lang: string };
+    const cachedTasks: PageTask[] = [];
+    const uncachedTasks: PageTask[] = [];
+
+    for (const lang of langCodes) {
+      for (const page of filteredPages) {
+        const relPath = relative(DOCS_DIR, page);
+        const task = { page, relPath, lang };
+        if (!isForce && !isDryRun && isCached(cache, relPath, lang, pageContents.get(page)!)) {
+          cachedTasks.push(task);
+        } else {
+          uncachedTasks.push(task);
+        }
+      }
+    }
+
+    console.log(`\n${filteredPages.length} MDX pages x ${langCodes.length} languages = ${filteredPages.length * langCodes.length} total`);
+    console.log(`  Cached (unchanged): ${cachedTasks.length}`);
+    console.log(`  Need translation: ${uncachedTasks.length}`);
+
+    // Record cached results
+    for (const { page, relPath, lang } of cachedTasks) {
+      results.push({
+        lang,
+        sourcePath: page,
+        outputPath: join(DOCS_DIR, lang, relPath),
+        inputTokens: 0,
+        outputTokens: 0,
+        cached: true,
+      });
+    }
+
+    // Translate uncached pages with concurrency limit
+    if (uncachedTasks.length > 0) {
+      const taskResults = await runWithConcurrency(
+        uncachedTasks.map(({ page, relPath, lang }) => async () => {
+          try {
+            const result = await translateMdxPage(page, lang, {
+              force: isForce,
+              dryRun: isDryRun,
+              model: resolveModel(lang),
+              cache,
+            });
+            const status = isDryRun
+              ? "would translate"
+              : `translated (${result.inputTokens}+${result.outputTokens} tokens)`;
+            console.log(`  ${relPath} [${lang}] -> ${status}`);
+            results.push(result);
+            if (!result.cached && !isDryRun) {
+              setCacheEntry(cache, relPath, lang, pageContents.get(page)!, result.inputTokens, result.outputTokens);
+            }
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            errors.push({ lang, source: relPath, error: msg });
+            console.error(`  ${relPath} [${lang}] -> ERROR: ${msg}`);
+          }
+        }),
+      );
+    }
+  }
+
+  // Translate README
+  if (!args["docs-only"]) {
+    console.log(`\nTranslating README...`);
+
+    // Read README once
+    const readmeSource = readFileSync(join(DOCS_DIR, "..", "README.md"), "utf-8");
+    const uncachedLangs: string[] = [];
+    for (const lang of langCodes) {
+      if (!isForce && !isDryRun && isCached(cache, "README.md", lang, readmeSource)) {
+        console.log(`  README.${lang}.md -> cached`);
+        results.push({
+          lang,
+          sourcePath: join(DOCS_DIR, "..", "README.md"),
+          outputPath: join(DOCS_DIR, "i18n", `README.${lang}.md`),
+          inputTokens: 0,
+          outputTokens: 0,
+          cached: true,
+        });
+      } else {
+        uncachedLangs.push(lang);
+      }
+    }
+
+    if (uncachedLangs.length > 0) {
+      await runWithConcurrency(
+        uncachedLangs.map((lang) => async () => {
+          try {
+            const langConfig = getLanguageByCode(lang)!;
+            const result = await translateReadme(lang, {
+              force: isForce,
+              dryRun: isDryRun,
+              model: resolveModel(lang),
+              cache,
+            });
+            const status = isDryRun
+              ? "would translate"
+              : `translated (${result.inputTokens}+${result.outputTokens} tokens)`;
+            console.log(`  README.${lang}.md -> ${langConfig.nativeName}: ${status}`);
+            results.push(result);
+            if (!result.cached && !isDryRun) {
+              setCacheEntry(cache, "README.md", lang, readmeSource, result.inputTokens, result.outputTokens);
+            }
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            errors.push({ lang, source: "README.md", error: msg });
+            console.error(`  README.${lang}.md -> ERROR: ${msg}`);
+          }
+        }),
+      );
+    }
+  }
+
+  // Batch write cache once at the end
+  if (!isDryRun) {
+    writeCache(cache);
+  }
+
+  // Summary
+  const translated = results.filter((r) => !r.cached && !isDryRun);
+  const cached = results.filter((r) => r.cached);
+  const totalInput = translated.reduce((s, r) => s + r.inputTokens, 0);
+  const totalOutput = translated.reduce((s, r) => s + r.outputTokens, 0);
+
+  console.log(`\n--- Summary ---`);
+  console.log(`Translated: ${translated.length}`);
+  console.log(`Cached (skipped): ${cached.length}`);
+  if (errors.length > 0) {
+    console.log(`Errors: ${errors.length}`);
+  }
+  if (totalInput > 0) {
+    console.log(`Total tokens: ${totalInput} input + ${totalOutput} output`);
+  }
+
+  if (errors.length > 0) {
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});