patina-cli 3.11.0

package/src/commands/doctor.js

@@ -0,0 +1,229 @@
+import { spawnSync } from 'node:child_process';
+import { HTTP_KEY_ENV_VARS, inspectHttpApiKeySource, providerHttpKeyEnvVars } from '../auth.js';
+import { listBackends } from '../backends/index.js';
+import { PROVIDERS } from '../providers.js';
+import { inputError } from '../errors.js';
+
+const MIN_NODE_MAJOR = 18;
+
+export function runDoctor(args = [], { version } = {}) {
+  const parsed = parseDoctorArgs(args);
+  if (parsed.help) {
+    printDoctorHelp();
+    return;
+  }
+
+  const report = buildDoctorReport({ version });
+  if (parsed.format === 'json') {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(formatDoctorText(report));
+  }
+
+  if (!report.ok) {
+    process.exitCode = Math.max(Number(process.exitCode) || 0, 1);
+  }
+}
+
+export function buildDoctorReport({ version } = {}) {
+  const checks = [];
+  const backends = listBackends();
+  const nodeVersion = process.versions.node;
+  const nodeMajor = Number(nodeVersion.split('.')[0]);
+  const nodeOk = Number.isFinite(nodeMajor) && nodeMajor >= MIN_NODE_MAJOR;
+
+  checks.push({
+    name: 'node',
+    status: nodeOk ? 'ok' : 'blocker',
+    summary: `Node ${nodeVersion}`,
+    detail: nodeOk
+      ? `meets package engine >=${MIN_NODE_MAJOR}`
+      : `requires Node >=${MIN_NODE_MAJOR}`,
+  });
+
+  checks.push({
+    name: 'cli-version',
+    status: version ? 'ok' : 'warning',
+    summary: `patina ${version || 'unknown'}`,
+    detail: 'read from package metadata',
+  });
+
+  const tmux = checkCommand('tmux', ['-V']);
+  checks.push({
+    name: 'tmux',
+    status: tmux.ok ? 'ok' : 'warning',
+    summary: tmux.ok ? tmux.stdout.trim() : 'tmux not found',
+    detail: tmux.ok
+      ? 'available for MAX omc dispatch workflows'
+      : 'only needed for tmux-based MAX dispatch; direct/API modes still work',
+  });
+
+  const apiKeySource = inspectHttpApiKeySource();
+  const apiKeys = HTTP_KEY_ENV_VARS.map((name) => ({
+    name,
+    set: Boolean(process.env[name]),
+  }));
+  checks.push({
+    name: 'api-key-env',
+    status: apiKeySource.source === 'PATINA_API_KEY_FILE' && !apiKeySource.ok
+      ? 'blocker'
+      : (apiKeySource.ok ? 'ok' : 'warning'),
+    summary: apiKeySource.ok
+      ? 'default HTTP API key source detected'
+      : 'no default HTTP API key source detected',
+    detail: apiKeySource.detail,
+  });
+
+  const providerKeys = Object.values(PROVIDERS).map((provider) => ({
+    name: provider.name,
+    apiKeyEnv: provider.apiKeyEnv,
+    providerEnvSet: Boolean(process.env[provider.apiKeyEnv]),
+    keySource: getProviderKeySource(provider),
+    baseURL: provider.baseURL,
+    defaultModel: provider.defaultModel,
+  }));
+
+  const usableBackends = backends.filter((b) => b.available && b.authenticated);
+  checks.push({
+    name: 'usable-backend',
+    status: usableBackends.length > 0 ? 'ok' : 'blocker',
+    summary: usableBackends.length > 0
+      ? `${usableBackends.length} authenticated backend(s)`
+      : 'no authenticated backend',
+    detail: usableBackends.length > 0
+      ? usableBackends.map((b) => b.name).join(', ')
+      : 'Set an API key or authenticate one local backend (`codex login`, `claude`, or `gemini`).',
+  });
+
+  const blockers = checks.filter((check) => check.status === 'blocker');
+  return {
+    ok: blockers.length === 0,
+    version: version || null,
+    node: {
+      version: nodeVersion,
+      required: `>=${MIN_NODE_MAJOR}.0.0`,
+      ok: nodeOk,
+    },
+    checks,
+    backends,
+    providers: providerKeys,
+    env: {
+      apiKeys,
+      PATINA_API_KEY_FILE: process.env.PATINA_API_KEY_FILE || null,
+    },
+    blockers: blockers.map((check) => ({
+      name: check.name,
+      summary: check.summary,
+      detail: check.detail,
+    })),
+  };
+}
+
+function parseDoctorArgs(args) {
+  const parsed = { format: 'text' };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case '--help':
+      case '-h':
+        parsed.help = true;
+        break;
+      case '--json':
+        parsed.format = 'json';
+        break;
+      case '--format': {
+        const value = args[++i];
+        if (!['json', 'text'].includes(value)) {
+          throw inputError(
+            'patina doctor --format expects json or text',
+            `Received ${value === undefined ? 'no value' : `"${value}"`}.`,
+            'Use `patina doctor --json` for CI-readable output.'
+          );
+        }
+        parsed.format = value;
+        break;
+      }
+      default:
+        throw inputError(
+          `unknown doctor option ${arg}`,
+          'The doctor command only accepts --json, --format, and --help.',
+          'Run `patina doctor --help` for usage.'
+        );
+    }
+  }
+  return parsed;
+}
+
+function checkCommand(cmd, args) {
+  try {
+    const result = spawnSync(cmd, args, { encoding: 'utf8' });
+    return {
+      ok: result.status === 0,
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+    };
+  } catch (err) {
+    return { ok: false, stdout: '', stderr: err.message };
+  }
+}
+
+function getProviderKeySource(provider) {
+  const source = inspectHttpApiKeySource({
+    envVars: providerHttpKeyEnvVars(provider.apiKeyEnv),
+  });
+  return source.ok ? source.source : null;
+}
+
+function formatDoctorText(report) {
+  const icon = (status) => status === 'ok' ? '✓' : (status === 'warning' ? '!' : '✗');
+  const lines = [
+    `patina doctor — ${report.ok ? 'ok' : 'blockers found'}`,
+    '',
+    'Checks:',
+  ];
+  for (const check of report.checks) {
+    lines.push(`  ${icon(check.status)} ${check.summary}`);
+    if (check.detail) lines.push(`    ${check.detail}`);
+  }
+
+  lines.push('', 'Backends:');
+  for (const backend of report.backends) {
+    const ok = backend.available && backend.authenticated;
+    lines.push(
+      `  ${ok ? '✓' : '!'} ${backend.name}: available=${yesNo(backend.available)}, authenticated=${yesNo(backend.authenticated)}`
+    );
+    if (!ok && backend.authHint) lines.push(`    → ${backend.authHint}`);
+  }
+
+  lines.push('', 'Provider keys:');
+  for (const provider of report.providers) {
+    lines.push(
+      `  ${provider.keySource ? '✓' : '!'} ${provider.name}: key=${provider.keySource || 'missing'} ` +
+      `(provider env ${provider.apiKeyEnv}=${provider.providerEnvSet ? 'set' : 'missing'})`
+    );
+  }
+
+  if (report.blockers.length > 0) {
+    lines.push('', 'Blockers:');
+    for (const blocker of report.blockers) {
+      lines.push(`  - ${blocker.summary}: ${blocker.detail}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function yesNo(value) {
+  return value ? 'yes' : 'no';
+}
+
+function printDoctorHelp() {
+  console.log(`patina doctor — check local CLI readiness
+
+Usage: patina doctor [--json]
+
+Checks Node version, patina CLI version, backend availability/authentication,
+tmux, and PATINA/provider API key environment variables. Exits 0 when no
+blockers are found, or 1 when a blocking setup issue is detected.
+`);
+}

package/src/commands/init.js

@@ -0,0 +1,208 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { spawnSync } from 'node:child_process';
+import { stdin as input, stdout as output } from 'node:process';
+import yaml from 'js-yaml';
+import { listBackends } from '../backends/index.js';
+import { inputError } from '../errors.js';
+import { createLogger } from '../logger.js';
+
+const LANGUAGES = ['ko', 'en', 'zh', 'ja'];
+const PROFILES = [
+  'default',
+  'blog',
+  'academic',
+  'technical',
+  'formal',
+  'social',
+  'email',
+  'legal',
+  'medical',
+  'marketing',
+  'narrative',
+  'instructional',
+  'casual-conversation',
+  'code-comment',
+  'commit-message',
+  'release-notes',
+];
+const TONES = ['profile-only', 'casual', 'professional', 'academic', 'narrative', 'marketing', 'instructional', 'auto'];
+const DISPATCH_MODES = ['omc', 'direct', 'api'];
+
+export async function runInit(args = [], { logger = createLogger() } = {}) {
+  const parsed = parseInitArgs(args);
+  if (parsed.help) {
+    printInitHelp();
+    return;
+  }
+
+  const target = resolve(process.cwd(), '.patina.yaml');
+  if (existsSync(target) && !parsed.force) {
+    if (parsed.defaults || !process.stdin.isTTY) {
+      throw inputError(
+        '.patina.yaml already exists',
+        'init will not overwrite an existing project config without confirmation.',
+        'Run `patina init --force` to replace it, or edit .patina.yaml manually.'
+      );
+    }
+  }
+
+  const detected = detectInitDefaults();
+  const answers = parsed.defaults
+    ? detected
+    : await promptForConfig(detected, { target, force: parsed.force, logger });
+
+  if (!answers) {
+    logger.info('init.kept_existing', { message: '[patina] kept existing .patina.yaml' });
+    return;
+  }
+
+  const config = buildInitConfig(answers);
+  writeFileSync(target, `${yaml.dump(config, { lineWidth: 100 }).trimEnd()}\n`, 'utf8');
+  console.log(`[patina] wrote ${target}`);
+}
+
+export function detectInitDefaults() {
+  const backends = listBackends();
+  const authenticated = backends.filter((b) => b.available && b.authenticated);
+  const preferredBackend = (
+    authenticated.find((b) => b.name !== 'openai-http') ||
+    authenticated[0] ||
+    backends.find((b) => b.name === 'openai-http')
+  )?.name || 'openai-http';
+
+  const maxModels = authenticated
+    .map((b) => MODEL_BY_BACKEND[b.name])
+    .filter(Boolean);
+
+  return {
+    language: 'ko',
+    profile: 'default',
+    tone: 'profile-only',
+    backend: preferredBackend,
+    maxModels: maxModels.length > 0 ? maxModels : ['claude', 'gemini'],
+    dispatch: commandAvailable('tmux') ? 'omc' : 'direct',
+  };
+}
+
+function parseInitArgs(args) {
+  const parsed = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case '--help':
+      case '-h':
+        parsed.help = true;
+        break;
+      case '--defaults':
+        parsed.defaults = true;
+        break;
+      case '--force':
+      case '--yes':
+      case '-y':
+        parsed.force = true;
+        break;
+      default:
+        throw inputError(
+          `unknown init option ${arg}`,
+          'The init command only accepts --defaults, --force, and --help.',
+          'Run `patina init --help` for usage.'
+        );
+    }
+  }
+  return parsed;
+}
+
+async function promptForConfig(defaults, { target, force, logger = createLogger() }) {
+  if (!process.stdin.isTTY) {
+    throw inputError(
+      'init needs an interactive terminal',
+      'guided setup asks questions before writing .patina.yaml.',
+      'Run `patina init --defaults` for a non-interactive config.'
+    );
+  }
+
+  const rl = createInterface({ input, output });
+  try {
+    if (existsSync(target) && !force) {
+      const overwrite = await ask(rl, `Overwrite existing .patina.yaml?`, 'no', ['yes', 'no'], logger);
+      if (overwrite !== 'yes') return null;
+    }
+
+    const language = await ask(rl, 'Language', defaults.language, LANGUAGES, logger);
+    const profile = await ask(rl, 'Profile', defaults.profile, PROFILES, logger);
+    const tone = await ask(rl, 'Tone', defaults.tone, TONES, logger);
+    const backendChoices = listBackends().map((b) => b.name);
+    const backend = await ask(rl, 'Backend', defaults.backend, backendChoices, logger);
+    const maxModels = await askMulti(rl, 'MAX models', defaults.maxModels, ['claude', 'codex', 'gemini'], logger);
+    const dispatch = await ask(rl, 'Dispatch mode', defaults.dispatch, DISPATCH_MODES, logger);
+    return { language, profile, tone, backend, maxModels, dispatch };
+  } finally {
+    rl.close();
+  }
+}
+
+async function ask(rl, label, defaultValue, choices, logger = createLogger()) {
+  const choiceHint = choices ? ` (${choices.join('/')})` : '';
+  const raw = (await rl.question(`${label}${choiceHint} [${defaultValue}]: `)).trim();
+  const value = raw || defaultValue;
+  if (choices && !choices.includes(value)) {
+    logger.warn('init.unknown_value', { message: `[patina] ${label}: unknown value "${value}", keeping ${defaultValue}` });
+    return defaultValue;
+  }
+  return value;
+}
+
+async function askMulti(rl, label, defaultValues, choices, logger = createLogger()) {
+  const raw = (await rl.question(`${label} (${choices.join(',')}) [${defaultValues.join(',')}]: `)).trim();
+  const values = (raw ? raw.split(',') : defaultValues)
+    .map((value) => value.trim())
+    .filter(Boolean);
+  const valid = values.filter((value) => choices.includes(value));
+  if (valid.length === 0) {
+    logger.warn('init.no_valid_values', { message: `[patina] ${label}: no valid values, keeping ${defaultValues.join(',')}` });
+    return defaultValues;
+  }
+  return [...new Set(valid)];
+}
+
+function buildInitConfig(answers) {
+  return {
+    language: answers.language,
+    profile: answers.profile,
+    tone: answers.tone === 'profile-only' ? null : answers.tone,
+    backend: answers.backend,
+    'max-models': answers.maxModels,
+    dispatch: answers.dispatch,
+  };
+}
+
+function commandAvailable(name) {
+  try {
+    const result = spawnSync(name, ['-V'], { stdio: 'ignore' });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+const MODEL_BY_BACKEND = {
+  'codex-cli': 'codex',
+  'claude-cli': 'claude',
+  'gemini-cli': 'gemini',
+};
+
+function printInitHelp() {
+  console.log(`patina init — create a project .patina.yaml
+
+Usage: patina init [--defaults] [--force]
+
+Guided mode asks for language, profile, tone, backend, MAX models, and dispatch
+mode. It preselects authenticated local backends when available.
+
+Options:
+  --defaults   Write detected defaults without prompts
+  --force      Overwrite an existing .patina.yaml
+`);
+}

package/src/config.js

@@ -0,0 +1,126 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+
+export function loadConfig(path = resolve(REPO_ROOT, '.patina.default.yaml')) {
+  const raw = readFileSync(path, 'utf8');
+  const parsed = yaml.load(raw);
+  if (!isPlainObject(parsed)) {
+    throw new Error(`Config at ${path} did not parse to a YAML mapping (got ${typeof parsed})`);
+  }
+  const config = parsed;
+
+  // User config: ~/.patina.yaml (global), then ./.patina.yaml (project, takes precedence).
+  for (const userPath of [resolve(homedir(), '.patina.yaml'), resolve(process.cwd(), '.patina.yaml')]) {
+    if (!existsSync(userPath)) continue;
+    const userRaw = readFileSync(userPath, 'utf8');
+    const userConfig = yaml.load(userRaw);
+    if (userConfig === null || userConfig === undefined) continue; // empty file
+    if (!isPlainObject(userConfig)) {
+      throw new Error(`User config at ${userPath} must be a YAML mapping (got ${Array.isArray(userConfig) ? 'array' : typeof userConfig})`);
+    }
+    deepMerge(config, userConfig);
+  }
+
+  return config;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+const ADDITIVE_LIST_KEYS = new Set(['blocklist', 'allowlist', 'skip-patterns']);
+
+function deepMerge(target, source) {
+  for (const key in source) {
+    if (isPlainObject(source[key])) {
+      if (!isPlainObject(target[key])) {
+        target[key] = {};
+      }
+      deepMerge(target[key], source[key]);
+    } else if (Array.isArray(source[key]) && ADDITIVE_LIST_KEYS.has(key)) {
+      const base = Array.isArray(target[key]) ? target[key] : [];
+      target[key] = [...new Set([...base, ...source[key]])];
+    } else if (Array.isArray(source[key])) {
+      target[key] = [...source[key]];
+    } else {
+      target[key] = source[key];
+    }
+  }
+}
+
+export function getRepoRoot() {
+  return REPO_ROOT;
+}
+
+const VALID_TONES = ['casual', 'professional', 'academic', 'narrative', 'marketing', 'instructional', 'auto'];
+
+// Resolve the effective tone from CLI flag and config (v3.10).
+// Priority: cliTone > configTone > unset. zh/ja + explicit tone → fallback path.
+// Returns: { tone, tone_source, tone_evidence, tone_confidence, warning? }
+export function resolveTone({ cliTone, configTone, lang }) {
+  if (cliTone !== undefined && cliTone !== null) {
+    if (!VALID_TONES.includes(cliTone)) {
+      throw new Error(
+        `Unknown tone '${cliTone}'. Valid tones: ${VALID_TONES.join(', ')}`
+      );
+    }
+  }
+  if (configTone !== undefined && configTone !== null && configTone !== '') {
+    if (!VALID_TONES.includes(configTone)) {
+      throw new Error(
+        `Invalid tone '${configTone}' in config. Valid tones: ${VALID_TONES.join(', ')}`
+      );
+    }
+  }
+
+  const effective = cliTone || (configTone === '' ? null : configTone) || null;
+
+  // Profile-only mode: nothing specified at all.
+  if (!effective) {
+    return {
+      tone: null,
+      tone_source: 'profile_only',
+      tone_evidence: [],
+      tone_confidence: null,
+    };
+  }
+
+  // zh/ja + any tone (including auto) → warning + fallback.
+  // Phase 4.5b heuristics only cover ko/en signals; auto on zh/ja would
+  // silently degrade to residual "professional" without useful evidence.
+  if ((lang === 'zh' || lang === 'ja') && effective) {
+    const label = effective === 'auto' ? 'auto-detection' : `tone "${effective}"`;
+    const warning = `${label} is en/ko-only in v1; falling back to default profile`;
+    return {
+      tone: null,
+      tone_source: 'unsupported_language_fallback',
+      tone_evidence: [warning],
+      tone_confidence: null,
+      warning,
+    };
+  }
+
+  if (effective === 'auto') {
+    // Detection runs in-prompt at SKILL.md Phase 4.5b. Mark request only.
+    return {
+      tone: 'auto',
+      tone_source: 'auto',
+      tone_evidence: [],
+      tone_confidence: null,
+    };
+  }
+
+  // User-specified named tone.
+  return {
+    tone: effective,
+    tone_source: 'user',
+    tone_evidence: ['user-specified'],
+    tone_confidence: 'high',
+  };
+}

package/src/errors.js

@@ -0,0 +1,53 @@
+export class PatinaCliError extends Error {
+  constructor({ what, why, action, exitCode = 1 }) {
+    super([what, why, action].filter(Boolean).join('\n'));
+    this.name = 'PatinaCliError';
+    this.what = what;
+    this.why = why;
+    this.action = action;
+    this.exitCode = exitCode;
+  }
+}
+
+export function inputError(what, why, action) {
+  return new PatinaCliError({ what, why, action, exitCode: 2 });
+}
+
+export function runtimeError(what, why, action) {
+  return new PatinaCliError({ what, why, action, exitCode: 1 });
+}
+
+export function renderCliError(err) {
+  const normalized = normalizeError(err);
+  return [
+    `[patina] Error: ${normalized.what}`,
+    `         ${normalized.why}`,
+    `         → ${normalized.action}`,
+  ].join('\n');
+}
+
+export function getExitCode(err, fallback = 1) {
+  const n = Number(err?.exitCode);
+  return Number.isInteger(n) && n >= 0 ? n : fallback;
+}
+
+function normalizeError(err) {
+  if (err instanceof PatinaCliError) {
+    return {
+      what: err.what || 'command failed',
+      why: err.why || 'patina could not complete the request.',
+      action: err.action || 'Run `patina --help` or `patina doctor` for next steps.',
+    };
+  }
+
+  const lines = String(err?.message || err || 'unknown error')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  return {
+    what: lines[0] || 'command failed',
+    why: lines.slice(1).join(' ') || 'The command hit a runtime failure before it could finish.',
+    action: 'Run `patina doctor` to inspect your environment, or rerun with `--help` for usage.',
+  };
+}