failproofai 0.0.2 → 0.0.4-beta.0

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);
+});

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

@@ -0,0 +1,248 @@
+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: "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: "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: "tr", name: "Turkish", nativeName: "T\u00fcrk\u00e7e", 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 },
+];
+
+export function getLanguagesByTier(maxTier: number): LanguageConfig[] {
+  return LANGUAGES.filter((l) => l.tier <= maxTier);
+}
+
+export function getLanguageByCode(code: string): LanguageConfig | undefined {
+  return LANGUAGES.find((l) => l.code === code);
+}
+
+export function getLanguageCodes(maxTier?: number): string[] {
+  const langs = maxTier ? getLanguagesByTier(maxTier) : LANGUAGES;
+  return langs.map((l) => l.code);
+}
+
+/** Return the default model for a given tier. Tier 1 gets Sonnet, Tier 2/3 gets Haiku. */
+export function getModelForTier(tier: number): string {
+  return tier <= 1 ? "claude-sonnet-4-6" : "claude-haiku-4-5-20251001";
+}
+
+/** Terms that should never be translated — kept as-is in all languages. */
+export const DO_NOT_TRANSLATE = [
+  "failproofai",
+  "Failproof AI",
+  "FailproofAI",
+  "Claude Code",
+  "Agents SDK",
+  "Claude",
+  "Anthropic",
+  "Node.js",
+  "Bun",
+  "npm",
+  "npx",
+  "MDX",
+  "JSON",
+  "JSONL",
+  "ESM",
+  "CJS",
+  "settings.json",
+  "policies-config.json",
+  "policies-config.local.json",
+  "hook-activity.jsonl",
+  "hook.log",
+  "dist/index.js",
+  ".failproofai",
+  "~/.failproofai",
+  "~/.claude",
+  // CLI commands and flags
+  "failproofai policies --install",
+  "failproofai policies --uninstall",
+  "--install",
+  "--uninstall",
+  "--scope",
+  "--port",
+  "--strict",
+  "--projects-path",
+  "--allowed-origins",
+  // Policy names
+  "block-sudo",
+  "block-rm-rf",
+  "sanitize-api-keys",
+  "prevent-secret-leakage",
+  "block-force-push",
+  "restrict-to-project",
+  "detect-loops",
+  // Technical terms
+  "PreToolUse",
+  "PostToolUse",
+  "PreNotification",
+  "PostNotification",
+  "allow",
+  "deny",
+  "instruct",
+  "customPolicies",
+  "localhost",
+  "stdin",
+  "stdout",
+];
+
+/** Navigation group translations for each language. */
+export const NAV_TRANSLATIONS: Record<
+  string,
+  {
+    docs: string;
+    examples: string;
+    gettingStarted: string;
+    coreConcepts: string;
+    cli: string;
+    tools: string;
+    advanced: string;
+  }
+> = {
+  en: {
+    docs: "Docs",
+    examples: "Examples",
+    gettingStarted: "Getting Started",
+    coreConcepts: "Core Concepts",
+    cli: "CLI",
+    tools: "Tools",
+    advanced: "Advanced",
+  },
+  zh: {
+    docs: "\u6587\u6863",
+    examples: "\u793a\u4f8b",
+    gettingStarted: "\u5feb\u901f\u5f00\u59cb",
+    coreConcepts: "\u6838\u5fc3\u6982\u5ff5",
+    cli: "CLI",
+    tools: "\u5de5\u5177",
+    advanced: "\u8fdb\u9636",
+  },
+  ja: {
+    docs: "\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8",
+    examples: "\u4f8b",
+    gettingStarted: "\u306f\u3058\u3081\u306b",
+    coreConcepts: "\u57fa\u672c\u6982\u5ff5",
+    cli: "CLI",
+    tools: "\u30c4\u30fc\u30eb",
+    advanced: "\u4e0a\u7d1a",
+  },
+  ko: {
+    docs: "\ubb38\uc11c",
+    examples: "\uc608\uc81c",
+    gettingStarted: "\uc2dc\uc791\ud558\uae30",
+    coreConcepts: "\ud575\uc2ec \uac1c\ub150",
+    cli: "CLI",
+    tools: "\ub3c4\uad6c",
+    advanced: "\uace0\uae09",
+  },
+  es: {
+    docs: "Documentaci\u00f3n",
+    examples: "Ejemplos",
+    gettingStarted: "Primeros pasos",
+    coreConcepts: "Conceptos principales",
+    cli: "CLI",
+    tools: "Herramientas",
+    advanced: "Avanzado",
+  },
+  "pt-br": {
+    docs: "Documenta\u00e7\u00e3o",
+    examples: "Exemplos",
+    gettingStarted: "Come\u00e7ando",
+    coreConcepts: "Conceitos principais",
+    cli: "CLI",
+    tools: "Ferramentas",
+    advanced: "Avan\u00e7ado",
+  },
+  de: {
+    docs: "Dokumentation",
+    examples: "Beispiele",
+    gettingStarted: "Erste Schritte",
+    coreConcepts: "Kernkonzepte",
+    cli: "CLI",
+    tools: "Werkzeuge",
+    advanced: "Fortgeschritten",
+  },
+  fr: {
+    docs: "Documentation",
+    examples: "Exemples",
+    gettingStarted: "D\u00e9marrage",
+    coreConcepts: "Concepts cl\u00e9s",
+    cli: "CLI",
+    tools: "Outils",
+    advanced: "Avanc\u00e9",
+  },
+  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",
+    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",
+  },
+  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",
+    cli: "CLI",
+    tools: "\u0909\u092a\u0915\u0930\u0923",
+    advanced: "\u0909\u0928\u094d\u0928\u0924",
+  },
+  tr: {
+    docs: "Belgeler",
+    examples: "\u00d6rnekler",
+    gettingStarted: "Ba\u015flang\u0131\u00e7",
+    coreConcepts: "Temel Kavramlar",
+    cli: "CLI",
+    tools: "Ara\u00e7lar",
+    advanced: "Geli\u015fmi\u015f",
+  },
+  vi: {
+    docs: "T\u00e0i li\u1ec7u",
+    examples: "V\u00ed d\u1ee5",
+    gettingStarted: "B\u1eaft \u0111\u1ea7u",
+    coreConcepts: "Kh\u00e1i ni\u1ec7m c\u1ed1t l\u00f5i",
+    cli: "CLI",
+    tools: "C\u00f4ng c\u1ee5",
+    advanced: "N\u00e2ng cao",
+  },
+  it: {
+    docs: "Documentazione",
+    examples: "Esempi",
+    gettingStarted: "Per iniziare",
+    coreConcepts: "Concetti chiave",
+    cli: "CLI",
+    tools: "Strumenti",
+    advanced: "Avanzato",
+  },
+  ar: {
+    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",
+    cli: "CLI",
+    tools: "\u0627\u0644\u0623\u062f\u0648\u0627\u062a",
+    advanced: "\u0645\u062a\u0642\u062f\u0645",
+  },
+  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",
+    coreConcepts: "\u05de\u05d5\u05e9\u05d2\u05d9 \u05d9\u05e1\u05d5\u05d3",
+    cli: "CLI",
+    tools: "\u05db\u05dc\u05d9\u05dd",
+    advanced: "\u05de\u05ea\u05e7\u05d3\u05dd",
+  },
+};