patina-cli 3.11.0

package/src/auth.js

@@ -0,0 +1,105 @@
+import { readFileSync } from 'node:fs';
+import { inputError } from './errors.js';
+
+export const HTTP_KEY_ENV_VARS = [
+  'PATINA_API_KEY',
+  'OPENAI_API_KEY',
+  'GEMINI_API_KEY',
+  'GROQ_API_KEY',
+  'TOGETHER_API_KEY',
+];
+
+// Default openai-http runs against the OpenAI-compatible default endpoint, so
+// only generic/OpenAI keys make it authenticated without an explicit provider.
+export const DEFAULT_HTTP_KEY_ENV_VARS = [
+  'PATINA_API_KEY',
+  'OPENAI_API_KEY',
+];
+
+export function providerHttpKeyEnvVars(providerApiKeyEnv) {
+  if (!providerApiKeyEnv) return DEFAULT_HTTP_KEY_ENV_VARS;
+  return uniqueEnvVars([providerApiKeyEnv, 'PATINA_API_KEY']);
+}
+
+export function inspectHttpApiKeySource({
+  env = process.env,
+  readFile = readFileSync,
+  envVars = DEFAULT_HTTP_KEY_ENV_VARS,
+} = {}) {
+  const filePath = env.PATINA_API_KEY_FILE;
+  if (filePath) {
+    const file = readApiKeyFile(filePath, readFile);
+    return file.ok
+      ? { ok: true, source: 'PATINA_API_KEY_FILE', envVars: [], filePath, detail: `Authenticated via PATINA_API_KEY_FILE (${filePath}).` }
+      : { ok: false, source: 'PATINA_API_KEY_FILE', envVars: [], filePath, detail: file.detail };
+  }
+
+  const present = uniqueEnvVars(envVars).filter((key) => env[key]);
+  if (present.length > 0) {
+    return { ok: true, source: present[0], envVars: present, filePath: null, detail: `Authenticated via ${present.join(', ')}.` };
+  }
+
+  return {
+    ok: false,
+    source: null,
+    envVars: [],
+    filePath: null,
+    detail: 'Set PATINA_API_KEY, PATINA_API_KEY_FILE, OPENAI_API_KEY, or select a provider with its key.',
+  };
+}
+
+export function resolveHttpApiKey({
+  explicitApiKey,
+  apiKeyFile,
+  env = process.env,
+  readFile = readFileSync,
+  envVars = DEFAULT_HTTP_KEY_ENV_VARS,
+} = {}) {
+  const filePath = apiKeyFile || env.PATINA_API_KEY_FILE;
+  if (filePath) {
+    const file = readApiKeyFile(filePath, readFile);
+    if (!file.ok) {
+      throw inputError(
+        file.what,
+        file.detail,
+        'Check the path, write the key into the file, or unset PATINA_API_KEY_FILE.'
+      );
+    }
+    return file.key;
+  }
+
+  if (explicitApiKey) return explicitApiKey;
+
+  const source = inspectHttpApiKeySource({ env, readFile, envVars });
+  return source.ok && source.source !== 'PATINA_API_KEY_FILE'
+    ? env[source.source]
+    : undefined;
+}
+
+function uniqueEnvVars(envVars) {
+  return [...new Set(envVars.filter(Boolean))];
+}
+
+function readApiKeyFile(filePath, readFile) {
+  let contents;
+  try {
+    contents = readFile(filePath, 'utf8');
+  } catch (err) {
+    return {
+      ok: false,
+      what: 'cannot read API key file',
+      detail: `${filePath}: ${err.message}`,
+    };
+  }
+
+  const key = contents.replace(/[\r\n]+$/, '').trim();
+  if (!key) {
+    return {
+      ok: false,
+      what: 'API key file is empty',
+      detail: filePath,
+    };
+  }
+
+  return { ok: true, key };
+}

package/src/backends/claude-cli.js

