amicus 1.0.0

package/bin/amicus.js

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+
+/**
+ * Amicus CLI Entry Point
+ *
+ * Spec Reference: §4 CLI Interface
+ * Routes commands to appropriate handlers.
+ */
+
+// Load API keys from all sources: process.env > sidecar .env > auth.json
+const { loadCredentials } = require('../src/utils/env-loader');
+loadCredentials();
+
+const { parseArgs, validateStartArgs, getUsage } = require('../src/cli');
+const { validateTaskId } = require('../src/utils/validators');
+const { resolveModelFromArgs, validateFallbackModel } = require('../src/utils/start-helpers');
+const { handleSetup, handleAbort, handleUpdate, handleMcp } = require('../src/cli-handlers');
+const { isOneShotCommand, armExitWatchdog } = require('../src/utils/lifecycle');
+const { logger } = require('../src/utils/logger');
+
+const VERSION = require('../package.json').version;
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+
+  // Install crash handler for MCP-spawned processes (have --task-id)
+  if (args['task-id'] && (command === 'start' || command === 'continue')) {
+    const { installCrashHandler } = require('../src/sidecar/crash-handler');
+    const project = args.cwd || process.cwd();
+    const handler = installCrashHandler(args['task-id'], project);
+    process.on('uncaughtException', (err) => {
+      handler(err);
+      process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+      handler(reason instanceof Error ? reason : new Error(String(reason)));
+      process.exit(1);
+    });
+  }
+
+  // Non-interactive update check (skip for mcp, --version, --help)
+  if (command !== 'mcp' && !args.version && !args.help) {
+    const { initUpdateCheck, getUpdateInfo, notifyUpdate } = require('../src/utils/updater');
+    await initUpdateCheck();
+    // Pass update info to Electron child process via env var,
+    // because update-notifier deletes the cache entry after reading it.
+    const cliUpdateInfo = getUpdateInfo();
+    if (cliUpdateInfo) {
+      process.env.AMICUS_UPDATE_INFO = JSON.stringify(cliUpdateInfo);
+      process.on('exit', () => {
+        process.stderr.write(
+          `\n  Update available: v${cliUpdateInfo.current} → v${cliUpdateInfo.latest}\n` +
+          '  Run `npm install -g amicus` to upgrade.\n\n'
+        );
+      });
+    }
+  }
+
+  // Handle --version
+  if (args.version) {
+    console.log(`amicus v${VERSION}`);
+    process.exit(0);
+  }
+
+  // Handle --help or no command
+  if (args.help || args._.length === 0) {
+    console.log(getUsage());
+    process.exit(0);
+  }
+
+  let exitCode = 0;
+  try {
+    switch (command) {
+      case 'start':
+        await handleStart(args);
+        break;
+      case 'fanout':
+        exitCode = await handleFanout(args);
+        break;
+      case 'list':
+        await handleList(args);
+        break;
+      case 'resume':
+        await handleResume(args);
+        break;
+      case 'continue':
+        await handleContinue(args);
+        break;
+      case 'read':
+        await handleRead(args);
+        break;
+      case 'models': {
+        const { handleModels } = require('../src/sidecar/models');
+        exitCode = await handleModels(args);
+        break;
+      }
+      case 'setup':
+        await handleSetup(args);
+        break;
+      case 'abort':
+        await handleAbort(args);
+        break;
+      case 'mcp':
+        await handleMcp();
+        break;
+      case 'update':
+        await handleUpdate();
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.log(getUsage());
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  // F3 #15: one-shot commands must not hang on a lingering handle. The work is
+  // done here; give natural drain a brief grace, then force-exit as a net.
+  // (mcp is long-lived and never reaches this point.)
+  if (exitCode) { process.exitCode = exitCode; }
+  if (isOneShotCommand(command)) {
+    armExitWatchdog(exitCode, 1500, { log: (m, meta) => logger.debug(m, meta) });
+  }
+}
+
+/**
+ * Handle 'sidecar start' command
+ * Spec Reference: §4.1
+ */
+async function handleStart(args) {
+  // F4: --prompt-file support (XOR --prompt) and --json gating
+  if (args.prompt !== undefined || args['prompt-file'] !== undefined) {
+    const { resolvePromptSource } = require('../src/utils/prompt-source');
+    const promptRes = resolvePromptSource(args);
+    if (promptRes.error) {
+      console.error(promptRes.error);
+      process.exit(1);
+    }
+    args.prompt = promptRes.prompt;
+  }
+  if (args.json && !args['no-ui']) {
+    console.error('Error: --json requires --no-ui');
+    process.exit(1);
+  }
+
+  const { model, alias } = resolveModelFromArgs(args);
+  args.model = model;
+  args.model = await validateFallbackModel(args, alias);
+
+  // Normalize agent: --agent takes precedence, otherwise use --mode
+  args.agent = args.agent || args.mode;
+
+  const validation = validateStartArgs(args);
+  if (!validation.valid) {
+    console.error(validation.error);
+    process.exit(1);
+  }
+
+  const { startSidecar } = require('../src/index');
+
+  await startSidecar({
+    taskId: args['task-id'],
+    model: args.model,
+    prompt: args.prompt,
+    sessionId: args['session-id'],
+    cwd: args.cwd,
+    contextTurns: args['context-turns'],
+    contextSince: args['context-since'],
+    contextMaxTokens: args['context-max-tokens'],
+    noUi: args['no-ui'],
+    timeout: args.timeout,
+    agent: args.agent,
+    mcp: args.mcp,
+    mcpConfig: args['mcp-config'],
+    thinking: args.thinking,
+    summaryLength: args['summary-length'],
+    client: args.client,
+    sessionDir: args['session-dir'],
+    foldShortcut: args['fold-shortcut'],
+    opencodePort: args['opencode-port'],
+    noMcp: args['no-mcp'],
+    excludeMcp: args['exclude-mcp'],
+    coworkProcess: args['cowork-process'],
+    position: args.position,
+    json: !!args.json,
+    modelInput: alias || null,
+  });
+}
+
+/**
+ * Handle 'amicus fanout' command (F4).
+ * Returns the wave exit code: 0 all complete, 2 partial, 1 none/hard failure,
+ * 130/143 when the wave was signal-aborted.
+ */
+async function handleFanout(args) {
+  const { resolvePromptSource } = require('../src/utils/prompt-source');
+  const promptRes = resolvePromptSource(args);
+  if (promptRes.error) {
+    console.error(promptRes.error);
+    process.exit(1);
+  }
+  if (typeof args.models !== 'string' || !args.models.trim()) {
+    console.error('Error: --models is required (comma-separated aliases or provider/model IDs)');
+    process.exit(1);
+  }
+  if (args['wave-id']) {
+    const check = validateTaskId(String(args['wave-id']));
+    if (!check.valid) {
+      console.error(check.error);
+      process.exit(1);
+    }
+  }
+  if (args.agent && String(args.agent).toLowerCase() === 'chat') {
+    console.error('Error: --agent chat is interactive-only; fanout is headless');
+    process.exit(1);
+  }
+  if (args.timeout !== undefined && args.timeout <= 0) {
+    console.error('Error: --timeout must be a positive number');
+    process.exit(1);
+  }
+  const { parseModelsList } = require('../src/sidecar/fanout');
+  if (parseModelsList(args.models).length === 0) {
+    console.error('Error: --models must contain at least one non-empty entry');
+    process.exit(1);
+  }
+
+  // Direct require — the src/index.js public re-export is added later (Task 13)
+  const { runFanout } = require('../src/sidecar/fanout');
+  const { exitCode } = await runFanout({
+    models: args.models,
+    prompt: promptRes.prompt,
+    promptMeta: promptRes.promptMeta,
+    waveId: args['wave-id'],
+    project: args.cwd || process.cwd(),
+    agent: args.agent || args.mode,
+    thinking: args.thinking,
+    timeout: args.timeout,
+    summaryLength: args['summary-length'],
+    includeContext: !args['no-context'],
+    sessionId: args['session-id'],
+    contextTurns: args['context-turns'],
+    contextSince: args['context-since'],
+    contextMaxTokens: args['context-max-tokens'],
+    mcp: args.mcp,
+    mcpConfig: args['mcp-config'],
+    noMcp: args['no-mcp'],
+    excludeMcp: args['exclude-mcp'],
+    noValidateModel: args['no-validate-model'],
+    json: !!args.json,
+    client: args.client,
+  });
+  return exitCode;
+}
+
+/**
+ * Handle 'sidecar list' command
+ * Spec Reference: §4.2
+ */
+async function handleList(args) {
+  const { listSidecars } = require('../src/index');
+
+  await listSidecars({
+    status: args.status,
+    all: args.all,
+    json: args.json,
+    project: args.cwd
+  });
+}
+
+/**
+ * Handle 'sidecar resume' command
+ * Spec Reference: §4.3
+ */
+async function handleResume(args) {
+  const taskId = args._[1];
+
+  if (!taskId) {
+    console.error('Error: task_id is required for resume');
+    console.error('Usage: sidecar resume <task_id>');
+    process.exit(1);
+  }
+
+  const taskIdCheck = validateTaskId(taskId);
+  if (!taskIdCheck.valid) {
+    console.error(taskIdCheck.error);
+    process.exit(1);
+  }
+
+  const { resumeSidecar } = require('../src/index');
+
+  await resumeSidecar({
+    taskId,
+    project: args.cwd,
+    headless: args['no-ui'],
+    timeout: args.timeout
+  });
+}
+
+/**
+ * Handle 'sidecar continue' command
+ * Spec Reference: §4.4
+ */
+async function handleContinue(args) {
+  const taskId = args._[1];
+
+  if (!taskId) {
+    console.error('Error: task_id is required for continue');
+    console.error('Usage: sidecar continue <task_id> --prompt "..."');
+    process.exit(1);
+  }
+
+  const taskIdCheck = validateTaskId(taskId);
+  if (!taskIdCheck.valid) {
+    console.error(taskIdCheck.error);
+    process.exit(1);
+  }
+
+  if (!args.prompt && !args.briefing) {
+    console.error('Error: --prompt is required for continue');
+    process.exit(1);
+  }
+
+  // F5: an explicitly passed --model gets the same resolution+validation as start.
+  if (args.model !== undefined) {
+    const { model, alias } = resolveModelFromArgs(args);
+    args.model = model;
+    args.model = await validateFallbackModel(args, alias);
+  }
+
+  const { continueSidecar } = require('../src/index');
+
+  await continueSidecar({
+    taskId,
+    newTaskId: args['task-id'],
+    briefing: args.prompt || args.briefing,
+    model: args.model,
+    project: args.cwd,
+    contextTurns: args['context-turns'],
+    contextMaxTokens: args['context-max-tokens'],
+    headless: args['no-ui'],
+    timeout: args.timeout
+  });
+}
+
+/**
+ * Handle 'sidecar read' command
+ * Spec Reference: §4.5
+ */
+async function handleRead(args) {
+  const taskId = args._[1];
+
+  if (!taskId) {
+    console.error('Error: task_id is required for read');
+    console.error('Usage: sidecar read <task_id> [--summary|--conversation]');
+    process.exit(1);
+  }
+
+  const taskIdCheck = validateTaskId(taskId);
+  if (!taskIdCheck.valid) {
+    console.error(taskIdCheck.error);
+    process.exit(1);
+  }
+
+  const { readSidecar } = require('../src/index');
+
+  await readSidecar({
+    taskId,
+    conversation: args.conversation,
+    metadata: args.metadata,
+    json: args.json,
+    project: args.cwd
+  });
+}
+
+// Run main
+main().catch(err => {
+  console.error(`Fatal error: ${err.message}`);
+  process.exit(1);
+});

package/electron/assets/icon.svg

@@ -0,0 +1,5 @@
+<svg width="1024" height="1024" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="16" height="16" rx="3" fill="#2D2B2A"/>
+  <path d="M3 2v12" stroke="#D97757" stroke-width="2" stroke-linecap="round"/>
+  <path d="M10 2v5c0 2-3 3-7 5" stroke="#D97757" stroke-width="2" stroke-linecap="round" stroke-opacity="0.6"/>
+</svg>

package/electron/fold.js

@@ -0,0 +1,163 @@
+/**
+ * Fold Logic
+ *
+ * Handles the fold action: showing overlay, requesting summary,
+ * outputting fold data to stdout, and closing the window.
+ */
+
+const { logger } = require('../src/utils/logger');
+const { requestSummaryFromModel } = require('./summary');
+const { getSummaryTemplate } = require('../src/prompt-builder');
+
+/**
+ * Create a fold handler bound to the window state
+ * @param {object} state - Shared state object
+ * @param {string} state.model - Model name
+ * @param {string} state.client - Client type
+ * @param {string} state.cwd - Working directory
+ * @param {string} state.sessionId - OpenCode session ID
+ * @param {string} state.taskId - Sidecar task ID
+ * @param {number} state.port - OpenCode server port
+ * @returns {{ triggerFold: Function, hasFolded: Function }}
+ */
+function createFoldHandler(state) {
+  let folded = false;
+
+  async function triggerFold(mainWindow, contentView) {
+    if (folded) { return; }
+    folded = true;
+
+    // Show fold progress in toolbar and content overlay
+    showFoldOverlay(mainWindow, contentView);
+
+    try {
+      // Ask the model to generate a structured summary
+      let summary = '';
+      try {
+        summary = await requestSummaryFromModel(
+          state.sessionId, state.port, getSummaryTemplate
+        );
+      } catch (err) {
+        logger.warn('Failed to get model summary', { error: err.message });
+      }
+
+      const output = [
+        '[SIDECAR_FOLD]',
+        `Model: ${state.model}`,
+        `Session: ${state.sessionId || state.taskId}`,
+        `Client: ${state.client}`,
+        `CWD: ${state.cwd}`,
+        `Mode: interactive`,
+        '---',
+        summary || 'Session ended without summary.'
+      ].join('\n');
+
+      process.stdout.write(output + '\n');
+      logger.info('Fold completed', { taskId: state.taskId });
+
+      // Show nudge overlay before closing
+      if (contentView) {
+        await contentView.webContents.executeJavaScript(`
+          (function() {
+            var overlay = document.getElementById('sidecar-fold-overlay');
+            if (overlay) {
+              while (overlay.firstChild) { overlay.removeChild(overlay.firstChild); }
+              var msg = document.createElement('div');
+              msg.style.cssText = 'color:#E8E0D8;font-family:-apple-system,BlinkMacSystemFont,sans-serif;font-size:15px;font-weight:500;text-align:center;max-width:320px;';
+              msg.textContent = 'Summary saved. Tell Claude you\\u2019re done with the Amicus session so it can read the results.';
+              overlay.appendChild(msg);
+            }
+          })();
+        `).catch(() => {});
+      }
+
+      // Wait 2.5s for user to read the nudge, then close
+      await new Promise(resolve => setTimeout(resolve, 2500));
+    } catch (err) {
+      logger.error('Fold failed', { error: err.message });
+      folded = false;
+      return;
+    }
+
+    // Close the window after fold
+    const { app } = require('electron');
+    if (mainWindow) {
+      mainWindow.close();
+    } else {
+      app.quit();
+    }
+  }
+
+  function hasFolded() {
+    return folded;
+  }
+
+  return { triggerFold, hasFolded };
+}
+
+/**
+ * Show fold progress overlay in both the toolbar and the content view.
+ * Note: The JS strings below contain only hardcoded markup (no user input),
+ * so there is no XSS risk from DOM manipulation.
+ */
+function showFoldOverlay(mainWindow, contentView) {
+  if (mainWindow) {
+    mainWindow.webContents.executeJavaScript(`
+      (function() {
+        var btn = document.getElementById('fold-btn');
+        if (btn) {
+          btn.textContent = '';
+          var span = document.createElement('span');
+          span.style.cssText = 'display:inline-flex;align-items:center;gap:6px;';
+          var spinner = document.createElement('span');
+          spinner.style.cssText = 'width:12px;height:12px;border:2px solid rgba(255,255,255,0.3);border-top-color:#fff;border-radius:50%;animation:spin 0.8s linear infinite;display:inline-block;';
+          span.appendChild(spinner);
+          span.appendChild(document.createTextNode('Generating summary\\u2026'));
+          btn.appendChild(span);
+          btn.disabled = true;
+          btn.style.opacity = '0.85';
+          btn.style.cursor = 'default';
+        }
+        if (!document.getElementById('fold-spin-style')) {
+          var style = document.createElement('style');
+          style.id = 'fold-spin-style';
+          style.textContent = '@keyframes spin { to { transform: rotate(360deg); } }';
+          document.head.appendChild(style);
+        }
+      })();
+    `).catch(() => {});
+  }
+  if (contentView) {
+    contentView.webContents.executeJavaScript(`
+      (function() {
+        if (!document.getElementById('fold-spin-style')) {
+          var style = document.createElement('style');
+          style.id = 'fold-spin-style';
+          style.textContent = '@keyframes spin { to { transform: rotate(360deg); } }';
+          document.head.appendChild(style);
+        }
+        var overlay = document.createElement('div');
+        overlay.id = 'sidecar-fold-overlay';
+        overlay.style.cssText = 'position:fixed;inset:0;background:rgba(0,0,0,0.55);display:flex;flex-direction:column;align-items:center;justify-content:center;z-index:99999;';
+
+        var spinDiv = document.createElement('div');
+        spinDiv.style.cssText = 'width:32px;height:32px;border:3px solid rgba(217,119,87,0.3);border-top-color:#D97757;border-radius:50%;animation:spin 0.8s linear infinite;margin-bottom:16px;';
+        overlay.appendChild(spinDiv);
+
+        var titleDiv = document.createElement('div');
+        titleDiv.style.cssText = 'color:#E8E0D8;font-family:-apple-system,BlinkMacSystemFont,sans-serif;font-size:15px;font-weight:500;';
+        titleDiv.textContent = 'Generating summary\\u2026';
+        overlay.appendChild(titleDiv);
+
+        var subtitleDiv = document.createElement('div');
+        subtitleDiv.style.cssText = 'color:#7A756F;font-family:-apple-system,BlinkMacSystemFont,sans-serif;font-size:12px;margin-top:6px;';
+        subtitleDiv.textContent = 'Folding session back to Claude Code';
+        overlay.appendChild(subtitleDiv);
+
+        document.body.appendChild(overlay);
+      })();
+    `).catch(() => {});
+  }
+}
+
+module.exports = { createFoldHandler, showFoldOverlay };