slackhive 0.1.37 → 0.1.39

package/cli/src/commands/init.ts

@@ -0,0 +1,514 @@
+/**
+ * @fileoverview `slackhive init` — clone, configure, and start SlackHive.
+ *
+ * @module cli/commands/init
+ */
+
+import { execSync, spawn } from 'child_process';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import prompts from 'prompts';
+
+const REPO_URL = 'https://github.com/pelago-labs/slackhive.git';
+
+interface InitOptions {
+  dir: string;
+  skipStart?: boolean;
+}
+
+function detectClaudeBin(): string {
+  let claudeBin: string;
+  try {
+    claudeBin = execSync('which claude', { encoding: 'utf-8' }).trim();
+  } catch {
+    throw new Error('Claude Code not found. Please install Claude Code first.');
+  }
+  if (!claudeBin) throw new Error('Claude Code not found. Please install Claude Code first.');
+  return claudeBin;
+}
+
+interface OAuthCredentials {
+  accessToken: string;
+  refreshToken: string;
+}
+
+/**
+ * Parses a JSON credential blob and extracts OAuth tokens.
+ */
+function parseOAuthFromJson(json: string): OAuthCredentials | null {
+  try {
+    const parsed = JSON.parse(json);
+    const oauth = parsed?.claudeAiOauth;
+    if (oauth?.accessToken && oauth?.refreshToken) {
+      return { accessToken: oauth.accessToken, refreshToken: oauth.refreshToken };
+    }
+  } catch { /* invalid json */ }
+  return null;
+}
+
+/**
+ * Extracts the OAuth credentials from the OS credential store.
+ * Tries macOS Keychain, then Linux secret-tool (GNOME Keyring).
+ * Returns access + refresh tokens, or null if not found.
+ */
+function extractOAuthCredentials(): OAuthCredentials | null {
+  // macOS: read from Keychain
+  try {
+    const creds = execSync('security find-generic-password -s "Claude Code-credentials" -w', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }).trim();
+    const result = parseOAuthFromJson(creds);
+    if (result) return result;
+  } catch { /* not macOS or not found */ }
+
+  // Linux: try secret-tool (GNOME Keyring)
+  try {
+    const creds = execSync('secret-tool lookup service "Claude Code-credentials"', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+    }).trim();
+    const result = parseOAuthFromJson(creds);
+    if (result) return result;
+  } catch { /* not available */ }
+
+  // Fallback: read credentials file directly (headless Linux / no keyring)
+  try {
+    const credPath = join(process.env.HOME || '~', '.claude', '.credentials.json');
+    if (existsSync(credPath)) {
+      const creds = readFileSync(credPath, 'utf-8').trim();
+      const result = parseOAuthFromJson(creds);
+      if (result) return result;
+    }
+  } catch { /* file not readable or invalid */ }
+
+  return null;
+}
+
+/**
+ * Runs `slackhive init` — interactive setup wizard.
+ *
+ * @param {InitOptions} opts - CLI options.
+ */
+export async function init(opts: InitOptions): Promise<void> {
+  const dir = resolve(opts.dir);
+
+  const O = chalk.hex('#D97757').bold;
+  const W = chalk.hex('#EBE6E0').bold;
+  console.log('');
+  console.log('      ' + W('│   │'));
+  console.log('   ' + W('───┼───┼───'));
+  console.log('  ' + O('>') + W(' ──┼──') + O('█') + W('┼──'));
+  console.log('      ' + W('│   │'));
+  console.log('');
+  console.log(chalk.bold('  SlackHive') + chalk.gray(' — AI agent teams on Slack'));
+  console.log('');
+
+  // ── Step 1: Check prerequisites ───────────────────────────────────────────
+  console.log(chalk.bold.hex('#D97757')('  [1/4]') + chalk.bold(' Checking prerequisites'));
+  console.log('');
+
+  const checks = [
+    { name: 'Docker daemon', cmd: 'docker info', errMsg: 'Docker is not running. Please start Docker Desktop and try again.' },
+    { name: 'Docker Compose', cmd: 'docker compose version', errMsg: 'Docker Compose not found. Please install Docker Desktop.' },
+    { name: 'Git', cmd: 'git --version', errMsg: 'Git not found. Please install Git first.' },
+  ];
+
+  for (const check of checks) {
+    const spinner = ora(`  Checking ${check.name}...`).start();
+    try {
+      execSync(check.cmd, { stdio: 'ignore' });
+      spinner.succeed(chalk.green(`${check.name} ready`));
+    } catch {
+      spinner.fail(chalk.red(`${check.name}: ${check.errMsg}`));
+      process.exit(1);
+    }
+  }
+  console.log('');
+
+  // ── Step 2: Clone ─────────────────────────────────────────────────────────
+  console.log(chalk.bold.hex('#D97757')('  [2/4]') + chalk.bold(' Getting SlackHive'));
+  console.log('');
+
+  if (existsSync(dir)) {
+    console.log(chalk.yellow(`  note: Directory ${opts.dir} already exists — using existing`));
+  } else {
+    const spinner = ora('  Cloning repository...').start();
+    try {
+      execSync(`git clone --depth 1 ${REPO_URL} "${dir}"`, { stdio: 'ignore' });
+      spinner.succeed('Repository cloned');
+    } catch {
+      spinner.fail('Failed to clone repository');
+      process.exit(1);
+    }
+  }
+  console.log('');
+
+  // ── Step 3: Configure .env ────────────────────────────────────────────────
+  const envPath = join(dir, '.env');
+  const freshEnv = !existsSync(envPath);
+
+  if (freshEnv) {
+    console.log(chalk.bold.hex('#D97757')('  [3/4]') + chalk.bold(' Configure environment'));
+    console.log('');
+
+    const authMode = await prompts({
+      type: 'select',
+      name: 'mode',
+      message: 'Claude authentication',
+      choices: [
+        { title: 'API Key — pay-per-use via Anthropic API', value: 'apikey' },
+        { title: 'Subscription — run `claude login` first', value: 'subscription' },
+      ],
+    });
+
+    if (!authMode.mode) {
+      console.log(chalk.red('\n  Setup cancelled.'));
+      process.exit(1);
+    }
+
+    const questions: prompts.PromptObject[] = [];
+    let oauthCreds: OAuthCredentials | null = null;
+
+    if (authMode.mode === 'apikey') {
+      questions.push({
+        type: 'text',
+        name: 'anthropicKey',
+        message: 'Anthropic API key',
+        validate: (v: string) => v.startsWith('sk-') ? true : 'Must start with sk-',
+      });
+    } else {
+      // Claude subscription mode — extract OAuth token
+      const claudeDir = join(process.env.HOME || '~', '.claude');
+      if (!existsSync(claudeDir)) {
+        console.log(chalk.yellow('\n  warning: ~/.claude not found. Run `claude login` first, then re-run `slackhive init`.'));
+        process.exit(1);
+      }
+      console.log(chalk.green('  ✓') + ' Found ~/.claude credentials');
+
+      const spinner = ora('  Extracting OAuth credentials...').start();
+      oauthCreds = extractOAuthCredentials();
+      if (oauthCreds) {
+        spinner.succeed('OAuth credentials extracted');
+      } else {
+        spinner.warn('Could not auto-extract credentials from keychain');
+        console.log(chalk.gray('  On Linux/headless servers, paste your OAuth token manually.'));
+        console.log(chalk.gray('  Get it from a machine where you ran `claude login`:'));
+        console.log(chalk.gray('    security find-generic-password -s "Claude Code-credentials" -w'));
+        console.log('');
+
+        const tokenResponse = await prompts([
+          { type: 'password', name: 'accessToken', message: 'OAuth access token (sk-ant-oat01-...)', validate: (v: string) => v.startsWith('sk-ant-oat') ? true : 'Must start with sk-ant-oat' },
+          { type: 'password', name: 'refreshToken', message: 'OAuth refresh token (sk-ant-ort01-...)', validate: (v: string) => v.startsWith('sk-ant-ort') ? true : 'Must start with sk-ant-ort' },
+        ]);
+        if (!tokenResponse.accessToken || !tokenResponse.refreshToken) {
+          console.log(chalk.red('\n  Setup cancelled. Use API Key mode instead on headless servers.'));
+          process.exit(1);
+        }
+        oauthCreds = { accessToken: tokenResponse.accessToken, refreshToken: tokenResponse.refreshToken };
+      }
+    }
+
+    questions.push(
+      { type: 'text', name: 'adminUsername', message: 'Admin username', initial: 'admin' },
+      { type: 'password', name: 'adminPassword', message: 'Admin password', validate: (v: string) => v.length >= 6 ? true : 'At least 6 characters' },
+      { type: 'text', name: 'postgresPassword', message: 'Postgres password', initial: randomSecret().slice(0, 16) },
+      { type: 'text', name: 'redisPassword', message: 'Redis password', initial: randomSecret().slice(0, 16) },
+    );
+
+    const response = await prompts(questions);
+
+    if (!response.adminPassword) {
+      console.log(chalk.red('\n  Setup cancelled.'));
+      process.exit(1);
+    }
+
+    let envContent = '# Generated by slackhive init\n\n';
+    if (authMode.mode === 'apikey') {
+      envContent += `ANTHROPIC_API_KEY=${response.anthropicKey}\n`;
+    } else {
+      envContent += `# Claude Code subscription — OAuth credentials from keychain\n`;
+      envContent += `CLAUDE_CODE_OAUTH_TOKEN=${oauthCreds!.accessToken}\n`;
+      envContent += `CLAUDE_CODE_OAUTH_REFRESH_TOKEN=${oauthCreds!.refreshToken}\n`;
+    }
+    envContent += `\nPOSTGRES_DB=slackhive\n`;
+    envContent += `POSTGRES_USER=slackhive\n`;
+    envContent += `POSTGRES_PASSWORD=${response.postgresPassword}\n`;
+    envContent += `\nREDIS_PASSWORD=${response.redisPassword}\n`;
+    envContent += `\nADMIN_USERNAME=${response.adminUsername}\n`;
+    envContent += `ADMIN_PASSWORD=${response.adminPassword}\n`;
+    envContent += `AUTH_SECRET=${randomSecret()}\n`;
+    envContent += `ENV_SECRET_KEY=${randomSecret()}\n`;
+    envContent += `\nNODE_ENV=production\n`;
+
+    writeFileSync(envPath, envContent);
+    console.log('');
+    console.log(chalk.green('  ✓') + ' .env file created');
+    console.log('');
+  } else {
+    console.log(chalk.bold.hex('#D97757')('  [3/4]') + chalk.bold(' Configure environment'));
+    console.log('');
+    // Check if existing .env is missing required keys
+    const envContents = existsSync(envPath) ? require('fs').readFileSync(envPath, 'utf-8') : '';
+    const missingKeys: string[] = [];
+    if (!envContents.includes('REDIS_PASSWORD=')) missingKeys.push('REDIS_PASSWORD');
+    if (!envContents.includes('AUTH_SECRET=')) missingKeys.push('AUTH_SECRET');
+    if (!envContents.includes('ENV_SECRET_KEY=')) missingKeys.push('ENV_SECRET_KEY');
+    if (missingKeys.length > 0) {
+      console.log(chalk.yellow(`  warning: .env is missing: ${missingKeys.join(', ')} — patching...`));
+      let patch = '';
+      if (!envContents.includes('REDIS_PASSWORD=')) patch += `\nREDIS_PASSWORD=${randomSecret().slice(0, 16)}\n`;
+      if (!envContents.includes('AUTH_SECRET=')) patch += `AUTH_SECRET=${randomSecret()}\n`;
+      if (!envContents.includes('ENV_SECRET_KEY=')) patch += `ENV_SECRET_KEY=${randomSecret()}\n`;
+      require('fs').appendFileSync(envPath, patch);
+      console.log(chalk.green('  ✓') + ' .env patched');
+    } else {
+      console.log(chalk.yellow('  note: .env already exists — skipping configuration'));
+    }
+    console.log('');
+  }
+
+  // ── Step 4: Build & start ─────────────────────────────────────────────────
+  let webReady = true;
+  if (!opts.skipStart) {
+    console.log(chalk.bold.hex('#D97757')('  [4/4]') + chalk.bold(' Building & starting services'));
+    console.log(chalk.gray('  This takes 3–5 minutes on first run while Docker builds images.'));
+    console.log('');
+
+    // Pre-flight: check Docker has enough disk space (need ~3GB)
+    try {
+      const dfOut = execSync('docker system df --format "{{.Size}}"', { encoding: 'utf-8' });
+      void dfOut; // just checking it runs without error
+    } catch {
+      console.log(chalk.yellow('  note: Could not check Docker disk usage — continuing anyway'));
+    }
+
+    // Pre-flight: warn if low disk space on host
+    try {
+      const df = execSync('df -k . | tail -1', { encoding: 'utf-8' }).trim();
+      const available = parseInt(df.split(/\s+/)[3]);
+      if (!isNaN(available) && available < 3 * 1024 * 1024) {
+        console.log(chalk.yellow(`  warning: less than 3GB disk space available. Build may fail.`));
+        console.log('');
+      }
+    } catch { /* non-fatal */ }
+
+    // Remove stale Postgres volume only on fresh init — prevents password mismatch
+    // when credentials were just generated. Skip if .env already existed (re-run).
+    if (freshEnv) {
+      try {
+        execSync('docker compose down -v', { cwd: dir, stdio: 'ignore' });
+      } catch { /* non-fatal — may not exist yet */ }
+    }
+
+    const buildOk = await runDockerBuild(dir, opts.dir);
+
+    if (buildOk) {
+      // If containers didn't come up during build, retry once silently
+      try {
+        execSync('docker compose up -d', { cwd: dir, stdio: 'ignore' });
+      } catch { /* non-fatal */ }
+
+      // Wait for web UI — up to 3 minutes
+      const webSpinner = ora('  Waiting for web UI to be ready...').start();
+      let ready = false;
+      for (let i = 0; i < 60; i++) {
+        try {
+          execSync('curl -sf http://localhost:3001/login', { stdio: 'ignore' });
+          ready = true;
+          break;
+        } catch {
+          await sleep(3000);
+        }
+      }
+      if (ready) {
+        webSpinner.succeed('Web UI is ready');
+      } else {
+        webReady = false;
+        webSpinner.stopAndPersist({ symbol: ' ' });
+      }
+    } else {
+      webReady = false;
+    }
+  }
+
+  // ── Done ──────────────────────────────────────────────────────────────────
+  console.log('');
+  if (webReady) {
+    console.log('  ' + chalk.bgHex('#D97757').black.bold('  SlackHive is ready!  '));
+    console.log('');
+    console.log(`  ${chalk.bold('Open:')}   ${chalk.cyan('http://localhost:3001')}`);
+  } else {
+    console.log('  ' + chalk.bold('Setup complete!'));
+    console.log('');
+    console.log(chalk.gray('  Services are still starting. Once ready:'));
+    console.log(`  ${chalk.bold('Run:')}    ${chalk.cyan('slackhive start')}`);
+    console.log(`  ${chalk.bold('Open:')}   ${chalk.cyan('http://localhost:3001')}`);
+  }
+  console.log(`  ${chalk.bold('Dir:')}    ${chalk.gray(dir)}`);
+  console.log('');
+  console.log(chalk.gray('  Useful commands:'));
+  console.log(chalk.gray('    slackhive start    — Start services'));
+  console.log(chalk.gray('    slackhive stop     — Stop services'));
+  console.log(chalk.gray('    slackhive status   — Show container status'));
+  console.log(chalk.gray('    slackhive logs     — Tail runner logs'));
+  console.log(chalk.gray('    slackhive update   — Pull latest & rebuild'));
+  console.log('');
+}
+
+/**
+ * Runs `docker compose up -d --build`.
+ * Shows a single updating spinner line with the current build step.
+ * Docker's raw progress output is suppressed to keep the terminal clean.
+ */
+function runDockerBuild(cwd: string, displayDir: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const proc = spawn('docker', ['compose', '--progress', 'plain', 'up', '-d', '--build'], {
+      cwd,
+      env: { ...process.env },
+    });
+
+    const startTime = Date.now();
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    let frameIdx = 0;
+
+    // Phased progress tracking
+    const phases = [
+      { name: 'Installing system packages', weight: 10, pattern: /apk add|fetch.*APKINDEX/i },
+      { name: 'Installing npm dependencies', weight: 30, pattern: /npm ci|npm install|added \d+ packages/i },
+      { name: 'Compiling TypeScript',        weight: 10, pattern: /tsc|--skipLibCheck/i },
+      { name: 'Building web app',            weight: 30, pattern: /next build|next\.config/i },
+      { name: 'Creating containers',         weight: 10, pattern: /exporting to image|naming to|exporting layers/i },
+      { name: 'Starting services',           weight: 10, pattern: /Container .*(Starting|Started|Healthy|Created)/i },
+    ];
+    let currentPhase = 0;
+    let phaseStartTime = Date.now();
+
+    function getProgress(): number {
+      let pct = 0;
+      for (let i = 0; i < currentPhase; i++) pct += phases[i].weight;
+      // Add partial progress within current phase
+      if (currentPhase < phases.length) {
+        const elapsed = (Date.now() - phaseStartTime) / 1000;
+        const estimatedDuration = currentPhase === 1 ? 90 : currentPhase === 3 ? 100 : 30;
+        const partial = Math.min(0.9, elapsed / estimatedDuration);
+        pct += phases[currentPhase].weight * partial;
+      }
+      return Math.min(99, Math.round(pct));
+    }
+
+    function renderBar(): string {
+      const pct = getProgress();
+      const cols = process.stdout.columns || 80;
+      const barWidth = Math.min(20, Math.max(10, cols - 55));
+      const filled = Math.round((pct / 100) * barWidth);
+      const empty = barWidth - filled;
+      const bar = chalk.hex('#D97757')('█'.repeat(filled)) + chalk.gray('░'.repeat(empty));
+      const elapsed = Math.floor((Date.now() - startTime) / 1000);
+      const phaseName = currentPhase < phases.length ? phases[currentPhase].name : 'Finishing';
+      const frame = frames[frameIdx++ % frames.length];
+      const pctStr = String(pct).padStart(2);
+      return `  ${chalk.hex('#D97757')(frame)} ${bar} ${chalk.bold(pctStr + '%')} ${phaseName} ${chalk.gray('(' + elapsed + 's)')}`;
+    }
+
+    const spinnerInterval = setInterval(() => {
+      process.stdout.write(`\r\x1b[K${renderBar()}`);
+    }, 80);
+
+    let buf = '';
+    const errorLines: string[] = [];
+
+    const onData = (chunk: Buffer) => {
+      buf += chunk.toString().replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+      const lines = buf.split('\n');
+      buf = lines.pop() ?? '';
+      for (const raw of lines) {
+        const line = raw.trim();
+        if (!line) continue;
+
+        // Check if we've entered a new phase
+        for (let i = currentPhase + 1; i < phases.length; i++) {
+          if (phases[i].pattern.test(line)) {
+            // Print completed phases
+            const elapsed = Math.floor((Date.now() - phaseStartTime) / 1000);
+            process.stdout.write('\r\x1b[K');
+            console.log('  ' + chalk.green('✓') + ' ' + phases[currentPhase].name + chalk.gray(` (${elapsed}s)`));
+            // Skip intermediate phases
+            for (let j = currentPhase + 1; j < i; j++) {
+              console.log('  ' + chalk.green('✓') + ' ' + phases[j].name + chalk.gray(' (cached)'));
+            }
+            currentPhase = i;
+            phaseStartTime = Date.now();
+            break;
+          }
+        }
+
+        if (/error/i.test(line)) errorLines.push(line);
+      }
+    };
+
+    proc.stdout.on('data', onData);
+    proc.stderr.on('data', onData);
+
+    proc.on('close', (code) => {
+      clearInterval(spinnerInterval);
+      process.stdout.write('\r\x1b[K');
+
+      if (code === 0) {
+        // Print any remaining phases as done
+        const elapsed = Math.floor((Date.now() - phaseStartTime) / 1000);
+        if (currentPhase < phases.length) {
+          console.log('  ' + chalk.green('✓') + ' ' + phases[currentPhase].name + chalk.gray(` (${elapsed}s)`));
+          for (let j = currentPhase + 1; j < phases.length; j++) {
+            console.log('  ' + chalk.green('✓') + ' ' + phases[j].name);
+          }
+        }
+        console.log('');
+        console.log('  ' + chalk.green('✓') + chalk.bold(' All services started'));
+        resolve(true);
+        return;
+      }
+
+      console.log('  ' + chalk.red('✗') + ' Failed to start services');
+      console.log('');
+
+      const allErrors = errorLines.join('\n').toLowerCase();
+      if (allErrors.includes('no space left') || allErrors.includes('disk full')) {
+        console.log(chalk.yellow('  Cause: Docker is out of disk space.'));
+        console.log(chalk.gray('  Fix:   docker system prune -a'));
+      } else if (allErrors.includes('port is already allocated') || allErrors.includes('address already in use')) {
+        const portMatch = /bind for .+:(\d+)/.exec(allErrors);
+        const port = portMatch ? portMatch[1] : 'a required port';
+        console.log(chalk.yellow(`  Cause: Port ${port} is already in use.`));
+        console.log(chalk.gray(`  Fix:   stop the process on port ${port} and retry`));
+      } else if (allErrors.includes('permission denied') || allErrors.includes('unauthorized')) {
+        console.log(chalk.yellow('  Cause: Docker permission denied — is Docker Desktop running?'));
+      } else if (allErrors.includes('memory') || allErrors.includes('oom')) {
+        console.log(chalk.yellow('  Cause: Docker ran out of memory.'));
+        console.log(chalk.gray('  Fix:   increase Docker Desktop memory to 4GB+ in Settings → Resources'));
+      } else if (allErrors.includes('network') || allErrors.includes('timeout') || allErrors.includes('pull') || allErrors.includes('tls') || allErrors.includes('certificate')) {
+        console.log(chalk.yellow('  Cause: Network/TLS error — try restarting Docker Desktop.'));
+      } else if (errorLines.length > 0) {
+        console.log(chalk.gray('  Error details:'));
+        errorLines.slice(-5).forEach(l => console.log(chalk.red('    ' + l)));
+      }
+
+      console.log('');
+      console.log(chalk.gray(`  To retry: cd ${displayDir} && docker compose up -d --build`));
+      resolve(false);
+    });
+  });
+}
+
+function randomSecret(): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  let result = '';
+  for (let i = 0; i < 32; i++) result += chars.charAt(Math.floor(Math.random() * chars.length));
+  return result;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(r => setTimeout(r, ms));
+}