@@ -0,0 +1,112 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_BACKEND_TIMEOUT_MS } from './contract.js';
+
+export const name = 'claude-cli';
+
+export function isAvailable() {
+  try {
+    const result = spawnSync('claude', ['--version'], { stdio: 'ignore' });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function isAuthenticated() {
+  // Claude Code stores OAuth tokens in ~/.claude/.credentials.json after the
+  // first interactive login. The path is consistent across platforms when the
+  // CLI is installed via the standard installer.
+  return existsSync(join(homedir(), '.claude', '.credentials.json'));
+}
+
+export function authHint() {
+  return 'Run `claude` once interactively and follow the OAuth prompt to authenticate (uses your Claude subscription, no API key needed).';
+}
+
+export async function invoke({ prompt, signal, timeout = DEFAULT_BACKEND_TIMEOUT_MS } = {}) {
+  if (!prompt || typeof prompt !== 'string') {
+    throw new Error('claude-cli backend: prompt must be a non-empty string');
+  }
+  throwIfAborted(signal);
+
+  // Spawn from a fresh temp directory so a prompt-injection in user text
+  // cannot read or write inside the caller's repo. claude -p prints to
+  // stdout, so no output file plumbing is needed (unlike codex-cli).
+  const dir = mkdtempSync(join(tmpdir(), 'patina-claude-'));
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn('claude', ['-p'], { stdio: ['pipe', 'pipe', 'pipe'], cwd: dir });
+
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (chunk) => { stdout += chunk; });
+    proc.stderr.on('data', (chunk) => { stderr += chunk; });
+
+    let settled = false;
+    let cleanupSignal = () => {};
+    const timer = setTimeout(() => {
+      finishReject(new Error(`claude-cli backend: timed out after ${timeout}ms`), { kill: true });
+    }, timeout);
+    if (signal) {
+      const onAbort = () => finishReject(abortError('claude-cli backend: aborted'), { kill: true });
+      signal.addEventListener('abort', onAbort, { once: true });
+      cleanupSignal = () => signal.removeEventListener('abort', onAbort);
+    }
+
+    proc.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        finishReject(new Error('claude-cli backend: `claude` CLI not found. Install Claude Code first.'));
+      } else {
+        finishReject(new Error(`claude-cli backend: failed to spawn claude (${err.message})`));
+      }
+    });
+
+    proc.on('close', (code) => {
+      if (settled) return;
+      if (code !== 0) {
+        finishReject(new Error(`claude-cli backend: claude exited with code ${code}\n${stderr}`));
+        return;
+      }
+      finishResolve(stdout);
+    });
+
+    proc.stdin.write(prompt);
+    proc.stdin.end();
+
+    function cleanup() {
+      try { rmSync(dir, { recursive: true, force: true }); } catch {}
+    }
+
+    function finishReject(err, { kill = false } = {}) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanupSignal();
+      if (kill) proc.kill('SIGKILL');
+      cleanup();
+      reject(err);
+    }
+
+    function finishResolve(content) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanupSignal();
+      cleanup();
+      resolve(content);
+    }
+  });
+}
+
+function abortError(message) {
+  const err = new Error(message);
+  err.name = 'AbortError';
+  return err;
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError('claude-cli backend: aborted');
+}

package/src/backends/codex-cli.js

