@matt82198/aesop 0.1.0-beta.5 → 0.1.0-rc.1

package/bin/cli.js

@@ -11,6 +11,24 @@ const helpFlag = args.includes('--help') || args.includes('-h');
 const forceFlag = args.includes('--force');
 const yesFlag = args.includes('--yes');
 
+// Check for runtime subcommands (doctor, watch, dash, status)
+const runtimeCommands = ['doctor', 'watch', 'dash', 'status'];
+const isRuntimeCommand = runtimeCommands.includes(args[0]);
+
+if (isRuntimeCommand) {
+  const commandMap = {
+    'doctor': '../tools/doctor.js',
+    'watch': '../tools/watch.js',
+    'dash': '../tools/dash.js',
+    'status': '../tools/status.js'
+  };
+  // Load and run the appropriate runtime module
+  // These modules run async code that sets process.exitCode and will cause Node to exit
+  require(commandMap[args[0]]);
+  // Return immediately to prevent further CLI scaffolding logic from running
+  return;
+}
+
 // Detect if stdin is a TTY (interactive terminal)
 function isInteractive() {
   return process.stdin.isTTY && process.stdout.isTTY;
@@ -69,8 +87,16 @@ aesop — Multi-agent orchestration template scaffolder
 Usage:
   npx @matt82198/aesop [target-dir] [options]
   npx @matt82198/aesop wizard [options]
+  npx @matt82198/aesop doctor
+  npx @matt82198/aesop watch
+  npx @matt82198/aesop dash
+  npx @matt82198/aesop status
 
 Commands:
+  doctor                  Preflight readiness check (Node.js, Python, git, config, dirs, hook, port)
+  watch                   Launch the watchdog daemon (spawns daemons/run-watchdog.sh)
+  dash                    Launch the web dashboard (spawns python3 ui/serve.py or python fallback)
+  status                  One-shot fleet status snapshot (heartbeats, dashboard port, git branch)
   wizard                  Interactive onboarding (prompts for project name, repos, port)
 
 Arguments:
@@ -83,8 +109,13 @@ Options:
   --name <name>           Project name (for headless scaffolding; generates CLAUDE.md + aesop.config.json)
   --domains <list>        Comma-separated domain list (e.g., "api,worker,monitoring")
   --repos <paths>         Comma-separated repo paths (e.g., "/path/to/repo1,/path/to/repo2")
+  --repo-urls <urls>      Comma-separated repo URLs (e.g., "https://github.com/user/repo1.git,https://github.com/user/repo2.git")
 
 Examples:
+  npx @matt82198/aesop doctor                               # Run preflight checks before starting
+  npx @matt82198/aesop watch                                # Launch watchdog daemon
+  npx @matt82198/aesop dash                                 # Launch web dashboard (default localhost:8770)
+  npx @matt82198/aesop status                               # Show fleet status (heartbeats, port, git)
   npx @matt82198/aesop                                      # Creates ./aesop-fleet/ with template
   npx @matt82198/aesop my-fleet                             # Creates ./my-fleet/ with template
   npx @matt82198/aesop wizard                               # Interactive onboarding (60-second setup)
@@ -106,8 +137,8 @@ Interactive wizard flow:
 After scaffolding, cd into the directory and:
   1. Review CLAUDE.md (pre-filled with your project info)
   2. Review aesop.config.json (pre-configured for your repos)
-  3. Run: bash daemons/run-watchdog.sh --once
-  4. Launch dashboard: python ui/serve.py
+  3. Run: aesop watch (or bash daemons/run-watchdog.sh)
+  4. Launch dashboard: aesop dash (or python3 ui/serve.py)
 `);
   process.exit(0);
 }
@@ -134,9 +165,9 @@ if (wizardModeRequested && wizardArgIndex >= 0) {
 }
 
 // Extract targetDir (first non-flag argument, excluding flag values)
-// Build set of indices consumed as flag values (tokens after --name/--domains/--repos)
+// Build set of indices consumed as flag values (tokens after --name/--domains/--repos/--repo-urls)
 const consumedIndices = new Set();
-const flagsWithValues = ['--name', '--domains', '--repos'];
+const flagsWithValues = ['--name', '--domains', '--repos', '--repo-urls'];
 for (let i = 0; i < args.length; i++) {
   if (flagsWithValues.includes(args[i]) && i + 1 < args.length) {
     consumedIndices.add(i + 1);
@@ -153,12 +184,13 @@ const targetDir = args.find((arg, idx) =>
 const projectName = getFlag('--name');
 const domainsStr = getFlag('--domains');
 const reposStr = getFlag('--repos');
+const repoUrlsStr = getFlag('--repo-urls');
 
 // Validate target directory doesn't exist or is empty (except for .git and aesop files)
 if (fs.existsSync(targetDir)) {
   const contents = fs.readdirSync(targetDir);
   // Allow .git and aesop scaffolded files to already exist (for idempotency)
-  const aesopDirs = ['daemons', 'dash', 'monitor', 'tools', 'ui', 'docs', '.git', 'state'];
+  const aesopDirs = ['daemons', 'dash', 'monitor', 'tools', 'ui', 'docs', 'state_store', 'skills', 'mcp', 'scan', 'hooks', '.git', 'state'];
   const aesopFiles = [
     'aesop.config.example.json',
     'aesop.config.json',
@@ -211,6 +243,11 @@ const filesToCopy = [
   'tools',
   'ui',
   'docs',
+  'state_store',
+  'skills',
+  'mcp',
+  'scan',
+  'hooks',
   'aesop.config.example.json',
   'README.md',
   'LICENSE',
@@ -277,7 +314,7 @@ function substituteTemplate(templateContent, projectName, domainsStr, reposStr)
   return result;
 }
 
-function generateConfigJson(targetDir, templateRoot, projectName, reposStr) {
+function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repoUrlsStr) {
   // Read example config
   const exampleConfigPath = path.join(templateRoot, 'aesop.config.example.json');
   let exampleConfig;
@@ -292,6 +329,7 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr) {
       brain_root: path.join(os.homedir(), '.claude'),
       scripts_root: path.join(os.homedir(), 'scripts'),
       temp_root: path.join(os.tmpdir()),
+      fleet_root: os.homedir(),
       repos: [],
       watchdog: {
         cycle_seconds: 150,
@@ -327,18 +365,26 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr) {
   exampleConfig.brain_root = '~/.claude';
   exampleConfig.scripts_root = '~/scripts';
   exampleConfig.temp_root = '~/.aesop-temp';
+  exampleConfig.fleet_root = os.homedir();
   exampleConfig._generated_note = 'This config uses portable ~ paths which expand at runtime on all platforms. Config loaders in ui/config.py (Python) and monitor/collect-signals.mjs (Node.js) automatically expand ~ paths to your home directory.';
 
   // Parse repos if provided
   if (reposStr) {
     const repos = reposStr.split(',').map(r => r.trim()).filter(r => r);
+    const repoUrls = repoUrlsStr ? repoUrlsStr.split(',').map(u => u.trim()).filter(u => u) : [];
+
     exampleConfig.repos = repos.map((repoPath, idx) => ({
       path: repoPath,
       name: path.basename(repoPath),
-      url: `https://github.com/user/${path.basename(repoPath)}.git`,
+      url: repoUrls[idx] || `https://github.com/user/${path.basename(repoPath)}.git`,
       primary_branch: 'main',
       backup_branch: 'backup/wip'
     }));