package/cli/src/commands/manage.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Management commands — start, stop, status, logs, update.
+ *
+ * All commands look for docker-compose.yml in the current directory
+ * or the `slackhive` subdirectory.
+ *
+ * @module cli/commands/manage
+ */
+
+import { execSync, spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+
+/**
+ * Finds the SlackHive project directory.
+ * Checks cwd first, then ./slackhive subdirectory.
+ *
+ * @returns {string} Path to the project directory.
+ */
+function findProjectDir(): string {
+  if (existsSync(join(process.cwd(), 'docker-compose.yml'))) {
+    return process.cwd();
+  }
+  const sub = join(process.cwd(), 'slackhive');
+  if (existsSync(join(sub, 'docker-compose.yml'))) {
+    return sub;
+  }
+  console.log(chalk.red('  Could not find SlackHive project.'));
+  console.log(chalk.gray('  Run this command from the SlackHive directory, or run `slackhive init` first.'));
+  process.exit(1);
+}
+
+/**
+ * Start all SlackHive services.
+ */
+export async function start(): Promise<void> {
+  const dir = findProjectDir();
+  const spinner = ora('Starting SlackHive services...').start();
+  try {
+    execSync('docker compose up -d', { cwd: dir, stdio: 'ignore' });
+    spinner.succeed('All services started');
+    console.log(chalk.gray('  Web UI: http://localhost:3001'));
+  } catch {
+    spinner.fail('Failed to start services');
+  }
+}
+
+/**
+ * Stop all SlackHive services.
+ */
+export async function stop(): Promise<void> {
+  const dir = findProjectDir();
+  const spinner = ora('Stopping SlackHive services...').start();
+  try {
+    execSync('docker compose stop', { cwd: dir, stdio: 'ignore' });
+    spinner.succeed('All services stopped');
+  } catch {
+    spinner.fail('Failed to stop services');
+  }
+}
+
+/**
+ * Show running SlackHive containers.
+ */
+export async function status(): Promise<void> {
+  const dir = findProjectDir();
+  try {
+    const output = execSync('docker compose ps', { cwd: dir, encoding: 'utf-8' });
+    console.log('');
+    console.log(chalk.bold('  SlackHive Status'));
+    console.log('');
+    console.log(output);
+  } catch {
+    console.log(chalk.red('  Failed to get status'));
+  }
+}
+
+/**
+ * Tail runner service logs.
+ */
+export async function logs(opts: { follow?: boolean }): Promise<void> {
+  const dir = findProjectDir();
+  const args = ['compose', 'logs', 'runner'];
+  if (opts.follow !== false) args.push('-f');
+
+  const proc = spawn('docker', args, { cwd: dir, stdio: 'inherit' });
+  proc.on('error', () => console.log(chalk.red('  Failed to tail logs')));
+}
+
+/**
+ * Pull latest changes and rebuild.
+ */
+export async function update(): Promise<void> {
+  const dir = findProjectDir();
+
+  const pullSpinner = ora('Pulling latest changes...').start();
+  try {
+    execSync('git pull', { cwd: dir, stdio: 'ignore' });
+    pullSpinner.succeed('Code updated');
+  } catch {
+    pullSpinner.fail('Failed to pull — do you have uncommitted changes?');
+    return;
+  }
+
+  const buildSpinner = ora('Rebuilding services (this may take a minute)...').start();
+  try {
+    execSync('docker compose up -d --build', { cwd: dir, stdio: 'ignore', timeout: 600000 });
+    buildSpinner.succeed('Services rebuilt and restarted');
+    console.log(chalk.gray('  Web UI: http://localhost:3001'));
+  } catch {
+    buildSpinner.fail('Failed to rebuild');
+  }
+}

package/cli/src/index.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview SlackHive CLI — install, configure, and manage SlackHive.
+ *
+ * Commands:
+ *   slackhive init     — Clone repo, configure .env, start services
+ *   slackhive start    — Start all Docker Compose services
+ *   slackhive stop     — Stop all services
+ *   slackhive status   — Show running containers
+ *   slackhive logs     — Tail runner logs
+ *   slackhive update   — Pull latest changes and rebuild
+ *
+ * @module cli
+ */
+
+import { Command } from 'commander';
+import { init } from './commands/init';
+import { start, stop, status, logs, update } from './commands/manage';
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { version } = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('slackhive')
+  .description('CLI to install and manage SlackHive — AI agent teams on Slack')
+  .version(version);
+
+program
+  .command('init')
+  .description('Clone SlackHive repo, configure environment, and start services')
+  .option('-d, --dir <path>', 'Directory to install into', 'slackhive')
+  .option('--skip-start', 'Skip starting services after init')
+  .action(init);
+
+program
+  .command('start')
+  .description('Start all SlackHive services')
+  .action(start);
+
+program
+  .command('stop')
+  .description('Stop all SlackHive services')
+  .action(stop);
+
+program
+  .command('status')
+  .description('Show running SlackHive containers')
+  .action(status);
+
+program
+  .command('logs')
+  .description('Tail runner service logs')
+  .option('-f, --follow', 'Follow log output', true)
+  .action(logs);
+
+program
+  .command('update')
+  .description('Pull latest changes and rebuild')
+  .action(update);
+
+program.parse(process.argv);