@matt82198/aesop 0.1.0 → 0.3.1

package/tools/eod_sweep.py

@@ -11,21 +11,32 @@ Output contract:
   Line 1: EOD-SWEEP: SAFE or EOD-SWEEP: AT-RISK — <n> findings
   Lines 2+: One finding per line (if any)
   Exit code 0 only when SAFE.
+  Verdict also appended to BUILDLOG.md (if --buildlog provided or AESOP_STATE_ROOT set).
 
 Usage: eod_sweep.py [--repos PATHS] [--readonly-repos PATHS] [--fix-push]
+                    [--buildlog PATH] [--timestamp YYYY-MM-DD HH:MM]
 
   --repos: Colon-separated paths to scan (default: empty; use env var or flag to specify)
   --readonly-repos: Colon-separated paths that should NOT be auto-pushed
   --fix-push: Auto-push unpushed commits in repos where safe
+  --buildlog: Path to BUILDLOG.md (default: AESOP_STATE_ROOT/BUILDLOG.md or ./state/BUILDLOG.md)
+  --timestamp: Timestamp for BUILDLOG entry (format: YYYY-MM-DD HH:MM; omit to exclude timestamp)
 """
 
 import json
+import os
 import subprocess
 import sys
+import os
 from pathlib import Path
 from datetime import datetime
 import time
 
+try:
+    from common import get_state_dir
+except ImportError:
+    from tools.common import get_state_dir
+
 
 class Finding:
     """A single finding with repo + message."""
@@ -38,13 +49,27 @@ class Finding:
 
 
 def get_git_status(repo_path):
-    """Return (is_clean, dirty_files_list) for a repo."""
+    """Return (is_clean, dirty_files_list) for a repo.
+
+    Returns:
+      (True, []): Repo is clean
+      (False, list): Repo is dirty with file list
+      (None, error_msg): Git command failed (FAIL-CLOSED: treat as AT-RISK)
+    """
     try:
-        output = subprocess.run(
-            ['git', '-C', str(repo_path), 'status', '--porcelain'],
+        # Resolve path to normalize 8.3 short names on Windows
+        resolved_path = Path(repo_path).resolve()
+        result = subprocess.run(
+            ['git', '-C', str(resolved_path), 'status', '--porcelain'],
             capture_output=True, text=True, timeout=5
-        ).stdout.strip()
+        )
+
+        # FAIL-CLOSED: Check return code before processing output
+        if result.returncode != 0:
+            error_msg = result.stderr.strip() if result.stderr.strip() else f"exit code {result.returncode}"
+            return (None, f"git status check failed: {error_msg}")
 
+        output = result.stdout.strip()
         if not output:
             return (True, [])
         else:
@@ -55,21 +80,56 @@ def get_git_status(repo_path):
 
 
 def get_ahead_count(repo_path):
-    """Return count of commits ahead of origin/HEAD (or None on error)."""
+    """Return count of commits ahead of origin/HEAD (or None on error).
+
+    Returns:
+      int >= 0: Number of commits ahead (0 = all pushed or no remote)
+      None: Git command failed unexpectedly (FAIL-CLOSED: treat as AT-RISK)
+    """
     try:
+        # Resolve path to normalize 8.3 short names on Windows
+        resolved_path = Path(repo_path).resolve()
         # First check if there's a tracking branch
-        try:
-            output = subprocess.run(
-                ['git', '-C', str(repo_path), 'rev-list', '--left-only', '--count', 'HEAD...@{u}'],
-                capture_output=True, text=True, timeout=5
-            ).stdout.strip()
-        except:
-            # Fallback to origin/HEAD if no upstream
-            output = subprocess.run(
-                ['git', '-C', str(repo_path), 'rev-list', '--left-only', '--count', 'HEAD...origin/HEAD'],
+        result = subprocess.run(
+            ['git', '-C', str(resolved_path), 'rev-list', '--left-only', '--count', 'HEAD...@{u}'],
+            capture_output=True, text=True, timeout=5
+        )
+
+        # If upstream tracking exists, use that result
+        if result.returncode == 0:
+            output = result.stdout.strip()
+            try:
+                return int(output) if output else 0
+            except:
+                return None
+
+        # If no upstream tracking, try origin/HEAD (fallback for single-branch or no-remote repos)
+        # Expected error for local-only repos: "fatal: no upstream configured"
+        stderr_lower = result.stderr.lower()
+        if 'no upstream configured' in stderr_lower:
+            # Local-only repo (no tracking branch), try origin/HEAD as fallback
+            result = subprocess.run(
+                ['git', '-C', str(resolved_path), 'rev-list', '--left-only', '--count', 'HEAD...origin/HEAD'],
                 capture_output=True, text=True, timeout=5
-            ).stdout.strip()
+            )
+
+        # Check return code; if fails, determine if it's an expected "no remote" error or a real error
+        if result.returncode != 0:
+            stderr_lower = result.stderr.lower()
+            # Expected errors for local-only repos (no remote configured)
+            expected_errors = [
+                'no upstream configured',
+                'ambiguous argument',
+                'unknown revision',
+                'not a valid object name',
+                'no such ref'
+            ]
+            if any(err in stderr_lower for err in expected_errors):
+                return 0  # No remote/tracking, treat as "all pushed"
+            else:
+                return None  # Real error, fail-closed
 
+        output = result.stdout.strip()
         try:
             return int(output) if output else 0
         except:
@@ -79,13 +139,26 @@ def get_ahead_count(repo_path):
 
 
 def check_untracked_files(repo_path):
-    """Return list of untracked files not in .gitignore."""
+    """Return list of untracked files not in .gitignore.
+
+    Returns:
+      []: No untracked files
+      [list]: Untracked files found
+      None: Git command failed (FAIL-CLOSED: treat as AT-RISK)
+    """
     try:
-        output = subprocess.run(
-            ['git', '-C', str(repo_path), 'ls-files', '--others', '--exclude-standard'],
+        # Resolve path to normalize 8.3 short names on Windows
+        resolved_path = Path(repo_path).resolve()
+        result = subprocess.run(
+            ['git', '-C', str(resolved_path), 'ls-files', '--others', '--exclude-standard'],
             capture_output=True, text=True, timeout=5
-        ).stdout.strip()
+        )
+
+        # FAIL-CLOSED: Check return code before processing output
+        if result.returncode != 0:
+            return None
 
+        output = result.stdout.strip()
         if output:
             return output.split('\n')
         return []
@@ -94,12 +167,18 @@ def check_untracked_files(repo_path):
 
 
 def check_repo(repo_path):
-    """Check a single repo; return list of Finding objects or None if repo doesn't exist."""
+    """Check a single repo; returns a list of Finding objects.
+
+    FAIL-CLOSED (runner incident): a repo the caller ASKED to check that does
+    not exist or is not a git repo is an AT-RISK finding, never a silent skip
+    — the silent-None path made the sweep report a vacuous SAFE (exit 0) when
+    fixture/real repos failed to initialize.
+    """
     if not repo_path.exists():
