amicus 1.0.0

package/src/utils/shared-server.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * @module shared-server
+ * Manages a single shared OpenCode server for MCP sessions.
+ */
+
+const { IdleWatchdog } = require('./idle-watchdog');
+const { getCompatEnv } = require('./env-compat');
+
+const MAX_RESTARTS = 3;
+const RESTART_WINDOW = 5 * 60 * 1000;
+const RESTART_BACKOFF = 2000;
+
+/**
+ * SharedServerManager - manages a single shared OpenCode server for MCP sessions.
+ *
+ * Tracks active sessions, handles lazy server startup, deduplicates concurrent
+ * start requests, and supervises the server with automatic restart on crash.
+ */
+class SharedServerManager {
+  /**
+   * @param {object} [options]
+   * @param {object} [options.logger] - Logger with .info(), .warn(), .error() methods
+   */
+  constructor(options = {}) {
+    this.logger = options.logger || console;
+    this.maxSessions = Number(process.env.SIDECAR_MAX_SESSIONS) || 20;
+    this.enabled = getCompatEnv('SHARED_SERVER') !== '0';
+
+    /** @type {object|null} Active server handle */
+    this.server = null;
+
+    /** @type {object|null} Active OpenCode client */
+    this.client = null;
+
+    /** @type {Map<string, IdleWatchdog>} Per-session watchdogs */
+    this._sessionWatchdogs = new Map();
+
+    /** @type {IdleWatchdog|null} Server-level idle watchdog (fires when no sessions remain) */
+    this._serverWatchdog = null;
+
+    /** @type {Promise|null} In-flight server start promise (for deduplication) */
+    this._starting = null;
+
+    /** @type {number[]} Timestamps of recent restart attempts */
+    this._restartTimestamps = [];
+  }
+
+  /**
+   * Number of active sessions.
+   * @returns {number}
+   */
+  get sessionCount() {
+    return this._sessionWatchdogs.size;
+  }
+
+  /**
+   * Ensure the shared server is running. Lazy-starts on first call.
+   * Deduplicates concurrent calls so only one start occurs.
+   *
+   * @param {object} [mcpConfig] - MCP configuration to pass to startOpenCodeServer
+   * @returns {Promise<{server: object, client: object}>}
+   */
+  async ensureServer(mcpConfig) {
+    if (this.server && this.client) {
+      return { server: this.server, client: this.client };
+    }
+    if (this._starting) {
+      return this._starting;
+    }
+    this._starting = this._doStartServer(mcpConfig).then(({ server, client }) => {
+      this.server = server;
+      this.client = client;
+      this._starting = null;
+      this._serverWatchdog = new IdleWatchdog({
+        mode: 'server',
+        onTimeout: () => {
+          this.logger.info?.('Shared server idle (no sessions) - shutting down');
+          this.shutdown();
+        },
+      }).start();
+      return { server, client };
+    }).catch((err) => {
+      this._starting = null;
+      throw err;
+    });
+    return this._starting;
+  }
+
+  /**
+   * Start the OpenCode server. Overrideable for testing.
+   *
+   * @param {object} [mcpConfig]
+   * @returns {Promise<{server: object, client: object}>}
+   */
+  async _doStartServer(mcpConfig) {
+    const { startOpenCodeServer } = require('../sidecar/session-utils');
+    return startOpenCodeServer(mcpConfig);
+  }
+
+  /**
+   * Register a new session. Cancels the server idle watchdog while sessions are active.
+   *
+   * @param {string} sessionId - Unique session identifier
+   * @param {Function} [onEvict] - Called when session is evicted due to idle timeout
+   * @throws {Error} If max session capacity is reached
+   */
+  addSession(sessionId, onEvict) {
+    if (this._sessionWatchdogs.size >= this.maxSessions) {
+      throw new Error(`Max sessions reached (${this.maxSessions}). Cannot add session ${sessionId}.`);
+    }
+    const watchdog = new IdleWatchdog({
+      mode: 'headless',
+      onTimeout: () => {
+        this.logger.info?.('Session idle timeout', { sessionId });
+        if (onEvict) { onEvict(sessionId); }
+        this.removeSession(sessionId);
+      },
+    }).start();
+    this._sessionWatchdogs.set(sessionId, watchdog);
+    if (this._serverWatchdog) {
+      this._serverWatchdog.cancel();
+    }
+  }
+
+  /**
+   * Deregister a session. Starts the server idle watchdog when no sessions remain.
+   *
+   * @param {string} sessionId
+   */
+  removeSession(sessionId) {
+    const watchdog = this._sessionWatchdogs.get(sessionId);
+    if (watchdog) {
+      watchdog.cancel();
+      this._sessionWatchdogs.delete(sessionId);
+    }
+    if (this._sessionWatchdogs.size === 0 && this._serverWatchdog) {
+      this._serverWatchdog.start();
+    }
+  }
+
+  /**
+   * Get the idle watchdog for a session.
+   *
+   * @param {string} sessionId
+   * @returns {IdleWatchdog|undefined}
+   */
+  getSessionWatchdog(sessionId) {
+    return this._sessionWatchdogs.get(sessionId);
+  }
+
+  /**
+   * Shut down the manager: cancel all watchdogs, close the server.
+   */
+  shutdown() {
+    for (const [, wd] of this._sessionWatchdogs) {
+      wd.cancel();
+    }
+    this._sessionWatchdogs.clear();
+    if (this._serverWatchdog) {
+      this._serverWatchdog.cancel();
+      this._serverWatchdog = null;
+    }
+    if (this.server) {
+      this.server.close();
+      this.server = null;
+      this.client = null;
+    }
+  }
+
+  /**
+   * Handle a server crash: log, notify sessions, then schedule restart.
+   *
+   * @param {number} exitCode - Process exit code from the crashed server
+   */
+  _onServerCrash(exitCode) {
+    this.logger.error?.('Shared server crashed', { exitCode });
+    for (const [id] of this._sessionWatchdogs) {
+      this.logger.warn?.('Session interrupted by server crash', { sessionId: id });
+    }
+    this.server = null;
+    this.client = null;
+    setTimeout(() => this._handleRestart(), RESTART_BACKOFF);
+  }
+
+  /**
+   * Attempt to restart the server, subject to rate limiting.
+   *
+   * @returns {Promise<boolean>} true if restart succeeded, false if rate-limited or failed
+   */
+  async _handleRestart() {
+    const now = Date.now();
+    this._restartTimestamps = this._restartTimestamps.filter(
+      (ts) => now - ts < RESTART_WINDOW
+    );
+    if (this._restartTimestamps.length >= MAX_RESTARTS) {
+      this.logger.error?.('Max restarts exceeded, not restarting shared server', {
+        restarts: this._restartTimestamps.length,
+        windowMs: RESTART_WINDOW,
+      });
+      return false;
+    }
+    this._restartTimestamps.push(now);
+    try {
+      await this.ensureServer();
+      this.logger.info?.('Shared server restarted successfully');
+      return true;
+    } catch (err) {
+      this.logger.error?.('Failed to restart shared server', { error: err.message });
+      return false;
+    }
+  }
+}
+
+module.exports = { SharedServerManager };

