@yemi33/squad 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 yemi33
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 yemi33
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/TODO.md

@@ -6,21 +6,21 @@ Ordered by difficulty: quick wins first, larger efforts later.
 
 ## Quick Wins (< 1 hour each)
 
-- [ ] **Output.log append, not overwrite** — keep all dispatch outputs, not just the last one. Rotate by dispatch ID.
-- [ ] **Persistent cooldowns** — save cooldown state to disk so engine restarts don't re-dispatch everything
-- [ ] **Worktree cleanup on merge/close** — when `pollPrStatus` detects a PR merged or abandoned, auto-remove its worktree. Currently only `runCleanup` catches old worktrees on a timer.
-- [ ] **Discovery skip logging** — log why items were skipped during discovery (cooldown, already dispatched, no idle agent) so users can diagnose "why isn't my work item being picked up?"
-- [ ] **Idle threshold alert** — if all agents are idle for >N minutes, notify via Teams/dashboard
-- [ ] **Config validation at startup** — verify all project paths exist, all agents defined, all playbooks exist. Fail fast with clear errors instead of silently skipping.
-- [ ] **macOS/Linux browser launch** — replace Windows `start` command with `open` (macOS) / `xdg-open` (Linux)
-- [ ] **Health check endpoint** — `/api/health` returning engine state, project reachability, agent statuses for monitoring
-- [ ] **Fan-out per-agent timeout** — when `@everyone` dispatches, set individual deadlines per agent instead of relying only on global `agentTimeout`
+- [x] **Output.log append, not overwrite** — per-dispatch archive at `output-{id}.log` + latest copy at `output.log`
+- [x] **Persistent cooldowns** — saved to `engine/cooldowns.json`, loaded at startup, 24hr auto-prune
+- [x] **Worktree cleanup on merge/close** — `handlePostMerge` removes worktrees when PR merges or is abandoned
+- [x] **Discovery skip logging** — PRD and work item discovery log skip counts by reason at debug level
+- [x] **Idle threshold alert** — warns when all agents idle >15min (configurable via `engine.idleAlertMinutes`)
+- [x] **Config validation at startup** — checks agents, project paths, playbooks, routing.md. Fatal errors exit(1).
+- [x] **macOS/Linux browser launch** — already platform-aware (was done previously)
+- [x] **Health check endpoint** — `GET /api/health` returning engine state, agents, project reachability, uptime
+- [x] **Fan-out per-agent timeout** — fan-out items carry `meta.deadline`, configurable via `engine.fanOutTimeout`
 
 ## Small Effort (1–3 hours each)
 
 - [ ] **Auto-retry with backoff** — when an agent errors, auto-retry with exponential backoff (5min, 15min, cap at 3 attempts) instead of requiring manual dashboard retry.
 - [ ] **Auto-escalation** — if an agent errors 3 times in a row, pause their dispatch and alert via dashboard/Teams
-- [ ] **Post-merge hooks** — when a PR merges, trigger configurable actions: clean up worktree, update PRD item status to `done`, notify Teams, update metrics
+- [x] **Post-merge hooks** — `handlePostMerge`: worktree cleanup, PRD status → implemented, prsMerged metric, Teams notification
 - [ ] **Pending dispatch explanation** — show in dashboard why each pending item hasn't been dispatched (no idle agent? cooldown? max concurrency?)
 - [ ] **Work item editing** — edit title, description, type, priority, agent assignment from the dashboard UI (currently requires editing JSON)
 - [ ] **Bulk operations** — retry/delete/reassign multiple work items at once

package/bin/squad.js

