champollion 0.3.3

package/lib/commands/models.js

@@ -0,0 +1,177 @@
+/**
+ * Command: models
+ *
+ * Lists available models for a translation provider by querying
+ * the provider's real API. Read-only — shows what models the user's
+ * API key has access to, without modifying any config.
+ *
+ * WHY THIS EXISTS:
+ *   When providers release new models, users need to discover the exact
+ *   slug to put in their config. This command bridges that gap —
+ *   instead of guessing or checking provider docs, run
+ *   `champollion models --method gemini` and see the real list.
+ *
+ * USAGE:
+ *   champollion models --method gemini      # List Gemini models
+ *   champollion models --method openai      # List OpenAI models
+ *   champollion models --method anthropic   # List Anthropic models
+ */
+
+import { resolveConfig } from '../config.js';
+import { fetchAvailableModels, resolveProviderApiKey, getProviderLabel, isListableProvider, getListableProviders } from '../models.js';
+import { output } from '../output.js';
+
+/**
+ * @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 listing off stdout; warnings still reach stderr.
+  const json = !!args.json;
+  if (json) output.setMode('quiet');
+
+  if (args.help) {
+    showHelp();
+    return 0;
+  }
+
+  const method = args.method;
+  if (!method) {
+    if (json) {
+      console.log(JSON.stringify({
+        command: 'models',
+        providers: getListableProviders().map(p => ({ method: p, label: getProviderLabel(p) })),
+        note: 'Pass --method <provider> to list its models.',
+      }, null, 2));
+      return 0;
+    }
+    output.raw('\n  Usage: champollion models --method <provider>\n');
+    output.raw('  Available providers with model listing:');
+    for (const provider of getListableProviders()) {
+      output.raw(`    - ${provider} (${getProviderLabel(provider)})`);
+    }
+    output.raw('');
+    output.raw('  Example: champollion models --method gemini\n');
+    return 0;
+  }
+
+  if (!isListableProvider(method)) {
+    if (json) {
+      console.log(JSON.stringify({
+        command: 'models',
+        method,
+        error: `Provider "${method}" does not support model listing.`,
+        providers: getListableProviders().map(p => ({ method: p, label: getProviderLabel(p) })),
+      }, null, 2));
+      return 1;
+    }
+    output.warn(`Provider "${method}" does not support model listing.`);
+    output.raw('');
+    output.raw('  Providers with model listing support:');
+    for (const provider of getListableProviders()) {
+      output.raw(`    - ${provider} (${getProviderLabel(provider)})`);
+    }
+    output.raw('');
+    return 1;
+  }
+
+  // Resolve API key from environment or .env files
+  const apiKey = resolveProviderApiKey(method, cwd);
+  if (!apiKey) {
+    const label = getProviderLabel(method);
+    if (json) {
+      console.log(JSON.stringify({
+        command: 'models',
+        method,
+        error: `No API key found for ${label}.`,
+      }, null, 2));
+      return 1;
+    }
+    output.warn(`No API key found for ${label}.`);
+    output.raw('');
+    output.raw(`  Set the environment variable or add it to .env.local.`);
+    output.raw(`  Then re-run: champollion models --method ${method}`);
+    output.raw('');
+    return 1;
+  }
+
+  // Fetch available models from the provider's real API
+  output.raw(`\n  Fetching models from ${getProviderLabel(method)}...\n`);
+  const models = await fetchAvailableModels(method, apiKey);
+
+  if (!models || models.length === 0) {
+    if (json) {
+      console.log(JSON.stringify({
+        command: 'models',
+        method,
+        error: 'Could not fetch model list. Check your API key and network connection.',
+      }, null, 2));
+      return 1;
+    }
+    output.warn('Could not fetch model list. Check your API key and network connection.');
+    return 1;
+  }
+
+  // Current config model, if a config exists (informational in both modes)
+  let currentModel = null;
+  try {
+    const config = resolveConfig(args, cwd);
+    if (config.model) currentModel = config.model;
+  } catch {
+    // No config file — that's fine, just don't show current model
+  }
+
+  if (json) {
+    console.log(JSON.stringify({
+      command: 'models',
+      method,
+      provider: getProviderLabel(method),
+      models,
+      count: models.length,
+      currentConfigModel: currentModel,
+    }, null, 2));
+    return 0;
+  }
+
+  // Display models as a numbered list
+  output.raw(`  Available models (${models.length}):\n`);
+  for (let i = 0; i < models.length; i++) {
+    output.raw(`    ${String(i + 1).padStart(3)}.  ${models[i]}`);
+  }
+
+  if (currentModel) {
+    output.raw('');
+    output.raw(`  Current config model: ${currentModel}`);
+  }
+
+  output.raw('');
+  output.raw('  To use a model, set "model" in your champollion.config.json');
+  output.raw('  or pass --model <id> to sync.\n');
+
+  return 0;
+}
+
+function showHelp() {
+  console.log(`
+  champollion models — List available models for a provider
+
+  USAGE
+    champollion models --method <provider>
+
+  DESCRIPTION
+    Queries the provider's real API to show which models your API key
+    has access to. Read-only — does not modify any config files.
+
+  OPTIONS
+    --method <provider>   Provider to query: gemini, openai, anthropic
+
+  EXAMPLES
+    champollion models --method gemini      # List Gemini models
+    champollion models --method openai      # List OpenAI models
+    champollion models --method anthropic   # List Anthropic models
+  `);
+}
+
+export { run };

package/lib/commands/plugin.js

@@ -0,0 +1,103 @@
+/**
+ * Command: plugin
+ *
+ * Manages method plugins for champollion:
+ *   - list:    Show installed plugins with metadata
+ *   - install: Install from a local directory (registry coming later)
+ *   - remove:  Remove an installed plugin
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  installPluginFromLocal, removePlugin, listPlugins,
+} from '../plugins.js';
+import { output } from '../output.js';
+
+/**
+ * @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) {
+  const subcommand = args._[1];
+  const pluginArg = args._[2];
+
+  if (subcommand === 'list') {
+    const installed = listPlugins(cwd);
+    if (installed.length === 0) {
+      output.raw('\n  No plugins installed.');
+      output.raw('  Install one: champollion plugin install <name-or-path>\n');
+    } else {
+      output.raw(`\n  Installed Plugins (${installed.length}):\n`);
+      for (const plugin of installed) {
+        const localeStr = plugin.locales.join(', ');
+        const benchStr = plugin.hasBenchmarks ? '| benchmarks: yes' : '';
+        output.raw(`    ${plugin.name} v${plugin.version}`);
+        output.raw(`      type: ${plugin.type}  |  locales: ${localeStr}  |  quality: ${plugin.qualityTier}  ${benchStr}`);
+        if (plugin.description) {
+          output.raw(`      ${plugin.description}`);
+        }
+      }
+      output.raw('');
+    }
+    return 0;
+  }
+
+  if (subcommand === 'install') {
+    if (!pluginArg) {
+      output.error('Usage: champollion plugin install <name-or-path>');
+      return 1;
+    }
+
+    // Determine install source: local path or name (future: registry URL)
+    const resolvedPath = path.resolve(pluginArg);
+    if (fs.existsSync(resolvedPath) && fs.statSync(resolvedPath).isDirectory()) {
+      // Local directory install
+      const result = installPluginFromLocal(resolvedPath, cwd);
+      if (result.success) {
+        output.ok(`Installed plugin: ${result.name}`);
+        output.raw(`     Location: .champollion/methods/${result.name}/\n`);
+        return 0;
+      } else {
+        output.error(`Install failed: ${result.error}`);
+        return 1;
+      }
+    } else {
+      // Name-based install — placeholder for future registry
+      output.error(`Plugin "${pluginArg}" not found as a local directory.`);
+      output.raw('     Remote plugin registries are not yet supported.');
+      output.raw('     Install from a local directory:\n');
+      output.raw(`     champollion plugin install ./path/to/${pluginArg}/\n`);
+      return 1;
+    }
+  }
+
+  if (subcommand === 'remove') {
+    if (!pluginArg) {
+      output.error('Usage: champollion plugin remove <name>');
+      return 1;
+    }
+
+    const result = removePlugin(pluginArg, cwd);
+    if (result.success) {
+      output.ok(`Removed plugin: ${pluginArg}`);
+      return 0;
+    } else {
+      output.error(result.error);
+      return 1;
+    }
+  }
+
+  // No valid subcommand — show help
+  output.raw(`
+  Plugin Commands:
+
+    champollion plugin list                List installed plugins
+    champollion plugin install <path>      Install a plugin from a local directory
+    champollion plugin remove <name>       Remove an installed plugin
+  `);
+  return 0;
+}
+
+export { run };

package/lib/commands/provenance.js

@@ -0,0 +1,45 @@
+/**
+ * Command: provenance
+ *
+ * Shows licensing and resource dependencies for all translation pairs.
+ * Important for commercial readiness audits — each method reports what
+ * external resources it relies on and their license status.
+ */
+
+import { resolveConfig, autoDetectLanguages } from '../config.js';
+import { resolvePairs } from '../pairs.js';
+import { formatProvenanceReport } from '../provenance.js';
+import { output } from '../output.js';
+
+/**
+ * @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) {
+  // provenance takes no subcommand — a stray positional (e.g. `provenance bogus`)
+  // is almost always a typo. Reject it with a non-zero exit instead of silently
+  // ignoring it and reporting on the whole project. Matches `tm`/`seo`.
+  const sub = args._[1];
+  if (sub && sub !== 'help') {
+    output.error(`Unknown subcommand: "${sub}". Usage: champollion provenance`);
+    return 1;
+  }
+
+  const config = resolveConfig(args, cwd);
+
+  let languages = config.resolvedLanguages;
+  if (Object.keys(languages).length === 0) {
+    languages = autoDetectLanguages(config);
+  }
+  config.resolvedLanguages = languages;
+
+  const pairs = resolvePairs(config);
+  const report = formatProvenanceReport(pairs);
+  output.raw('\n  champollion — Provenance Report\n');
+  output.raw(report);
+
+  return 0;
+}
+
+export { run };

package/lib/commands/recommend.js

@@ -0,0 +1,75 @@
+/**
+ * Command: recommend
+ *
+ * Method guidance for a language pair — availability + cited evidence.
+ * CLI port of `mt-eval recommend` (arena/mt_eval_harness/recommend.py); the
+ * assembly/honesty logic lives in lib/recommend.js.
+ *
+ * Usage:
+ *   champollion recommend eng yor                    # Human-readable guidance
+ *   champollion recommend eng yor --use commercial   # STRICT commercial lane
+ *   champollion recommend eng yor --json             # Machine-readable payload
+ */
+
+import { output } from '../output.js';
+import { recommend, renderText } from '../recommend.js';
+import { resolveCode } from '../registers.js';
+
+const USE_CONTEXTS = ['non-commercial', 'commercial'];
+
+/**
+ * @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) {
+  const srcInput = args._[1];
+  const tgtInput = args._[2];
+  if (!srcInput || !tgtInput) {
+    output.error('recommend requires a source and target language code.');
+    output.error('Usage: champollion recommend <src> <tgt> [--use commercial] [--json]');
+    output.error('Example: champollion recommend eng yor');
+    return 1;
+  }
+
+  // The evidence indexes are keyed by ISO 639-3; accept the 2-letter codes a
+  // champollion.config.json uses (en → eng, zh → cmn) via the language-card
+  // alias bridge, and surface the resolution rather than silently relabelling.
+  const src = resolveCode(srcInput);
+  const tgt = resolveCode(tgtInput);
+
+  // --use is a string flag; a bare `--use` parses as boolean true — treat it
+  // as invalid rather than silently defaulting.
+  const useContext = (args.use == null || args.use === false)
+    ? 'non-commercial'
+    : String(args.use);
+  if (!USE_CONTEXTS.includes(useContext)) {
+    output.error(`Invalid --use value "${useContext}". Valid lanes: ${USE_CONTEXTS.join(', ')}.`);
+    return 1;
+  }
+
+  const payload = recommend(src, tgt, { useContext, cwd });
+  if (src !== srcInput) payload.pair.source_input = srcInput;
+  if (tgt !== tgtInput) payload.pair.target_input = tgtInput;
+
+  if (args.json) {
+    // Single JSON document on stdout (mirrors `mt-eval recommend --json`) —
+    // keep stdout pure for piping into jq.
+    console.log(JSON.stringify(payload, null, 2));
+    return 0;
+  }
+
+  output.raw('');
+  if (src !== srcInput || tgt !== tgtInput) {
+    const resolved = [];
+    if (src !== srcInput) resolved.push(`${srcInput} → ${src}`);
+    if (tgt !== tgtInput) resolved.push(`${tgtInput} → ${tgt}`);
+    output.raw(`(codes resolved to ISO 639-3: ${resolved.join(', ')})`);
+    output.raw('');
+  }
+  output.raw(renderText(payload));
+  output.raw('');
+  return 0;
+}
+
+export { run };