@@ -0,0 +1,121 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_BACKEND_TIMEOUT_MS } from './contract.js';
+
+export const name = 'codex-cli';
+
+export function isAvailable() {
+  try {
+    const result = spawnSync('codex', ['--version'], { stdio: 'ignore' });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function isAuthenticated() {
+  return existsSync(join(homedir(), '.codex', 'auth.json'));
+}
+
+export function authHint() {
+  return 'Run `codex login` to authenticate (uses your ChatGPT Plus account, no API key needed).';
+}
+
+export async function invoke({ prompt, signal, timeout = DEFAULT_BACKEND_TIMEOUT_MS } = {}) {
+  if (!prompt || typeof prompt !== 'string') {
+    throw new Error('codex-cli backend: prompt must be a non-empty string');
+  }
+  throwIfAborted(signal);
+
+  // Run codex from a fresh temp directory with the read-only sandbox so that
+  // a prompt-injection in user text cannot read the caller's repo or write
+  // arbitrary files. The output file lives inside the same temp dir so codex
+  // can still drop the last message there.
+  const dir = mkdtempSync(join(tmpdir(), 'patina-codex-'));
+  const outFile = join(dir, 'last-message.txt');
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn('codex', [
+      'exec',
+      '--skip-git-repo-check',
+      '--sandbox', 'read-only',
+      '-C', dir,
+      '--output-last-message', outFile,
+    ], { stdio: ['pipe', 'pipe', 'pipe'], cwd: dir });
+
+    let stderr = '';
+    proc.stderr.on('data', (chunk) => { stderr += chunk; });
+
+    let settled = false;
+    let cleanupSignal = () => {};
+    const timer = setTimeout(() => {
+      finishReject(new Error(`codex-cli backend: timed out after ${timeout}ms`), { kill: true });
+    }, timeout);
+    if (signal) {
+      const onAbort = () => finishReject(abortError('codex-cli backend: aborted'), { kill: true });
+      signal.addEventListener('abort', onAbort, { once: true });
+      cleanupSignal = () => signal.removeEventListener('abort', onAbort);
+    }
+
+    proc.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        finishReject(new Error('codex-cli backend: `codex` CLI not found. Install it from https://github.com/openai/codex'));
+      } else {
+        finishReject(new Error(`codex-cli backend: failed to spawn codex (${err.message})`));
+      }
+    });
+
+    proc.on('close', (code) => {
+      if (settled) return;
+      if (code !== 0) {
+        finishReject(new Error(`codex-cli backend: codex exited with code ${code}\n${stderr}`));
+        return;
+      }
+
+      try {
+        const content = readFileSync(outFile, 'utf8');
+        finishResolve(content);
+      } catch (err) {
+        finishReject(new Error(`codex-cli backend: failed to read output file (${err.message})`));
+      }
+    });
+
+    proc.stdin.write(prompt);
+    proc.stdin.end();
+
+    function cleanup() {
+      try { rmSync(dir, { recursive: true, force: true }); } catch {}
+    }
+
+    function finishReject(err, { kill = false } = {}) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanupSignal();
+      if (kill) proc.kill('SIGKILL');
+      cleanup();
+      reject(err);
+    }
+
+    function finishResolve(content) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanupSignal();
+      cleanup();
+      resolve(content);
+    }
+  });
+}
+
+function abortError(message) {
+  const err = new Error(message);
+  err.name = 'AbortError';
+  return err;
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError('codex-cli backend: aborted');
+}

package/src/backends/contract.js

@@ -0,0 +1,21 @@
+export const DEFAULT_BACKEND_TIMEOUT_MS = 180_000;
+
+export function isRetryableBackendError(err, { attemptIndex = 0, signal } = {}) {
+  if (signal?.aborted) return false;
+  const status = extractStatus(err);
+  if (status === 429 || status === 503) return true;
+  return err?.name === 'AbortError' && attemptIndex === 0;
+}
+
+export function describeBackendError(err) {
+  const status = extractStatus(err);
+  if (status) return `HTTP ${status}`;
+  return err?.name || 'error';
+}
+
+function extractStatus(err) {
+  const direct = Number(err?.status);
+  if (Number.isFinite(direct)) return direct;
+  const match = String(err?.message || '').match(/\bHTTP\s+(429|503)\b/);
+  return match ? Number(match[1]) : null;
+}

package/src/backends/gemini-cli.js

