champollion 0.3.3

package/lib/commands/status.js

@@ -0,0 +1,265 @@
+/**
+ * Command: status
+ *
+ * Shows the translation pair graph, config summary, installed plugins,
+ * TM cache stats, and benchmark scores. A diagnostic tool for understanding
+ * how the project is configured before running sync.
+ */
+
+import { resolveConfig, autoDetectLanguages } from '../config.js';
+import { resolvePairs, QUALITY_TIERS } from '../pairs.js';
+import { loadPlugins, resolvePluginForPair } from '../plugins.js';
+import { DEFAULT_REGISTERS, getLanguageCard, getRegisterPresets, DEFAULT_REGISTER_FALLBACK } from '../registers.js';
+import { loadTM, tmSize, TM_DIR, TM_FILENAME } from '../tm.js';
+import { getMethod } from '../translate.js';
+import { output } from '../output.js';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// CLI version — read from package.json (the single source of truth), never a
+// hardcoded literal. Mirrors bin/cli.js's --version read.
+const { version: CLI_VERSION } = JSON.parse(
+  fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf-8'),
+);
+
+/**
+ * @param {import('../types.js').CLIArgs} args - Parsed CLI arguments
+ * @param {string} cwd - Working directory
+ * @returns {Promise<number>} Exit code (0 = success, 1 = error)
+ */
+async function run(args, cwd) {
+  // --json: stdout carries exactly one JSON document. Quiet mode keeps the
+  // human status display off stdout.
+  const json = !!args.json;
+  if (json) output.setMode('quiet');
+
+  const config = resolveConfig(args, cwd);
+
+  // Auto-detect languages if not configured
+  let languages = config.resolvedLanguages;
+  if (Object.keys(languages).length === 0) {
+    languages = autoDetectLanguages(config);
+  }
+  config.resolvedLanguages = languages;
+
+  const pairs = resolvePairs(config);
+
+  // Load installed plugins to enrich status display
+  const plugins = loadPlugins(cwd);
+
+  if (json) {
+    return runJson(config, pairs, plugins, cwd);
+  }
+
+  output.raw('\n  champollion v3 — Translation Status\n');
+  output.raw(`  Input locale:  ${config.inputLocale}`);
+  output.raw(`  Locales dir:   ${config.localesDir}`);
+  output.raw(`  Default model: ${config.model}`);
+  if (config.temperature != null) {
+    output.raw(`  Temperature:   ${config.temperature}`);
+  }
+  output.raw(`  Config version: ${config.version || '2 (legacy)'}`);
+
+
+  // Show installed plugins summary
+  if (plugins.size > 0) {
+    output.raw(`  Plugins:       ${plugins.size} installed`);
+  }
+
+  // Show Translation Memory status — gives users immediate feedback
+  // that caching is working and how much is cached.
+  const tmPath = path.join(cwd, TM_DIR, TM_FILENAME);
+  if (fs.existsSync(tmPath)) {
+    const tm = loadTM(cwd);
+    const count = tmSize(tm);
+    const stat = fs.statSync(tmPath);
+    const sizeKB = (stat.size / 1024).toFixed(1);
+    output.raw(`  TM cache:      ${count.toLocaleString()} entries (${sizeKB} KB)`);
+  } else {
+    output.raw('  TM cache:      empty (will populate on first sync)');
+  }
+  output.raw('');
+
+  if (pairs.size === 0) {
+    output.raw('  No translation pairs configured.');
+    output.raw('  Run `champollion init` or add languages to your config.\n');
+  } else {
+    output.raw(`  Translation Pairs (${pairs.size}):\n`);
+    for (const [pairKey, pairConfig] of pairs) {
+      const tier = QUALITY_TIERS[pairConfig.qualityTier];
+      const tierLabel = tier ? tier.label : pairConfig.qualityTier;
+      const dirLabel = pairConfig.dir === 'rtl' ? ' [RTL]' : '';
+      // Show the RESOLVED script decision, not the converter's existence.
+      // The old label printed the registry key ("[crk]"), which read as if
+      // conversion were happening whether or not it was.
+      const res = pairConfig.scriptResolution;
+      let scriptLabel = '';
+      if (res?.converterKey) scriptLabel = ` [script: ${res.script ?? res.converterKey}]`;
+      else if (res?.source === 'choice-required') scriptLabel = ' [script: CHOICE REQUIRED — see `champollion sync`]';
+      else if (res?.source === 'default' && pairConfig.scripts) scriptLabel = ` [script: ${res.script} (converter available)]`;
+      // Display arrow is a UI-only semantic element, not a data separator
+      output.raw(`    ${pairKey}  →  ${pairConfig.name}${dirLabel}${scriptLabel}`);
+
+      // Resolve display model — direct providers may have model=null in the
+      // pair config, meaning the method class picks its own default at runtime.
+      // Show the resolved model so users know what will actually be used.
+      let displayModel = pairConfig.model;
+      if (!displayModel && pairConfig.method !== 'api') {
+        try {
+          const method = getMethod(pairConfig.method);
+          displayModel = method._getDefaultModel?.() || 'auto';
+        } catch { displayModel = 'auto'; }
+      }
+      const modelStr = pairConfig.method === 'api' ? '' : `  |  model: ${displayModel || 'auto'}`;
+
+      // Show benchmarks if plugin has them; otherwise show tier as self-reported
+      let qualityStr = '';
+      if (pairConfig.methodPlugin) {
+        const resolvedPair = resolvePluginForPair(plugins, pairConfig);
+        const benchmarks = resolvedPair.pluginBenchmarks;
+        if (benchmarks && benchmarks[pairConfig.target]) {
+          const bm = benchmarks[pairConfig.target];
+          const parts = [];
+          if (bm.corpus_chrf) parts.push(`chrF++ ${bm.corpus_chrf}`);
+          if (bm.exact_match_rate) parts.push(`exact ${Math.round(bm.exact_match_rate * 100)}%`);
+          qualityStr = `  |  benchmarks: ${parts.join(', ')}`;
+        } else {
+          qualityStr = `  |  quality: ${tierLabel} (self-reported, no benchmarks)`;
+        }
+      } else {
+        qualityStr = `  |  quality: ${tierLabel}`;
+      }
+      output.raw(`      method: ${pairConfig.method}${modelStr}${qualityStr}`);
+
+      // Plugin badge — show name and version (benchmarks already shown above)
+      if (pairConfig.methodPlugin) {
+        const resolvedPair = resolvePluginForPair(plugins, pairConfig);
+        if (resolvedPair.pluginName) {
+          let pluginLine = `      [PLUGIN] ${resolvedPair.pluginName}`;
+          if (resolvedPair.pluginVersion) pluginLine += ` v${resolvedPair.pluginVersion}`;
+          output.raw(pluginLine);
+        }
+      }
+
+      // API badge
+      if (pairConfig.method === 'api') {
+        output.raw('      [API] Translation runs server-side (IP protected)');
+      }
+
+      // Google Translate badge
+      if (pairConfig.method === 'google-translate') {
+        output.raw('      Google Cloud Translation API');
+      }
+    }
+    output.raw('');
+
+    // Show active registers for each pair with structured card info
+    output.raw('  Registers:\n');
+    for (const [pairKey, pairConfig] of pairs) {
+      const card = getLanguageCard(pairConfig.target);
+      const presets = getRegisterPresets(pairConfig.target);
+      const systemLabel = card?.formality?.system ? ` (${card.formality.system})` : '';
+
+      // Use registerPreset for direct lookup — no fragile prompt text matching
+      const presetKey = pairConfig.registerPreset;
+      const matchedPreset = presetKey
+        ? presets.find(p => p.key === presetKey)
+        : null;
+
+      if (matchedPreset) {
+        // Known preset — show key, label, and formality system
+        const marker = matchedPreset.isDefault ? ' ★' : '';
+        output.raw(`    ${pairConfig.target}  ${matchedPreset.key}${marker}${systemLabel} — ${matchedPreset.label}`);
+      } else {
+        // Custom register text — show truncated text
+        const regText = pairConfig.register || DEFAULT_REGISTER_FALLBACK;
+        const truncated = regText.length > 55 ? regText.slice(0, 52) + '...' : regText;
+        output.raw(`    ${pairConfig.target}  (custom)${systemLabel} — "${truncated}"`);
+      }
+    }
+    output.raw('');
+  }
+
+  return 0;
+}
+
+/**
+ * --json: assemble everything the human display computes into a single
+ * JSON document — config summary, TM cache stats, pair graph with resolved
+ * models/tiers/plugins, and per-pair register info.
+ */
+function runJson(config, pairs, plugins, cwd) {
+  const tmPath = path.join(cwd, TM_DIR, TM_FILENAME);
+  let tm = { exists: false, entries: 0, sizeBytes: 0 };
+  if (fs.existsSync(tmPath)) {
+    const stat = fs.statSync(tmPath);
+    tm = { exists: true, entries: tmSize(loadTM(cwd)), sizeBytes: stat.size };
+  }
+
+  const pairList = [];
+  for (const [pairKey, pairConfig] of pairs) {
+    const tier = QUALITY_TIERS[pairConfig.qualityTier];
+    const resolvedPair = resolvePluginForPair(plugins, pairConfig);
+
+    // Same display-model resolution as the human path: direct providers may
+    // have model=null (the method class picks its own default at runtime).
+    let displayModel = pairConfig.model;
+    if (!displayModel && pairConfig.method !== 'api') {
+      try {
+        const method = getMethod(pairConfig.method);
+        displayModel = method._getDefaultModel?.() || 'auto';
+      } catch { displayModel = 'auto'; }
+    }
+
+    const presets = getRegisterPresets(pairConfig.target);
+    const matchedPreset = pairConfig.registerPreset
+      ? presets.find(p => p.key === pairConfig.registerPreset)
+      : null;
+
+    pairList.push({
+      pair: pairKey,
+      target: pairConfig.target,
+      name: pairConfig.name,
+      method: pairConfig.method,
+      model: pairConfig.method === 'api' ? null : (displayModel || 'auto'),
+      qualityTier: pairConfig.qualityTier,
+      qualityTierLabel: tier ? tier.label : pairConfig.qualityTier,
+      dir: pairConfig.dir || 'ltr',
+      scripts: pairConfig.scripts || null,
+      // Resolved script decision (kept alongside legacy `scripts` for compat)
+      script: pairConfig.scriptResolution
+        ? {
+          resolved: pairConfig.scriptResolution.script,
+          source: pairConfig.scriptResolution.source,
+          converts: !!pairConfig.scriptResolution.converterKey,
+        }
+        : null,
+      plugin: resolvedPair.pluginName
+        ? { name: resolvedPair.pluginName, version: resolvedPair.pluginVersion || null }
+        : null,
+      benchmarks: resolvedPair.pluginBenchmarks?.[pairConfig.target] || null,
+      register: matchedPreset
+        ? { preset: matchedPreset.key, label: matchedPreset.label, isDefault: !!matchedPreset.isDefault }
+        : { preset: null, custom: pairConfig.register || DEFAULT_REGISTER_FALLBACK },
+    });
+  }
+
+  console.log(JSON.stringify({
+    command: 'status',
+    version: CLI_VERSION,
+    inputLocale: config.inputLocale,
+    localesDir: config.localesDir,
+    defaultModel: config.model,
+    temperature: config.temperature ?? null,
+    configVersion: config.version || '2 (legacy)',
+    format: config.format,
+    contentDir: config.contentDir || null,
+    plugins: plugins.size,
+    tm,
+    pairs: pairList,
+  }, null, 2));
+
+  return 0;
+}
+
+export { run };

