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

package/scripts/translate-docs/mdx-translator.ts

@@ -0,0 +1,153 @@
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getLanguageByCode } from "./config";
+import { translateContent } from "./translator";
+import {
+  readCache,
+  writeCache,
+  isCached,
+  setCacheEntry,
+} from "./cache";
+import type { TranslationResult, TranslationCache } from "./types";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DOCS_DIR = join(__dirname, "..", "..", "docs");
+
+/**
+ * Rewrite internal doc links to include the language prefix.
+ * e.g. href="/built-in-policies" -> href="/es/built-in-policies"
+ *      [Getting started](/getting-started) -> [Getting started](/es/getting-started)
+ */
+export function rewriteInternalLinks(
+  content: string,
+  lang: string,
+): string {
+  // Rewrite MDX component href attributes pointing to internal paths
+  let result = content.replace(
+    /href="(\/[^"]*?)"/g,
+    (_match, path: string) => {
+      // Skip external URLs and anchors
+      if (path.startsWith("/http") || path === "/") return `href="${path}"`;
+      return `href="/${lang}${path}"`;
+    },
+  );
+
+  // Rewrite Markdown links with internal paths
+  result = result.replace(
+    /\]\((\/[^)]*?)\)/g,
+    (_match, path: string) => {
+      if (path.startsWith("/http") || path === "/") return `](${path})`;
+      return `](/${lang}${path})`;
+    },
+  );
+
+  return result;
+}
+
+/**
+ * Translate a single MDX doc page for a given language.
+ */
+export async function translateMdxPage(
+  sourcePath: string,
+  lang: string,
+  options: { force?: boolean; dryRun?: boolean; model?: string; cache?: TranslationCache } = {},
+): Promise<TranslationResult> {
+  const relPath = relative(DOCS_DIR, sourcePath);
+  const outputPath = join(DOCS_DIR, lang, relPath);
+  const sourceContent = readFileSync(sourcePath, "utf-8");
+
+  const langConfig = getLanguageByCode(lang);
+  if (!langConfig) throw new Error(`Unknown language: ${lang}`);
+
+  // Check cache — use provided cache object or read from disk
+  if (!options.force && !options.dryRun) {
+    const cache = options.cache ?? readCache();
+    if (isCached(cache, relPath, lang, sourceContent)) {
+      return {
+        lang,
+        sourcePath,
+        outputPath,
+        inputTokens: 0,
+        outputTokens: 0,
+        cached: true,
+      };
+    }
+  }
+
+  if (options.dryRun) {
+    return {
+      lang,
+      sourcePath,
+      outputPath,
+      inputTokens: 0,
+      outputTokens: 0,
+      cached: false,
+    };
+  }
+
+  // Translate
+  const { translated, inputTokens, outputTokens } = await translateContent(
+    sourceContent,
+    lang,
+    langConfig.name,
+    options.model,
+  );
+
+  // Rewrite internal links
+  const withLinks = rewriteInternalLinks(translated, lang);
+
+  // Write output
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, withLinks);
+
+  // Update cache — skip if caller manages the cache (batch write)
+  if (!options.cache) {
+    const cache = readCache();
+    setCacheEntry(cache, relPath, lang, sourceContent, inputTokens, outputTokens);
+    writeCache(cache);
+  }
+
+  return {
+    lang,
+    sourcePath,
+    outputPath,
+    inputTokens,
+    outputTokens,
+    cached: false,
+  };
+}
+
+/**
+ * Get all MDX page paths from the docs directory (English only, no language subdirs).
+ */
+export function getEnglishMdxPages(): string[] {
+  const results: string[] = [];
+
+  function walk(dir: string, prefix: string = "") {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const rel = prefix ? `${prefix}/${entry}` : entry;
+      if (statSync(full).isDirectory()) {
+        // Skip language directories at the top level
+        if (!prefix && isLanguageDir(entry)) continue;
+        // Skip non-doc directories like logo, i18n
+        if (!prefix && (entry === "logo" || entry === "i18n")) continue;
+        walk(full, rel);
+      } else if (entry.endsWith(".mdx")) {
+        results.push(full);
+      }
+    }
+  }
+
+  walk(DOCS_DIR);
+  return results.sort();
+}
+
+function isLanguageDir(name: string): boolean {
+  const langCodes = [
+    "zh", "ja", "ko", "es", "pt-br", "de", "fr",
+    "ru", "hi", "tr", "vi", "it", "ar", "he",
+  ];
+  return langCodes.includes(name);
+}