@@ -0,0 +1,135 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_BACKEND_TIMEOUT_MS } from './contract.js';
+
+export const name = 'gemini-cli';
+
+export function isAvailable() {
+  try {
+    const result = spawnSync('gemini', ['--version'], { stdio: 'ignore' });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function isAuthenticated() {
+  // Two valid auth paths: OAuth (Code Assist) or API key. Either is enough
+  // for `gemini -p` to run; checking both avoids false negatives.
+  return (
+    existsSync(join(homedir(), '.gemini', 'gemini-credentials.json')) ||
+    !!process.env.GEMINI_API_KEY
+  );
+}
+
+export function authHint() {
+  if (process.env.GEMINI_API_KEY) {
+    return 'Authenticated via GEMINI_API_KEY env var.';
+  }
+  return 'Run `gemini` once interactively to log in via Google OAuth, or set GEMINI_API_KEY.';
+}
+
+export async function invoke({ prompt, model, signal, timeout = DEFAULT_BACKEND_TIMEOUT_MS } = {}) {
+  if (!prompt || typeof prompt !== 'string') {
+    throw new Error('gemini-cli backend: prompt must be a non-empty string');
+  }
+  throwIfAborted(signal);
+
+  // gemini -p '' reads the prompt from stdin (when -p arg is empty, stdin is
+  // appended). --output-format text avoids JSON wrapping. Spawn from a temp
+  // directory for the same prompt-injection containment reason as codex-cli;
+  // --skip-trust is required because the temp dir isn't in gemini's trusted
+  // workspace list (otherwise gemini exits 55).
+  const dir = mkdtempSync(join(tmpdir(), 'patina-gemini-'));
+  const args = ['-p', '', '--output-format', 'text', '--skip-trust'];
+  if (model) args.push('-m', model);
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn('gemini', args, { stdio: ['pipe', 'pipe', 'pipe'], cwd: dir });
+
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (chunk) => { stdout += chunk; });
+    proc.stderr.on('data', (chunk) => { stderr += chunk; });
+
+    let settled = false;
+    let cleanupSignal = () => {};
+    const timer = setTimeout(() => {
+      finishReject(new Error(`gemini-cli backend: timed out after ${timeout}ms`), { kill: true });
+    }, timeout);
+    if (signal) {
+      const onAbort = () => finishReject(abortError('gemini-cli backend: aborted'), { kill: true });
+      signal.addEventListener('abort', onAbort, { once: true });
+      cleanupSignal = () => signal.removeEventListener('abort', onAbort);
+    }
+
+    proc.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        finishReject(new Error('gemini-cli backend: `gemini` CLI not found. Install Gemini CLI first.'));
+      } else {
+        finishReject(new Error(`gemini-cli backend: failed to spawn gemini (${err.message})`));
+      }
+    });
+
+    proc.on('close', (code) => {
+      if (settled) return;
+      if (code !== 0) {
+        finishReject(new Error(`gemini-cli backend: gemini exited with code ${code}\n${stderr}`));
+        return;
+      }
+      finishResolve(stripGeminiNoise(stdout));
+    });
+
+    proc.stdin.write(prompt);
+    proc.stdin.end();
+
+    function cleanup() {
+      try { rmSync(dir, { recursive: true, force: true }); } catch {}
+    }
+
+    function finishReject(err, { kill = false } = {}) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanupSignal();
+      if (kill) proc.kill('SIGKILL');
+      cleanup();
+      reject(err);
+    }
+
+    function finishResolve(content) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanupSignal();
+      cleanup();
+      resolve(content);
+    }
+  });
+}
+
+function abortError(message) {
+  const err = new Error(message);
+  err.name = 'AbortError';
+  return err;
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError('gemini-cli backend: aborted');
+}
+
+// Gemini CLI prepends benign warnings to stdout (e.g. "Ripgrep is not
+// available. Falling back to GrepTool.", "MCP issues detected..."). They
+// aren't part of the model's response, so strip leading lines that match
+// known noise patterns before returning.
+function stripGeminiNoise(text) {
+  const lines = text.split(/\r?\n/);
+  const noiseRe = /^(Warning:|Ripgrep is not available|MCP issues detected|Loaded cached credentials)/i;
+  let i = 0;
+  while (i < lines.length && (noiseRe.test(lines[i]) || lines[i].trim() === '')) {
+    i++;
+  }
+  return lines.slice(i).join('\n');
+}

package/src/backends/index.js

