amicus 1.0.0

package/src/utils/input-validators.js

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * @module input-validators
+ * MCP input validation with structured error responses.
+ * Composes validators from validators.js and adds model resolution.
+ */
+
+// Lazy require to avoid circular dependency (validators.js re-exports from here)
+let _validators;
+function getValidators() {
+  if (!_validators) { _validators = require('./validators'); }
+  return _validators;
+}
+
+/**
+ * Find candidates that start with the input or vice versa.
+ * @param {string} input
+ * @param {string[]} candidates
+ * @returns {string[]} Up to 3 matching candidates
+ */
+function findSimilar(input, candidates) {
+  if (!input) { return []; }
+  const lower = input.toLowerCase();
+  return candidates.filter(c => {
+    const cl = c.toLowerCase();
+    return cl.startsWith(lower) || lower.startsWith(cl);
+  }).slice(0, 3);
+}
+
+/**
+ * Validate sidecar_start inputs before session creation.
+ * Composes existing validators and adds model resolution.
+ * @param {Object} input - Raw MCP tool input
+ * @returns {{ valid: true, resolvedModel: string } | { valid: false, error: Object }}
+ */
+function validateStartInputs(input) {
+  // 1. Prompt
+  const { validatePromptContent, validateHeadlessAgent } = getValidators();
+  const promptResult = validatePromptContent(input.prompt);
+  if (!promptResult.valid) {
+    return {
+      valid: false,
+      error: {
+        type: 'validation_error',
+        field: 'prompt',
+        message: promptResult.error,
+      },
+    };
+  }
+
+  // 2. Model: resolve alias to full provider/model string
+  const { tryResolveModel, getEffectiveAliases } = require('./config');
+  const { model: resolved, error: modelError } = tryResolveModel(input.model);
+  if (modelError) {
+    const aliases = Object.keys(getEffectiveAliases());
+    const suggestions = findSimilar(input.model, aliases);
+    return {
+      valid: false,
+      error: {
+        type: 'validation_error',
+        field: 'model',
+        message: input.model
+          ? `Model '${input.model}' not found. ${modelError}`
+          : `No model specified and no default configured. ${modelError}`,
+        suggestions,
+        available: aliases,
+      },
+    };
+  }
+
+  // 3. Timeout: positive number, max 60 minutes
+  if (input.timeout !== undefined) {
+    const t = Number(input.timeout);
+    if (isNaN(t) || t <= 0) {
+      return {
+        valid: false,
+        error: {
+          type: 'validation_error',
+          field: 'timeout',
+          message: `Timeout must be a positive number (minutes). Got: ${input.timeout}`,
+        },
+      };
+    }
+    if (t > 60) {
+      return {
+        valid: false,
+        error: {
+          type: 'validation_error',
+          field: 'timeout',
+          message: `Timeout cannot exceed 60 minutes. Got: ${t}`,
+        },
+      };
+    }
+  }
+
+  // 4. Agent + headless compatibility
+  // Note: MCP Zod schema defaults agent to 'Chat'. The handler auto-converts
+  // Chat to Build for headless mode (line ~92 in mcp-server.js). Only reject
+  // if the user explicitly set agent to Chat with noUi (not the Zod default).
+  // We detect explicit by checking if agent was in the original input vs Zod default.
+  // Since we can't distinguish here, skip validation for Chat+noUi -
+  // the handler will convert it to Build before use.
+  if (input.noUi && input.agent) {
+    const lower = input.agent.toLowerCase();
+    // Only reject chat if it's NOT the auto-convertible case
+    // The handler converts chat -> build for headless, so we allow it
+    if (lower !== 'chat') {
+      const agentResult = validateHeadlessAgent(input.agent);
+      if (!agentResult.valid) {
+        return {
+          valid: false,
+          error: {
+            type: 'validation_error',
+            field: 'agent',
+            message: agentResult.error,
+            suggestions: ['Build', 'Plan'],
+          },
+        };
+      }
+    }
+  }
+
+  return { valid: true, resolvedModel: resolved };
+}
+
+module.exports = { validateStartInputs, findSimilar };

