@the-open-engine/zeroshot 5.4.0

package/cli/lib/first-run.js

@@ -0,0 +1,211 @@
+/**
+ * First-Run Setup Wizard
+ *
+ * Interactive setup on first use:
+ * - Welcome banner
+ * - Max model ceiling selection (sonnet/opus/haiku)
+ * - Auto-update preference
+ * - Marks setup as complete
+ */
+
+const readline = require('readline');
+const { loadSettings, saveSettings } = require('../../lib/settings');
+const { detectProviders } = require('../../src/providers');
+
+/**
+ * Print welcome banner
+ */
+function printWelcome() {
+  console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║                                                               ║
+║   Welcome to Zeroshot!                                        ║
+║   Multi-agent orchestration engine                            ║
+║                                                               ║
+║   Let's configure a few settings to get started.              ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝
+`);
+}
+
+/**
+ * Create readline interface
+ * @returns {readline.Interface}
+ */
+function createReadline() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+/**
+ * Prompt for provider selection
+ * @param {readline.Interface} rl
+ * @param {object} detected
+ * @returns {Promise<string>}
+ */
+function promptProvider(rl, detected) {
+  console.log('\nWhich AI provider would you like to use by default?\n');
+
+  const available = Object.entries(detected).filter(([_, status]) => status.available);
+
+  if (available.length === 0) {
+    console.log('No AI CLI tools detected. Please install one of:');
+    console.log('  - Claude Code: npm install -g @anthropic-ai/claude-code');
+    console.log('  - Codex CLI:   npm install -g @openai/codex');
+    console.log('  - Gemini CLI:  npm install -g @google/gemini-cli');
+    process.exit(1);
+  }
+
+  available.forEach(([name], i) => {
+    console.log(`  ${i + 1}) ${name} (installed)`);
+  });
+
+  return new Promise((resolve) => {
+    rl.question('\nChoice [1]: ', (answer) => {
+      const idx = parseInt(answer) - 1 || 0;
+      resolve(available[idx]?.[0] || available[0][0]);
+    });
+  });
+}
+
+/**
+ * Prompt for model selection
+ * @param {readline.Interface} rl
+ * @returns {Promise<string>}
+ */
+function promptModel(rl) {
+  return new Promise((resolve) => {
+    console.log('What is the maximum Claude model agents can use? (cost ceiling)\n');
+    console.log('  1) sonnet  - Agents can use sonnet or haiku (recommended)');
+    console.log('  2) opus    - Agents can use opus, sonnet, or haiku');
+    console.log('  3) haiku   - Agents can only use haiku (lowest cost)\n');
+
+    rl.question('Enter 1, 2, or 3 [2]: ', (answer) => {
+      const choice = answer.trim() || '2';
+      switch (choice) {
+        case '2':
+          resolve('opus');
+          break;
+        case '3':
+          resolve('haiku');
+          break;
+        default:
+          resolve('sonnet');
+      }
+    });
+  });
+}
+
+/**
+ * Prompt for auto-update preference
+ * @param {readline.Interface} rl
+ * @returns {Promise<boolean>}
+ */
+function promptAutoUpdate(rl) {
+  return new Promise((resolve) => {
+    console.log('\nWould you like zeroshot to check for updates automatically?');
+    console.log('(Checks npm registry every 24 hours)\n');
+
+    rl.question('Enable auto-update checks? [Y/n]: ', (answer) => {
+      const normalized = answer.trim().toLowerCase();
+      // Default to yes if empty or starts with 'y'
+      resolve(normalized === '' || normalized === 'y' || normalized === 'yes');
+    });
+  });
+}
+
+/**
+ * Print completion message
+ * @param {object} settings - Saved settings
+ */
+function printComplete(settings) {
+  console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║  Setup complete!                                              ║
+╚═══════════════════════════════════════════════════════════════╝
+
+Your settings:
+  • Provider:     ${settings.defaultProvider}
+  • Max model:    ${settings.maxModel} (Claude ceiling)
+  • Auto-updates: ${settings.autoCheckUpdates ? 'enabled' : 'disabled'}
+
+Change anytime with: zeroshot settings set <key> <value>
+
+Get started:
+  zeroshot run "Fix the bug in auth.js"
+  zeroshot run 123  (GitHub issue number)
+  zeroshot --help
+
+`);
+}
+
+/**
+ * Check if first-run setup is needed
+ * @param {object} settings - Current settings
+ * @returns {boolean}
+ */
+function detectFirstRun(settings) {
+  return !settings.firstRunComplete;
+}
+
+/**
+ * Main entry point - run first-time setup if needed
+ * @param {object} options
+ * @param {boolean} options.quiet - Skip interactive prompts
+ * @returns {Promise<boolean>} True if setup was run
+ */
+async function checkFirstRun(options = {}) {
+  const settings = loadSettings();
+
+  // Already completed setup
+  if (!detectFirstRun(settings)) {
+    return false;
+  }
+
+  // Quiet mode - use defaults, mark complete
+  if (options.quiet) {
+    settings.firstRunComplete = true;
+    saveSettings(settings);
+    return true;
+  }
+
+  // Interactive setup
+  printWelcome();
+
+  const rl = createReadline();
+
+  try {
+    const detected = await detectProviders();
+    const provider = await promptProvider(rl, detected);
+    settings.defaultProvider = provider;
+
+    // Model ceiling selection
+    const model = await promptModel(rl);
+    settings.maxModel = model;
+
+    // Auto-update preference
+    const autoUpdate = await promptAutoUpdate(rl);
+    settings.autoCheckUpdates = autoUpdate;
+
+    // Mark complete
+    settings.firstRunComplete = true;
+    saveSettings(settings);
+
+    // Print completion
+    printComplete(settings);
+
+    return true;
+  } finally {
+    rl.close();
+  }
+}
+
+module.exports = {
+  checkFirstRun,
+  // Exported for testing
+  detectFirstRun,
+  printWelcome,
+  printComplete,
+};