+
+    // Add _repos_note if URLs weren't provided (user must edit them)
+    if (!repoUrlsStr) {
+      exampleConfig._repos_note = 'Repository URLs are currently placeholders (https://github.com/user/<name>.git). Update each repo.url in the repos array with the actual repository URL. This is a required manual step before the daemon can clone repositories.';
+    }
   }
 
   return exampleConfig;
@@ -349,7 +395,7 @@ async function printNextStepsAndWatchdog(rl, targetDir, configPath, port) {
   console.log('\n🎯 Next 3 commands to get started:\n');
   console.log(`  1. cd ${targetDir}`);
   console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
-  console.log(`  3. python ui/serve.py  (launch dashboard on localhost:${port})`);
+  console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${port})`);
   console.log('\n📖 After that, review:');
   console.log('  • CLAUDE.md (pre-filled with your project info)');
   console.log('  • aesop.config.json (pre-configured for your repos)');
@@ -376,6 +422,133 @@ async function printNextStepsAndWatchdog(rl, targetDir, configPath, port) {
   });
 }
 
+function installPreCommitWaveguard(targetDir, templateRoot) {
+  // Install the pre-commit waveguard hook to prevent commits during a wave
+  // Try to locate .git directory
+  const gitDir = path.join(targetDir, '.git');
+  if (!fs.existsSync(gitDir)) {
+    // No git repo, skip hook installation silently
+    return;
+  }
+
+  // SECURITY: Check if .git itself is a symlink/junction (refuse to follow it outside targetDir)
+  try {
+    const gitDirLstat = fs.lstatSync(gitDir);
+    if (gitDirLstat.isSymbolicLink()) {
+      console.warn('⚠ Warning: .git is a symlink (security risk)');
+      console.warn('  Skipping pre-commit hook installation. Please remove the symlink and re-run scaffold.');
+      return;
+    }
+  } catch (e) {
+    // lstat failed; proceed (may be a permission issue)
+  }
+
+  // Ensure hooks directory exists
+  const gitHooksDir = path.join(gitDir, 'hooks');
+  if (!fs.existsSync(gitHooksDir)) {
+    fs.mkdirSync(gitHooksDir, { recursive: true });
+  }
+
+  // SECURITY: Check if gitHooksDir is a symlink (refuse to install through symlinked dir)
+  try {
+    const hooksLstat = fs.lstatSync(gitHooksDir);
+    if (hooksLstat.isSymbolicLink()) {
+      console.warn('⚠ Warning: .git/hooks directory is a symlink (security risk)');
+      console.warn('  Skipping pre-commit hook installation. Please remove the symlink and re-run scaffold.');
+      return;
+    }
+  } catch (e) {
+    // lstat failed; proceed (may be a permission issue)
+  }
+
+  const waveguardSource = path.join(templateRoot, 'hooks', 'pre-commit-waveguard.sh');
+  const preCommitDest = path.join(gitHooksDir, 'pre-commit');
+
+  if (!fs.existsSync(waveguardSource)) {
+    // Waveguard source doesn't exist, skip
+    return;
+  }
+
+  // Check if pre-commit hook already exists
+  if (fs.existsSync(preCommitDest)) {
+    // SECURITY: Check if existing pre-commit is a symlink (refuse to follow it)
+    try {
+      const destLstat = fs.lstatSync(preCommitDest);
+      if (destLstat.isSymbolicLink()) {
+        console.warn('⚠ Warning: Existing .git/hooks/pre-commit is a symlink (security risk)');
+        console.warn('  Skipping pre-commit hook installation. Please remove the symlink and re-run scaffold.');
+        return;
+      }
+    } catch (e) {
+      // lstat failed; proceed
+    }
+
+    // Backup existing pre-commit hook
+    const backupPath = path.join(gitHooksDir, 'pre-commit.waveguard-backup');
+    if (!fs.existsSync(backupPath)) {
+      // Only backup if we haven't already
+      try {
+        const existingContent = fs.readFileSync(preCommitDest, 'utf8');
+        // Check if waveguard is already in the hook
+        if (existingContent.includes('pre-commit-waveguard')) {
+          console.log('✓ Pre-commit waveguard already installed (no changes)');
+          return;
+        }
+        // Backup the existing hook
+        fs.copyFileSync(preCommitDest, backupPath);
+        console.log('✓ Backed up existing pre-commit hook to .git/hooks/pre-commit.waveguard-backup');
+      } catch (e) {
+        // Failed to backup, still try to install
+      }
+    }
+  }
+
+  // Create wrapper script that calls the waveguard hook
+  const wrapperScript = `#!/usr/bin/env bash
+set -uo pipefail
+
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+if [ -z "$repo_root" ]; then
+  exit 1
+fi
+
+waveguard_hook="$repo_root/hooks/pre-commit-waveguard.sh"
+if [ -f "$waveguard_hook" ]; then
+  bash "$waveguard_hook"
+  waveguard_exit=$?
+  if [ $waveguard_exit -ne 0 ]; then
+    exit $waveguard_exit
+  fi
+fi
+
+backup_hook="$repo_root/.git/hooks/pre-commit.waveguard-backup"
+if [ -f "$backup_hook" ] && [ -x "$backup_hook" ]; then
+  bash "$backup_hook"
+  exit $?
+fi
+
+exit 0
+`;
+
+  // Install the hook using copyFileSync (not symlink) to avoid dangling links
+  if (fs.existsSync(preCommitDest)) {
+    fs.unlinkSync(preCommitDest);
+  }
+  fs.writeFileSync(preCommitDest, wrapperScript);
+  console.log('✓ Installed pre-commit waveguard hook to .git/hooks/pre-commit');
+
+  // Ensure hook is executable
+  try {
+    fs.chmodSync(preCommitDest, 0o755);
+  } catch (e) {
+    // On Windows, chmod fails harmlessly; on POSIX, warn the user to chmod manually
+    if (process.platform !== 'win32') {
+      console.warn('⚠ Warning: Failed to chmod +x the pre-commit hook. Please run manually:');
+      console.warn(`  chmod +x "${preCommitDest}"`);
+    }
+  }
+}
+
 function installPrePushHook(targetDir, templateRoot) {
   // Try to locate .git directory
   const gitDir = path.join(targetDir, '.git');
@@ -460,36 +633,34 @@ function installPrePushHook(targetDir, templateRoot) {
   }
 
   // Install the hook
-  if (process.platform === 'win32') {
-    // Windows: copy the file
-    fs.copyFileSync(hookSource, hookDest);
-    console.log('✓ Copied pre-push policy hook to .git/hooks/pre-push');
-  } else {
-    // Unix: symlink for easy updates
-    // First remove if exists
-    if (fs.existsSync(hookDest)) {
-      fs.unlinkSync(hookDest);
-    }
-    // Create symlink relative to .git/hooks/
-    const relPath = path.relative(gitHooksDir, hookSource);
-    fs.symlinkSync(relPath, hookDest);
-    console.log('✓ Symlinked pre-push policy hook to .git/hooks/pre-push');
+  // Use copyFileSync on all platforms to avoid dangling symlinks after npx cache clean
+  // which would disable branch protection and the secret gate
+  if (fs.existsSync(hookDest)) {
+    fs.unlinkSync(hookDest);
   }
+  fs.copyFileSync(hookSource, hookDest);
+  console.log('✓ Copied pre-push policy hook to .git/hooks/pre-push');
 
   // Ensure hook is executable
   try {
     fs.chmodSync(hookDest, 0o755);
   } catch (e) {
-    // On Windows, chmod may fail; that's okay
+    // On Windows, chmod fails harmlessly; on POSIX, warn the user to chmod manually
+    if (process.platform !== 'win32') {
+      console.warn('⚠ Warning: Failed to chmod +x the pre-push hook. Please run manually:');
+      console.warn(`  chmod +x "${hookDest}"`);
+    }
   }
 }
 
-// Main execution function
-(async () => {
-  try {
-    let finalProjectName = projectName;
+// Main execution function (skip if runtime command detected)
+if (!isRuntimeCommand) {
+  (async () => {
+    try {
+      let finalProjectName = projectName;
     let finalReposStr = reposStr;
     let finalDomainsStr = domainsStr;
+    let finalRepoUrlsStr = repoUrlsStr;
     let finalTargetDir = targetDir;
     let configPath = path.join(targetDir, 'aesop.config.json');
     let dashboardPort = 8770;
@@ -597,11 +768,7 @@ function installPrePushHook(targetDir, templateRoot) {
         console.warn(`⚠ Warning: aesop.config.json already exists at ${configPath}`);
       } else {
         // Generate aesop.config.json
-        const config = generateConfigJson(finalTargetDir, templateRoot, finalProjectName, finalReposStr);
-        // Update dashboard port if specified in wizard mode
-        if (wizardMode && dashboardPort !== 8770) {
-          config.dashboard.refresh_seconds = 1;
-        }
+        const config = generateConfigJson(finalTargetDir, templateRoot, finalProjectName, finalReposStr, finalRepoUrlsStr);
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
         console.log('✓ Generated aesop.config.json (configured for your repos)');
       }
@@ -618,6 +785,9 @@ function installPrePushHook(targetDir, templateRoot) {
     // Install the pre-push hook
     installPrePushHook(finalTargetDir, templateRoot);
 
+    // Install the pre-commit waveguard hook
+    installPreCommitWaveguard(finalTargetDir, templateRoot);
+
     console.log(`\n✅ Scaffolded aesop template into "${finalTargetDir}" (${copiedCount} files)`);
 
     if (wizardMode && wizardRl) {
@@ -629,7 +799,7 @@ function installPrePushHook(targetDir, templateRoot) {
       console.log('\n🎯 Next 3 commands to get started:\n');
       console.log(`  1. cd ${finalTargetDir}`);
       console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
-      console.log(`  3. python ui/serve.py  (launch dashboard on localhost:${dashboardPort})`);
+      console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${dashboardPort})`);
       console.log('\n📖 After that, review:');
       console.log('  • CLAUDE.md (pre-filled with your project info)');
       console.log('  • aesop.config.json (pre-configured for your repos)');