package/src/utils/lifecycle.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * Process-lifecycle helpers for the one-shot CLI commands (F3 #15).
+ *
+ * One-shot commands must return control to the shell when their work is done.
+ * If a stray handle (e.g. the OpenCode Go server) keeps Node's event loop
+ * alive, the force-exit watchdog guarantees the process still exits.
+ */
+
+// One-shot commands spin up the OpenCode server and must return to the shell
+// when done (F3 #15). Deliberately EXCLUDED: `mcp` (long-lived server), and
+// `setup`/`update` (no OpenCode server to leak, and `setup` can be a long-lived
+// interactive Electron flow that must never be force-exited).
+const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'read', 'abort', 'fanout', 'models']);
+
+/** @param {string} command @returns {boolean} */
+function isOneShotCommand(command) {
+  return ONE_SHOT_COMMANDS.has(command);
+}
+
+/**
+ * Arm an unref'd timer that force-exits if the loop has not drained by `ms`.
+ * Natural drain still wins: an unref'd timer never holds the process open, so
+ * a clean exit happens before this fires. Injectable exit/log for tests.
+ *
+ * @param {number} [code=0]
+ * @param {number} [ms=1500]
+ * @param {{exit?: Function, log?: Function}} [deps]
+ * @returns {NodeJS.Timeout}
+ */
+function armExitWatchdog(code = 0, ms = 1500, deps = {}) {
+  const exit = deps.exit || process.exit;
+  const log = deps.log;
+  const t = setTimeout(() => {
+    if (log) { log('force-exit watchdog fired — a handle kept the event loop alive', { code, ms }); }
+    exit(code);
+  }, ms);
+  if (t.unref) { t.unref(); }
+  return t;
+}
+
+module.exports = { isOneShotCommand, armExitWatchdog, ONE_SHOT_COMMANDS };

package/src/utils/logger.js

@@ -0,0 +1,84 @@
+/**
+ * Structured Logger Module
+ *
+ * Spec Reference: CLAUDE.md - Structured Logging Guidelines
+ * Outputs JSON-formatted logs to stderr (stdout reserved for summary output).
+ */
+
+const LOG_LEVELS = { error: 0, warn: 1, info: 2, debug: 3 };
+
+/**
+ * Get current log level from environment
+ * @returns {number} Numeric log level
+ */
+function getCurrentLevel() {
+  const levelName = process.env.LOG_LEVEL || 'error';
+  return LOG_LEVELS[levelName] ?? LOG_LEVELS.info;
+}
+
+/**
+ * Create a log entry and write to stderr
+ * @param {string} level - Log level name
+ * @param {string} msg - Log message
+ * @param {object} ctx - Additional context fields
+ */
+function log(level, msg, ctx = {}) {
+  const currentLevel = getCurrentLevel();
+  const levelNum = LOG_LEVELS[level];
+
+  if (levelNum > currentLevel) {
+    return;
+  }
+
+  const entry = {
+    level,
+    msg,
+    ...ctx,
+    ts: new Date().toISOString()
+  };
+
+  try {
+    console.error(JSON.stringify(entry));
+  } catch (err) {
+    // Ignore EPIPE errors when pipe is closed (e.g., during shutdown)
+    if (err.code !== 'EPIPE') {
+      // Can't log here - would be recursive
+    }
+  }
+}
+
+/**
+ * Structured logger with level-based filtering
+ * @type {{error: Function, warn: Function, info: Function, debug: Function}}
+ */
+const logger = {
+  /**
+   * Log an error message
+   * @param {string} msg - Error message
+   * @param {object} [ctx] - Additional context
+   */
+  error: (msg, ctx = {}) => log('error', msg, ctx),
+
+  /**
+   * Log a warning message
+   * @param {string} msg - Warning message
+   * @param {object} [ctx] - Additional context
+   */
+  warn: (msg, ctx = {}) => log('warn', msg, ctx),
+
+  /**
+   * Log an info message
+   * @param {string} msg - Info message
+   * @param {object} [ctx] - Additional context
+   */
+  info: (msg, ctx = {}) => log('info', msg, ctx),
+
+  /**
+   * Log a debug message
+   * @param {string} msg - Debug message
+   * @param {object} [ctx] - Additional context
+   */
+  debug: (msg, ctx = {}) => log('debug', msg, ctx)
+};
+
+module.exports = { logger, LOG_LEVELS };

package/src/utils/mcp-discovery.js