package/cli/lib/update-checker.js

@@ -0,0 +1,281 @@
+/**
+ * Update Checker - Checks npm registry for newer versions
+ *
+ * Features:
+ * - 24-hour check interval (avoids registry spam)
+ * - 5-second timeout (non-blocking if offline)
+ * - Interactive prompt for manual update
+ * - Respects quiet mode (no prompts in CI/scripts)
+ */
+
+const https = require('https');
+const { spawn } = require('child_process');
+const readline = require('readline');
+const { loadSettings, saveSettings } = require('../../lib/settings');
+
+// 24 hours in milliseconds
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+// Timeout for npm registry fetch (5 seconds)
+const FETCH_TIMEOUT_MS = 5000;
+
+// npm registry URL
+const REGISTRY_URL = 'https://registry.npmjs.org/@the-open-engine/zeroshot/latest';
+
+/**
+ * Get current package version
+ * @returns {string}
+ */
+function getCurrentVersion() {
+  const pkg = require('../../package.json');
+  return pkg.version;
+}
+
+/**
+ * Compare semver versions
+ * @param {string} current - Current version (e.g., "1.5.0")
+ * @param {string} latest - Latest version (e.g., "1.6.0")
+ * @returns {boolean} True if latest > current
+ */
+function isNewerVersion(current, latest) {
+  const currentParts = current.split('.').map(Number);
+  const latestParts = latest.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const c = currentParts[i] || 0;
+    const l = latestParts[i] || 0;
+    if (l > c) return true;
+    if (l < c) return false;
+  }
+  return false;
+}
+
+/**
+ * Fetch latest version from npm registry
+ * @returns {Promise<string|null>} Latest version or null on failure
+ */
+function fetchLatestVersion() {
+  return new Promise((resolve) => {
+    const req = https.get(REGISTRY_URL, { timeout: FETCH_TIMEOUT_MS }, (res) => {
+      if (res.statusCode !== 200) {
+        resolve(null);
+        return;
+      }
+
+      let data = '';
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          resolve(json.version || null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+
+    req.on('error', () => {
+      resolve(null);
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+
+    // Additional safety timeout
+    setTimeout(() => {
+      req.destroy();
+      resolve(null);
+    }, FETCH_TIMEOUT_MS + 1000);
+  });
+}
+
+/**
+ * Prompt user for update confirmation
+ * @param {string} currentVersion
+ * @param {string} latestVersion
+ * @returns {Promise<boolean>} True if user wants to update
+ */
+function promptForUpdate(currentVersion, latestVersion) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    console.log(`\n📦 Update available: ${currentVersion} → ${latestVersion}`);
+    rl.question('   Install now? [y/N] ', (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+/**
+ * Check if we have write permission to npm global directory
+ * @returns {boolean} True if we can write to npm global prefix
+ */
+function canWriteToNpmGlobal() {
+  const { execSync } = require('child_process');
+  const fs = require('fs');
+
+  try {
+    // Get npm global prefix (e.g., /usr/lib or /home/user/.nvm/versions/node/...)
+    const prefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
+    const globalModulesDir = require('path').join(prefix, 'lib', 'node_modules');
+
+    // Check if directory exists and is writable
+    fs.accessSync(globalModulesDir, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run npm install to update the package
+ * @returns {Promise<boolean>} True if update succeeded
+ */
+function runUpdate() {
+  return new Promise((resolve) => {
+    // Check permissions BEFORE attempting update
+    if (!canWriteToNpmGlobal()) {
+      console.log('\n⚠️  Cannot auto-update: no write permission to npm global directory.');
+      console.log('   Run manually with sudo:');
+      console.log('   sudo npm install -g @the-open-engine/zeroshot@latest\n');
+      resolve(false);
+      return;
+    }
+
+    console.log('\n📥 Installing update...');
+
+    const proc = spawn('npm', ['install', '-g', '@the-open-engine/zeroshot@latest'], {
+      stdio: 'inherit',
+      shell: true,
+    });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        console.log('✅ Update installed successfully!');
+        console.log('   Restart zeroshot to use the new version.\n');
+        resolve(true);
+      } else {
+        console.log('❌ Update failed. Try manually:');
+        console.log('   sudo npm install -g @the-open-engine/zeroshot@latest\n');
+        resolve(false);
+      }
+    });
+
+    proc.on('error', () => {
+      console.log('❌ Update failed. Try manually:');
+      console.log('   sudo npm install -g @the-open-engine/zeroshot@latest\n');
+      resolve(false);
+    });
+  });
+}
+
+/**
+ * Check if update check should run
+ * @param {object} settings - Current settings
+ * @returns {boolean}
+ */
+function shouldCheckForUpdates(settings) {
+  // Disabled by user
+  if (!settings.autoCheckUpdates) {
+    return false;
+  }
+
+  // Never checked before
+  if (!settings.lastUpdateCheckAt) {
+    return true;
+  }
+
+  // Check if 24 hours have passed
+  const elapsed = Date.now() - settings.lastUpdateCheckAt;
+  return elapsed >= CHECK_INTERVAL_MS;
+}
+
+/**
+ * Main entry point - check for updates
+ * @param {object} options
+ * @param {boolean} options.quiet - Skip interactive prompts
+ * @returns {Promise<void>}
+ */
+async function checkForUpdates(options = {}) {
+  const settings = loadSettings();
+
+  // Skip check if not due
+  if (!shouldCheckForUpdates(settings)) {
+    return;
+  }
+
+  const currentVersion = getCurrentVersion();
+  const latestVersion = await fetchLatestVersion();
+
+  // Update last check timestamp regardless of result
+  settings.lastUpdateCheckAt = Date.now();
+  saveSettings(settings);
+
+  // Network failure - silently skip
+  if (!latestVersion) {
+    return;
+  }
+
+  // No update available
+  if (!isNewerVersion(currentVersion, latestVersion)) {
+    return;
+  }
+
+  // Already notified about this version
+  if (settings.lastSeenVersion === latestVersion) {
+    return;
+  }
+
+  // Update lastSeenVersion so we don't nag about the same version
+  settings.lastSeenVersion = latestVersion;
+  saveSettings(settings);
+
+  // Check write permissions upfront
+  const hasWriteAccess = canWriteToNpmGlobal();
+
+  // Quiet mode - just inform, no prompt
+  if (options.quiet) {
+    console.log(`📦 Update available: ${currentVersion} → ${latestVersion}`);
+    if (hasWriteAccess) {
+      console.log('   Run: npm install -g @the-open-engine/zeroshot@latest\n');
+    } else {
+      console.log('   Run: sudo npm install -g @the-open-engine/zeroshot@latest\n');
+    }
+    return;
+  }
+
+  // No write permission - inform user but don't offer interactive prompt
+  // (they'd say yes then get an error, which is frustrating UX)
+  if (!hasWriteAccess) {
+    console.log(`\n📦 Update available: ${currentVersion} → ${latestVersion}`);
+    console.log('   Run: sudo npm install -g @the-open-engine/zeroshot@latest\n');
+    return;
+  }
+
+  // Interactive mode - prompt for update (only if we have write access)
+  const wantsUpdate = await promptForUpdate(currentVersion, latestVersion);
+  if (wantsUpdate) {
+    await runUpdate();
+  }
+}
+
+module.exports = {
+  checkForUpdates,
+  // Exported for testing and CLI update command
+  getCurrentVersion,
+  isNewerVersion,
+  fetchLatestVersion,
+  runUpdate,
+  shouldCheckForUpdates,
+  canWriteToNpmGlobal,
+  CHECK_INTERVAL_MS,
+};

package/cli/message-formatter-utils.js

@@ -0,0 +1,75 @@
+/**
+ * Message formatting utilities for CLI output
+ * Extracted from index.js to reduce complexity
+ */
+
+const chalk = require('chalk');
+
+/**
+ * Get color for sender based on consistent hashing
+ * @param {string} sender - Sender name
+ * @returns {Function} Chalk color function
+ */
+function getColorForSender(sender) {
+  const colors = [chalk.cyan, chalk.magenta, chalk.yellow, chalk.green, chalk.blue];
+  let hash = 0;
+  for (let i = 0; i < sender.length; i++) {
+    hash = (hash << 5) - hash + sender.charCodeAt(i);
+    hash = hash & hash;
+  }
+  return colors[Math.abs(hash) % colors.length];
+}
+
+/**
+ * Build message prefix with timestamp, sender, and optional cluster ID
+ * @param {Object} msg - Message object
+ * @param {boolean} showClusterId - Whether to show cluster ID
+ * @param {boolean} isActive - Whether cluster is active
+ * @returns {string} Formatted prefix
+ */
+function buildMessagePrefix(msg, showClusterId, isActive) {
+  const color = isActive ? getColorForSender(msg.sender) : chalk.dim;
+
+  let senderLabel = msg.sender;
+  if (showClusterId && msg.cluster_id) {
+    senderLabel = `${msg.cluster_id}/${msg.sender}`;
+  }
+
+  const modelSuffix = msg.sender_model ? chalk.dim(` [${msg.sender_model}]`) : '';
+  return color(`${senderLabel.padEnd(showClusterId ? 25 : 15)} |`) + modelSuffix;
+}
+
+/**
+ * Build cluster prefix for watch mode
+ * @param {string} clusterId - Cluster ID
+ * @param {boolean} isActive - Whether cluster is active
+ * @returns {string} Formatted prefix
+ */
+function buildClusterPrefix(clusterId, isActive) {
+  return isActive
+    ? chalk.white(`${clusterId.padEnd(20)} |`)
+    : chalk.dim(`${clusterId.padEnd(20)} |`);
+}
+
+/**
+ * Parse and normalize data fields (handles string JSON)
+ * @param {string|Array} data - Data to parse
+ * @returns {Array} Parsed array
+ */
+function parseDataField(data) {
+  if (typeof data === 'string') {
+    try {
+      return JSON.parse(data);
+    } catch {
+      return [];
+    }
+  }
+  return Array.isArray(data) ? data : [];
+}
+
+module.exports = {
+  getColorForSender,
+  buildMessagePrefix,
+  buildClusterPrefix,
+  parseDataField,
+};