package/scripts/translate-docs/mintlify-nav.ts

@@ -0,0 +1,107 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { NAV_TRANSLATIONS, LANGUAGES } from "./config";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DOCS_JSON_PATH = join(__dirname, "..", "..", "docs", "docs.json");
+
+interface NavGroup {
+  group: string;
+  pages: string[];
+}
+
+interface NavTab {
+  tab: string;
+  groups: NavGroup[];
+}
+
+interface LanguageNav {
+  language: string;
+  tabs: NavTab[];
+}
+
+/**
+ * Build a navigation entry for a specific language by transforming the
+ * English navigation structure.
+ */
+export function buildLanguageNav(
+  englishTabs: NavTab[],
+  lang: string,
+): LanguageNav {
+  const t = NAV_TRANSLATIONS[lang];
+  if (!t) throw new Error(`No nav translations for language: ${lang}`);
+
+  const groupNameMap: Record<string, string> = {
+    "Getting Started": t.gettingStarted,
+    "Core Concepts": t.coreConcepts,
+    CLI: t.cli,
+    Tools: t.tools,
+    Advanced: t.advanced,
+    Examples: t.examples,
+  };
+
+  const tabNameMap: Record<string, string> = {
+    Docs: t.docs,
+    Examples: t.examples,
+  };
+
+  const tabs: NavTab[] = englishTabs.map((tab) => ({
+    tab: tabNameMap[tab.tab] || tab.tab,
+    groups: tab.groups.map((group) => ({
+      group: groupNameMap[group.group] || group.group,
+      pages: group.pages.map((page) => `${lang}/${page}`),
+    })),
+  }));
+
+  return { language: lang, tabs };
+}
+
+/**
+ * Read the current docs.json config.
+ */
+export function readDocsConfig(): Record<string, unknown> {
+  return JSON.parse(readFileSync(DOCS_JSON_PATH, "utf-8"));
+}
+
+/**
+ * Generate the full languages array for docs.json from the English nav
+ * and a list of language codes.
+ */
+export function generateLanguagesArray(
+  englishTabs: NavTab[],
+  langCodes: string[],
+): LanguageNav[] {
+  // English first (default)
+  const english: LanguageNav = { language: "en", tabs: englishTabs };
+  const others = langCodes.map((code) => buildLanguageNav(englishTabs, code));
+  return [english, ...others];
+}
+
+/**
+ * Update docs.json to use the languages array structure.
+ */
+export function updateDocsJson(langCodes: string[]): void {
+  const config = readDocsConfig();
+  const nav = config.navigation as Record<string, unknown>;
+
+  // Extract existing English tabs
+  const englishTabs = nav.tabs as NavTab[];
+  if (!englishTabs) {
+    throw new Error("docs.json navigation.tabs not found — is this already using the languages format?");
+  }
+
+  // Build languages array
+  const languages = generateLanguagesArray(englishTabs, langCodes);
+
+  // Replace tabs with languages, preserve global
+  const newNav: Record<string, unknown> = {
+    languages,
+  };
+  if (nav.global) {
+    newNav.global = nav.global;
+  }
+
+  config.navigation = newNav;
+  writeFileSync(DOCS_JSON_PATH, JSON.stringify(config, null, 2) + "\n");
+}

package/scripts/translate-docs/readme-translator.ts

