@matt82198/aesop 0.1.0-beta.4 → 0.1.0-beta.5

package/tools/ci_merge_wait.py

@@ -8,19 +8,23 @@ status is SUCCESS — this is the whole point (prevents merge-on-CI-failure edge
 
 Usage:
   python ci_merge_wait.py <PR-number> [--timeout SECONDS] [--poll SECONDS] [--merge-method merge|squash|rebase]
+                          [--dry-run] [--self-test]
 
 Options:
   --timeout SECONDS      Max seconds to wait for CI to conclude (default: 3600)
   --poll SECONDS         Poll interval in seconds (default: 10)
   --merge-method METHOD  Merge strategy: merge, squash, rebase (default: merge)
+  --dry-run              Skip actual merge, just verify CI status and report what would happen
+  --self-test            Run offline self-test of polling/decision logic (no network, no PR required)
 
 Exit codes:
-  0 = PR merged successfully
+  0 = PR merged successfully, dry-run verified, or self-test passed
+  1 = General error or self-test failed
   2 = CI checks failed (do NOT merge, prints which check failed)
   3 = Timeout waiting for CI to conclude
   4 = PR not mergeable or has merge conflicts
 
-Requires: gh CLI available on PATH. Gracefully exits with error if gh is missing.
+Requires: gh CLI available on PATH (unless --self-test). Gracefully exits with error if gh is missing.
 """
 
 import argparse
@@ -98,12 +102,17 @@ def check_ci_status(status_rollup):
         return ("success", None)
 
 
-def merge_pr(pr_number, merge_method):
+def merge_pr(pr_number, merge_method, dry_run=False):
     """
     Merge the PR using gh pr merge.
     This call is STRUCTURALLY UNREACHABLE unless CI is SUCCESS.
+    If dry_run is True, report what would be done without actually merging.
     Returns True on success, False on error.
     """
+    if dry_run:
+        print(f"[DRY-RUN] Would merge PR #{pr_number} with --{merge_method}")
+        return True
+
     result = subprocess.run(
         ["gh", "pr", "merge", str(pr_number), f"--{merge_method}"],
         capture_output=True,
@@ -113,12 +122,73 @@ def merge_pr(pr_number, merge_method):
     return result.returncode == 0
 
 
+def run_self_test():
+    """
+    Run self-test with mocked CI status checks.
+    No network calls; verifies the merge guard logic.
+    Returns True if all tests pass, False otherwise.
+    """
+    print("Running self-test with mocked CI statuses...")
+
+    # Mock status rollup: all checks SUCCESS
+    success_rollup = [
+        {"name": "test-unit", "status": "SUCCESS"},
+        {"name": "test-integration", "status": "SUCCESS"},
+        {"name": "lint", "status": "SUCCESS"},
+    ]
+
+    # Test 1: success case
+    ci_status, failed_check = check_ci_status(success_rollup)
+    if ci_status != "success":
+        print(f"FAIL: Expected 'success', got '{ci_status}'")
+        return False
+    print("[OK] success case: merge guard permits merge")
+
+    # Test 2: pending case
+    pending_rollup = [
+        {"name": "test-unit", "status": "PENDING"},
+        {"name": "test-integration", "status": "SUCCESS"},
+    ]
+    ci_status, failed_check = check_ci_status(pending_rollup)
+    if ci_status != "pending":
+        print(f"FAIL: Expected 'pending', got '{ci_status}'")
+        return False
+    print("[OK] pending case: merge guard blocks merge (structurally unreachable)")
+
+    # Test 3: failure case
+    failure_rollup = [
+        {"name": "test-unit", "status": "FAILURE"},
+        {"name": "test-integration", "status": "SUCCESS"},
+    ]
+    ci_status, failed_check = check_ci_status(failure_rollup)
+    if ci_status != "failure" or failed_check != "test-unit":
+        print(f"FAIL: Expected 'failure' with 'test-unit', got '{ci_status}' / '{failed_check}'")
+        return False
+    print("[OK] failure case: merge guard blocks merge (structurally unreachable)")
+
+    # Test 4: no checks (treat as success)
+    ci_status, _ = check_ci_status([])
+    if ci_status != "success":
+        print(f"FAIL: Expected 'success' for no checks, got '{ci_status}'")
+        return False
+    print("[OK] no-checks case: treated as success")
+
+    print("\nAll self-tests passed!")
+    return True
+
+
 def main():
     parser = argparse.ArgumentParser(
         description=__doc__,
         formatter_class=argparse.RawDescriptionHelpFormatter
     )
-    parser.add_argument("pr_number", type=int, help="GitHub PR number")
+    parser.add_argument(
+        "pr_number",
+        type=int,
+        nargs="?",
+        default=None,
+        help="GitHub PR number (required unless using --self-test)"
+    )
     parser.add_argument(
         "--timeout",
         type=int,
@@ -137,9 +207,31 @@ def main():
         default="merge",
         help="Merge strategy (default: merge)"
     )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Skip actual merge, just verify CI status and report what would happen"
+    )
+    parser.add_argument(
+        "--self-test",
+        action="store_true",
+        help="Run offline self-test of polling/decision logic (no network)"
+    )
 
     args = parser.parse_args()
 
+    # Handle self-test mode
+    if args.self_test:
+        if run_self_test():
+            sys.exit(0)
+        else:
+            sys.exit(1)
+
+    # Validate PR is provided for non-self-test mode
+    if args.pr_number is None:
+        print("ERROR: PR number is required (unless using --self-test)")
+        sys.exit(1)
+
     # Validate inputs
     if args.pr_number <= 0:
         print("ERROR: PR number must be positive")
@@ -185,11 +277,32 @@ def main():
             print(f"CI FAILED: {failed_check}")
             sys.exit(2)
         elif ci_status == "success":
-            # SUCCESS: CI is green, proceed to merge
+            # SUCCESS: CI is green, re-check immediately before proceeding
+            print(f"CI GREEN: All checks passed. Re-checking status before merge...")
+            final_check = get_pr_status(args.pr_number)
+            if final_check is None:
+                print("ERROR: final status check failed")
+                sys.exit(1)
+
+            final_rollup = final_check.get("statusCheckRollup", [])
+            final_ci_status, final_failed = check_ci_status(final_rollup)
+
+            if final_ci_status != "success":
+                print(f"CI STATUS CHANGED: {final_failed}")
+                sys.exit(2)
+
+            # SUCCESS: CI is still green, proceed to merge
             # This merge call is STRUCTURALLY UNREACHABLE unless ci_status == "success"
-            print(f"CI GREEN: All checks passed. Merging PR #{args.pr_number}...")
-            if merge_pr(args.pr_number, args.merge_method):
-                print(f"MERGED: PR #{args.pr_number} merged successfully")
+            if args.dry_run:
+                print(f"[DRY-RUN] PR #{args.pr_number} CI is green, would merge...")
+            else:
+                print(f"CI CONFIRMED GREEN. Merging PR #{args.pr_number}...")
+
+            if merge_pr(args.pr_number, args.merge_method, dry_run=args.dry_run):
+                if args.dry_run:
+                    print(f"[DRY-RUN] PR #{args.pr_number} merge command would succeed")
+                else:
+                    print(f"MERGED: PR #{args.pr_number} merged successfully")
                 sys.exit(0)
             else:
                 print("ERROR: merge failed (PR state changed?)")

package/tools/fleet_prompt_extractor.py

@@ -0,0 +1,134 @@
+"""Extract NEW fleet spawn prompts (Agent/Task) for review cycle with deduplication."""
+import argparse
+import hashlib
+import json
+import os
+import pathlib
+import sys
+from datetime import datetime, timedelta
+
+
+def walk_jsonl(directory):
+    """Recursively find all .jsonl files in a directory."""
+    result = []
+    for root, dirs, files in os.walk(directory):
+        for f in files:
+            if f.endswith(".jsonl"):
+                result.append(os.path.join(root, f))
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Extract new fleet spawn prompts (Agent/Task) for review, with dedup by SHA1."
+    )
+    parser.add_argument(
+        "roots", nargs="+", help="Root directories containing .jsonl transcripts to scan"
+    )
+    parser.add_argument(
+        "-s", "--seen-file", required=True, help="Path to seen-set JSON file for dedup (will be created/updated)"
+    )
+    parser.add_argument(
+        "-m", "--minutes", type=int, default=30, help="Look back this many minutes (default 30)"
+    )
+    parser.add_argument(
+        "-x", "--exclude-session", help="Exclude transcripts from this session ID substring"
+    )
+    parser.add_argument(
+        "--max", type=int, default=20, help="Cap prompts per review cycle (default 20)"
+    )
+
+    args = parser.parse_args()
+
+    # Load seen set
+    seen_set = set()
+    if os.path.exists(args.seen_file):
+        try:
+            with open(args.seen_file, "r", encoding="utf-8") as f:
+                seen_set = set(json.load(f))
+        except Exception:
+            pass
+
+    # Gather .jsonl files
+    files = []
+    for root in args.roots:
+        if os.path.exists(root):
+            files.extend(walk_jsonl(root))
+
+    # Time filter
+    since_ms = (datetime.now() - timedelta(minutes=args.minutes)).timestamp() * 1000
+
+    out = []
+    for fp in files:
+        # Session exclusion
+        if args.exclude_session and args.exclude_session in fp:
+            continue
+
+        try:
+            st = os.stat(fp)
+            if st.st_mtime_ns / 1e6 < since_ms:
+                continue
+        except Exception:
+            continue
+
+        try:
+            with open(fp, "r", encoding="utf-8") as f:
+                lines = f.read().split("\n")
+        except Exception:
+            continue
+
+        base = os.path.basename(fp)
+        for line in lines:
+            if not line.strip() or ('"Agent"' not in line and '"Task"' not in line):
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            content = obj.get("message", {}).get("content")
+            if not isinstance(content, list):
+                continue
+
+            for c in content:
+                if c.get("type") != "tool_use" or c.get("name") not in ["Agent", "Task"]:
+                    continue
+
+                prompt = (c.get("input", {}).get("prompt") or c.get("input", {}).get("description") or "").strip()
+                if len(prompt) < 8:
+                    continue
+
+                key = hashlib.sha1(prompt.encode()).hexdigest()[:16]
+                if key in seen_set:
+                    continue
+
+                seen_set.add(key)
+                out.append(
+                    {
+                        "key": key,
+                        "src": base,
+                        "label": (c.get("input", {}).get("description") or "")[:80],
+                        "prompt": prompt[:700],
+                    }
+                )
+
+                if len(out) >= args.max:
+                    break
+
+            if len(out) >= args.max:
+                break
+
+        if len(out) >= args.max:
+            break
+
+    # Write updated seen set
+    pathlib.Path(args.seen_file).parent.mkdir(parents=True, exist_ok=True)
+    with open(args.seen_file, "w", encoding="utf-8") as f:
+        json.dump(sorted(list(seen_set)), f)
+
+    # Output to stdout as JSON
+    sys.stdout.write(json.dumps(out))
+
+
+if __name__ == "__main__":
+    main()

package/tools/healthcheck.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""
+Healthcheck tool — Aggregates fleet health signals.
+
+Checks:
+- Heartbeat ages (watchdog, monitor) from config-driven state paths
+- Tracker open-item counts by lane (state/tracker.json)
+- Security-alert count and severity (state/SECURITY-ALERTS.log, if present)
+- Orchestrator status age and phase (state/orchestrator-status.json)
+
+Output: One line `HEALTH: 🟢|🟡|🔴 <reason>` + compact bullet list of non-green contributors.
+
+Green = all heartbeats fresh + no HIGH alerts
+Yellow = stale heartbeat OR unreviewed MED alert
+Red = HIGH alert OR watchdog dead while agents running
+
+Config read at CALL time. Graceful on missing files (missing = reported, not crash).
+Encoding: UTF-8 always. --json mode outputs machine-readable format.
+"""
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from time import time
+
+# Import UI config for state path resolution
+UI_DIR = Path(__file__).parent.parent / "ui"
+if str(UI_DIR) not in sys.path:
+    sys.path.insert(0, str(UI_DIR))
+
+try:
+    import config
+except ImportError:
+    print("ERROR: Unable to import config module from ui/", file=sys.stderr)
+    sys.exit(2)
+
+
+def check_health(json_mode=False):
+    """
+    Aggregate health signals and return health ball + reason.
+
+    Returns:
+        str: Either human-readable "HEALTH: 🟢|🟡|🔴 <reason>\n- bullet list"
+             or JSON string (if json_mode=True)
+    """
+    # Reload config at call time to pick up env vars
+    config.reload()
+
+    issues = []  # List of (severity, message) tuples
+
+    # 1. Check heartbeats
+    watchdog_status = _check_heartbeat("watchdog", config.WATCHDOG_HEARTBEAT, threshold=300)
+    if watchdog_status:
+        issues.append(watchdog_status)
+
+    monitor_status = _check_heartbeat("monitor", config.MONITOR_HEARTBEAT, threshold=3600)
+    if monitor_status:
+        issues.append(monitor_status)
+
+    # 2. Check security alerts
+    alert_status = _check_alerts(config.ALERTS_LOG)
+    if alert_status:
+        issues.append(alert_status)
+
+    # 3. Check orchestrator status
+    orch_status = _check_orchestrator_status(config.ORCH_STATUS_FILE)
+    if orch_status:
+        issues.append(orch_status)
+
+    # 4. Check tracker items (informational, not severity-driving)
+    tracker_info = _check_tracker(config.TRACKER_FILE)
+
+    # Determine ball color based on issue severities
+    ball = "🟢"  # Default green
+    for severity, msg in issues:
+        if severity == "RED":
+            ball = "🔴"
+            break
+        elif severity == "YELLOW" and ball != "🔴":
+            ball = "🟡"
+
+    # Build output
+    if json_mode:
+        return _format_json(ball, issues, tracker_info)
+    else:
+        return _format_human(ball, issues, tracker_info)
+
+
+def _check_heartbeat(name, heartbeat_file, threshold=300):
+    """
+    Check heartbeat freshness.
+
+    Returns:
+        tuple (severity, message) or None if all OK
+    """
+    if not heartbeat_file.exists():
+        return ("YELLOW", f"no {name} heartbeat file")
+
+    try:
+        content = heartbeat_file.read_text(encoding="utf-8").strip()
+        if not content:
+            return ("YELLOW", f"{name} heartbeat empty")
+
+        try:
+            timestamp = int(content)
+        except ValueError:
+            return ("YELLOW", f"{name} heartbeat unparseable")
+
+        age_seconds = int(time()) - timestamp
+        if age_seconds >= threshold * 2:
+            # Watchdog dead while orchestrator might be active
+            if name == "watchdog" and age_seconds >= 600:
+                return ("RED", f"watchdog dead ({age_seconds}s)")
+            return ("YELLOW", f"{name} stale ({age_seconds}s > {threshold}s threshold)")
+        elif age_seconds > threshold:
+            return ("YELLOW", f"{name} stale ({age_seconds}s)")
+
+        return None
+    except Exception as e:
+        return ("YELLOW", f"{name} heartbeat read error: {e}")
+
+
+def _check_alerts(alerts_file):
+    """
+    Check security alerts for HIGH severity.
+
+    Returns:
+        tuple (severity, message) or None if all OK
+    """
+    if not alerts_file.exists():
+        return None
+
+    try:
+        content = alerts_file.read_text(encoding="utf-8").strip()
+        if not content:
+            return None
+
+        lines = content.split("\n")
+        unreviewed = [
+            line.strip() for line in lines
+            if line.strip()
+            and "NOTE:" not in line
+            and "RESOLVED-FP" not in line
+        ]
+
+        if not unreviewed:
+            return None
+
+        # Check for HIGH severity
+        high_count = sum(1 for line in unreviewed if "[HIGH]" in line)
+        if high_count > 0:
+            return ("RED", f"{high_count} HIGH severity alerts")
+
+        # Check for MED severity
+        med_count = sum(1 for line in unreviewed if "[MED]" in line)
+        if med_count > 0:
+            return ("YELLOW", f"{med_count} unreviewed MED alerts")
+
+        if unreviewed:
+            return ("YELLOW", f"{len(unreviewed)} unreviewed alerts")
+
+        return None
+    except Exception as e:
+        return ("YELLOW", f"alert check error: {e}")
+
+
+def _check_orchestrator_status(status_file):
+    """
+    Check orchestrator status age (informational; reports stale status).
+
+    Returns:
+        tuple (severity, message) or None if all OK
+    """
+    if not status_file.exists():
+        return None
+
+    try:
+        content = status_file.read_text(encoding="utf-8").strip()
+        if not content:
+            return None
+
+        data = json.loads(content)
+        if not isinstance(data, dict):
+            return None
+
+        # Check updated_at age
+        updated_at_str = data.get("updated_at", "")
+        if not updated_at_str:
+            return None
+
+        updated_at_str = updated_at_str.rstrip("Z")
+        try:
+            updated_at = datetime.fromisoformat(updated_at_str)
+            age_seconds = int((datetime.now(timezone.utc).replace(tzinfo=None) - updated_at).total_seconds())
+
+            # >1800s (30min) is stale for orchestrator
+            if age_seconds > 1800:
+                return ("YELLOW", f"orchestrator status stale ({age_seconds}s)")
+        except Exception:
+            pass
+
+        return None
+    except Exception as e:
+        return ("YELLOW", f"orchestrator status check error: {e}")
+
+
+def _check_tracker(tracker_file):
+    """
+    Aggregate tracker item counts by lane (informational only).
+
+    Returns:
+        dict or None with lane counts
+    """
+    if not tracker_file.exists():
+        return None
+
+    try:
+        content = tracker_file.read_text(encoding="utf-8").strip()
+        if not content:
+            return None
+
+        data = json.loads(content)
+        if not isinstance(data, dict):
+            return None
+
+        items = data.get("items", [])
+        if not items:
+            return None
+
+        # Count by lane
+        lanes = {}
+        for item in items:
+            lane = item.get("lane", "unknown")
+            if lane not in lanes:
+                lanes[lane] = 0
+            lanes[lane] += 1
+
+        return lanes
+    except Exception:
+        return None
+
+
+def _format_human(ball, issues, tracker_info):
+    """Format human-readable output."""
+    reason = "OK"
+    if issues:
+        reasons = [msg for severity, msg in issues]
+        reason = "; ".join(reasons)
+
+    lines = [f"HEALTH: {ball} {reason}"]
+
+    if tracker_info:
+        lane_str = ", ".join(f"{lane}: {count}" for lane, count in sorted(tracker_info.items()))
+        lines.append(f"  Tracker: {lane_str}")
+
+    return "\n".join(lines)
+
+
+def _format_json(ball, issues, tracker_info):
+    """Format JSON output."""
+    result = {
+        "ball": ball,
+        "health": "OK" if ball == "🟢" else ("DEGRADED" if ball == "🟡" else "CRITICAL"),
+        "issues": [{"severity": severity, "message": msg} for severity, msg in issues],
+        "tracker": tracker_info or {},
+    }
+    return json.dumps(result, indent=2)
+
+
+def main():
+    """CLI entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Aesop healthcheck — aggregate fleet health signals"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON"
+    )
+
+    args = parser.parse_args()
+
+    try:
+        output = check_health(json_mode=args.json)
+        print(output)
+        sys.exit(0)
+    except Exception as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/tools/secret_scan.py

@@ -101,12 +101,19 @@ def is_binary_file(filepath):
 
 
 def should_skip_file(filepath):
-    """Check if file should be skipped entirely (.git/, __pycache__, .pyc, .pyo)."""
+    """Check if file should be skipped entirely (.git/, node_modules/, __pycache__, .pyc, .pyo)."""
     # Skip .git directories — match a path COMPONENT, not a substring
     # (".git" in str(path) also matched ".gitignore" and skipped scanning it).
     if ".git" in filepath.parts:
         return True
 
+    # Skip node_modules — third-party deps, always git-ignored, never our code.
+    # CI installs them via `npm ci` for the dashboard build, so a whole-tree
+    # scan would otherwise walk thousands of package files (README example
+    # connection strings, files literally named token.js → false positives).
+    if "node_modules" in filepath.parts:
+        return True
+
     # Skip __pycache__ directories
     if "__pycache__" in filepath.parts:
         return True