@@ -0,0 +1,194 @@
+/**
+ * MCP Discovery - Discovers MCP servers from parent LLM configuration
+ *
+ * Supports discovering MCP servers from:
+ * - Claude Code (reads plugin chain from ~/.claude/)
+ * - Cowork / Claude Desktop (reads claude_desktop_config.json)
+ *
+ * @module utils/mcp-discovery
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { logger } = require('./logger');
+
+/**
+ * Normalize .mcp.json to a flat { name: config } map.
+ * Handles both Format A (wrapped) and Format B (flat).
+ *
+ * @param {object|null|undefined} raw - Raw parsed JSON from .mcp.json
+ * @returns {object} Normalized server configs
+ */
+function normalizeMcpJson(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return {};
+  }
+  // Format A: { mcpServers: { name: config } }
+  if (raw.mcpServers && typeof raw.mcpServers === 'object') {
+    return raw.mcpServers;
+  }
+  // Format B: { name: config } (flat)
+  return raw;
+}
+
+/**
+ * Discover MCP servers from Claude Code's plugin chain AND ~/.claude.json.
+ *
+ * Discovery sources (merged, in priority order):
+ * 1. ~/.claude.json → mcpServers  (servers added via `claude mcp add`)
+ * 2. Enabled plugins → .mcp.json entries
+ *
+ * @param {string} [claudeDir] - Path to ~/.claude directory (for testing)
+ * @param {string} [claudeJsonPath] - Path to ~/.claude.json (for testing)
+ * @returns {object|null} Merged MCP server configs, or null if none found
+ */
+function discoverClaudeCodeMcps(claudeDir, claudeJsonPath) {
+  const baseDir = claudeDir || path.join(os.homedir(), '.claude');
+  const jsonPath = claudeJsonPath || path.join(os.homedir(), '.claude.json');
+
+  // Source 1: ~/.claude.json → mcpServers (servers added via `claude mcp add`)
+  let claudeJsonServers = {};
+  try {
+    if (fs.existsSync(jsonPath)) {
+      const raw = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+      if (raw.mcpServers && typeof raw.mcpServers === 'object') {
+        claudeJsonServers = raw.mcpServers;
+        logger.debug('Read MCP servers from ~/.claude.json', {
+          serverCount: Object.keys(claudeJsonServers).length
+        });
+      }
+    }
+  } catch (err) {
+    logger.debug('Failed to read ~/.claude.json', { error: err.message });
+  }
+
+  // Source 2: Plugin chain (settings.json → installed_plugins.json → .mcp.json)
+  const pluginServers = {};
+
+  try {
+    const settingsPath = path.join(baseDir, 'settings.json');
+    if (!fs.existsSync(settingsPath)) {
+      // No settings.json — skip plugin discovery, may still have claude.json servers
+      const merged = { ...claudeJsonServers };
+      delete merged.sidecar;
+      return Object.keys(merged).length > 0 ? merged : null;
+    }
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    const enabledPlugins = settings.enabledPlugins;
+    if (!enabledPlugins || typeof enabledPlugins !== 'object') {
+      const merged = { ...claudeJsonServers };
+      delete merged.sidecar;
+      return Object.keys(merged).length > 0 ? merged : null;
+    }
+
+    let installedPlugins = {};
+    try {
+      const pluginsDir = path.join(baseDir, 'plugins');
+      const installedPath = path.join(pluginsDir, 'installed_plugins.json');
+      if (fs.existsSync(installedPath)) {
+        const installed = JSON.parse(fs.readFileSync(installedPath, 'utf-8'));
+        installedPlugins = installed.plugins || {};
+      }
+    } catch (err) {
+      logger.debug('Failed to read installed plugins', { error: err.message });
+    }
+
+    // Read blocklist
+    let blocklist = [];
+    try {
+      const blocklistPath = path.join(baseDir, 'plugins', 'blocklist.json');
+      if (fs.existsSync(blocklistPath)) {
+        blocklist = JSON.parse(fs.readFileSync(blocklistPath, 'utf-8'));
+        if (!Array.isArray(blocklist)) { blocklist = []; }
+      }
+    } catch {
+      // Ignore blocklist read errors
+    }
+
+    for (const [pluginName, isEnabled] of Object.entries(enabledPlugins)) {
+      if (!isEnabled) { continue; }
+      if (blocklist.includes(pluginName)) {
+        logger.debug('Skipping blocklisted plugin', { pluginName });
+        continue;
+      }
+
+      const pluginInfo = installedPlugins[pluginName];
+      if (!pluginInfo || !pluginInfo.installPath) { continue; }
+
+      try {
+        const mcpPath = path.join(pluginInfo.installPath, '.mcp.json');
+        if (!fs.existsSync(mcpPath)) { continue; }
+        const raw = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
+        const servers = normalizeMcpJson(raw);
+
+        for (const [name, config] of Object.entries(servers)) {
+          pluginServers[name] = config;
+        }
+      } catch (err) {
+        logger.debug('Failed to read plugin MCP config', { pluginName, error: err.message });
+      }
+    }
+  } catch (err) {
+    logger.debug('Failed to read Claude Code settings', { error: err.message });
+  }
+
+  // Merge: plugin servers first, then claude.json overwrites (higher priority)
+  const merged = { ...pluginServers, ...claudeJsonServers };
+
+  // Always exclude sidecar itself to prevent recursive spawning
+  delete merged.sidecar;
+
+  return Object.keys(merged).length > 0 ? merged : null;
+}
+
+/**
+ * Discover MCP servers from Cowork / Claude Desktop config.
+ *
+ * @param {string} [configDir] - Path to config directory (for testing)
+ * @returns {object|null} MCP server configs, or null if none found
+ */
+function discoverCoworkMcps(configDir) {
+  const baseDir = configDir || (
+    process.platform === 'darwin'
+      ? path.join(os.homedir(), 'Library', 'Application Support', 'Claude')
+      : path.join(os.homedir(), '.config', 'Claude')
+  );
+
+  try {
+    const configPath = path.join(baseDir, 'claude_desktop_config.json');
+    if (!fs.existsSync(configPath)) { return null; }
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    if (!config.mcpServers || Object.keys(config.mcpServers).length === 0) {
+      return null;
+    }
+    return config.mcpServers;
+  } catch (err) {
+    logger.debug('Failed to read Cowork config', { error: err.message });
+    return null;
+  }
+}
+
+/**
+ * Discover MCP servers from the parent LLM's configuration.
+ *
+ * @param {string} [clientType] - Client type: 'code-local', 'code-web', 'cowork'
+ * @returns {object|null} Discovered MCP server configs, or null
+ */
+function discoverParentMcps(clientType) {
+  if (clientType === 'cowork') {
+    return discoverCoworkMcps();
+  }
+  if (!clientType || clientType === 'code-local' || clientType === 'code-web') {
+    return discoverClaudeCodeMcps();
+  }
+  logger.debug('Unknown client type for MCP discovery', { clientType });
+  return null;
+}
+
+module.exports = {
+  discoverParentMcps,
+  discoverClaudeCodeMcps,
+  discoverCoworkMcps,
+  normalizeMcpJson
+};