@@ -0,0 +1,159 @@
+import { callLLM } from '../api.js';
+import * as codexCli from './codex-cli.js';
+import * as claudeCli from './claude-cli.js';
+import * as geminiCli from './gemini-cli.js';
+import { inspectHttpApiKeySource } from '../auth.js';
+import { inputError } from '../errors.js';
+import {
+  DEFAULT_BACKEND_TIMEOUT_MS,
+  describeBackendError,
+  isRetryableBackendError,
+} from './contract.js';
+
+const openaiHttp = {
+  name: 'openai-http',
+  isAvailable: () => true,
+  isAuthenticated: () => inspectHttpApiKeySource().ok,
+  authHint: () => inspectHttpApiKeySource().detail,
+  invoke: ({
+    prompt,
+    apiKey,
+    baseURL,
+    model,
+    signal,
+    timeout = DEFAULT_BACKEND_TIMEOUT_MS,
+    temperature,
+    seed,
+    onResponse,
+    cache,
+  }) =>
+    callLLM({ prompt, apiKey, baseURL, model, signal, timeout, temperature, seed, onResponse, cache }),
+};
+
+const REGISTRY = {
+  'openai-http': openaiHttp,
+  'codex-cli': codexCli,
+  'claude-cli': claudeCli,
+  'gemini-cli': geminiCli,
+};
+
+export function listBackends() {
+  return Object.keys(REGISTRY).map((key) => {
+    const b = REGISTRY[key];
+    return {
+      name: key,
+      available: b.isAvailable(),
+      authenticated: b.isAuthenticated(),
+      authHint: b.authHint(),
+    };
+  });
+}
+
+export function listBackendNames() {
+  return Object.keys(REGISTRY);
+}
+
+export function selectBackend({ name, model } = {}) {
+  if (name) {
+    const backend = resolveBackend(name);
+    return { backend, autoSelected: false, reason: 'explicit' };
+  }
+
+  if (model && /^codex(-|$)/i.test(model)) {
+    return { backend: REGISTRY['codex-cli'], autoSelected: false, reason: 'model heuristic' };
+  }
+  if (model && /^claude(-|$)/i.test(model)) {
+    return { backend: REGISTRY['claude-cli'], autoSelected: false, reason: 'model heuristic' };
+  }
+  if (model && /^gemini(-|$)/i.test(model)) {
+    return { backend: REGISTRY['gemini-cli'], autoSelected: false, reason: 'model heuristic' };
+  }
+
+  // No silent auto-fallback to any CLI backend. Sending arbitrary text to a
+  // coding agent is a higher-trust action than calling a plain completion
+  // API, so require an explicit `--backend <name>` (or `--model <prefix>`).
+  // See issue #88.
+  return { backend: REGISTRY['openai-http'], autoSelected: false, reason: 'default' };
+}
+
+export function selectBackendChain({ name, model } = {}) {
+  if (name) {
+    const names = String(name)
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    if (names.length === 0) {
+      throw inputError(
+        '--backend expects at least one backend name',
+        'The comma-separated backend list was empty.',
+        `Available backends are: ${Object.keys(REGISTRY).join(', ')}.`
+      );
+    }
+    return {
+      backends: names.map(resolveBackend),
+      autoSelected: false,
+      reason: names.length > 1 ? 'explicit chain' : 'explicit',
+    };
+  }
+
+  const selected = selectBackend({ model });
+  return {
+    backends: [selected.backend],
+    autoSelected: selected.autoSelected,
+    reason: selected.reason,
+  };
+}
+
+export async function invokeBackendChain({
+  backends,
+  prompt,
+  apiKey,
+  baseURL,
+  model,
+  signal,
+  timeout = DEFAULT_BACKEND_TIMEOUT_MS,
+  temperature,
+  seed,
+  onResponse,
+  cache,
+  logger,
+}) {
+  if (!Array.isArray(backends) || backends.length === 0) {
+    throw inputError(
+      'no backend selected',
+      'patina could not resolve a backend to run.',
+      'Pass --backend openai-http, codex-cli, claude-cli, or gemini-cli.'
+    );
+  }
+
+  let lastError = null;
+  for (let attemptIndex = 0; attemptIndex < backends.length; attemptIndex++) {
+    const backend = backends[attemptIndex];
+    try {
+      return await backend.invoke({ prompt, apiKey, baseURL, model, signal, timeout, temperature, seed, onResponse, cache });
+    } catch (err) {
+      lastError = err;
+      const next = backends[attemptIndex + 1];
+      if (!next || !isRetryableBackendError(err, { attemptIndex, signal })) {
+        throw err;
+      }
+      logger?.warn?.('backend.fallback', {
+        message: `[patina] ${backend.name} failed with ${describeBackendError(err)}; falling back to ${next.name}`,
+      });
+    }
+  }
+
+  throw lastError || new Error('backend fallback chain failed without an error');
+}
+
+function resolveBackend(name) {
+  const backend = REGISTRY[name];
+  if (!backend) {
+    throw inputError(
+      `Unknown backend: ${name}`,
+      `Available backends are: ${Object.keys(REGISTRY).join(', ')}.`,
+      'Run `patina --list-backends` to inspect local availability.'
+    );
+  }
+  return backend;
+}