package/lib/commands/submit.js

@@ -0,0 +1,332 @@
+/**
+ * Command: submit
+ *
+ * The low-friction CLI front door to Champollion's REVIEW-GATED community
+ * submission path. It gathers the fields for a chosen submission type and
+ * prints a PRE-FILLED GitHub issue URL (optionally also writing a local
+ * submission JSON). The GitHub issue IS the human-review queue: a maintainer
+ * reviews each one against IP / license / sovereignty rules before adding the
+ * entry to the relevant source-of-truth. Nothing here is auto-approved, and
+ * this command never writes to a registry, a card, or a database.
+ *
+ * Six submission types (see lib/submit.mjs / .github/ISSUE_TEMPLATE/):
+ *   dataset · resource · method · human-service · external-result · card-correction
+ *
+ * Interactive wizard when stdin is a TTY; fully scriptable via flags otherwise
+ * (--type + --values/--field + --attest, or --yes). See `champollion submit --help`.
+ *
+ * Exit codes: 0 = URL produced (or cancelled); 1 = invalid/incomplete request.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { output } from '../output.js';
+import {
+  SUBMISSION_TYPES,
+  ATTESTATION_TEXT,
+  DEFAULT_REPO_BASE,
+  resolveType,
+  repoBaseFromRepository,
+  validateSubmission,
+  buildIssueUrl,
+  buildSubmissionRecord,
+} from '../submit.mjs';
+
+function isInteractive() {
+  return process.stdin.isTTY === true;
+}
+
+function ask(rl, question, defaultValue) {
+  return new Promise((resolve) => {
+    const suffix = defaultValue ? ` (${defaultValue})` : '';
+    rl.question(`  ${question}${suffix}: `, (answer) => {
+      resolve(answer.trim() || defaultValue || '');
+    });
+  });
+}
+
+/** Resolve the repo base from cli/package.json, falling back to the default. */
+function resolveRepoBase(args) {
+  if (args.repo) return repoBaseFromRepository(args.repo);
+  try {
+    const pkgUrl = new URL('../../package.json', import.meta.url);
+    const pkg = JSON.parse(fs.readFileSync(pkgUrl, 'utf-8'));
+    const repoUrl = pkg?.repository?.url || pkg?.repository;
+    return repoBaseFromRepository(repoUrl);
+  } catch {
+    return DEFAULT_REPO_BASE;
+  }
+}
+
+const BOOL_RE = /^(true|yes|1|y|on)$/i;
+
+/** Coerce any string-y bool field values (from --values/--field) to real booleans. */
+function coerceBools(type, values) {
+  for (const f of type.fields) {
+    if (f.kind === 'bool' && typeof values[f.id] === 'string') {
+      values[f.id] = BOOL_RE.test(values[f.id].trim());
+    }
+  }
+  return values;
+}
+
+// ── Interactive wizard ──────────────────────────────────────────────────────
+
+async function pickType(rl, args) {
+  const pre = resolveType(args.type);
+  if (pre) return pre;
+  console.log('');
+  console.log('  What are you submitting?');
+  console.log('');
+  SUBMISSION_TYPES.forEach((t, i) => {
+    console.log(`    ${i + 1}. ${t.label}`);
+    console.log(`       ${t.blurb}`);
+  });
+  console.log('');
+  const choice = await ask(rl, 'Choose a type (number or name)', '1');
+  return resolveType(choice) || SUBMISSION_TYPES[0];
+}
+
+async function runInteractive(rl, args) {
+  console.log('');
+  console.log('  champollion — Submit to the index');
+  console.log('  ════════════════════════════════════════════════');
+  console.log('');
+  console.log('  Every submission is HUMAN-REVIEWED for IP / license / sovereignty');
+  console.log('  compliance before anything is added — nothing is auto-approved. This');
+  console.log('  command just gathers the fields and hands you a pre-filled GitHub issue.');
+
+  const type = await pickType(rl, args);
+  console.log('');
+  console.log(`  ${type.label}`);
+  console.log('  ────────────────────────────────────────────────');
+
+  const values = {};
+  for (const f of type.fields) {
+    if (f.kind === 'bool') continue; // handled together at the end
+    if (f.kind === 'choice') {
+      console.log('');
+      console.log(`  ${f.label}${f.required ? '  (required)' : ''}`);
+      f.choices.forEach((c, i) => console.log(`    ${i + 1}. ${c}`));
+      const pick = await ask(rl, 'Choose', '');
+      if (pick) {
+        const idx = /^\d+$/.test(pick) ? Number(pick) - 1 : f.choices.findIndex((c) => c.toLowerCase() === pick.toLowerCase());
+        values[f.id] = f.choices[idx] != null ? f.choices[idx] : pick;
+      }
+    } else {
+      let v = await ask(rl, `${f.label}${f.required ? '  (required)' : ''}`, '');
+      if (!v && f.required) v = await ask(rl, `↳ ${f.id} is required`, '');
+      if (v) values[f.id] = v;
+    }
+  }
+
+  // Confirmations (attestation + any per-type consent) — must be affirmative.
+  console.log('');
+  console.log('  Confirmation');
+  console.log('  ────────────────────────────────────────────────');
+  for (const f of type.fields) {
+    if (f.kind !== 'bool') continue;
+    const yn = await ask(rl, `${f.label}\n    Confirm? (y/N)`, 'N');
+    values[f.id] = BOOL_RE.test(yn.trim());
+  }
+  return { type, values };
+}
+
+// ── Non-interactive (flags) ─────────────────────────────────────────────────
+
+function gatherFromFlags(type, args) {
+  const values = {};
+  if (args.values) {
+    try {
+      const parsed = JSON.parse(args.values);
+      if (parsed && typeof parsed === 'object') Object.assign(values, parsed);
+    } catch {
+      // Surface as a validation error path: leave values empty so required
+      // fields are reported missing rather than silently swallowing bad JSON.
+      output.warn('--values was not valid JSON; ignoring it.');
+    }
+  }
+  const fieldFlags = args.field == null ? [] : (Array.isArray(args.field) ? args.field : [args.field]);
+  for (const pair of fieldFlags) {
+    const s = String(pair);
+    const eq = s.indexOf('=');
+    if (eq === -1) continue;
+    values[s.slice(0, eq).trim()] = s.slice(eq + 1);
+  }
+  // --attest confirms every required confirmation at once; --consent is a
+  // narrower alias for the human-service provider-consent box.
+  if (args.attest) for (const f of type.fields) if (f.kind === 'bool') values[f.id] = true;
+  if (args.consent) values.consent = true;
+  return coerceBools(type, values);
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function run(args, cwd) {
+  if (args.help) {
+    showHelp();
+    return 0;
+  }
+  if (args.list) {
+    if (args.json) {
+      console.log(JSON.stringify({
+        types: SUBMISSION_TYPES.map((t) => ({
+          key: t.key, label: t.label, template: t.template,
+          target_ssot: t.ssot,
+          fields: t.fields.map((f) => ({ id: f.id, kind: f.kind, required: !!f.required })),
+        })),
+        attestation: ATTESTATION_TEXT,
+      }, null, 2));
+      return 0;
+    }
+    console.log('');
+    console.log('  Submission types (champollion submit --type <key>):');
+    console.log('');
+    SUBMISSION_TYPES.forEach((t, i) => {
+      console.log(`    ${i + 1}. ${t.key} — ${t.label}`);
+      console.log(`       ${t.blurb}`);
+      console.log(`       → reviewed, then added to: ${t.ssot}`);
+    });
+    console.log('');
+    console.log('  Every submission is human-reviewed; nothing is auto-approved.');
+    console.log('');
+    return 0;
+  }
+
+  const repoBase = resolveRepoBase(args);
+
+  // Gather the submission (interactive wizard or flags).
+  let type;
+  let values;
+  if (!args.yes && isInteractive()) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      ({ type, values } = await runInteractive(rl, args));
+    } finally {
+      rl.close();
+    }
+  } else {
+    type = resolveType(args.type);
+    if (!type) {
+      output.error('Choose a submission type with --type (run `champollion submit --list`).');
+      return 1;
+    }
+    values = gatherFromFlags(type, args);
+  }
+
+  // Validate — collect every problem, fail loud.
+  const v = validateSubmission(type, values);
+  if (!v.ok) {
+    console.error('[ERR] Cannot build this submission:');
+    for (const e of v.errors) console.error(`      • ${e}`);
+    console.error('');
+    console.error('      The compliance attestation is required. Re-run and confirm it');
+    console.error('      (interactively, or pass --attest with the other fields).');
+    return 1;
+  }
+
+  const issueUrl = buildIssueUrl({ type, values, repoBase });
+  const generatedAt = new Date().toISOString();
+  const record = buildSubmissionRecord({ type, values, repoBase, generatedAt });
+
+  // Optionally save a local content-free copy.
+  let localPath = null;
+  if (args.out) {
+    localPath = path.resolve(cwd, args.out);
+    try {
+      fs.mkdirSync(path.dirname(localPath), { recursive: true });
+      fs.writeFileSync(localPath, JSON.stringify(record, null, 2) + '\n', 'utf-8');
+    } catch (e) {
+      output.error(`Could not write the local submission file to ${localPath}: ${e.message}`);
+      return 1;
+    }
+  }
+
+  // ── Report ──
+  if (args.json) {
+    console.log(JSON.stringify({
+      ok: true,
+      type: type.key,
+      target_ssot: type.ssot,
+      title: `${type.titlePrefix}${values[type.fields.find((f) => f.primary)?.id] ?? ''}`.trimEnd(),
+      labels: type.labels,
+      attestationConfirmed: values.attestation === true,
+      issueUrl,
+      localPath,
+      review: 'human-reviewed — not auto-approved',
+    }, null, 2));
+    return 0;
+  }
+
+  console.log('');
+  output.ok(`Submission ready: ${type.label}`);
+  console.log('');
+  console.log('  This will be HUMAN-REVIEWED for IP / license / sovereignty compliance');
+  console.log('  before anything is added to the index — nothing is auto-approved.');
+  console.log('');
+  console.log('  Open this pre-filled GitHub issue to file it (review the attestation box');
+  console.log('  in the browser, then submit):');
+  console.log('');
+  console.log(`    ${issueUrl}`);
+  console.log('');
+  if (localPath) {
+    console.log(`  Saved a local copy: ${localPath}`);
+    console.log('');
+  }
+  return 0;
+}
+
+function showHelp() {
+  console.log(`
+  champollion submit — Propose an entry for the Champollion index (review-gated)
+
+  USAGE
+    champollion submit [options]
+
+  DESCRIPTION
+    Gather the fields for a submission and print a PRE-FILLED GitHub issue URL
+    (optionally writing a local submission JSON). The GitHub issue is the
+    human-review queue: a maintainer reviews every submission against IP /
+    license / sovereignty rules before adding it to a source-of-truth. Nothing
+    is auto-approved, and this command never writes to a registry or database.
+
+    Interactive when run in a terminal; fully scriptable with flags (or --yes).
+
+  SUBMISSION TYPES  (--type)
+    dataset           A benchmark / evaluation corpus (metadata + fetch pointer only).
+    resource          A dictionary / archive / app / FST / tool (a pointer, not a copy).
+    method            A translation method / MT engine / LLM provider.
+    human-service     An opt-in human translation provider (contact PII stays out-of-band).
+    external-result   A published result from another system/paper (cited, never re-hosted).
+
+  OPTIONS
+    --type <key>      Submission type (see --list). Required when non-interactive.
+    --values <json>   JSON object of field id → value (e.g. '{"dataset-name":"X"}').
+    --field <id=val>  Set one field (repeatable): --field source-url=https://…
+    --attest          Confirm the required compliance attestation (and consent).
+    --consent         human-service: confirm the provider's listing consent.
+    --out <path>      Also write a local content-free submission JSON here.
+    --repo <url>      Override the GitHub repo for the issue URL (advanced/testing).
+    --list            List the submission types (add --json for JSON).
+    --json            Machine-readable output (for agents).
+    --yes             Non-interactive; take values from flags.
+
+  ATTESTATION (required on every submission)
+    "${ATTESTATION_TEXT}"
+
+  EXAMPLES
+    champollion submit                                   # interactive wizard
+    champollion submit --list                            # see the types
+    # A dataset submission, fully from flags:
+    champollion submit --yes --type dataset --attest \\
+      --field dataset-name="GlobalVoices eng-amh" \\
+      --field pairs=eng-amh --field license=CC-BY-4.0 \\
+      --field source-url=https://globalvoices.org
+    # An external result, with a saved local copy:
+    champollion submit --yes --type external-result --attest --out ./submission.json \\
+      --values '{"system-name":"NLLB-200","pairs":"eng-crk","dataset":"FLORES-200","metric":"chrF++","score":"28.4","citation":"https://arxiv.org/abs/2207.04672"}'
+  `);
+}
+
+export { run };