@@ -0,0 +1,154 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LANGUAGES, getLanguageByCode } from "./config";
+import { translateContent } from "./translator";
+import { readCache, writeCache, isCached, setCacheEntry } from "./cache";
+import type { TranslationResult, TranslationCache } from "./types";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = join(__dirname, "..", "..");
+const README_PATH = join(ROOT_DIR, "README.md");
+const I18N_DIR = join(ROOT_DIR, "docs", "i18n");
+
+function buildLanguageSelector(currentLang: string): string {
+  const flags: Record<string, string> = {
+    en: "\ud83c\uddfa\ud83c\uddf8",
+    zh: "\ud83c\udde8\ud83c\uddf3",
+    ja: "\ud83c\uddef\ud83c\uddf5",
+    ko: "\ud83c\uddf0\ud83c\uddf7",
+    es: "\ud83c\uddea\ud83c\uddf8",
+    "pt-br": "\ud83c\udde7\ud83c\uddf7",
+    de: "\ud83c\udde9\ud83c\uddea",
+    fr: "\ud83c\uddeb\ud83c\uddf7",
+    ru: "\ud83c\uddf7\ud83c\uddfa",
+    hi: "\ud83c\uddee\ud83c\uddf3",
+    tr: "\ud83c\uddf9\ud83c\uddf7",
+    vi: "\ud83c\uddfb\ud83c\uddf3",
+    it: "\ud83c\uddee\ud83c\uddf9",
+    ar: "\ud83c\uddf8\ud83c\udde6",
+    he: "\ud83c\uddee\ud83c\uddf1",
+  };
+
+  const links: string[] = [];
+
+  // English link (to root README)
+  if (currentLang !== "en") {
+    links.push(`[${flags.en} English](../../README.md)`);
+  }
+
+  for (const lang of LANGUAGES) {
+    const flag = flags[lang.code] || "";
+    if (lang.code === currentLang) {
+      links.push(`**${flag} ${lang.nativeName}**`);
+    } else {
+      links.push(`[${flag} ${lang.nativeName}](README.${lang.code}.md)`);
+    }
+  }
+
+  return links.join(" | ");
+}
+
+export async function translateReadme(
+  lang: string,
+  options: { force?: boolean; dryRun?: boolean; model?: string; cache?: TranslationCache } = {},
+): Promise<TranslationResult> {
+  const outputPath = join(I18N_DIR, `README.${lang}.md`);
+  const sourceContent = readFileSync(README_PATH, "utf-8");
+
+  const langConfig = getLanguageByCode(lang);
+  if (!langConfig) throw new Error(`Unknown language: ${lang}`);
+
+  // Check cache — use provided cache object or read from disk
+  if (!options.force && !options.dryRun) {
+    const cache = options.cache ?? readCache();
+    if (isCached(cache, "README.md", lang, sourceContent)) {
+      return {
+        lang,
+        sourcePath: README_PATH,
+        outputPath,
+        inputTokens: 0,
+        outputTokens: 0,
+        cached: true,
+      };
+    }
+  }
+
+  if (options.dryRun) {
+    return {
+      lang,
+      sourcePath: README_PATH,
+      outputPath,
+      inputTokens: 0,
+      outputTokens: 0,
+      cached: false,
+    };
+  }
+
+  // Translate
+  const { translated, inputTokens, outputTokens } = await translateContent(
+    sourceContent,
+    lang,
+    langConfig.name,
+    options.model,
+  );
+
+  // Build the final output with header
+  const disclaimer = langConfig.rtl
+    ? `> **\u26a0\ufe0f** \u0647\u0630\u0647 \u062a\u0631\u062c\u0645\u0629 \u0622\u0644\u064a\u0629. \u0644\u0644\u0627\u0637\u0644\u0627\u0639 \u0639\u0644\u0649 \u0623\u062d\u062f\u062b \u0625\u0635\u062f\u0627\u0631\u060c \u0631\u0627\u062c\u0639 [English README](../../README.md).`
+    : `> **\u26a0\ufe0f** This is an auto-generated translation. For the latest version, see the [English README](../../README.md). Community corrections welcome!`;
+
+  const langSelector = buildLanguageSelector(lang);
+  const rtlOpen = langConfig.rtl ? `<div dir="rtl">\n\n` : "";
+  const rtlClose = langConfig.rtl ? `\n\n</div>` : "";
+
+  const output = `${disclaimer}\n\n${langSelector}\n\n---\n${rtlOpen}\n${translated}\n${rtlClose}`;
+
+  // Write output
+  mkdirSync(I18N_DIR, { recursive: true });
+  writeFileSync(outputPath, output);
+
+  // Update cache — skip if caller manages the cache (batch write)
+  if (!options.cache) {
+    const cache = readCache();
+    setCacheEntry(cache, "README.md", lang, sourceContent, inputTokens, outputTokens);
+    writeCache(cache);
+  }
+
+  return {
+    lang,
+    sourcePath: README_PATH,
+    outputPath,
+    inputTokens,
+    outputTokens,
+    cached: false,
+  };
+}
+
+/**
+ * Build the language selector line to add to the main README.
+ */
+export function buildMainReadmeLanguageLinks(): string {
+  const flags: Record<string, string> = {
+    zh: "\ud83c\udde8\ud83c\uddf3",
+    ja: "\ud83c\uddef\ud83c\uddf5",
+    ko: "\ud83c\uddf0\ud83c\uddf7",
+    es: "\ud83c\uddea\ud83c\uddf8",
+    "pt-br": "\ud83c\udde7\ud83c\uddf7",
+    de: "\ud83c\udde9\ud83c\uddea",
+    fr: "\ud83c\uddeb\ud83c\uddf7",
+    ru: "\ud83c\uddf7\ud83c\uddfa",
+    hi: "\ud83c\uddee\ud83c\uddf3",
+    tr: "\ud83c\uddf9\ud83c\uddf7",
+    vi: "\ud83c\uddfb\ud83c\uddf3",
+    it: "\ud83c\uddee\ud83c\uddf9",
+    ar: "\ud83c\uddf8\ud83c\udde6",
+    he: "\ud83c\uddee\ud83c\uddf1",
+  };
+
+  const links = LANGUAGES.map(
+    (l) => `[${flags[l.code] || ""} ${l.nativeName}](docs/i18n/README.${l.code}.md)`,
+  );
+
+  return `**Translations**: ${links.join(" | ")}`;
+}

