claude-capsule-kit 3.0.0

package/crew/lib/crew-config-reader.js

@@ -0,0 +1,255 @@
+/**
+ * Crew Config Reader - Load, validate, hash, and resolve .crew-config.json
+ *
+ * Supports two config formats:
+ * - Old: { team: {...}, project: {...} }
+ * - New: { profiles: { dev: {...}, review: {...} }, default: "dev", project: {...} }
+ *
+ * Old format auto-normalizes at resolve time (no file rewrite needed).
+ */
+
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { createHash } from 'crypto';
+import { ROLE_PRESETS } from './role-presets.js';
+
+/**
+ * Load .crew-config.json from project root.
+ * @param {string} projectRoot - Path to project root
+ * @returns {object} Parsed config
+ * @throws {Error} If file not found or invalid JSON
+ */
+export function loadCrewConfig(projectRoot) {
+  const configPath = resolve(projectRoot, '.crew-config.json');
+  const raw = readFileSync(configPath, 'utf-8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Compute a short hash of the config for change detection.
+ * @param {object} configObj - Config object to hash
+ * @returns {string} 12-char hex hash
+ */
+export function hashConfig(configObj) {
+  return createHash('sha256')
+    .update(JSON.stringify(configObj))
+    .digest('hex')
+    .slice(0, 12);
+}
+
+/**
+ * Resolve which profile to use from a config.
+ *
+ * Old format ({ team }) → returns { profile: config.team, profileName: 'default' }
+ * New format ({ profiles }) → looks up requestedName || config.default || first key
+ *
+ * @param {object} config - Parsed .crew-config.json
+ * @param {string} [requestedName] - Profile name from CLI arg
+ * @returns {{ profile: object, profileName: string }}
+ * @throws {Error} If profile not found
+ */
+export function resolveProfile(config, requestedName) {
+  // Old format — single team
+  if (config.team && !config.profiles) {
+    return { profile: config.team, profileName: 'default' };
+  }
+
+  // New format — multiple profiles
+  if (!config.profiles || typeof config.profiles !== 'object') {
+    throw new Error('Config must have either "team" or "profiles" section');
+  }
+
+  const profileNames = Object.keys(config.profiles);
+  if (profileNames.length === 0) {
+    throw new Error('No profiles defined in config');
+  }
+
+  const name = requestedName || config.default || profileNames[0];
+  const profile = config.profiles[name];
+
+  if (!profile) {
+    throw new Error(
+      `Profile "${name}" not found. Available: ${profileNames.join(', ')}`
+    );
+  }
+
+  return { profile, profileName: name };
+}
+
+/**
+ * Resolve teammates from a team/profile config.
+ * Supports two formats:
+ * - Flat: { teammates: [...] } — backward compatible
+ * - Grouped: { crews: [{ name, teammates: [...] }] } — crew grouping
+ *
+ * Returns a flat array of teammates with `crew` property set on each.
+ * When using flat format, crew defaults to 'default'.
+ *
+ * @param {object} teamOrProfile - Team or profile object
+ * @param {string} [filterCrew] - Optional crew name to filter by
+ * @returns {object[]} Flat array of teammates with crew metadata
+ */
+export function resolveTeammates(teamOrProfile, filterCrew) {
+  let teammates = [];
+
+  if (teamOrProfile.crews && Array.isArray(teamOrProfile.crews)) {
+    // Grouped format: flatten crews into teammates with crew metadata
+    for (const crew of teamOrProfile.crews) {
+      for (const mate of crew.teammates || []) {
+        teammates.push({ ...mate, crew: crew.name });
+      }
+    }
+  } else if (teamOrProfile.teammates && Array.isArray(teamOrProfile.teammates)) {
+    // Flat format: assign 'default' crew
+    teammates = teamOrProfile.teammates.map(m => ({ ...m, crew: m.crew || 'default' }));
+  }
+
+  // Filter by crew if requested
+  if (filterCrew) {
+    teammates = teammates.filter(m => m.crew === filterCrew);
+  }
+
+  return teammates;
+}
+
+/**
+ * List crew names from a team/profile config.
+ * @param {object} teamOrProfile - Team or profile object
+ * @returns {string[]} Array of crew names
+ */
+export function listCrews(teamOrProfile) {
+  if (teamOrProfile.crews && Array.isArray(teamOrProfile.crews)) {
+    return teamOrProfile.crews.map(c => c.name);
+  }
+  return ['default'];
+}
+
+/**
+ * Validate a crew config. Returns array of error strings (empty = valid).
+ * Handles both old format (team) and new format (profiles).
+ * @param {object} config - Config to validate
+ * @returns {string[]} Array of validation errors
+ */
+export function validateConfig(config) {
+  const errors = [];
+
+  // Detect format
+  if (config.profiles) {
+    // New multi-profile format
+    if (typeof config.profiles !== 'object' || Array.isArray(config.profiles)) {
+      errors.push('"profiles" must be an object');
+      return errors;
+    }
+
+    const profileNames = Object.keys(config.profiles);
+    if (profileNames.length === 0) {
+      errors.push('"profiles" must contain at least one profile');
+      return errors;
+    }
+
+    if (config.default && !config.profiles[config.default]) {
+      errors.push(`"default" profile "${config.default}" does not exist in profiles`);
+    }
+
+    for (const pName of profileNames) {
+      const profile = config.profiles[pName];
+      const pfx = `profiles.${pName}`;
+      errors.push(...validateTeam(profile, pfx));
+    }
+  } else if (config.team) {
+    // Old single-team format
+    errors.push(...validateTeam(config.team, 'team'));
+  } else {
+    errors.push('Missing "team" or "profiles" section');
+  }
+
+  return errors;
+}
+
+/**
+ * Validate a single team object (used for both old and new format).
+ * @param {object} team - Team object with name, teammates[]
+ * @param {string} prefix - Error prefix (e.g. "team" or "profiles.dev")
+ * @returns {string[]} Validation errors
+ */
+function validateTeam(team, prefix) {
+  const errors = [];
+
+  if (!team.name || typeof team.name !== 'string') {
+    errors.push(`${prefix}.name is required and must be a string`);
+  }
+
+  // Support both flat teammates and crews grouping
+  if (team.crews && Array.isArray(team.crews)) {
+    if (team.crews.length === 0) {
+      errors.push(`${prefix}.crews must be a non-empty array`);
+      return errors;
+    }
+    for (let c = 0; c < team.crews.length; c++) {
+      const crew = team.crews[c];
+      if (!crew.name || typeof crew.name !== 'string') {
+        errors.push(`${prefix}.crews[${c}]: name is required`);
+      }
+      if (!Array.isArray(crew.teammates) || crew.teammates.length === 0) {
+        errors.push(`${prefix}.crews[${c}].teammates must be a non-empty array`);
+        continue;
+      }
+      for (let i = 0; i < crew.teammates.length; i++) {
+        const t = crew.teammates[i];
+        if (!t.name || typeof t.name !== 'string') {
+          errors.push(`${prefix}.crews[${c}].teammate[${i}]: name is required`);
+        }
+        if (!t.branch || typeof t.branch !== 'string') {
+          errors.push(`${prefix}.crews[${c}].teammate[${i}]: branch is required`);
+        }
+        if (t.role && !ROLE_PRESETS[t.role]) {
+          errors.push(
+            `${prefix}.crews[${c}].teammate[${i}]: unknown role "${t.role}". Valid: ${Object.keys(ROLE_PRESETS).join(', ')}`
+          );
+        }
+      }
+    }
+  } else if (Array.isArray(team.teammates)) {
+    if (team.teammates.length === 0) {
+      errors.push(`${prefix}.teammates must be a non-empty array`);
+      return errors;
+    }
+    for (let i = 0; i < team.teammates.length; i++) {
+      const t = team.teammates[i];
+      if (!t.name || typeof t.name !== 'string') {
+        errors.push(`${prefix}.teammate[${i}]: name is required`);
+      }
+      if (!t.branch || typeof t.branch !== 'string') {
+        errors.push(`${prefix}.teammate[${i}]: branch is required`);
+      }
+      if (t.role && !ROLE_PRESETS[t.role]) {
+        errors.push(
+          `${prefix}.teammate[${i}]: unknown role "${t.role}". Valid: ${Object.keys(ROLE_PRESETS).join(', ')}`
+        );
+      }
+    }
+  } else {
+    errors.push(`${prefix} must have either "teammates" or "crews" array`);
+  }
+
+  return errors;
+}
+
+/**
+ * Resolve the worktree path for a teammate branch.
+ * Convention:
+ *   default profile: {projectRoot}-{sanitized-branch}
+ *   named profile:   {projectRoot}-{profileName}-{sanitized-branch}
+ *
+ * @param {string} projectRoot - Path to main project
+ * @param {string} branch - Git branch name
+ * @param {string} [profileName] - Profile name (null/'default' = no prefix)
+ * @returns {string} Absolute path for worktree
+ */
+export function resolveWorktreePath(projectRoot, branch, profileName) {
+  const sanitized = branch.replace(/\//g, '--');
+  if (!profileName || profileName === 'default') {
+    return `${projectRoot}-${sanitized}`;
+  }
+  return `${projectRoot}-${profileName}-${sanitized}`;
+}

package/crew/lib/health-monitor.js

@@ -0,0 +1,171 @@
+/**
+ * Crew Health Monitor - Detect crashed/hung teammates
+ *
+ * Checks teammate health by examining:
+ * 1. last_active timestamps in team-state.json
+ * 2. Recent git commits in worktrees
+ * 3. Configurable staleness threshold
+ */
+
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { loadTeamState } from './team-state-manager.js';
+
+/**
+ * Health status values:
+ * - active: Updated recently (within threshold)
+ * - idle: No recent updates but not yet stale
+ * - unresponsive: Stale beyond threshold, may be hung
+ * - crashed: Worktree exists but no activity and very stale
+ */
+
+/**
+ * Check health of all teammates in a crew profile.
+ * @param {string} projectHash - 12-char project hash
+ * @param {string} profileName - Profile name
+ * @param {object} options - Health check options
+ * @param {number} [options.staleThresholdMinutes=10] - Minutes before teammate is considered stale
+ * @param {number} [options.commitWindowMinutes=30] - Window for checking recent commits
+ * @returns {Array<object>} Array of teammate health reports
+ */
+export function checkHealth(projectHash, profileName, options = {}) {
+  const staleThresholdMinutes = options.staleThresholdMinutes || 10;
+  const commitWindowMinutes = options.commitWindowMinutes || 30;
+
+  const state = loadTeamState(projectHash, profileName);
+  if (!state || !state.teammates) {
+    return [];
+  }
+
+  const staleThresholdMs = staleThresholdMinutes * 60 * 1000;
+  const now = Date.now();
+  const results = [];
+
+  for (const [name, mate] of Object.entries(state.teammates)) {
+    const report = {
+      name,
+      branch: mate.branch,
+      status: mate.status || 'unknown',
+      lastActive: mate.last_active || null,
+      worktreePath: mate.worktree_path || null,
+      recentCommits: 0,
+      health: 'unknown'
+    };
+
+    // Calculate age of last activity
+    let ageMs = null;
+    if (mate.last_active) {
+      ageMs = now - new Date(mate.last_active).getTime();
+    }
+
+    // Check for recent commits in worktree
+    if (mate.worktree_path && existsSync(mate.worktree_path)) {
+      try {
+        const sinceTime = `${commitWindowMinutes} minutes ago`;
+        const output = execSync(
+          `git -C "${mate.worktree_path}" log --oneline --since="${sinceTime}"`,
+          { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+        );
+        report.recentCommits = output.trim().split('\n').filter(line => line.length > 0).length;
+      } catch {
+        report.recentCommits = 0;
+      }
+    }
+
+    // Determine health status
+    if (!mate.last_active) {
+      report.health = 'unresponsive';
+    } else if (ageMs < staleThresholdMs) {
+      report.health = 'active';
+    } else if (ageMs < staleThresholdMs * 2) {
+      // Between threshold and 2x threshold: idle
+      report.health = 'idle';
+    } else if (mate.worktree_path && existsSync(mate.worktree_path) && report.recentCommits === 0) {
+      // Very stale and no recent commits: likely crashed
+      report.health = 'crashed';
+    } else {
+      report.health = 'unresponsive';
+    }
+
+    results.push(report);
+  }
+
+  return results;
+}
+
+/**
+ * Format health report as human-readable text.
+ * @param {Array<object>} healthReports - Array from checkHealth()
+ * @returns {string} Formatted report text
+ */
+export function formatHealthReport(healthReports) {
+  if (healthReports.length === 0) {
+    return 'No teammates found.';
+  }
+
+  const lines = [];
+  lines.push('Crew Health Report');
+  lines.push('─'.repeat(100));
+  lines.push(
+    '  Name'.padEnd(22) +
+    'Branch'.padEnd(32) +
+    'Health'.padEnd(14) +
+    'Last Active'.padEnd(22) +
+    'Commits (30m)'
+  );
+  lines.push('─'.repeat(100));
+
+  for (const report of healthReports) {
+    const healthIcon = {
+      active: '✓',
+      idle: '○',
+      unresponsive: '⚠',
+      crashed: '✗',
+      unknown: '?'
+    }[report.health] || '?';
+
+    const healthLabel = `${healthIcon} ${report.health}`;
+    const lastActive = report.lastActive
+      ? formatAge(new Date(report.lastActive))
+      : 'never';
+
+    lines.push(
+      `  ${report.name.padEnd(20)}${report.branch.padEnd(32)}${healthLabel.padEnd(14)}${lastActive.padEnd(22)}${report.recentCommits}`
+    );
+  }
+
+  lines.push('');
+
+  // Add recovery steps for unhealthy teammates
+  const unhealthy = healthReports.filter(r => r.health === 'crashed' || r.health === 'unresponsive');
+  if (unhealthy.length > 0) {
+    lines.push('Recovery Steps:');
+    lines.push('─'.repeat(100));
+    for (const report of unhealthy) {
+      lines.push(`\n${report.name} (${report.health}):`);
+      lines.push(`  1. Check worktree status: git -C "${report.worktreePath}" status`);
+      lines.push(`  2. Check recent commits: git -C "${report.worktreePath}" log --oneline -5`);
+      lines.push(`  3. If crashed, re-spawn the teammate using the stored spawn prompt`);
+      lines.push(`  4. If unresponsive, send a message: SendMessage(type="message", recipient="${report.name}", ...)`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format time age as human-readable string.
+ * @param {Date} timestamp - Timestamp to format
+ * @returns {string} Age string like "5m ago", "2h ago"
+ */
+function formatAge(timestamp) {
+  const ageMs = Date.now() - timestamp.getTime();
+  const ageMinutes = Math.floor(ageMs / 60000);
+  const ageHours = Math.floor(ageMs / 3600000);
+  const ageDays = Math.floor(ageMs / 86400000);
+
+  if (ageDays > 0) return `${ageDays}d ago`;
+  if (ageHours > 0) return `${ageHours}h ago`;
+  if (ageMinutes > 0) return `${ageMinutes}m ago`;
+  return 'just now';
+}