@@ -1,164 +1,164 @@
-#!/usr/bin/env node
-/**
- * Squad CLI — Central AI dev team manager
- *
- * Usage:
- *   squad init                     Bootstrap ~/.squad/ with default config and agents
- *   squad add <project-dir>        Link a project (interactive)
- *   squad remove <project-dir>     Unlink a project
- *   squad list                     List linked projects
- *   squad start                    Start the engine
- *   squad stop                     Stop the engine
- *   squad status                   Show engine status
- *   squad pause / resume           Pause/resume dispatching
- *   squad dash                     Start the dashboard
- *   squad work <title> [opts-json] Add a work item
- *   squad spawn <agent> <prompt>   Manually spawn an agent
- *   squad dispatch                 Force a dispatch cycle
- *   squad discover                 Dry-run work discovery
- *   squad cleanup                  Run cleanup manually
- *   squad plan <file|text> [proj]  Run a plan
- */
-
-const fs = require('fs');
-const path = require('path');
-const { spawn, execSync } = require('child_process');
-
-const SQUAD_HOME = path.join(require('os').homedir(), '.squad');
-const PKG_ROOT = path.resolve(__dirname, '..');
-
-const [cmd, ...rest] = process.argv.slice(2);
-
-// ─── Init: bootstrap ~/.squad/ from package templates ───────────────────────
-
-function init() {
-  if (fs.existsSync(path.join(SQUAD_HOME, 'engine.js'))) {
-    console.log(`\n  Squad already installed at ${SQUAD_HOME}`);
-    console.log('  To reinitialize config: squad init --force\n');
-    if (!rest.includes('--force')) return;
-  }
-
-  console.log(`\n  Bootstrapping Squad to ${SQUAD_HOME}...\n`);
-  fs.mkdirSync(SQUAD_HOME, { recursive: true });
-
-  // Copy all package files to ~/.squad/
-  const exclude = new Set([
-    'bin', 'node_modules', '.git', '.claude', 'package.json',
-    'package-lock.json', 'LICENSE', '.npmignore', '.gitignore',
-  ]);
-
-  copyDir(PKG_ROOT, SQUAD_HOME, exclude);
-
-  // Create config from template if it doesn't exist
-  const configPath = path.join(SQUAD_HOME, 'config.json');
-  if (!fs.existsSync(configPath)) {
-    const tmpl = path.join(SQUAD_HOME, 'config.template.json');
-    if (fs.existsSync(tmpl)) {
-      fs.copyFileSync(tmpl, configPath);
-    }
-  }
-
-  // Ensure runtime directories exist
-  const dirs = [
-    'engine', 'notes/inbox', 'notes/archive',
-    'identity', 'plans',
-  ];
-  for (const d of dirs) {
-    fs.mkdirSync(path.join(SQUAD_HOME, d), { recursive: true });
-  }
-
-  // Run squad.js init to populate config with defaults
-  execSync(`node "${path.join(SQUAD_HOME, 'squad.js')}" init`, { stdio: 'inherit' });
-
-  console.log('\n  Next steps:');
-  console.log('    squad add ~/my-project    Link your first project');
-  console.log('    squad start               Start the engine');
-  console.log('    squad dash                Open the dashboard\n');
-}
-
-function copyDir(src, dest, exclude) {
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  for (const entry of entries) {
-    if (exclude.has(entry.name)) continue;
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      fs.mkdirSync(destPath, { recursive: true });
-      copyDir(srcPath, destPath, new Set()); // only exclude at top level
-    } else {
-      // Don't overwrite user-modified files (except on --force)
-      if (fs.existsSync(destPath) && !rest.includes('--force')) {
-        // Always update engine code files
-        if (!entry.name.endsWith('.js') && !entry.name.endsWith('.html')) continue;
-      }
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
-// ─── Delegate: run commands against installed ~/.squad/ ─────────────────────
-
-function ensureInstalled() {
-  if (!fs.existsSync(path.join(SQUAD_HOME, 'engine.js'))) {
-    console.log('\n  Squad is not installed. Run: squad init\n');
-    process.exit(1);
-  }
-}
-
-function delegate(script, args) {
-  ensureInstalled();
-  const child = spawn(process.execPath, [path.join(SQUAD_HOME, script), ...args], {
-    stdio: 'inherit',
-    cwd: SQUAD_HOME,
-  });
-  child.on('exit', code => process.exit(code || 0));
-}
-
-// ─── Command routing ────────────────────────────────────────────────────────
-
-const engineCmds = new Set([
-  'start', 'stop', 'status', 'pause', 'resume',
-  'queue', 'sources', 'discover', 'dispatch',
-  'spawn', 'work', 'cleanup', 'mcp-sync', 'plan',
-]);
-
-if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
-  console.log(`
-  Squad — Central AI dev team manager
-
-  Setup:
-    squad init                     Bootstrap ~/.squad/ (first time)
-    squad add <project-dir>        Link a project (interactive)
-    squad remove <project-dir>     Unlink a project
-    squad list                     List linked projects
-
-  Engine:
-    squad start                    Start engine daemon
-    squad stop                     Stop the engine
-    squad status                   Show agents, projects, queue
-    squad pause / resume           Pause/resume dispatching
-    squad dispatch                 Force a dispatch cycle
-    squad discover                 Dry-run work discovery
-    squad work <title> [opts]      Add a work item
-    squad spawn <agent> <prompt>   Manually spawn an agent
-    squad plan <file|text> [proj]  Run a plan
-    squad cleanup                  Clean temp files, worktrees, zombies
-
-  Dashboard:
-    squad dash                     Start web dashboard (default :7331)
-
-  Home: ${SQUAD_HOME}
-`);
-} else if (cmd === 'init') {
-  init();
-} else if (cmd === 'add' || cmd === 'remove' || cmd === 'list') {
-  delegate('squad.js', [cmd, ...rest]);
-} else if (cmd === 'dash' || cmd === 'dashboard') {
-  delegate('dashboard.js', rest);
-} else if (engineCmds.has(cmd)) {
-  delegate('engine.js', [cmd, ...rest]);
-} else {
-  console.log(`  Unknown command: ${cmd}`);
-  console.log('  Run "squad help" for usage.\n');
-  process.exit(1);
-}
+#!/usr/bin/env node
+/**
+ * Squad CLI — Central AI dev team manager
+ *
+ * Usage:
+ *   squad init                     Bootstrap ~/.squad/ with default config and agents
+ *   squad add <project-dir>        Link a project (interactive)
+ *   squad remove <project-dir>     Unlink a project
+ *   squad list                     List linked projects
+ *   squad start                    Start the engine
+ *   squad stop                     Stop the engine
+ *   squad status                   Show engine status
+ *   squad pause / resume           Pause/resume dispatching
+ *   squad dash                     Start the dashboard
+ *   squad work <title> [opts-json] Add a work item
+ *   squad spawn <agent> <prompt>   Manually spawn an agent
+ *   squad dispatch                 Force a dispatch cycle
+ *   squad discover                 Dry-run work discovery
+ *   squad cleanup                  Run cleanup manually
+ *   squad plan <file|text> [proj]  Run a plan
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn, execSync } = require('child_process');
+
+const SQUAD_HOME = path.join(require('os').homedir(), '.squad');
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+// ─── Init: bootstrap ~/.squad/ from package templates ───────────────────────
+
+function init() {
+  if (fs.existsSync(path.join(SQUAD_HOME, 'engine.js'))) {
+    console.log(`\n  Squad already installed at ${SQUAD_HOME}`);
+    console.log('  To reinitialize config: squad init --force\n');
+    if (!rest.includes('--force')) return;
+  }
+
+  console.log(`\n  Bootstrapping Squad to ${SQUAD_HOME}...\n`);
+  fs.mkdirSync(SQUAD_HOME, { recursive: true });
+
+  // Copy all package files to ~/.squad/
+  const exclude = new Set([
+    'bin', 'node_modules', '.git', '.claude', 'package.json',
+    'package-lock.json', 'LICENSE', '.npmignore', '.gitignore',
+  ]);
+
+  copyDir(PKG_ROOT, SQUAD_HOME, exclude);
+
+  // Create config from template if it doesn't exist
+  const configPath = path.join(SQUAD_HOME, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    const tmpl = path.join(SQUAD_HOME, 'config.template.json');
+    if (fs.existsSync(tmpl)) {
+      fs.copyFileSync(tmpl, configPath);
+    }
+  }
+
+  // Ensure runtime directories exist
+  const dirs = [
+    'engine', 'notes/inbox', 'notes/archive',
+    'identity', 'plans',
+  ];
+  for (const d of dirs) {
+    fs.mkdirSync(path.join(SQUAD_HOME, d), { recursive: true });
+  }
+
+  // Run squad.js init to populate config with defaults
+  execSync(`node "${path.join(SQUAD_HOME, 'squad.js')}" init`, { stdio: 'inherit' });
+
+  console.log('\n  Next steps:');
+  console.log('    squad add ~/my-project    Link your first project');
+  console.log('    squad start               Start the engine');
+  console.log('    squad dash                Open the dashboard\n');
+}
+
+function copyDir(src, dest, exclude) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (exclude.has(entry.name)) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDir(srcPath, destPath, new Set()); // only exclude at top level
+    } else {
+      // Don't overwrite user-modified files (except on --force)
+      if (fs.existsSync(destPath) && !rest.includes('--force')) {
+        // Always update engine code files
+        if (!entry.name.endsWith('.js') && !entry.name.endsWith('.html')) continue;
+      }
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// ─── Delegate: run commands against installed ~/.squad/ ─────────────────────
+
+function ensureInstalled() {
+  if (!fs.existsSync(path.join(SQUAD_HOME, 'engine.js'))) {
+    console.log('\n  Squad is not installed. Run: squad init\n');
+    process.exit(1);
+  }
+}
+
+function delegate(script, args) {
+  ensureInstalled();
+  const child = spawn(process.execPath, [path.join(SQUAD_HOME, script), ...args], {
+    stdio: 'inherit',
+    cwd: SQUAD_HOME,
+  });
+  child.on('exit', code => process.exit(code || 0));
+}
+
+// ─── Command routing ────────────────────────────────────────────────────────
+
+const engineCmds = new Set([
+  'start', 'stop', 'status', 'pause', 'resume',
+  'queue', 'sources', 'discover', 'dispatch',
+  'spawn', 'work', 'cleanup', 'mcp-sync', 'plan',
+]);
+
+if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(`
+  Squad — Central AI dev team manager
+
+  Setup:
+    squad init                     Bootstrap ~/.squad/ (first time)
+    squad add <project-dir>        Link a project (interactive)
+    squad remove <project-dir>     Unlink a project
+    squad list                     List linked projects
+
+  Engine:
+    squad start                    Start engine daemon
+    squad stop                     Stop the engine
+    squad status                   Show agents, projects, queue
+    squad pause / resume           Pause/resume dispatching
+    squad dispatch                 Force a dispatch cycle
+    squad discover                 Dry-run work discovery
+    squad work <title> [opts]      Add a work item
+    squad spawn <agent> <prompt>   Manually spawn an agent
+    squad plan <file|text> [proj]  Run a plan
+    squad cleanup                  Clean temp files, worktrees, zombies
+
+  Dashboard:
+    squad dash                     Start web dashboard (default :7331)
+
+  Home: ${SQUAD_HOME}
+`);
+} else if (cmd === 'init') {
+  init();
+} else if (cmd === 'add' || cmd === 'remove' || cmd === 'list') {
+  delegate('squad.js', [cmd, ...rest]);
+} else if (cmd === 'dash' || cmd === 'dashboard') {
+  delegate('dashboard.js', rest);
+} else if (engineCmds.has(cmd)) {
+  delegate('engine.js', [cmd, ...rest]);
+} else {
+  console.log(`  Unknown command: ${cmd}`);
+  console.log('  Run "squad help" for usage.\n');
+  process.exit(1);
+}