package/scripts/translate-docs/translator.ts

@@ -0,0 +1,68 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { DO_NOT_TRANSLATE } from "./config";
+
+let client: Anthropic | null = null;
+
+function getClient(): Anthropic {
+  if (!client) {
+    client = new Anthropic();
+  }
+  return client;
+}
+
+const SYSTEM_PROMPT = `You are a professional technical documentation translator. Your task is to translate documentation content precisely and naturally into the target language.
+
+## Rules
+
+1. **Preserve all code blocks exactly as-is** — never translate content inside backtick-fenced code blocks (\`\`\`...\`\`\`) or inline code (\`...\`).
+2. **Preserve MDX component syntax** — tags like <Card>, <CardGroup>, <CodeGroup>, <Steps>, <Step>, <Note>, <Tip>, <Tabs>, <Tab>, <Warning> must remain unchanged. Their attribute names (title, icon, href, cols) must remain in English. Only translate the text content of the \`title\` attribute and the text body between tags.
+3. **Preserve YAML frontmatter keys** — only translate the string values of \`title\` and \`description\`. Keep the \`icon\` value unchanged.
+4. **Preserve all URLs and paths** — never modify href values, image paths, or links.
+5. **Preserve Markdown structure** — headers (#, ##), lists (-, *), tables (|), bold (**), italic (*), links ([text](url)) must keep their Markdown formatting.
+6. **Preserve badge/shield URLs** — any [![...](https://img.shields.io/...)](url) pattern must remain completely unchanged.
+
+## Do-not-translate list
+
+The following terms must NEVER be translated — keep them exactly as-is in the output:
+${DO_NOT_TRANSLATE.map((t) => `- ${t}`).join("\n")}
+
+## Translation quality
+
+- Use natural, idiomatic phrasing in the target language — do NOT produce word-for-word literal translations.
+- Technical documentation should read as if originally written in the target language by a native-speaking developer.
+- Maintain the same level of formality and tone as the source.
+- For languages that distinguish formal/informal registers, use a professional but approachable tone.
+
+## Output
+
+Return ONLY the translated content. Do not add explanations, notes, or commentary.`;
+
+export async function translateContent(
+  content: string,
+  targetLang: string,
+  targetLangName: string,
+  model: string = "claude-sonnet-4-6",
+): Promise<{ translated: string; inputTokens: number; outputTokens: number }> {
+  const anthropic = getClient();
+
+  const response = await anthropic.messages.create({
+    model,
+    max_tokens: 16384,
+    system: [{ type: "text", text: SYSTEM_PROMPT, cache_control: { type: "ephemeral" } }],
+    messages: [
+      {
+        role: "user",
+        content: `Translate the following documentation content into ${targetLangName} (${targetLang}).\n\n---\n\n${content}`,
+      },
+    ],
+  });
+
+  const translated =
+    response.content[0].type === "text" ? response.content[0].text : "";
+
+  return {
+    translated,
+    inputTokens: response.usage.input_tokens,
+    outputTokens: response.usage.output_tokens,
+  };
+}