@@ -646,7 +816,7 @@ function installPrePushHook(targetDir, templateRoot) {
       console.log(`  6. cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
       console.log('\nRun the daemon and dashboard:');
       console.log('  7. bash daemons/run-watchdog.sh --once  (test run)');
-      console.log('  8. python ui/serve.py  (launch dashboard on localhost:8770)');
+      console.log('  8. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:8770)');
     } else {
       console.log('\nConfiguration steps:');
       console.log(`  1. cd ${finalTargetDir}`);
@@ -658,12 +828,13 @@ function installPrePushHook(targetDir, templateRoot) {
       console.log(`  6. cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
       console.log('\nRun the daemon and dashboard:');
       console.log('  7. bash daemons/run-watchdog.sh --once  (test run)');
-      console.log('  8. python ui/serve.py  (launch dashboard on localhost:8770)');
+      console.log('  8. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:8770)');
     }
     console.log('\nFor full documentation, see the README.md in the scaffolded directory.');
     process.exit(0);
-  } catch (err) {
-    console.error(`Error scaffolding template: ${err.message}`);
-    process.exit(1);
-  }
-})();
+    } catch (err) {
+      console.error(`Error scaffolding template: ${err.message}`);
+      process.exit(1);
+    }
+  })();
+}

package/daemons/CLAUDE.md