package/lib/commands/sync.js

@@ -0,0 +1,89 @@
+/**
+ * Command: sync
+ *
+ * Translates & syncs all locale files based on the project config.
+ * Delegates entirely to lib/sync.runSync — this module just bridges
+ * CLI arguments to the sync engine's options object.
+ */
+
+import { runSync } from '../sync.js';
+import { output } from '../output.js';
+
+/**
+ * Map a runSync result to a process exit code.
+ *
+ * Exit codes (documented contract for CI pipelines + agents):
+ *   0 — clean: everything translated, verification passed.
+ *   1 — catastrophic: failures occurred and NOTHING was translated.
+ *       This is the bad-key / 401 case — every locale failed, so
+ *       totalProcessed is 0. The old gate (`totalFailed > 0 &&
+ *       totalProcessed > 0`) returned 0 here, so a `sync` wired into a
+ *       pre-deploy hook went green while silently shipping English
+ *       fallbacks. Any failure with zero progress must be loud.
+ *   2 — partial: some keys translated but others failed, OR verification
+ *       found errors. The run did real work but isn't clean.
+ *       ALSO used for a --max-cost abort: the pre-run estimate exceeded the
+ *       cap (or was unknowable — unknown ≠ free), so the sync deliberately
+ *       stopped BEFORE any API call. Not catastrophic (nothing broke,
+ *       nothing was spent), but definitely not a clean pass either.
+ *
+ * Pure and total (never throws) so it can be unit-tested directly.
+ *
+ * @param {{ totalProcessed?: number, totalFailed?: number, verifyErrors?: number, maxCostAborted?: boolean } | null | undefined} result
+ * @returns {number} exit code
+ */
+function computeExitCode(result) {
+  if (!result) return 0;
+
+  // --max-cost abort: deliberate pre-run stop, exit 2 by documented contract.
+  if (result.maxCostAborted) return 2;
+
+  const processed = result.totalProcessed || 0;
+  const failed = result.totalFailed || 0;
+  const verifyErrors = result.verifyErrors || 0;
+
+  // Catastrophic: failures with no successful work. A fully-failed sync
+  // (bad key, every locale errored) must never exit 0.
+  if (failed > 0 && processed === 0) return 1;
+
+  // Partial: real work done but something failed, or files didn't verify.
+  if (failed > 0 || verifyErrors > 0) return 2;
+
+  return 0;
+}
+
+/**
+ * @param {import('../types.js').CLIArgs} args - Parsed CLI arguments
+ * @param {string} cwd - Working directory
+ * @returns {Promise<number>} Exit code: 0 = success, 1 = error, 2 = partial failure
+ */
+async function run(args, cwd) {
+  // Set output mode before any sync work begins.
+  // --json: machine-readable NDJSON, one JSON object per line.
+  // --quiet: suppress info/ok messages, show only warnings and errors.
+  if (args.json) output.setMode('json');
+  else if (args.quiet) output.setMode('quiet');
+
+  let result;
+  try {
+    result = await runSync({
+      dryRun: !!args.dry,
+      cwd,
+      cliArgs: args,
+    });
+  } catch (err) {
+    // In --json mode every outcome must be machine-parseable — including a
+    // hard error (missing locales dir, preflight failure). Emit a structured
+    // summary object instead of letting the dispatcher print a bare [ERR]
+    // line that an agent would have to regex.
+    if (args.json) {
+      output.summary({ command: 'sync', ok: false, error: err.message });
+      return 1;
+    }
+    throw err;
+  }
+
+  return computeExitCode(result);
+}
+
+export { run, computeExitCode };