package/scripts/translate-docs/types.ts

@@ -0,0 +1,43 @@
+export interface LanguageConfig {
+  code: string;
+  name: string;
+  nativeName: string;
+  tier: 1 | 2 | 3;
+  rtl?: boolean;
+}
+
+export interface CacheEntry {
+  sourceHash: string;
+  targetLang: string;
+  translatedAt: string;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface TranslationCache {
+  sourceHash: string;
+  lastUpdated: string;
+  translations: Record<string, CacheEntry>;
+}
+
+export interface TranslateOptions {
+  languages: string[];
+  tier?: number;
+  pagesFilter?: string[];
+  readmeOnly?: boolean;
+  docsOnly?: boolean;
+  dryRun?: boolean;
+  force?: boolean;
+  updateNav?: boolean;
+  validate?: boolean;
+  model?: string;
+}
+
+export interface TranslationResult {
+  lang: string;
+  sourcePath: string;
+  outputPath: string;
+  inputTokens: number;
+  outputTokens: number;
+  cached: boolean;
+}

package/src/hooks/custom-hooks-loader.ts

@@ -116,7 +116,7 @@ export interface LoadAllResult {
  * 3. User convention: ~/.failproofai/policies/*policies.{js,mjs,ts} (alphabetical)
  *
  * Each file is loaded independently (fail-open per file).
- * Convention hooks are tagged with __conventionSource so the handler can distinguish them.
+ * Convention hooks are tagged with __conventionScope so the handler can build scoped prefixes.
  */
 export async function loadAllCustomHooks(
   customPoliciesPath: string | undefined,
@@ -181,16 +181,23 @@ export async function loadAllCustomHooks(
     );
   }
 
-  // Tag convention hooks so the handler can register them with a "convention/" prefix.
-  // Track by object reference (not name) to avoid mis-tagging an explicit custom hook
-  // that happens to share the same name as a convention hook.
+  // Tag convention hooks with their scope so the handler can build scoped prefixes.
+  // Build a name→scope map from conventionSources, then tag by object reference
+  // to avoid mis-tagging an explicit custom hook that shares the same name.
+  const hookNameToScope = new Map<string, string>();
+  for (const source of conventionSources) {
+    for (const name of source.hookNames) {
+      hookNameToScope.set(name, source.scope);
+    }
+  }
   const conventionHookRefs = new Set<CustomHook>();
   for (const hook of allHooks.slice(hooksBeforeConvention)) {
     conventionHookRefs.add(hook);
   }
   for (const hook of allHooks) {
     if (conventionHookRefs.has(hook)) {
-      (hook as CustomHook & { __conventionSource?: boolean }).__conventionSource = true;
+      (hook as CustomHook & { __conventionScope?: string }).__conventionScope =
+        hookNameToScope.get(hook.name) ?? "project";
     }
   }
 

package/src/hooks/handler.ts

@@ -78,8 +78,9 @@ export async function handleHookEvent(eventType: string): Promise<number> {
 
   for (const hook of customHooksList) {
     const hookName = hook.name;
-    const isConvention = (hook as CustomHook & { __conventionSource?: boolean }).__conventionSource === true;
-    const prefix = isConvention ? "convention" : "custom";
+    const conventionScope = (hook as CustomHook & { __conventionScope?: string }).__conventionScope;
+    const isConvention = !!conventionScope;
+    const prefix = isConvention ? `.failproofai-${conventionScope}` : "custom";
     const fn: PolicyFunction = async (ctx): Promise<PolicyResult> => {
       try {
         const result = await Promise.race([
@@ -98,6 +99,7 @@ export async function handleHookEvent(eventType: string): Promise<number> {
           error_type: isTimeout ? "timeout" : "exception",
           event_type: eventType,
           is_convention_policy: isConvention,
+          convention_scope: conventionScope ?? null,
         });
         return { decision: "allow" };
       }
@@ -170,7 +172,10 @@ export async function handleHookEvent(eventType: string): Promise<number> {
   if (result.decision === "deny" || result.decision === "instruct") {
     try {
       const isCustomHook = result.policyName?.startsWith("custom/") ?? false;
-      const isConventionPolicy = result.policyName?.startsWith("convention/") ?? false;
+      const isConventionPolicy = result.policyName?.startsWith(".failproofai-") ?? false;
+      const conventionScope = isConventionPolicy
+        ? result.policyName!.match(/^\.failproofai-(project|user)\//)?.[1] ?? null
+        : null;
       const hasCustomParams =
         !isCustomHook && !isConventionPolicy && !!(result.policyName && config.policyParams?.[result.policyName]);
       const paramKeysOverridden = hasCustomParams
@@ -184,6 +189,7 @@ export async function handleHookEvent(eventType: string): Promise<number> {
         decision: result.decision,
         is_custom_hook: isCustomHook,
         is_convention_policy: isConventionPolicy,
+        convention_scope: conventionScope,
         has_custom_params: hasCustomParams,
         param_keys_overridden: paramKeysOverridden,
       });

package/src/hooks/manager.ts

@@ -267,7 +267,9 @@ export async function installHooks(
   }
 
   for (const eventType of HOOK_EVENT_TYPES) {
-    const command = `"${binaryPath}" --hook ${eventType}`;
+    const command = scope === "project"
+      ? `npx -y failproofai --hook ${eventType}`
+      : `"${binaryPath}" --hook ${eventType}`;
     const hookEntry: ClaudeHookEntry = {
       type: "command",
       command,
@@ -323,6 +325,7 @@ export async function installHooks(
       has_custom_hooks_path: !!(configToWrite.customPoliciesPath),
       has_policy_params: !!(configToWrite.policyParams && Object.keys(configToWrite.policyParams).length > 0),
       param_policy_names: configToWrite.policyParams ? Object.keys(configToWrite.policyParams) : [],
+      command_format: scope === "project" ? "npx" : "absolute",
     });
   } catch {
     // Telemetry is best-effort — never block the operation
@@ -330,7 +333,12 @@ export async function installHooks(
 
   console.log(`Failproof AI hooks installed for all ${HOOK_EVENT_TYPES.length} event types (scope: ${scope}).`);
   console.log(`Settings: ${settingsPath}`);
-  console.log(`Binary:   ${binaryPath}`);
+  if (scope === "project") {
+    console.log(`Command:  npx -y failproofai`);
+    console.log(`\nThis file can be committed to git — no machine-specific paths.`);
+  } else {
+    console.log(`Binary:   ${binaryPath}`);
+  }
 
   // Warn about duplicate-scope installations
   const otherScopes = deduplicateScopes(HOOK_SCOPES, cwd).filter((s) => s !== scope);