champollion 0.3.3 → 0.4.0

package/lib/methods/external.js

@@ -3,7 +3,7 @@
  *
  * This is the core Champollion deployment pipeline for custom methods:
  *
- *   1. pip install crk-translate (or quechua-translate, or any module)
+ *   1. python3 -m pip install crk-translate (or quechua-translate, or any module)
  *   2. champollion init → wizard detects the module, offers it
  *   3. champollion sync → bridge spawns, translates, done
  *
@@ -51,6 +51,55 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
  */
 const BRIDGE_SCRIPT = resolve(__dirname, '..', 'bridge', 'method_bridge.py');
 
+/** Interpreter names tried in order (python3 on macOS/Linux, python on Windows). */
+const PYTHON_CANDIDATES = ['python3', 'python'];
+
+/**
+ * Spawn the first Python interpreter that exists.
+ *
+ * spawn() reports a missing executable ASYNCHRONOUSLY, as an 'error' event
+ * with code ENOENT — a try/catch around spawn() never sees it. So wait for
+ * 'spawn' (it started) or 'error' (it didn't), and move to the next name only
+ * on ENOENT. Rejects with an actionable message when none exists.
+ *
+ * @param {string[]} args
+ * @param {import('node:child_process').SpawnOptions} options
+ * @returns {Promise<import('node:child_process').ChildProcess>}
+ */
+function spawnPython(args, options) {
+  return new Promise((resolvePromise, reject) => {
+    const attempt = (i) => {
+      const proc = spawn(PYTHON_CANDIDATES[i], args, options);
+      const onSpawn = () => {
+        proc.removeListener('error', onError);
+        resolvePromise(proc);
+      };
+      const onError = (err) => {
+        proc.removeListener('spawn', onSpawn);
+        if (err.code !== 'ENOENT') return reject(err);
+        if (i + 1 < PYTHON_CANDIDATES.length) return attempt(i + 1);
+        reject(new Error(
+          `Python is required for external method modules but was not found ` +
+          `(tried ${PYTHON_CANDIDATES.join(', ')} on PATH).\n` +
+          '  Install Python 3.10+ from https://python.org'
+        ));
+      };
+      proc.once('spawn', onSpawn);
+      proc.once('error', onError);
+    };
+    attempt(0);
+  });
+}
+
+/**
+ * Bridges alive in this process. Killed on exit as a backstop, so no Python
+ * child outlives the CLI even on a path that never called shutdown().
+ */
+const liveBridges = new Set();
+process.once('exit', () => {
+  for (const proc of liveBridges) proc.kill();
+});
+
 class ExternalMethod extends TranslationMethod {
   constructor(options = {}) {
     super('external', options);
@@ -58,6 +107,13 @@ class ExternalMethod extends TranslationMethod {
     this._process = null;
     this._rl = null;
     this._methodName = null;
+    // In-flight bridge start, shared by concurrent callers so they don't each
+    // spawn a process.
+    this._starting = null;
+    // The bridge answers one JSON line per request, in order. Requests are
+    // chained so concurrent callers (pairs translating in parallel on one
+    // shared instance) can never read each other's response line.
+    this._queue = Promise.resolve();
   }
 
   /**
@@ -69,7 +125,13 @@ class ExternalMethod extends TranslationMethod {
    */
   async _ensureBridge(cwd) {
     if (this._process) return;
+    if (!this._starting) {
+      this._starting = this._startBridge(cwd).finally(() => { this._starting = null; });
+    }
+    await this._starting;
+  }
 
+  async _startBridge(cwd) {
     const methodPath = this._methodPath
       ? resolve(cwd || '.', this._methodPath)
       : null;
@@ -77,42 +139,43 @@ class ExternalMethod extends TranslationMethod {
     const args = [BRIDGE_SCRIPT];
     if (methodPath) args.push('--method', methodPath);
 
-    // Try python3 first (macOS/Linux convention), then python (Windows)
-    let pythonCmd = 'python3';
-    try {
-      this._process = spawn(pythonCmd, args, {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        cwd: cwd || process.cwd(),
-      });
-    } catch {
-      pythonCmd = 'python';
-      this._process = spawn(pythonCmd, args, {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        cwd: cwd || process.cwd(),
-      });
-    }
-
-    // Handle spawn failure (Python not installed)
-    this._process.on('error', (err) => {
-      if (err.code === 'ENOENT') {
-        throw new Error(
-          'Python is required for external method modules but was not found.\n' +
-          '  Install Python 3.10+ from https://python.org'
-        );
+    const proc = await spawnPython(args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      cwd: cwd || process.cwd(),
+    });
+    this._process = proc;
+    liveBridges.add(proc);
+
+    // A later process error (e.g. EPIPE) must not become an uncaught
+    // exception; pending reads reject via _readResponse's listeners.
+    proc.on('error', (err) => output.warn(`  [method] bridge error: ${err.message}`));
+    // A dead bridge is forgotten so the next request starts a fresh one
+    // instead of writing into a closed pipe.
+    proc.once('exit', () => {
+      liveBridges.delete(proc);
+      if (this._process === proc) {
+        this._process = null;
+        this._rl = null;
       }
-      throw err;
     });
 
     // Python logging → CLI info channel (stderr is for logs, not errors)
-    const stderrRl = createInterface({ input: this._process.stderr });
+    const stderrRl = createInterface({ input: proc.stderr });
     stderrRl.on('line', (line) => output.info(`  [method] ${line}`));
 
     // stdout → JSON-lines protocol
-    this._rl = createInterface({ input: this._process.stdout });
+    this._rl = createInterface({ input: proc.stdout });
 
     // Wait for the ready signal (first line of output)
-    const ready = await this._readResponse();
+    let ready;
+    try {
+      ready = await this._readResponse();
+    } catch (err) {
+      proc.kill();
+      throw err;
+    }
     if (!ready.ok) {
+      proc.kill();
       throw new Error(ready.error);
     }
     this._methodName = ready.name || 'External Method';
@@ -123,41 +186,62 @@ class ExternalMethod extends TranslationMethod {
    * Send a JSON request line and read the response line.
    */
   async _request(obj) {
-    return new Promise((resolve, reject) => {
+    const send = () => new Promise((resolve, reject) => {
+      if (!this._process) {
+        reject(new Error('Method bridge is not running.'));
+        return;
+      }
+      // Arm the reader before writing so the response line can't slip past.
+      const response = this._readResponse();
+      response.then(resolve, reject);
       const line = JSON.stringify(obj) + '\n';
       this._process.stdin.write(line, 'utf-8', (err) => {
-        if (err) return reject(err);
-        this._readResponse().then(resolve).catch(reject);
+        if (err) reject(err);
       });
     });
+    const result = this._queue.then(send, send);
+    this._queue = result.catch(() => {});
+    return result;
   }
 
   /**
    * Read one JSON-lines response from the bridge subprocess.
    */
   _readResponse() {
+    const rl = this._rl;
+    const proc = this._process;
     return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        rl.removeListener('line', onLine);
+        proc.removeListener('exit', onExit);
+        proc.removeListener('error', onError);
+      };
       const onLine = (line) => {
+        cleanup();
         try {
           resolve(JSON.parse(line));
         } catch (e) {
           reject(new Error(`Invalid response from method bridge: ${line}`));
         }
-        this._rl.removeListener('line', onLine);
-        this._process.removeListener('exit', onExit);
       };
 
       const onExit = (code) => {
-        this._rl.removeListener('line', onLine);
+        cleanup();
         reject(new Error(
           `Method bridge exited unexpectedly (code ${code}).\n` +
           '  Check that the method module is installed correctly.\n' +
-          '  Verify the method module is pip-installed (e.g., pip install <package-name>).'
+          '  Verify the method module is installed (e.g., python3 -m pip install <package-name>).'
         ));
       };
 
-      this._rl.on('line', onLine);
-      this._process.once('exit', onExit);
+      const onError = (err) => {
+        cleanup();
+        reject(err);
+      };
+
+      rl.on('line', onLine);
+      proc.once('exit', onExit);
+      proc.once('error', onError);
     });
   }
 
@@ -173,26 +257,18 @@ class ExternalMethod extends TranslationMethod {
    * @returns {Promise<Array<{name, method_id, supported_pairs, entry_point, plugin_path}>>}
    */
   static async discoverMethods(cwd) {
-    return new Promise((resolve) => {
-      let proc;
-      try {
-        proc = spawn('python3', [BRIDGE_SCRIPT, '--discover'], {
-          stdio: ['pipe', 'pipe', 'pipe'],
-          cwd: cwd || process.cwd(),
-        });
-      } catch {
-        try {
-          proc = spawn('python', [BRIDGE_SCRIPT, '--discover'], {
-            stdio: ['pipe', 'pipe', 'pipe'],
-            cwd: cwd || process.cwd(),
-          });
-        } catch {
-          // Python not available — no method modules discoverable
-          resolve([]);
-          return;
-        }
-      }
+    let proc;
+    try {
+      proc = await spawnPython([BRIDGE_SCRIPT, '--discover'], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: cwd || process.cwd(),
+      });
+    } catch {
+      // Python not available — no method modules discoverable
+      return [];
+    }
 
+    return new Promise((resolve) => {
       let data = '';
       proc.stdout.on('data', (chunk) => { data += chunk; });
 
@@ -307,7 +383,7 @@ class ExternalMethod extends TranslationMethod {
   getSetupHelp() {
     return [
       '  External method module.',
-      '  1. Install a method module (e.g., pip install <module-name>)',
+      '  1. Install a method module (e.g., python3 -m pip install <module-name>)',
       '  2. Run: champollion init',
       '  3. The wizard will detect and configure it automatically.',
     ];
@@ -317,14 +393,21 @@ class ExternalMethod extends TranslationMethod {
    * Clean up: send shutdown command and kill the subprocess.
    */
   async shutdown() {
-    if (this._process) {
-      try {
-        await this._request({ action: 'shutdown' });
-      } catch {
-        // Process may already be dead — that's fine
-      }
-      this._process.kill();
+    if (this._starting) {
+      try { await this._starting; } catch { /* never started — nothing to stop */ }
+    }
+    const proc = this._process;
+    if (!proc) return;
+    try {
+      await this._request({ action: 'shutdown' });
+    } catch {
+      // Process may already be dead — that's fine
+    }
+    proc.kill();
+    liveBridges.delete(proc);
+    if (this._process === proc) {
       this._process = null;
+      this._rl = null;
     }
   }
 }

package/lib/methods/gemini.js

@@ -32,6 +32,7 @@ class GeminiMethod extends DirectLLMMethod {
   _getApiKeyOptionsKey() { return 'geminiApiKey'; }
   _getDefaultModel()     { return DEFAULT_MODEL; }
   _getProviderLabel()    { return 'Gemini'; }
+  _getModelVendor()      { return 'google'; }
 
   // ── API request/response shape ───────────────────────────────────
 

package/lib/methods/google-translate.js

@@ -43,6 +43,7 @@ const GOOGLE_REQUEST_TIMEOUT_MS = 15000;
 class GoogleTranslateMethod extends TranslationMethod {
   constructor(options = {}) {
     super('google-translate', options);
+    this.translatesRawText = true; // see base.js
   }
 
   // ── API resolution helpers ──────────────────────────────────────

package/lib/methods/http-utils.js

@@ -111,7 +111,48 @@ function stripCodeFences(text) {
     .trim();
 }
 
+/**
+ * True only when an endpoint provably stays on this machine — the same rule
+ * as the harness's LocalProvider.is_loopback_endpoint(): unix sockets,
+ * `localhost` (and `*.localhost`), loopback IPs (127.0.0.0/8, ::1) and the
+ * unspecified addresses 0.0.0.0 / :: (a client connecting to them reaches
+ * this host). A LAN or private-range address is another machine: false.
+ *
+ * Used to price a model served here as "$0 API cost (runs on this machine)"
+ * instead of "unknown" — never for an endpoint that only might be local.
+ *
+ * @param {string|null|undefined} url
+ * @returns {boolean}
+ */
+function isLoopbackEndpoint(url) {
+  if (!url || typeof url !== 'string') return false;
+  if (/^(?:http\+)?unix:/i.test(url)) return true;
+  let host;
+  try { host = new URL(url.includes('//') ? url : `http://${url}`).hostname; } catch { return false; }
+  host = host.replace(/^\[|\]$/g, '').toLowerCase();
+  if (!host) return false;
+  if (host === 'localhost' || host.endsWith('.localhost')) return true;
+  if (/^127(?:\.\d{1,3}){3}$/.test(host)) return host.split('.').every(o => Number(o) <= 255);
+  if (host === '0.0.0.0' || host === '::1' || host === '::') return true;
+  // IPv4-mapped IPv6 loopback (::ffff:127.0.0.1 → URL writes ::ffff:7f00:1).
+  if (/^::ffff:(?:127(?:\.\d{1,3}){3}|7f[0-9a-f]{2}:[0-9a-f]{1,4})$/.test(host)) return true;
+  return false;
+}
+
+/** The cost estimate for a model served on this machine (see isLoopbackEndpoint). */
+function localMachineCost(endpoint) {
+  return {
+    estimatedCost: 0,
+    currency: 'USD',
+    source: 'local-machine',
+    local: true,
+    note: `$0 API cost — runs on this machine (${endpoint}); your own hardware and power are not counted.`,
+  };
+}
+
 export {
+  isLoopbackEndpoint,
+  localMachineCost,
   MAX_RETRIES,
   BASE_DELAY_MS,
   REQUEST_TIMEOUT_MS,

package/lib/methods/libretranslate.js

@@ -12,6 +12,7 @@ const LIBRETRANSLATE_REQUEST_TIMEOUT_MS = 15000;
 class LibreTranslateMethod extends TranslationMethod {
   constructor(options = {}) {
     super('libretranslate', options);
+    this.translatesRawText = true; // see base.js
   }
 
   // ── API resolution helpers ──────────────────────────────────────
@@ -24,7 +25,6 @@ class LibreTranslateMethod extends TranslationMethod {
    */
   _resolveApiEndpoint(options) {
     return options.libretranslateApiUrl
-      || getEnvOrFileVar('LIBRETRANSLATE_API_URL')
       || getEnvOrFileVar('LIBRETRANSLATE_API_URL', options.cwd)
       || 'http://localhost:5000/translate';
   }
@@ -36,7 +36,6 @@ class LibreTranslateMethod extends TranslationMethod {
    */
   _resolveApiKey(options) {
     return options.libretranslateApiKey
-      || getEnvOrFileVar('LIBRETRANSLATE_API_KEY')
       || getEnvOrFileVar('LIBRETRANSLATE_API_KEY', options.cwd);
   }
 
@@ -181,6 +180,10 @@ class LibreTranslateMethod extends TranslationMethod {
       if (!response.ok) {
         return {
           ready: false,
+          // A server that is down or failing: sync decides after its plan
+          // whether this run needs it (lib/sync.js deferred probes).
+          unreachable: true,
+          endpoint: baseUrl,
           reason:
             `LibreTranslate server at ${baseUrl} responded with ${response.status}.\n` +
             `  Check that LibreTranslate is running and accessible.`,
@@ -190,6 +193,8 @@ class LibreTranslateMethod extends TranslationMethod {
     } catch (err) {
       return {
         ready: false,
+        unreachable: true,
+        endpoint: baseUrl,
         reason:
           `Cannot reach LibreTranslate server at ${baseUrl}.\n` +
           `  ${err.name === 'AbortError' ? 'Connection timed out.' : err.message}\n` +