package/src/utils/mcp-validators.js

@@ -0,0 +1,78 @@
+/**
+ * MCP Validators
+ *
+ * Validation for MCP spec and config file arguments.
+ * Extracted from validators.js to keep modules under 300 lines.
+ */
+
+const fs = require('fs');
+
+/**
+ * Validate MCP spec format (OPTIONAL - only validates if provided)
+ * @param {string} mcp
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateMcpSpec(mcp) {
+  // Skip validation if not provided - MCP is optional
+  if (!mcp) {
+    return { valid: true };
+  }
+
+  // Format: name=url or name=command
+  if (!mcp.includes('=')) {
+    return {
+      valid: false,
+      error: `Error: --mcp must be in format 'name=url' or 'name=command'. Got: '${mcp}'`
+    };
+  }
+
+  // Split on first '=' only (value can contain '=')
+  const eqIndex = mcp.indexOf('=');
+  const name = mcp.slice(0, eqIndex);
+  const value = mcp.slice(eqIndex + 1);
+
+  if (!name || !value) {
+    return {
+      valid: false,
+      error: `Error: --mcp must have both name and value. Got: '${mcp}'`
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate MCP config file exists and is valid JSON (OPTIONAL)
+ * @param {string} mcpConfig
+ * @returns {{valid: boolean, error?: string}}
+ */
+function validateMcpConfigFile(mcpConfig) {
+  // Skip validation if not provided - MCP config is optional
+  if (!mcpConfig) {
+    return { valid: true };
+  }
+
+  if (!fs.existsSync(mcpConfig)) {
+    return {
+      valid: false,
+      error: `Error: --mcp-config file does not exist: ${mcpConfig}`
+    };
+  }
+
+  try {
+    const content = fs.readFileSync(mcpConfig, 'utf-8');
+    JSON.parse(content);
+  } catch (e) {
+    return {
+      valid: false,
+      error: `Error: --mcp-config file is not valid JSON: ${mcpConfig}`
+    };
+  }
+
+  return { valid: true };
+}
+
+module.exports = {
+  validateMcpSpec,
+  validateMcpConfigFile
+};

package/src/utils/model-catalog.js