package/src/utils/start-helpers.js

@@ -0,0 +1,76 @@
+/**
+ * Start Command Helpers
+ *
+ * Model resolution and validation helpers extracted from bin/amicus.js
+ * to keep the CLI entry point under the 300-line limit.
+ */
+
+/**
+ * Resolve model from args: resolve alias or config default.
+ * Returns { model, alias } or calls process.exit(1) on error.
+ * @param {object} args - Parsed CLI arguments
+ * @returns {{ model: string, alias: string|undefined }}
+ */
+function resolveModelFromArgs(args) {
+  const { resolveModel, loadConfig } = require('./config');
+  const rawAlias = args.model;
+  let model;
+  try {
+    model = resolveModel(args.model);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  // Determine the alias used (explicit or config default)
+  let alias = rawAlias;
+  if (alias === undefined) {
+    const cfg = loadConfig();
+    if (cfg && cfg.default && !cfg.default.includes('/')) {
+      alias = cfg.default;
+    }
+  }
+  return { model, alias };
+}
+
+/**
+ * Validate models before launch (F3 #18: default-on).
+ * --no-validate-model opts out; the old opt-in --validate-model is a no-op kept for back-compat.
+ * Returns the (possibly corrected) model string.
+ * @param {object} args - Parsed CLI arguments
+ * @param {string|undefined} alias - The alias used for resolution
+ * @returns {Promise<string>} Validated model string
+ */
+async function validateFallbackModel(args, alias) {
+  // F3 #18: validation is default-on. --no-validate-model opts out; the old
+  // opt-in --validate-model is now a no-op kept for back-compat.
+  if (args['no-validate-model']) { return args.model; }
+
+  const headless = args['no-ui'] || !process.stdin.isTTY;
+  const { detectFallback } = require('./config');
+
+  // Direct-API fallback path: keep the provider-API existence check.
+  if (alias && detectFallback(alias, args.model)) {
+    const { validateDirectModel } = require('./model-validator');
+    try {
+      return await validateDirectModel(args.model, alias, { headless });
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  }
+
+  // OpenRouter (and any) resolved model: validate against the live catalog.
+  const { validateAgainstCatalog } = require('./model-validator');
+  try {
+    return await validateAgainstCatalog(args.model, alias);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  resolveModelFromArgs,
+  validateFallbackModel,
+};

package/src/utils/thinking-validators.js

@@ -0,0 +1,92 @@
+/**
+ * Thinking Level Validators
+ *
+ * Model-specific thinking level validation.
+ * Extracted from validators.js to keep modules under 300 lines.
+ */
+
+/**
+ * Model-specific thinking level support (static fallback)
+ * Maps model patterns to their supported thinking levels.
+ *
+ * NOTE: For dynamic, up-to-date capabilities, use model-capabilities.js
+ * which fetches from OpenRouter API and caches the results.
+ * This static map is used as a fast fallback for CLI validation.
+ */
+const MODEL_THINKING_SUPPORT = {
+  // OpenAI GPT-5.x does NOT support 'minimal'
+  'gpt-5': ['none', 'low', 'medium', 'high', 'xhigh'],
+  // o3/o3-mini supports all levels
+  'o3': ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'],
+  // Gemini supports all levels
+  'gemini': ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'],
+  // Default: all levels supported
+  'default': ['none', 'minimal', 'low', 'medium', 'high', 'xhigh']
+};
+
+/**
+ * Get supported thinking levels for a model (synchronous, static fallback)
+ *
+ * For dynamic lookup from OpenRouter API cache, use:
+ *   const { getSupportedThinkingLevels } = require('./model-capabilities');
+ *
+ * @param {string} model - Model identifier
+ * @returns {string[]} Array of supported thinking levels
+ */
+function getSupportedThinkingLevels(model) {
+  if (!model) {return MODEL_THINKING_SUPPORT.default;}
+
+  const modelLower = model.toLowerCase();
+
+  // Check each known model pattern
+  for (const [pattern, levels] of Object.entries(MODEL_THINKING_SUPPORT)) {
+    if (pattern !== 'default' && modelLower.includes(pattern)) {
+      return levels;
+    }
+  }
+
+  return MODEL_THINKING_SUPPORT.default;
+}
+
+/**
+ * Validate thinking level for a specific model (synchronous)
+ *
+ * For async validation with dynamic API cache, use:
+ *   const { validateThinkingForModel } = require('./model-capabilities');
+ *
+ * @param {string} thinking - Thinking level ('minimal', 'low', 'medium', 'high', 'xhigh', 'none')
+ * @param {string} model - Model identifier
+ * @returns {{valid: boolean, error?: string, warning?: string, adjustedLevel?: string}}
+ */
+function validateThinkingLevel(thinking, model) {
+  if (!thinking) {
+    return { valid: true };
+  }
+
+  const allLevels = MODEL_THINKING_SUPPORT.default;
+  if (!allLevels.includes(thinking)) {
+    return {
+      valid: false,
+      error: `Error: --thinking must be one of: ${allLevels.join(', ')}`
+    };
+  }
+
+  const supportedLevels = getSupportedThinkingLevels(model);
+  if (!supportedLevels.includes(thinking)) {
+    // Map to nearest supported level
+    const fallback = thinking === 'minimal' ? 'low' : 'medium';
+    return {
+      valid: true,
+      warning: `Warning: Model '${model}' does not support thinking level '${thinking}'. Using '${fallback}' instead.`,
+      adjustedLevel: fallback
+    };
+  }
+
+  return { valid: true };
+}
+
+module.exports = {
+  MODEL_THINKING_SUPPORT,
+  getSupportedThinkingLevels,
+  validateThinkingLevel
+};

package/src/utils/update-notifier-loader.js

@@ -0,0 +1,18 @@
+/**
+ * update-notifier Loader
+ *
+ * update-notifier v6+ is ESM-only: require() throws ERR_REQUIRE_ESM, so the
+ * package must be loaded with a dynamic import(). The import lives in this
+ * CJS seam so unit tests can mock it — jest's CJS test VM cannot execute a
+ * native import() without --experimental-vm-modules.
+ */
+
+/**
+ * Dynamically import the update-notifier module.
+ * @returns {Promise<object>} Module namespace; the constructor is `.default`
+ */
+function loadUpdateNotifier() {
+  return import('update-notifier');
+}
+
+module.exports = { loadUpdateNotifier };

package/src/utils/updater.js

@@ -0,0 +1,157 @@
+/**
+ * Updater Module
+ *
+ * Self-update functionality for amicus.
+ * Checks for new versions via update-notifier and performs
+ * updates via npm install -g.
+ *
+ * Supports AMICUS_MOCK_UPDATE (or legacy SIDECAR_MOCK_UPDATE) env var for testing:
+ *   "available" — getUpdateInfo returns fake update
+ *   "updating"  — getUpdateInfo returns fake update
+ *   "success"   — performUpdate resolves immediately
+ *   "error"     — performUpdate returns failure
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const { logger } = require('./logger');
+const { getCompatEnv } = require('./env-compat');
+const { loadUpdateNotifier } = require('./update-notifier-loader');
+
+const pkg = require(path.join(__dirname, '..', '..', 'package.json'));
+
+const MOCK_MODES = ['available', 'updating', 'success', 'error'];
+const FAKE_LATEST = '99.0.0';
+
+/** @type {import('update-notifier').UpdateNotifier|null} */
+let notifier = null;
+
+/**
+ * Check if mock mode is active
+ * @returns {string|null} The mock mode or null
+ */
+function getMockMode() {
+  const mode = getCompatEnv('MOCK_UPDATE');
+  if (mode && MOCK_MODES.includes(mode)) {
+    return mode;
+  }
+  return null;
+}
+
+/**
+ * Initialize the update checker with package info.
+ * Async because update-notifier is ESM-only and must be loaded with a
+ * dynamic import(). In mock mode, skips the real update-notifier call.
+ * @returns {Promise<void>}
+ */
+async function initUpdateCheck() {
+  const mock = getMockMode();
+  if (mock) {
+    logger.debug('Update check skipped (mock mode)', { mock });
+    return;
+  }
+
+  try {
+    const mod = await loadUpdateNotifier();
+    const updateNotifier = mod.default || mod;
+    notifier = updateNotifier({
+      pkg: { name: pkg.name, version: pkg.version }
+    });
+  } catch (err) {
+    logger.warn('Failed to initialize update checker', { error: err.message });
+  }
+}
+
+/**
+ * Get update information from the cached check.
+ * @returns {{ current: string, latest: string, hasUpdate: boolean }|null}
+ */
+function getUpdateInfo() {
+  const mock = getMockMode();
+  if (mock) {
+    return {
+      current: pkg.version,
+      latest: FAKE_LATEST,
+      hasUpdate: true
+    };
+  }
+
+  if (!notifier || !notifier.update) {
+    return null;
+  }
+
+  return {
+    current: notifier.update.current,
+    latest: notifier.update.latest,
+    hasUpdate: true
+  };
+}
+
+/**
+ * Display update notification via update-notifier's built-in notify.
+ * Mentions `amicus update` as the upgrade command.
+ */
+function notifyUpdate() {
+  if (!notifier) {
+    return;
+  }
+
+  notifier.notify({
+    message: 'Update available: {currentVersion} -> {latestVersion}\n' +
+      'Run `amicus update` to upgrade'
+  });
+}
+
+/**
+ * Perform the actual update by spawning npm install -g.
+ * @returns {Promise<{ success: boolean, newVersion?: string, error?: string }>}
+ */
+function performUpdate() {
+  const mock = getMockMode();
+
+  if (mock === 'success') {
+    return Promise.resolve({ success: true, newVersion: FAKE_LATEST });
+  }
+
+  if (mock === 'error') {
+    return Promise.resolve({
+      success: false,
+      error: 'Mock update error for testing'
+    });
+  }
+
+  return new Promise((resolve) => {
+    let stderr = '';
+
+    const proc = spawn('npm', ['install', '-g', 'amicus@latest'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: true
+    });
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve({ success: true });
+      } else {
+        resolve({
+          success: false,
+          error: stderr.trim() || `npm exited with code ${code}`
+        });
+      }
+    });
+
+    proc.on('error', (err) => {
+      resolve({ success: false, error: err.message });
+    });
+  });
+}
+
+module.exports = {
+  initUpdateCheck,
+  getUpdateInfo,
+  notifyUpdate,
+  performUpdate
+};