-        return None
+        return [Finding(repo_path, "repo path does not exist")]
 
     if not (repo_path / '.git').exists():
-        return None
+        return [Finding(repo_path, "not a git repository (.git missing)")]
 
     findings = []
 
@@ -130,8 +209,10 @@ def check_repo(repo_path):
 def push_repo(repo_path):
     """Push commits for a repo (return True if successful)."""
     try:
+        # Resolve path to normalize 8.3 short names on Windows
+        resolved_path = Path(repo_path).resolve()
         result = subprocess.run(
-            ['git', '-C', str(repo_path), 'push'],
+            ['git', '-C', str(resolved_path), 'push'],
             capture_output=True, text=True, timeout=30
         )
         return result.returncode == 0
@@ -153,13 +234,64 @@ def run_secret_scan(repo_path):
         return False
 
 
+def append_to_buildlog(buildlog_path, verdict_line, timestamp_str=None):
+    """Append verdict to BUILDLOG.md (append-only).
+
+    Args:
+        buildlog_path: Path to BUILDLOG.md file.
+        verdict_line: The verdict line to append (e.g., "EOD-SWEEP: SAFE").
+        timestamp_str: Optional timestamp string (format: YYYY-MM-DD HH:MM).
+                      If None, timestamp is omitted from the entry.
+
+    Raises:
+        OSError: If file operations fail (permission denied, locked file, etc.).
+    """
+    try:
+        buildlog_path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        # Parent directory creation failed; re-raise with context
+        raise OSError(f"Failed to create parent directory for BUILDLOG: {e}") from e
+
+    # Create header if file doesn't exist
+    try:
+        if not buildlog_path.exists():
+            buildlog_path.write_text("# Build Log (append-only)\n")
+    except OSError as e:
+        # File creation failed; re-raise with context
+        raise OSError(f"Failed to create BUILDLOG file: {e}") from e
+
+    # Build entry line with optional timestamp
+    if timestamp_str:
+        entry_line = f"### [{timestamp_str}] {verdict_line}"
+    else:
+        entry_line = f"### {verdict_line}"
+
+    # Append to BUILDLOG with retry logic for Windows file locking
+    max_retries = 3
+    retry_delay = 0.1  # seconds
+    last_error = None
+
+    for attempt in range(max_retries):
+        try:
+            with open(buildlog_path, "a", encoding="utf-8") as f:
+                f.write(entry_line + "\n")
+            return
+        except OSError as e:
+            last_error = e
+            if attempt < max_retries - 1:
+                time.sleep(retry_delay)
+
+    # All retries failed
+    raise OSError(f"Failed to append to BUILDLOG after {max_retries} attempts: {last_error}") from last_error
+
+
 def main():
     import argparse
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument(
         '--repos',
         default='',
-        help='Colon-separated paths to scan (default: empty)'
+        help="os.pathsep-separated paths (; on Windows, : on POSIX)"
     )
     parser.add_argument(
         '--readonly-repos',
@@ -171,17 +303,31 @@ def main():
         action='store_true',
         help='Auto-push unpushed commits'
     )