@@ -0,0 +1,103 @@
+/**
+ * OpenRouter model catalog cache (F3 #18 / F5 foundation).
+ *
+ * Caches the combined provider model list to ~/.config/amicus/model-catalog.json
+ * with a TTL so model validation doesn't hit the network on every launch.
+ * Schema v2: enriched rows ({id, name, contextLength, pricing}) written at every
+ * refresh; v1 caches (no schemaVersion) are treated as stale and refreshed, but
+ * remain usable as a graceful-degradation fallback when the refresh returns empty.
+ * Degrades gracefully: a failed/empty refresh falls back to stale cache, and
+ * callers treat an empty catalog as "cannot validate" (never block a launch).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Lazy-load these so jest.doMock() in tests can intercept them after
+// this module is first required (the test pattern re-mocks mid-test).
+function _getConfigDir() { return require('./config').getConfigDir(); }
+function _readApiKeyValues() { return require('./api-key-store').readApiKeyValues(); }
+async function _fetchAllModels(keys) { return require('./model-fetcher').fetchAllModels(keys); }
+
+const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h
+const CATALOG_SCHEMA_VERSION = 2;
+
+/** @returns {string} Absolute path to the catalog cache file */
+function catalogPath() {
+  return path.join(_getConfigDir(), 'model-catalog.json');
+}
+
+/** @returns {{fetchedAt: number, models: Array}|null} */
+function readCache() {
+  try {
+    const raw = fs.readFileSync(catalogPath(), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed && Array.isArray(parsed.models)) { return parsed; }
+  } catch { /* missing/corrupt */ }
+  return null;
+}
+
+/** Write the cache atomically (tmp+rename). Best-effort; never throws. @param {Array} models */
+function writeCache(models) {
+  const target = catalogPath();
+  const tmp = `${target}.${process.pid}.tmp`;
+  try {
+    fs.mkdirSync(_getConfigDir(), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(tmp, JSON.stringify({ schemaVersion: CATALOG_SCHEMA_VERSION, fetchedAt: Date.now(), models }, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, target);
+  } catch {
+    try { fs.unlinkSync(tmp); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * Force a refresh from the provider APIs and update the cache.
+ * @returns {Promise<Array<{id,name}>>} the fetched models (may be [] offline)
+ */
+async function refreshCatalog() {
+  const keys = _readApiKeyValues();
+  const models = await _fetchAllModels(keys);
+  // The anthropic rows are a hardcoded zero-network floor: a result containing
+  // ONLY them means every network provider failed. Treat that as a failed
+  // refresh — never clobber a previously-good cache with the floor (the
+  // "stale cache stands" contract).
+  const networkRows = (models || []).filter(m => m && typeof m.id === 'string' && !m.id.startsWith('anthropic/'));
+  if (networkRows.length === 0) { return []; }
+  writeCache(models);
+  return models;
+}
+
+/**
+ * Get the catalog, refreshing if the cache is missing or older than maxAgeMs.
+ * Graceful: on an empty refresh, returns stale cache if present, else [].
+ * @param {{maxAgeMs?: number}} [opts]
+ * @returns {Promise<Array<{id,name}>>}
+ */
+async function getCatalog(opts = {}) {
+  const maxAgeMs = opts.maxAgeMs === undefined ? DEFAULT_MAX_AGE_MS : opts.maxAgeMs;
+  const cache = readCache();
+  // A future fetchedAt (clock skew / hand-edited file) reads as indefinitely
+  // fresh; acceptable for a model catalog. v1 caches (no schemaVersion) always
+  // read as stale so they get refreshed to v2 on next access.
+  const fresh = cache && cache.schemaVersion === CATALOG_SCHEMA_VERSION &&
+    (Date.now() - cache.fetchedAt) <= maxAgeMs;
+  if (fresh) { return cache.models; }
+
+  const refreshed = await refreshCatalog();
+  if (refreshed.length > 0) { return refreshed; }
+  return cache ? cache.models : []; // stale fallback / empty
+}
+
+/**
+ * Catalog rows plus cache timestamp (for UI display).
+ * @returns {Promise<{models: Array, fetchedAt: number|null}>}
+ */
+async function getCatalogInfo(opts = {}) {
+  const models = await getCatalog(opts);
+  const cache = readCache();
+  return { models, fetchedAt: cache ? cache.fetchedAt : null };
+}
+
+module.exports = { getCatalog, refreshCatalog, catalogPath, getCatalogInfo, CATALOG_SCHEMA_VERSION };