amicus 1.0.0

package/src/sidecar/session-utils.js

@@ -0,0 +1,288 @@
+/**
+ * Sidecar Session Utilities - Shared functionality for session management
+ * Consolidates duplicated code from start.js, resume.js, continue.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { detectConflicts, formatConflictWarning } = require('../conflict');
+const { logger } = require('../utils/logger');
+const {
+  SESSIONS_DIR,
+  getSessionDir,
+  resolveExistingSessionDir
+} = require('../session-manager');
+
+/** Standard heartbeat interval in milliseconds */
+const HEARTBEAT_INTERVAL = 15000;
+
+/** Session path utilities - eliminates magic strings across modules */
+const SessionPaths = {
+  /** Get canonical root sessions directory (amicus) — used for WRITES. */
+  rootDir(project) {
+    return path.join(project, '.claude', SESSIONS_DIR);
+  },
+
+  /** Get canonical session directory for a specific task — used for WRITES. */
+  sessionDir(project, taskId) {
+    return getSessionDir(project, taskId);
+  },
+
+  /**
+   * Resolve an EXISTING session directory for READS: prefer amicus, fall back
+   * to legacy `sidecar_sessions` (backward-compat shim). Use this when
+   * resuming/continuing an existing session so pre-rebrand sessions are found.
+   */
+  resolveSessionDir(project, taskId) {
+    return resolveExistingSessionDir(project, taskId);
+  },
+
+  /** Get metadata.json path */
+  metadataFile(sessionDir) {
+    return path.join(sessionDir, 'metadata.json');
+  },
+
+  /** Get conversation.jsonl path */
+  conversationFile(sessionDir) {
+    return path.join(sessionDir, 'conversation.jsonl');
+  },
+
+  /** Get summary.md path */
+  summaryFile(sessionDir) {
+    return path.join(sessionDir, 'summary.md');
+  },
+
+  /** Get initial_context.md path */
+  contextFile(sessionDir) {
+    return path.join(sessionDir, 'initial_context.md');
+  }
+};
+
+/** Save system prompt and user message to initial_context.md */
+function saveInitialContext(sessionDir, systemPrompt, userMessage) {
+  const content = `# System Prompt\n\n${systemPrompt}\n\n# User Message (Task)\n\n${userMessage}`;
+  fs.writeFileSync(SessionPaths.contextFile(sessionDir), content, { mode: 0o600 });
+}
+
+/** Finalize session - detect conflicts, save summary, update metadata */
+function finalizeSession(sessionDir, summary, project, metadata, opts = {}) {
+  const metaPath = SessionPaths.metadataFile(sessionDir);
+
+  // Detect file conflicts
+  const conflicts = detectConflicts(
+    { written: metadata.filesWritten },
+    project,
+    new Date(metadata.createdAt)
+  );
+
+  if (conflicts.length > 0) {
+    const conflictWarning = formatConflictWarning(conflicts);
+    if (opts.quietStdout) {
+      // JSON mode: stdout must stay pure JSON (F4) — warn on stderr instead.
+      process.stderr.write(`\n${conflictWarning}\n`);
+    } else {
+      console.log(`\n${conflictWarning}\n`);
+    }
+    metadata.conflicts = conflicts;
+  }
+
+  // Save summary
+  fs.writeFileSync(SessionPaths.summaryFile(sessionDir), summary, { mode: 0o600 });
+
+  // Update metadata to complete
+  metadata.status = 'complete';
+  metadata.completedAt = new Date().toISOString();
+  fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+
+  logger.info('Session complete', { taskId: metadata.taskId });
+}
+
+/** Output summary to stdout with standard formatting */
+function outputSummary(summary) {
+  console.log(summary);
+}
+
+/**
+ * Create a heartbeat that writes status to stderr periodically.
+ * When sessionDir is provided, includes message count and latest activity.
+ *
+ * @param {number} [interval=HEARTBEAT_INTERVAL] - Interval in milliseconds
+ * @param {string} [sessionDir] - Session directory to read progress from
+ * @returns {{ stop: () => void }}
+ */
+function createHeartbeat(interval = HEARTBEAT_INTERVAL, sessionDir) {
+  const startTime = Date.now();
+  const intervalId = setInterval(() => {
+    const elapsed = Math.round((Date.now() - startTime) / 1000);
+    const mins = Math.floor(elapsed / 60);
+    const secs = elapsed % 60;
+    const ts = mins > 0 ? `${mins}m${secs}s` : `${secs}s`;
+
+    if (sessionDir) {
+      const { readProgress } = require('./progress');
+      const progress = readProgress(sessionDir);
+      process.stderr.write(`[sidecar] ${ts} | ${progress.messages} messages | ${progress.latest}\n`);
+    } else {
+      process.stderr.write(`[sidecar] still running... ${ts} elapsed\n`);
+    }
+  }, interval);
+
+  return {
+    stop() {
+      clearInterval(intervalId);
+    }
+  };
+}
+
+/**
+ * Execute sidecar in either headless or interactive mode
+ * Consolidates the if/else pattern duplicated across start, resume, continue
+ */
+async function executeMode(options) {
+  const {
+    headless,
+    runHeadless,
+    runInteractive,
+    model,
+    systemPrompt,
+    userMessage,
+    taskId,
+    project,
+    timeout,
+    agent,
+    extraOptions = {},
+    defaultSummary = '## Sidecar Results: No Output\n\nSession completed without summary.',
+    operationType = 'task'
+  } = options;
+
+  let result;
+
+  if (headless) {
+    result = await runHeadless(
+      model,
+      systemPrompt,
+      userMessage,
+      taskId,
+      project,
+      timeout * 60 * 1000,
+      agent,
+      extraOptions
+    );
+
+    result.summary = result.summary || defaultSummary;
+
+    if (result.timedOut) {
+      logger.warn(`${operationType} timed out`, { taskId });
+    }
+    if (result.error) {
+      logger.error(`${operationType} error`, { taskId, error: result.error });
+    }
+  } else {
+    logger.info(`Launching interactive ${operationType}`, { taskId, model, agent });
+
+    result = await runInteractive(
+      model,
+      systemPrompt,
+      userMessage,
+      taskId,
+      project,
+      { agent, ...extraOptions }
+    );
+
+    result.summary = result.summary || '';
+
+    if (result.error) {
+      logger.error(`Interactive ${operationType} error`, { taskId, error: result.error });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Start OpenCode server, wait for health, return client+server.
+ * Shared by headless and interactive modes.
+ *
+ * @param {object} [mcpConfig] - Optional MCP server configuration
+ * @param {object} [options] - Additional server options
+ * @param {string} [options.client] - Client type (e.g. 'cowork', 'code-local')
+ * @param {string} [options.systemPrompt] - System prompt to set on agent config (hidden from UI)
+ * @param {string} [options.agentName] - Agent to set systemPrompt on (default: 'chat')
+ * @returns {Promise<{client: object, server: object}>}
+ * @throws {Error} If server fails to start or health check fails
+ */
+async function startOpenCodeServer(mcpConfig, options = {}) {
+  const { checkHealth, startServer } = require('../opencode-client');
+  const { ensureNodeModulesBinInPath } = require('../utils/path-setup');
+  const { ensurePortAvailable } = require('../utils/server-setup');
+  const { waitForServer } = require('../headless');
+
+  ensureNodeModulesBinInPath();
+
+  // Use specified port, or 0 to let the OS auto-assign (enables parallel sessions)
+  const port = options.port || 0;
+  if (port > 0) {
+    ensurePortAvailable(port);
+  }
+
+  const serverOptions = { port };
+  if (mcpConfig) { serverOptions.mcp = mcpConfig; }
+  if (options.client) { serverOptions.client = options.client; }
+  if (options.systemPrompt) { serverOptions.systemPrompt = options.systemPrompt; }
+  if (options.agentName) { serverOptions.agentName = options.agentName; }
+
+  const { client, server } = await startServer(serverOptions);
+  logger.debug('OpenCode server started', { url: server.url });
+
+  const ready = await waitForServer(client, checkHealth);
+  if (!ready) {
+    server.close();
+    throw new Error('OpenCode server failed to become ready');
+  }
+
+  return { client, server };
+}
+
+/**
+ * Check if a process with the given PID is still alive.
+ * @param {number|null} pid
+ * @returns {boolean}
+ */
+function isProcessAlive(pid) {
+  if (!pid) { return false; }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a session's processes are alive.
+ * @param {Object} metadata - Session metadata with pid and goPid
+ * @returns {'alive'|'server-dead'|'dead'}
+ */
+function checkSessionLiveness(metadata) {
+  if (!metadata) { return 'dead'; }
+  const nodeAlive = isProcessAlive(metadata.pid);
+  const goAlive = isProcessAlive(metadata.goPid);
+
+  if (nodeAlive && goAlive) { return 'alive'; }
+  if (nodeAlive && !goAlive) { return 'server-dead'; }
+  return 'dead';
+}
+
+module.exports = {
+  HEARTBEAT_INTERVAL,
+  SessionPaths,
+  saveInitialContext,
+  finalizeSession,
+  outputSummary,
+  createHeartbeat,
+  executeMode,
+  startOpenCodeServer,
+  isProcessAlive,
+  checkSessionLiveness
+};

package/src/sidecar/setup-window.js

@@ -0,0 +1,79 @@
+/**
+ * Setup Window Launcher
+ *
+ * Spawns the Electron window in setup mode (SIDECAR_MODE=setup)
+ * for API key configuration. Waits for the window to close and
+ * returns whether setup completed successfully.
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const { logger } = require('../utils/logger');
+const { getElectronPath } = require('./interactive');
+const { getCompatEnv } = require('../utils/env-compat');
+
+/**
+ * Launch the Electron setup window for API key entry
+ * @returns {Promise<{ success: boolean, error?: string }>}
+ */
+function launchSetupWindow() {
+  return new Promise((resolve) => {
+    const electronPath = getElectronPath();
+    if (!electronPath) {
+      resolve({ success: false, error: 'Electron not installed' });
+      return;
+    }
+    const mainPath = path.join(__dirname, '..', '..', 'electron', 'main.js');
+
+    const env = {
+      ...process.env,
+      AMICUS_MODE: 'setup'
+    };
+
+    const debugPort = getCompatEnv('DEBUG_PORT');
+    const args = debugPort
+      ? [`--remote-debugging-port=${debugPort}`, mainPath]
+      : [mainPath];
+    logger.info('Launching setup window', { debugPort: debugPort || 'disabled' });
+
+    const proc = spawn(electronPath, args, {
+      env,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    proc.stdout.setEncoding('utf-8');
+    proc.stdout.on('data', (chunk) => { stdout += chunk; });
+
+    proc.stderr.setEncoding('utf-8');
+    proc.stderr.on('data', (chunk) => {
+      logger.debug('Setup window stderr', { data: chunk.trim() });
+    });
+
+    proc.on('close', (code) => {
+      logger.info('Setup window closed', { code });
+
+      // Check if setup completed (stdout contains JSON status)
+      if (stdout.includes('"status":"complete"')) {
+        // Parse enriched JSON for default model and keyCount
+        try {
+          const jsonLine = stdout.split('\n').find(l => l.includes('"status":"complete"'));
+          const data = JSON.parse(jsonLine);
+          const result = { success: true };
+          if (data.default) { result.default = data.default; }
+          if (data.keyCount) { result.keyCount = data.keyCount; }
+          resolve(result);
+        } catch (_err) {
+          resolve({ success: true });
+        }
+      } else {
+        resolve({
+          success: false,
+          error: 'Setup window closed without completing'
+        });
+      }
+    });
+  });
+}
+
+module.exports = { launchSetupWindow };

package/src/sidecar/setup.js

@@ -0,0 +1,280 @@
+/**
+ * Sidecar Setup Wizard
+ *
+ * Provides interactive setup, alias management, and API key detection
+ * for the sidecar configuration.
+ *
+ * runInteractiveSetup() is Electron-first: launches the GUI wizard,
+ * falls back to runReadlineSetup() for headless environments.
+ */
+
+const path = require('path');
+const readline = require('readline');
+const { loadConfig, saveConfig, getDefaultAliases, getConfigDir } = require('../utils/config');
+const { logger } = require('../utils/logger');
+
+const { getCuratedModels } = require('../utils/curated-models');
+/**
+ * Model choices presented during readline setup — derived from curated-models (F5).
+ * @type {Array<{number: number, alias: string, label: string}>}
+ */
+const MODEL_CHOICES = getCuratedModels().map((c, i) => ({
+  number: i + 1, alias: c.alias, label: `${c.label} (${c.blurb})`
+}));
+
+/**
+ * Add a model alias to the existing config (or create config if none exists)
+ * @param {string} name - Alias name
+ * @param {string} modelString - Full model identifier
+ */
+function addAlias(name, modelString) {
+  if (typeof name === 'string') { name = name.trim(); }
+  if (typeof modelString === 'string') { modelString = modelString.trim(); }
+  if (!name || typeof name !== 'string' || name === 'null') {
+    throw new Error(`Invalid alias name: '${name}'. Alias name must be a non-empty string.`);
+  }
+  if (!modelString || typeof modelString !== 'string' || modelString === 'null') {
+    throw new Error(
+      `Invalid model value for alias '${name}': '${modelString}'. ` +
+      'Model must be a non-empty string (e.g., openrouter/google/gemini-3.1-pro-preview).'
+    );
+  }
+  const cfg = loadConfig() || { aliases: {} };
+  if (!cfg.aliases) {
+    cfg.aliases = {};
+  }
+  cfg.aliases[name] = modelString;
+  saveConfig(cfg);
+  logger.info('Alias added', { name, model: modelString });
+}
+
+/**
+ * Create a new config with all default aliases and the chosen default model
+ * @param {string} defaultModel - Default model alias or full model string
+ * @returns {object} The created config object
+ */
+function createDefaultConfig(defaultModel) {
+  const cfg = {
+    default: defaultModel,
+    aliases: getDefaultAliases()
+  };
+  saveConfig(cfg);
+  logger.info('Default config created', {
+    default: defaultModel,
+    aliasCount: Object.keys(cfg.aliases).length
+  });
+  return cfg;
+}
+
+/**
+ * Detect available API keys from .env file and process.env
+ * @returns {{openrouter: boolean, google: boolean, openai: boolean, anthropic: boolean}}
+ */
+function detectApiKeys() {
+  const { readApiKeys } = require('../utils/api-key-store');
+  return readApiKeys();
+}
+
+/**
+ * Prompt the user with a question via readline
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} prompt - Question text
+ * @returns {Promise<string>} User's answer
+ */
+function askQuestion(rl, prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Resolve user input to a model alias name
+ * @param {string} input - User input (number 1-5 or alias name)
+ * @returns {string|null} Resolved alias name, or null if invalid
+ */
+function resolveChoice(input) {
+  const num = parseInt(input, 10);
+  if (num >= 1 && num <= MODEL_CHOICES.length) {
+    return MODEL_CHOICES[num - 1].alias;
+  }
+
+  const defaults = getDefaultAliases();
+  if (defaults[input] !== undefined) {
+    return input;
+  }
+
+  return null;
+}
+
+/**
+ * Launch the Electron setup wizard
+ * @returns {Promise<{success: boolean, default?: string, keyCount?: number}>}
+ */
+async function launchWizard() {
+  const { launchSetupWindow } = require('./setup-window');
+  return launchSetupWindow();
+}
+
+/**
+ * Standalone API key setup — launches the Electron window directly
+ * Used by `sidecar setup --api-keys`
+ * @returns {Promise<boolean>} true if keys were configured
+ */
+async function runApiKeySetup() {
+  try {
+    const result = await launchWizard();
+    return result.success;
+  } catch (err) {
+    logger.warn('Could not launch setup window', { error: err.message });
+    return false;
+  }
+}
+
+/**
+ * Seed/refresh the model catalog (F5). Never throws — setup must complete offline.
+ * A floor-only/offline refresh returns [] (see model-catalog), reported as unavailable.
+ * @param {(line: string) => void} [print] - defaults to console.log
+ */
+/* eslint-disable no-console -- CLI wizard requires direct console output */
+async function seedCatalog(print) {
+  const log = print ?? console.log;
+  try {
+    log('Refreshing model catalog...');
+    const { refreshCatalog } = require('../utils/model-catalog');
+    const models = await refreshCatalog();
+    if (models.length > 0) {
+      log(`Model catalog seeded (${models.length} models).`);
+      return;
+    }
+  } catch (err) {
+    logger.debug('Catalog seed failed', { error: err.message });
+  }
+  log('Model catalog unavailable (offline?) — it will refresh on first start.');
+}
+
+/**
+ * Run the readline-based setup wizard (headless fallback)
+ *
+ * Guides the user through:
+ * 1. API key detection
+ * 2. Default model selection
+ * 3. Config file creation
+ */
+async function runReadlineSetup() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    console.log('');
+    console.log('=== Sidecar Setup Wizard ===');
+    console.log('');
+
+    const keys = detectApiKeys();
+
+    const foundKeys = Object.entries(keys)
+      .filter(([, found]) => found)
+      .map(([provider]) => provider);
+
+    if (foundKeys.length > 0) {
+      console.log(`API keys detected: ${foundKeys.join(', ')}`);
+    } else {
+      console.log('No API keys detected.');
+      console.log('Set OPENROUTER_API_KEY to get started, or run: sidecar setup');
+    }
+    console.log('');
+
+    console.log('Choose your default model:');
+    console.log('');
+    for (const choice of MODEL_CHOICES) {
+      console.log(`  ${choice.number}) ${choice.alias} - ${choice.label}`);
+    }
+    console.log('');
+
+    const answer = await askQuestion(rl, 'Pick a default (1-5 or alias name): ');
+    const chosen = resolveChoice(answer);
+
+    if (!chosen) {
+      console.log(`Invalid choice: "${answer}". Using "gemini" as default.`);
+      const cfg = createDefaultConfig('gemini');
+      await seedCatalog();
+      const aliasCount = Object.keys(cfg.aliases).length;
+      console.log('');
+      console.log(`Config created with ${aliasCount} aliases.`);
+      console.log(`Config path: ${path.join(getConfigDir(), 'config.json')}`);
+      return;
+    }
+
+    const cfg = createDefaultConfig(chosen);
+    await seedCatalog();
+    const aliasCount = Object.keys(cfg.aliases).length;
+
+    console.log('');
+    console.log(`Default model set to: ${chosen}`);
+    console.log(`Config created with ${aliasCount} aliases.`);
+    console.log(`Config path: ${path.join(getConfigDir(), 'config.json')}`);
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Run the interactive setup wizard (Electron-first)
+ *
+ * Attempts to launch the Electron GUI wizard. If Electron is not
+ * available or fails, falls back to the readline-based setup.
+ */
+async function runInteractiveSetup() {
+  try {
+    const result = await launchWizard();
+    if (result.success) {
+      // Wizard handled config creation; if it returned a default, ensure config exists
+      if (result.default) {
+        const existing = loadConfig();
+        if (!existing || !existing.default) {
+          createDefaultConfig(result.default);
+        }
+      }
+
+      await seedCatalog();
+
+      const configPath = path.join(getConfigDir(), 'config.json');
+      const keyLabel = result.keyCount
+        ? `${result.keyCount} API key(s) configured.`
+        : 'API keys configured.';
+      const modelLabel = result.default
+        ? `Default model: ${result.default}`
+        : '';
+
+      console.log('');
+      console.log('Setup complete!');
+      if (keyLabel) { console.log(keyLabel); }
+      if (modelLabel) { console.log(modelLabel); }
+      console.log(`Config: ${configPath}`);
+      return;
+    }
+  } catch (err) {
+    logger.debug('Electron wizard unavailable, falling back to readline', {
+      error: err.message
+    });
+  }
+
+  // Fallback to readline
+  await runReadlineSetup();
+}
+
+/* eslint-enable no-console */
+
+module.exports = {
+  addAlias,
+  createDefaultConfig,
+  detectApiKeys,
+  runInteractiveSetup,
+  runReadlineSetup,
+  runApiKeySetup,
+  seedCatalog,
+  MODEL_CHOICES,
+};