+    parser.add_argument(
+        '--buildlog',
+        default=None,
+        help='Path to BUILDLOG.md (default: AESOP_STATE_ROOT/BUILDLOG.md or ./state/BUILDLOG.md)'
+    )
+    parser.add_argument(
+        '--timestamp',
+        default=None,
+        help='Timestamp for BUILDLOG entry (format: YYYY-MM-DD HH:MM; omit to exclude timestamp)'
+    )
     args = parser.parse_args()
 
     # Parse repos
+    # Split on os.pathsep (';' on Windows, ':' on POSIX): a ':' delimiter
+    # eats Windows drive letters (the runner's vacuous-SAFE incident: tmp on
+    # C:, checkout on D:, drive-relative remainder resolved to nothing and
+    # the old silent-skip reported SAFE with zero repos scanned).
     repos_to_check = []
     if args.repos:
-        repos_to_check = [Path(p) for p in args.repos.split(':') if p]
+        repos_to_check = [Path(p) for p in args.repos.split(os.pathsep) if p]
 
     # Parse readonly repos
     readonly_repos = set()
     if args.readonly_repos:
-        readonly_repos = {Path(p) for p in args.readonly_repos.split(':') if p}
+        readonly_repos = {Path(p) for p in args.readonly_repos.split(os.pathsep) if p}
 
     findings = []
 
@@ -232,6 +378,22 @@ def main():
     for finding in findings:
         print(f"  {finding}")
 
