failproofai 0.0.13 → 0.0.14-beta.1

package/scripts/sync-agent-cli-harnesses-prompt.md

@@ -32,7 +32,6 @@ tracked in `src/hooks/types.ts` and written to disk by `src/hooks/integrations.t
 | Cursor Agent   | `CURSOR_HOOK_EVENT_TYPES`          | `CURSOR_EVENT_MAP`     | `.cursor/hooks.json` |
 | OpenCode       | `OPENCODE_HOOK_EVENT_TYPES`        | `OPENCODE_EVENT_MAP`   | `.opencode/opencode.json` + `.opencode/plugins/failproofai.mjs` |
 | Pi             | `PI_HOOK_EVENT_TYPES`              | `PI_EVENT_MAP`         | `.pi/settings.json` |
-| Gemini CLI     | `GEMINI_HOOK_EVENT_TYPES`          | `GEMINI_EVENT_MAP`     | `.gemini/settings.json` |
 
 ## What "drift" means — three scopes
 
@@ -62,7 +61,7 @@ For each verified CLI, compare the upstream docs to this repo across three scope
   when you only need to **inspect** a committed fixture, prefer
   `git show HEAD:<path>` (e.g. `git show HEAD:.codex/hooks.json`) — it is never
   blocked and is the reliable way to read `.claude/settings.json`, `.codex/hooks.json`,
-  `.cursor/hooks.json`, `.github/hooks/failproofai.json`, `.gemini/settings.json`,
+  `.cursor/hooks.json`, `.github/hooks/failproofai.json`,
   `.pi/settings.json`, and `.opencode/*`.
 - Do **NOT** run `failproofai policies --install` (or any `failproofai` subcommand)
   to regenerate a fixture — it is blocked. Edit fixtures by hand.
@@ -76,7 +75,7 @@ Spawn one subagent per CLI (seven, in parallel). Each subagent, for its CLI:
    **settings-file schema** (top-level keys, per-entry shape, command field name,
    timeout field name **and unit**, and whether `matcher` / `version` / `$schema`
    are present). **Use upstream casing exactly** — Codex snake_case, Cursor
-   camelCase, OpenCode dot.namespaced, Pi snake_case, Claude/Copilot/Gemini
+   camelCase, OpenCode dot.namespaced, Pi snake_case, Claude/Copilot
    PascalCase. Do **not** normalize.
 2. Compare against this repo: the CLI's `*HOOK_EVENT_TYPES` array + paired
    `*EVENT_MAP` (scope 1); its `*_TOOL_MAP` / `*_TOOL_INPUT_MAP` and its branch in
@@ -98,7 +97,6 @@ surface is documented in the package source, not a clean enumeration).
 | Cursor    | https://cursor.com/docs/hooks |
 | OpenCode  | https://opencode.ai/docs/plugins/ |
 | Pi        | https://www.npmjs.com/package/@mariozechner/pi-coding-agent |
-| Gemini    | https://geminicli.com/docs/hooks/ · https://geminicli.com/docs/reference/tools/ (tool names) |
 
 ## Phase 2 — Decide what to do (do this BEFORE editing any files)
 
@@ -122,7 +120,6 @@ changes that block a clean stop on the comment / no-op paths below.
 
      > This open sync PR is missing newly-detected drift:
      > - **Cursor**: upstream added event `afterEdit` — append to `CURSOR_HOOK_EVENT_TYPES` (+ a `CURSOR_EVENT_MAP` entry).
-     > - **Gemini**: the `run_shell_command` tool was renamed to `shell` — the `GEMINI_TOOL_MAP` key is stale.
      >
      > (hook-sync bot — please fold these into this PR rather than opening a second sync PR.)
 
@@ -140,7 +137,7 @@ requires.
 - **Append** new events just before `] as const`, preserving upstream casing.
 - **Delete** removed events; if the CLI has an `*EVENT_MAP`, also delete the same
   key from that map (the `Record` is exhaustive — a stale key fails `tsc`).
-- For **map-bearing CLIs** (Codex, Cursor, OpenCode, Pi, Gemini), do **NOT** invent
+- For **map-bearing CLIs** (Codex, Cursor, OpenCode, Pi), do **NOT** invent
   the canonical mapping for a newly-added event — leave it out of the `*EVENT_MAP`
   so `tsc` fails intentionally, and add a reviewer-checklist item to the PR body
   (see below). For **Claude and Copilot** (no map), the build stays green.
@@ -148,9 +145,9 @@ requires.
   - If `HOOK_EVENT_TYPES` (Claude) changed: in `__tests__/hooks/manager.test.ts`,
     update the `installs hooks for all <N> event types` description AND both
     `expect(Object.keys(written.hooks)).toHaveLength(<N>)` assertions.
-  - If `GEMINI_HOOK_EVENT_TYPES` changed: in `__tests__/hooks/integrations.test.ts`,
-    update the `expect(gemini.eventTypes).toHaveLength(<N>)` assertion AND the
-    matching description string.
+  - If a CLI's `*_HOOK_EVENT_TYPES` changed: in `__tests__/hooks/integrations.test.ts`,
+    update the matching `expect(<cli>.eventTypes).toHaveLength(<N>)` assertion AND the
+    description string.
   - Locate these by searching for the current count number.
 
 ### Scope 2 / Scope 3 (tool schema / settings-file shape)
@@ -211,7 +208,7 @@ The PR **body** must contain, in order:
   `__tests__/e2e/hooks/<cli>-integration.e2e.test.ts`, the seven dogfood fixtures
   (`.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`,
   `.github/hooks/failproofai.json`, `.opencode/opencode.json`,
-  `.opencode/plugins/failproofai.mjs`, `.pi/settings.json`, `.gemini/settings.json`),
+  `.opencode/plugins/failproofai.mjs`, `.pi/settings.json`),
   and `CHANGELOG.md`.
 - Do **NOT** edit `.failproofai/policies-config.json` (the entrypoint manages it),
   `src/hooks/handler.ts`, `src/hooks/manager.ts`, or any other source file.

package/scripts/translate-docs/cli.ts

@@ -3,10 +3,23 @@ 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 {
+  LANGUAGES,
+  getLanguagesByTier,
+  getLanguageByCode,
+  getModelForTier,
+} from "./config";
+import {
+  getEnglishMdxPages,
+  translateMdxPage,
+  pruneOrphanedTranslations,
+} from "./mdx-translator";
 import { translateReadme } from "./readme-translator";
-import { updateDocsJson, readDocsConfig } from "./mintlify-nav";
+import {
+  getNavigationPageReferences,
+  updateDocsJson,
+  readDocsConfig,
+} from "./mintlify-nav";
 import { readCache, writeCache, isCached, setCacheEntry } from "./cache";
 import type { TranslationResult } from "./types";
 
@@ -24,6 +37,8 @@ const { values: args } = parseArgs({
     force: { type: "boolean", short: "f", default: false },
     "update-nav": { type: "boolean", default: false },
     validate: { type: "boolean", default: false },
+    prune: { type: "boolean", default: false },
+    "no-prune": { type: "boolean", default: false },
     model: { type: "string", short: "m" },
     help: { type: "boolean", short: "h", default: false },
   },
@@ -44,6 +59,8 @@ Options:
   -f, --force              Ignore cache, re-translate everything
       --update-nav         Regenerate docs.json navigation after translation
       --validate           Check all nav references resolve to files
+      --prune              Only delete translations whose English source is gone
+      --no-prune           Skip the prune step during a normal translation run
   -m, --model <model>      Claude model override (default: Sonnet for Tier 1, Haiku for Tier 2/3)
   -h, --help               Show this help
 
@@ -56,6 +73,7 @@ Examples:
   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
+  bun scripts/translate-docs/cli.ts --prune --tier 3      # Drop orphaned translations
 `);
   process.exit(0);
 }
@@ -87,44 +105,14 @@ async function validateNavReferences(): Promise<boolean> {
   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;
-            }
-          }
-        }
-      }
+  for (const reference of getNavigationPageReferences(nav)) {
+    total++;
+    const filePath = join(DOCS_DIR, `${reference.page}.mdx`);
+    if (!existsSync(filePath)) {
+      const context = reference.language ? ` [${reference.language}]` : "";
+      console.error(`  MISSING${context}: ${reference.page} -> ${filePath}`);
+      missing++;
+      valid = false;
     }
   }
 
@@ -153,6 +141,26 @@ async function main() {
     return;
   }
 
+  // Prune-only mode
+  if (args.prune) {
+    const langCodes = resolveLanguages();
+    const cache = readCache();
+    const pruned = pruneOrphanedTranslations(langCodes, {
+      dryRun: args["dry-run"],
+      cache,
+    });
+    for (const file of pruned) {
+      console.log(
+        `  ${args["dry-run"] ? "would remove" : "removed"}: ${file}`,
+      );
+    }
+    if (pruned.length > 0 && !args["dry-run"]) writeCache(cache);
+    console.log(
+      `\n${pruned.length} orphaned translation(s)${args["dry-run"] ? " would be" : ""} removed.`,
+    );
+    return;
+  }
+
   const langCodes = resolveLanguages();
   const isDryRun = args["dry-run"];
   const isForce = args.force;
@@ -169,7 +177,9 @@ async function main() {
     `${isDryRun ? "[DRY RUN] " : ""}Translating into: ${langCodes.join(", ")}`,
   );
   if (!modelOverride) {
-    console.log(`Models: Tier 1 -> ${getModelForTier(1)}, Tier 2/3 -> ${getModelForTier(2)}`);
+    console.log(
+      `Models: Tier 1 -> ${getModelForTier(1)}, Tier 2/3 -> ${getModelForTier(2)}`,
+    );
   } else {
     console.log(`Model override: ${modelOverride}`);
   }
@@ -186,10 +196,17 @@ async function main() {
   // configured in translator.ts) to absorb per-request transient
   // `Connection error.` from LB-induced replica flapping.
   // Override via TRANSLATE_MAX_CONCURRENT (integer >= 1; otherwise default).
-  const parsedConcurrent = Number.parseInt(process.env.TRANSLATE_MAX_CONCURRENT ?? "", 10);
+  const parsedConcurrent = Number.parseInt(
+    process.env.TRANSLATE_MAX_CONCURRENT ?? "",
+    10,
+  );
   const MAX_CONCURRENT =
-    Number.isInteger(parsedConcurrent) && parsedConcurrent > 0 ? parsedConcurrent : 4;
-  async function runWithConcurrency<T>(tasks: (() => Promise<T>)[]): Promise<T[]> {
+    Number.isInteger(parsedConcurrent) && parsedConcurrent > 0
+      ? parsedConcurrent
+      : 4;
+  async function runWithConcurrency<T>(
+    tasks: (() => Promise<T>)[],
+  ): Promise<T[]> {
     const results: T[] = [];
     let i = 0;
     async function next(): Promise<void> {
@@ -198,12 +215,33 @@ async function main() {
         results[idx] = await tasks[idx]();
       }
     }
-    await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENT, tasks.length) }, () => next()));
+    await Promise.all(
+      Array.from({ length: Math.min(MAX_CONCURRENT, tasks.length) }, () =>
+        next(),
+      ),
+    );
     return results;
   }
 
   // Translate docs
   if (!args["readme-only"]) {
+    // Drop translations orphaned by an upstream English deletion before
+    // translating, so a stale locale page can never outlive its source.
+    if (!args["no-prune"]) {
+      const pruned = pruneOrphanedTranslations(langCodes, {
+        dryRun: isDryRun,
+        cache,
+      });
+      for (const file of pruned) {
+        console.log(`  ${isDryRun ? "would prune" : "pruned"}: ${file}`);
+      }
+      if (pruned.length > 0) {
+        console.log(
+          `${pruned.length} orphaned translation(s)${isDryRun ? " would be" : ""} removed.`,
+        );
+      }
+    }
+
     const pages = getEnglishMdxPages();
     const filteredPages = args.pages
       ? pages.filter((p) => {
@@ -227,7 +265,11 @@ async function main() {
       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)!)) {
+        if (
+          !isForce &&
+          !isDryRun &&
+          isCached(cache, relPath, lang, pageContents.get(page)!)
+        ) {
           cachedTasks.push(task);
         } else {
           uncachedTasks.push(task);
@@ -235,7 +277,9 @@ async function main() {
       }
     }
 
-    console.log(`\n${filteredPages.length} MDX pages x ${langCodes.length} languages = ${filteredPages.length * langCodes.length} total`);
+    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}`);
 
@@ -268,7 +312,14 @@ async function main() {
             console.log(`  ${relPath} [${lang}] -> ${status}`);
             results.push(result);
             if (!result.cached && !isDryRun) {
-              setCacheEntry(cache, relPath, lang, pageContents.get(page)!, result.inputTokens, result.outputTokens);
+              setCacheEntry(
+                cache,
+                relPath,
+                lang,
+                pageContents.get(page)!,
+                result.inputTokens,
+                result.outputTokens,
+              );
             }
           } catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -285,10 +336,17 @@ async function main() {
     console.log(`\nTranslating README...`);
 
     // Read README once
-    const readmeSource = readFileSync(join(DOCS_DIR, "..", "README.md"), "utf-8");
+    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)) {
+      if (
+        !isForce &&
+        !isDryRun &&
+        isCached(cache, "README.md", lang, readmeSource)
+      ) {
         console.log(`  README.${lang}.md -> cached`);
         results.push({
           lang,
@@ -317,10 +375,19 @@ async function main() {
             const status = isDryRun
               ? "would translate"
               : `translated (${result.inputTokens}+${result.outputTokens} tokens)`;
-            console.log(`  README.${lang}.md -> ${langConfig.nativeName}: ${status}`);
+            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);
+              setCacheEntry(
+                cache,
+                "README.md",
+                lang,
+                readmeSource,
+                result.inputTokens,
+                result.outputTokens,
+              );
             }
           } catch (err) {
             const msg = err instanceof Error ? err.message : String(err);

package/scripts/translate-docs/config.ts

@@ -2,22 +2,60 @@ import type { LanguageConfig } from "./types";
 
 export const LANGUAGES: LanguageConfig[] = [
   // Tier 1 — largest developer populations
-  { code: "zh", name: "Chinese (Simplified)", nativeName: "\u7b80\u4f53\u4e2d\u6587", tier: 1 },
+  {
+    code: "zh",
+    name: "Chinese (Simplified)",
+    nativeName: "\u7b80\u4f53\u4e2d\u6587",
+    tier: 1,
+  },
   { code: "ja", name: "Japanese", nativeName: "\u65e5\u672c\u8a9e", tier: 1 },
   { code: "ko", name: "Korean", nativeName: "\ud55c\uad6d\uc5b4", tier: 1 },
   { code: "es", name: "Spanish", nativeName: "Espa\u00f1ol", tier: 1 },
-  { code: "pt-br", name: "Portuguese (Brazil)", nativeName: "Portugu\u00eas", tier: 1 },
+  {
+    code: "pt-br",
+    mintlifyCode: "pt-BR",
+    name: "Portuguese (Brazil)",
+    nativeName: "Portugu\u00eas",
+    tier: 1,
+  },
   { code: "de", name: "German", nativeName: "Deutsch", tier: 1 },
   { code: "fr", name: "French", nativeName: "Fran\u00e7ais", tier: 1 },
   // Tier 2 — strong tech communities
-  { code: "ru", name: "Russian", nativeName: "\u0420\u0443\u0441\u0441\u043a\u0438\u0439", tier: 2 },
-  { code: "hi", name: "Hindi", nativeName: "\u0939\u093f\u0928\u094d\u0926\u0940", tier: 2 },
+  {
+    code: "ru",
+    name: "Russian",
+    nativeName: "\u0420\u0443\u0441\u0441\u043a\u0438\u0439",
+    tier: 2,
+  },
+  {
+    code: "hi",
+    name: "Hindi",
+    nativeName: "\u0939\u093f\u0928\u094d\u0926\u0940",
+    tier: 2,
+  },
   { code: "tr", name: "Turkish", nativeName: "T\u00fcrk\u00e7e", tier: 2 },
-  { code: "vi", name: "Vietnamese", nativeName: "Ti\u1ebfng Vi\u1ec7t", tier: 2 },
+  {
+    code: "vi",
+    name: "Vietnamese",
+    nativeName: "Ti\u1ebfng Vi\u1ec7t",
+    tier: 2,
+  },
   { code: "it", name: "Italian", nativeName: "Italiano", tier: 2 },
   // Tier 3 — RTL languages
-  { code: "ar", name: "Arabic", nativeName: "\u0627\u0644\u0639\u0631\u0628\u064a\u0629", tier: 3, rtl: true },
-  { code: "he", name: "Hebrew", nativeName: "\u05e2\u05d1\u05e8\u05d9\u05ea", tier: 3, rtl: true },
+  {
+    code: "ar",
+    name: "Arabic",
+    nativeName: "\u0627\u0644\u0639\u0631\u0628\u064a\u0629",
+    tier: 3,
+    rtl: true,
+  },
+  {
+    code: "he",
+    name: "Hebrew",
+    nativeName: "\u05e2\u05d1\u05e8\u05d9\u05ea",
+    tier: 3,
+    rtl: true,
+  },
 ];
 
 export function getLanguagesByTier(maxTier: number): LanguageConfig[] {
@@ -184,17 +222,21 @@ export const NAV_TRANSLATIONS: Record<
   ru: {
     docs: "\u0414\u043e\u043a\u0443\u043c\u0435\u043d\u0442\u0430\u0446\u0438\u044f",
     examples: "\u041f\u0440\u0438\u043c\u0435\u0440\u044b",
-    gettingStarted: "\u041d\u0430\u0447\u0430\u043b\u043e \u0440\u0430\u0431\u043e\u0442\u044b",
-    coreConcepts: "\u041e\u0441\u043d\u043e\u0432\u043d\u044b\u0435 \u043a\u043e\u043d\u0446\u0435\u043f\u0446\u0438\u0438",
+    gettingStarted:
+      "\u041d\u0430\u0447\u0430\u043b\u043e \u0440\u0430\u0431\u043e\u0442\u044b",
+    coreConcepts:
+      "\u041e\u0441\u043d\u043e\u0432\u043d\u044b\u0435 \u043a\u043e\u043d\u0446\u0435\u043f\u0446\u0438\u0438",
     cli: "CLI",
     tools: "\u0418\u043d\u0441\u0442\u0440\u0443\u043c\u0435\u043d\u0442\u044b",
-    advanced: "\u041f\u0440\u043e\u0434\u0432\u0438\u043d\u0443\u0442\u044b\u0439",
+    advanced:
+      "\u041f\u0440\u043e\u0434\u0432\u0438\u043d\u0443\u0442\u044b\u0439",
   },
   hi: {
     docs: "\u0926\u0938\u094d\u0924\u093e\u0935\u0947\u091c\u093c",
     examples: "\u0909\u0926\u093e\u0939\u0930\u0923",
     gettingStarted: "\u0936\u0941\u0930\u0942 \u0915\u0930\u0947\u0902",
-    coreConcepts: "\u092e\u0942\u0932 \u0905\u0935\u0927\u093e\u0930\u0923\u093e\u090f\u0901",
+    coreConcepts:
+      "\u092e\u0942\u0932 \u0905\u0935\u0927\u093e\u0930\u0923\u093e\u090f\u0901",
     cli: "CLI",
     tools: "\u0909\u092a\u0915\u0930\u0923",
     advanced: "\u0909\u0928\u094d\u0928\u0924",
@@ -230,7 +272,8 @@ export const NAV_TRANSLATIONS: Record<
     docs: "\u0627\u0644\u0645\u0633\u062a\u0646\u062f\u0627\u062a",
     examples: "\u0623\u0645\u062b\u0644\u0629",
     gettingStarted: "\u0627\u0644\u0628\u062f\u0627\u064a\u0629",
-    coreConcepts: "\u0627\u0644\u0645\u0641\u0627\u0647\u064a\u0645 \u0627\u0644\u0623\u0633\u0627\u0633\u064a\u0629",
+    coreConcepts:
+      "\u0627\u0644\u0645\u0641\u0627\u0647\u064a\u0645 \u0627\u0644\u0623\u0633\u0627\u0633\u064a\u0629",
     cli: "CLI",
     tools: "\u0627\u0644\u0623\u062f\u0648\u0627\u062a",
     advanced: "\u0645\u062a\u0642\u062f\u0645",
@@ -238,7 +281,8 @@ export const NAV_TRANSLATIONS: Record<
   he: {
     docs: "\u05ea\u05d9\u05e2\u05d5\u05d3",
     examples: "\u05d3\u05d5\u05d2\u05de\u05d0\u05d5\u05ea",
-    gettingStarted: "\u05ea\u05d7\u05d9\u05dc\u05ea \u05e2\u05d1\u05d5\u05d3\u05d4",
+    gettingStarted:
+      "\u05ea\u05d7\u05d9\u05dc\u05ea \u05e2\u05d1\u05d5\u05d3\u05d4",
     coreConcepts: "\u05de\u05d5\u05e9\u05d2\u05d9 \u05d9\u05e1\u05d5\u05d3",
     cli: "CLI",
     tools: "\u05db\u05dc\u05d9\u05dd",