@@ -30,7 +30,7 @@
    - Guards both daemon mode and `--once` mode (no bypass).
 2. **Testing override**: Set `AESOP_WATCHDOG_CYCLE_CMD` env var to replace backup-fleet.sh invocation (allows tests to use mock cycle without running real backup).
 3. **CRLF-safe, no line continuations**: Use POSIX-safe heredocs; never add `\` for line wrap.
-4. **Secret-scan gate**: `scan_tracked_files()` calls `$AESOP_ROOT/tools/secret_scan.py` on staged/modified files; non-0 exit blocks push, marks repo BLOCKED.
+4. **Secret-scan gate**: `scan_tracked_files()` calls `$AESOP_ROOT/tools/secret_scan.py` on tracked modifications and untracked files; non-0 exit blocks push, marks repo BLOCKED.
 5. **Append-only logs**: FLEET-BACKUP.log only grows; rotate via tools/rotate_logs.py.
 6. **Path dedup via realpath**: Avoids processing symlinked repos or dot-dir aliases twice.
 7. **Alert Bridge integration** (NEW wave-14): After each backup-fleet.sh cycle, run-watchdog.sh calls `python $AESOP_ROOT/tools/alert_bridge.py --scan || true` to post HIGH/CRITICAL security alerts and heartbeat staleness to Slack/Discord. No-op if webhook_url null/absent in aesop.config.json (feature opt-in). Uses cursor file for idempotent dispatch (no re-sends). See tools/alert_bridge.py for details.