+    # Append to BUILDLOG if path is available
+    buildlog_path = None
+    if args.buildlog:
+        buildlog_path = Path(args.buildlog)
+    else:
+        # Try to derive from AESOP_STATE_ROOT or default to ./state
+        state_dir = get_state_dir()
+        buildlog_path = state_dir / "BUILDLOG.md"
+
+    if buildlog_path:
+        try:
+            append_to_buildlog(buildlog_path, verdict_line, args.timestamp)
+        except OSError as e:
+            # Log error but don't fail the verdict — exit code depends on findings, not BUILDLOG
+            print(f"WARNING: Failed to append to BUILDLOG: {e}", file=sys.stderr)
+
     sys.exit(exit_code)
 
 

package/tools/fleet.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+
+/**
+ * Aesop fleet — One-shot fleet snapshot
+ *
+ * Prints a comprehensive fleet status snapshot:
+ *  - Agents (from dash-extra.mjs --json passthrough)
+ *  - Heartbeat ages (watchdog + monitor, seconds, with STALE status if >threshold)
+ *  - Tracker lane counts (from state/tracker.json)
+ *  - Orchestrator status (from state/orchestrator-status.json)
+ *
+ * Graceful degradation: any missing state file produces explicit 'unavailable: <why>'
+ * rather than crashing or leaving blank output. Never crashes; always exits cleanly.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const CURRENT_DIR = process.cwd();
+const WATCHDOG_STALE_THRESHOLD = 300; // seconds
+const MONITOR_STALE_THRESHOLD = 3600; // seconds
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function readHeartbeat(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const content = fs.readFileSync(filePath, 'utf8').trim();
+    const timestamp = parseInt(content, 10);
+    if (isNaN(timestamp)) {
+      return null;
+    }
+    return timestamp;
+  } catch (e) {
+    return null;
+  }
+}
+
+function getHeartbeatStatus(timestamp, threshold) {
+  if (timestamp === null) {
+    return { age: null, status: 'MISSING' };
+  }
+  const now = Math.floor(Date.now() / 1000);
+  const age = now - timestamp;
+  const isStale = age > threshold;
+  const status = isStale ? 'STALE' : 'OK';
+  return { age, status };
+}
+
+function loadJSON(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const content = fs.readFileSync(filePath, 'utf8').trim();
+    if (!content) {
+      return null;
+    }
+    return JSON.parse(content);
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Invoke dash-extra.mjs --json to get active agents
+ * Returns { agents: [...] } or { unavailable: "reason" }
+ */
+function getFleetAgents(aesopRoot) {
+  return new Promise((resolve) => {
+    const dashExtraPath = path.join(aesopRoot, 'dash', 'dash-extra.mjs');
+
+    if (!fs.existsSync(dashExtraPath)) {
+      resolve({ unavailable: 'dash-extra.mjs not found' });
+      return;
+    }
+
+    try {
+      const proc = spawn('node', [dashExtraPath, '--json'], {
+        cwd: aesopRoot,
+        env: {
+          ...process.env,
+          AESOP_ROOT: aesopRoot
+        },
+        timeout: 5000,
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+
+      let stdout = '';
+      let stderr = '';
+      let resolved = false;
+
+      const cleanup = () => {
+        if (!resolved) {
+          resolved = true;
+          if (proc && !proc.killed) {
+            try {
+              proc.kill();
+            } catch (e) {
+              // ignore
+            }
+          }
+        }
+      };
+
+      const timeoutHandle = setTimeout(() => {
+        cleanup();
+        resolve({ unavailable: 'dash-extra.mjs timeout' });
+      }, 6000);
+
+      proc.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on('close', (code) => {
+        clearTimeout(timeoutHandle);
+        if (!resolved) {
+          resolved = true;
+          if (code === 0 && stdout.trim()) {
+            try {
+              const agents = JSON.parse(stdout);
+              resolve({
+                agents: Array.isArray(agents) ? agents : [],
+                count: Array.isArray(agents) ? agents.length : 0
+              });
+            } catch (e) {
+              resolve({ unavailable: 'failed to parse dash-extra output' });
+            }
+          } else {
+            resolve({ unavailable: 'dash-extra.mjs failed' });
+          }
+        }
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(timeoutHandle);
+        cleanup();
+        if (!resolved) {
+          resolved = true;
+          resolve({ unavailable: 'dash-extra.mjs spawn error' });
+        }
+      });
+    } catch (e) {
+      resolve({ unavailable: 'exception spawning dash-extra.mjs' });
+    }
+  });
+}
+
+function getTrackerLaneCounts(trackerPath) {
+  const tracker = loadJSON(trackerPath);
+  if (!tracker) {
+    return { unavailable: 'tracker.json not found or malformed' };
+  }
+
+  const items = tracker.items || [];
+  const byLane = {};
+
+  for (const item of items) {
+    const lane = item.lane || 'unknown';
+    byLane[lane] = (byLane[lane] || 0) + 1;
+  }
+
+  return {
+    total_items: items.length,
+    by_lane: byLane
+  };
+}
+
+function getOrchestratorStatus(orchStatusPath) {
+  const status = loadJSON(orchStatusPath);
+  if (!status) {
+    return { unavailable: 'orchestrator-status.json not found or malformed' };
+  }
+  return status;
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+(async function main() {
+  try {
+    // Determine AESOP_ROOT
+    const aesopRoot = process.env.AESOP_ROOT || CURRENT_DIR;
+
+    const stateDir = path.join(aesopRoot, 'state');
+    const watchdogHeartbeatPath = path.join(stateDir, '.watchdog-heartbeat');
+    const monitorHeartbeatPath = path.join(stateDir, '.monitor-heartbeat');
+    const trackerPath = path.join(stateDir, 'tracker.json');
+    const orchStatusPath = path.join(stateDir, 'orchestrator-status.json');
+
+    // Gather all data concurrently
+    const [watchdogTs, monitorTs, agentsData, trackerData, orchStatusData] = await Promise.all([
+      Promise.resolve(readHeartbeat(watchdogHeartbeatPath)),
+      Promise.resolve(readHeartbeat(monitorHeartbeatPath)),
+      getFleetAgents(aesopRoot),
+      Promise.resolve(getTrackerLaneCounts(trackerPath)),
+      Promise.resolve(getOrchestratorStatus(orchStatusPath))
+    ]);
+
+    // Build result object
+    const result = {
+      timestamp: new Date().toISOString(),
+      aesop_root: aesopRoot,
+      heartbeats: {
+        watchdog: null,
+        monitor: null
+      },
+      agents: agentsData,
+      tracker: trackerData,
+      orchestrator: orchStatusData
+    };
+
+    // Process watchdog heartbeat
+    const watchdogStatus = getHeartbeatStatus(watchdogTs, WATCHDOG_STALE_THRESHOLD);
+    if (watchdogStatus.age !== null) {
+      result.heartbeats.watchdog = {
+        age_seconds: watchdogStatus.age,
+        status: watchdogStatus.status,
+        threshold_seconds: WATCHDOG_STALE_THRESHOLD
+      };
+    } else {
+      result.heartbeats.watchdog = {
+        unavailable: watchdogStatus.status
+      };
+    }
+
+    // Process monitor heartbeat
+    const monitorStatus = getHeartbeatStatus(monitorTs, MONITOR_STALE_THRESHOLD);
+    if (monitorStatus.age !== null) {
+      result.heartbeats.monitor = {
+        age_seconds: monitorStatus.age,
+        status: monitorStatus.status,
+        threshold_seconds: MONITOR_STALE_THRESHOLD
+      };
+    } else {
+      result.heartbeats.monitor = {
+        unavailable: monitorStatus.status
+      };
+    }
+
+    // Output JSON
+    console.log(JSON.stringify(result, null, 2));
+
+    process.exitCode = 0;
+  } catch (err) {
+    console.error(`Error gathering fleet snapshot: ${err.message}`);
+    process.exitCode = 1;
+  }
+})();