@matt82198/aesop 0.1.0 → 0.3.1

package/tools/fleet_ledger.py

@@ -7,6 +7,12 @@ Subcommands:
     Manually append one ledger line (verdict = OK|FAILED|EMPTY|HUNG, default OK)
     phase = build|verify|repair|other (optional, default null)
     wave = wave number as integer (optional, default null)
+  append-wave --report-file <path> --wave <id> --phase <phase> --timestamp <iso>
+    Append one ledger row from a workflow report JSON for a specific phase.
+    Report shape: {tokens:{buildOut,verifyOut,repairOut,...}, integration:{green:bool,...}, ...}
+    Creates: model=haiku, verdict from integration.green, tokens_out from tokens.<phase>Out.
+    Skips if identical wave+phase+timestamp row already exists (idempotent).
+    Tolerates missing fields (defaults to 0).
   harvest
     Scan session tasks directories for agent outcomes and append missing entries.
     (Tracks state in ledger directory for resume capability)
@@ -56,6 +62,62 @@ def ensure_ledger_header():
         ledger_file.write_text(header, encoding='utf-8')
 
 
+def _validate_iso_timestamp(ts):
+    """Validate and normalize ISO 8601 timestamp.
+
+    Args:
+        ts: Timestamp string to validate
+
+    Returns:
+        Validated timestamp string or None if invalid
+
+    Raises:
+        ValueError: If timestamp is invalid
+    """
+    import re
+    if not ts:
+        return None
+
+    ts_str = str(ts).strip()
+
+    # Reject if contains control characters, pipes, newlines, etc.
+    if '\n' in ts_str or '\r' in ts_str or '|' in ts_str:
+        raise ValueError(f"Timestamp contains forbidden characters: {repr(ts_str)}")
+
+    # Validate ISO 8601 format: YYYY-MM-DDTHH:MM:SS[.fff][+HH:MM]
+    # This is a strict pattern to prevent injection via malformed timestamps
+    iso_pattern = r'^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:[+-]\d{2}:\d{2}|Z)?$'
+    if not re.match(iso_pattern, ts_str):
+        raise ValueError(f"Timestamp does not match ISO 8601 format: {ts_str}")
+
+    return ts_str
+
+
+def _validate_phase(phase):
+    """Validate and normalize phase name.
+
+    Args:
+        phase: Phase name to validate
+
+    Returns:
+        Validated phase string (max 15 chars) or empty string if None
+
+    Raises:
+        ValueError: If phase contains forbidden characters
+    """
+    if phase is None:
+        return ''
+
+    phase_str = str(phase).strip()
+
+    # Reject if contains forbidden characters (pipes, newlines, etc.)
+    if '|' in phase_str or '\n' in phase_str or '\r' in phase_str:
+        raise ValueError(f"Phase contains forbidden characters: {repr(phase_str)}")
+
+    # Truncate to 15 chars for idempotency consistency
+    return phase_str[:15]
+
+
 def append_ledger_line(iso_ts, agent_type, model, duration_sec, tokens_in, tokens_out, verdict='OK', phase=None, wave=None):
     """Append one line to the ledger.
 
@@ -69,20 +131,32 @@ def append_ledger_line(iso_ts, agent_type, model, duration_sec, tokens_in, token
         verdict: OK|FAILED|EMPTY|HUNG (default OK)
         phase: build|verify|repair|other (optional, default None)
         wave: wave number as int or None (optional, default None)
+
+    Raises:
+        ValueError: If timestamp or phase validation fails
     """
     ensure_ledger_header()
     ledger_file, _, _ = get_ledger_paths()
 
+    # Validate and sanitize iso_ts: must be valid ISO 8601 format
+    try:
+        iso_ts = _validate_iso_timestamp(iso_ts)
+        if iso_ts is None:
+            iso_ts = '-'
+    except ValueError as e:
+        # Reject invalid timestamps to prevent injection
+        raise ValueError(f"Invalid timestamp: {e}") from e
+
     # Sanitize fields: no pipes, truncate to reasonable length
     agent_type = str(agent_type or '-').replace('|', '').strip()[:30]
     model = str(model or '-').replace('|', '').strip()[:30]
     verdict = str(verdict or 'OK').replace('|', '').strip()[:10]
 
-    # Sanitize optional fields
-    if phase is not None:
-        phase = str(phase).replace('|', '').strip()[:15]
-    else:
-        phase = ''
+    # Validate and sanitize optional fields
+    try:
+        phase = _validate_phase(phase)
+    except ValueError as e:
+        raise ValueError(f"Invalid phase: {e}") from e
 
     if wave is not None:
         try:
@@ -141,6 +215,7 @@ def harvest():
     seen_agents, _ = load_harvest_state()
     new_seen = set(seen_agents)
     harvested_count = 0
+    skipped_count = 0
 
     # Determine temp root for tasks scanning
     if os.environ.get("AESOP_TEMP_ROOT"):
@@ -170,6 +245,11 @@ def harvest():
             except json.JSONDecodeError:
                 continue
 
+            # Type guard: skip non-dict scalars (int, string, etc.)
+            if not isinstance(obj, dict):
+                skipped_count += 1
+                continue
+
             # Look for agent spawn events (type='assistant' with Agent/Task tool_use)
             # or completion events (type='assistant' with usage data)
             agent_id = obj.get('agentId') or obj.get('uuid')
@@ -219,6 +299,8 @@ def harvest():
 
     ledger_file, _, _ = get_ledger_paths()
     print(f'Harvested {harvested_count} new agent outcomes to {ledger_file}')
+    if skipped_count > 0:
+        print(f'Skipped {skipped_count} malformed JSONL lines (non-dict scalars)')
     return harvested_count
 
 
@@ -260,6 +342,101 @@ def rotate():
     print(f'Live ledger now has {len(new_ledger) - len(header_lines)} data lines')
 
 
+def append_wave(report_file, wave, phase, timestamp):
+    """Append one row to the ledger from a workflow report JSON.
+
+    Args:
+        report_file: Path to JSON report file
+        wave: Wave number (string or int)
+        phase: Phase name (build|verify|repair)
+        timestamp: ISO 8601 timestamp (must be provided by caller)
+
+    Workflow report shape:
+        {
+            "tokens": {
+                "buildOut": int,
+                "verifyOut": int,
+                "repairOut": int,
+                "totalOut": int,
+                ...
+            },
+            "integration": {
+                "green": bool,
+                ...
+            },
+            ...
+        }
+
+    Returns:
+        Tuple: (success, message)
+    """
+    try:
+        report_path = Path(report_file)
+        if not report_path.exists():
+            return False, f"Report file not found: {report_file}"
+
+        report_text = report_path.read_text(encoding='utf-8')
+        report = json.loads(report_text)
+    except (json.JSONDecodeError, IOError) as e:
+        return False, f"Failed to read/parse report: {e}"
+
+    # Extract data from report with graceful defaults
+    tokens_section = report.get('tokens', {})
+    integration_section = report.get('integration', {})
+
+    # Determine verdict from integration.green
+    is_green = integration_section.get('green', False)
+    verdict = 'OK' if is_green else 'FAILED'
+
+    # Extract tokens_out based on phase
+    phase_key = f'{phase}Out'
+    tokens_out = tokens_section.get(phase_key, 0)
+    try:
+        tokens_out = int(tokens_out) if tokens_out else 0
+    except (ValueError, TypeError):
+        tokens_out = 0
+
+    # Model is always haiku for append-wave
+    model = 'haiku'
+    agent_type = 'waverun'
+
+    # Validate inputs
+    try:
+        wave_num = int(wave) if wave else None
+    except (ValueError, TypeError):
+        return False, f"Invalid wave number: {wave}"
+
+    # Validate and sanitize inputs consistently with append_ledger_line
+    # This ensures idempotency check uses the same values as the actual write
+    try:
+        iso_ts_sanitized = _validate_iso_timestamp(timestamp)
+        if iso_ts_sanitized is None:
+            iso_ts_sanitized = '-'
+    except ValueError as e:
+        return False, f"Invalid timestamp: {e}"
+
+    try:
+        phase_sanitized = _validate_phase(phase)
+    except ValueError as e:
+        return False, f"Invalid phase: {e}"
+
+    # Idempotency check: see if this exact row already exists
+    existing_rows = parse_ledger_rows()
+    for row in existing_rows:
+        if (row['iso_ts'] == iso_ts_sanitized and
+            row['phase'] == phase_sanitized and
+            row['wave'] == wave_num and
+            row['model'] == model):
+            return True, f"Row already exists (wave={wave_num}, phase={phase_sanitized}, ts={iso_ts_sanitized}); skipping"
+
+    # Append the row with validated inputs
+    try:
+        append_ledger_line(timestamp, agent_type, model, 0, 0, tokens_out, verdict, phase, wave_num)
+        return True, f"Appended: wave={wave_num} phase={phase_sanitized} tokens_out={tokens_out} verdict={verdict}"
+    except ValueError as e:
+        return False, f"Failed to append row: {e}"
+
+
 def parse_ledger_rows():
     """Parse and return all ledger rows as structured data.
 
@@ -421,8 +598,33 @@ def main():
         phase = sys.argv[9] if len(sys.argv) > 9 else None
         wave = sys.argv[10] if len(sys.argv) > 10 else None
 
-        append_ledger_line(ts, agent_type, model, dur, ti, to, verdict, phase, wave)
-        print(f'Appended: {ts} {agent_type} {model} {dur}s {ti}->{to} [{verdict}] phase={phase} wave={wave}')
+        try:
+            append_ledger_line(ts, agent_type, model, dur, ti, to, verdict, phase, wave)
+            print(f'Appended: {ts} {agent_type} {model} {dur}s {ti}->{to} [{verdict}] phase={phase} wave={wave}')
+        except ValueError as e:
+            print(f'Error: {e}', file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == 'append-wave':
+        # append-wave --report-file <path> --wave <id> --phase <phase> --timestamp <iso>
+        import argparse
+        parser = argparse.ArgumentParser(description='Append wave outcome to ledger from report JSON')
+        parser.add_argument('--report-file', required=True, help='Path to workflow report JSON')
+        parser.add_argument('--wave', required=True, help='Wave number')
+        parser.add_argument('--phase', required=True, help='Phase name (build|verify|repair)')
+        parser.add_argument('--timestamp', required=True, help='ISO 8601 timestamp')
+
+        try:
+            args = parser.parse_args(sys.argv[2:])
+        except SystemExit:
+            sys.exit(1)
+
+        success, message = append_wave(args.report_file, args.wave, args.phase, args.timestamp)
+        if success:
+            print(message)
+        else:
+            print(message, file=sys.stderr)
+        sys.exit(0 if success else 1)
 
     elif cmd == 'harvest':
         harvest()

package/tools/git_identity_check.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""
+git_identity_check.py — Validate a repo's effective git user.name/user.email.
+
+Validates that a repository's git user identity matches expected values. Can read
+expected values from CLI args (--expect-name/--expect-email) or from an 'identity'
+block in aesop.config.json. Verifies values are physically persisted in .git/config
+(via grep, not just cache).
+
+Usage:
+    python tools/git_identity_check.py --repo <path> --expect-name <name> --expect-email <email> [--mode warn|fail]
+    python tools/git_identity_check.py --repo <path> --config aesop.config.json [--mode warn|fail]
+
+Modes:
+    --mode warn  — Print drift report and exit 0 (default)
+    --mode fail  — Exit 1 if drift detected, exit 0 if matched
+
+Examples:
+    python tools/git_identity_check.py --repo /path/to/repo --expect-name "Matt Culliton" --expect-email "matt82198@gmail.com" --mode fail
+    python tools/git_identity_check.py --repo /path/to/repo --config aesop.config.json --mode fail
+"""
+
+import sys
+import json
+import subprocess
+from pathlib import Path
+from typing import Optional, Tuple, List
+
+
+def get_identity_from_args(args: List[str]) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Parse CLI arguments for --expect-name and --expect-email.
+
+    Args:
+        args: Command line arguments list
+
+    Returns:
+        Tuple of (name, email) where either can be None if not provided
+    """
+    name = None
+    email = None
+
+    i = 0
+    while i < len(args):
+        if args[i] == "--expect-name" and i + 1 < len(args):
+            name = args[i + 1]
+            i += 2
+        elif args[i] == "--expect-email" and i + 1 < len(args):
+            email = args[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    return name, email
+
+
+def get_identity_from_config_file(config_path: str) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Read identity expectations from aesop.config.json 'identity' block.
+
+    Config file format:
+    {
+        "identity": {
+            "user_name": "Expected Name",
+            "user_email": "expected@example.com"
+        }
+    }
+
+    Args:
+        config_path: Path to aesop.config.json
+
+    Returns:
+        Tuple of (name, email) where either can be None if not found
+    """
+    try:
+        config_file = Path(config_path)
+        if not config_file.exists():
+            return None, None
+
+        with open(config_file, "r", encoding="utf-8") as f:
+            config = json.load(f)
+
+        identity = config.get("identity", {})
+        name = identity.get("user_name")
+        email = identity.get("user_email")
+
+        return name, email
+    except (json.JSONDecodeError, IOError, OSError):
+        return None, None
+
+
+def get_git_identity(repo_path: str) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Get current git user.name and user.email via git config command (local scope only).
+
+    Uses: git -C <repo> config --local user.name/user.email
+
+    Only reads from local repo config, not system/global fallback.
+
+    Args:
+        repo_path: Path to git repository
+
+    Returns:
+        Tuple of (name, email) where either can be None if not set
+    """
+    name = None
+    email = None
+
+    try:
+        result = subprocess.run(
+            ["git", "-C", repo_path, "config", "--local", "user.name"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode == 0:
+            name = result.stdout.strip()
+            if not name:
+                name = None
+    except (subprocess.SubprocessError, FileNotFoundError):
+        pass
+
+    try:
+        result = subprocess.run(
+            ["git", "-C", repo_path, "config", "--local", "user.email"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode == 0:
+            email = result.stdout.strip()
+            if not email:
+                email = None
+    except (subprocess.SubprocessError, FileNotFoundError):
+        pass
+
+    return name, email
+
+
+def get_physical_git_identity(repo_path: str) -> Tuple[Optional[str], Optional[str]]:
+    """
+    Read git user identity directly from .git/config file (grep-based, not cache).
+
+    This function bypasses git's config cache to detect if the .git/config file
+    has physically persisted values that differ from what git command reports.
+
+    Args:
+        repo_path: Path to git repository
+
+    Returns:
+        Tuple of (name, email) where either can be None if not found in file
+    """
+    name = None
+    email = None
+
+    git_config = Path(repo_path) / ".git" / "config"
+
+    if not git_config.exists():
+        return None, None
+
+    try:
+        content = git_config.read_text(encoding="utf-8")
+
+        # Parse user.name
+        for line in content.split("\n"):
+            line = line.strip()
+            if line.startswith("name = "):
+                name = line[7:]  # Remove "name = " prefix
+                break
+
+        # Parse user.email
+        for line in content.split("\n"):
+            line = line.strip()
+            if line.startswith("email = "):
+                email = line[8:]  # Remove "email = " prefix
+                break
+
+        return name, email
+    except (IOError, OSError):
+        return None, None
+
+
+def validate_identity(
+    repo_path: str,
+    expected_name: Optional[str] = None,
+    expected_email: Optional[str] = None,
+) -> List[str]:
+    """
+    Validate repo's git identity against expected values.
+
+    Checks both git config cache and physical .git/config file. Returns list of
+    error messages if validation fails (empty list if all checks pass).
+
+    Args:
+        repo_path: Path to git repository
+        expected_name: Expected git user.name (None to skip validation)
+        expected_email: Expected git user.email (None to skip validation)
+
+    Returns:
+        List of error messages (empty if validation passes)
+    """
+    errors = []
+
+    # Get current identity from git config
+    current_name, current_email = get_git_identity(repo_path)
+
+    # Get physical identity from .git/config file
+    physical_name, physical_email = get_physical_git_identity(repo_path)
+
+    # Check for config cache vs physical file drift
+    if current_name != physical_name:
+        errors.append(
+            f"Git config drift for user.name: cache='{current_name}' vs physical='{physical_name}'"
+        )
+    if current_email != physical_email:
+        errors.append(
+            f"Git config drift for user.email: cache='{current_email}' vs physical='{physical_email}'"
+        )
+
+    # Validate against expected values (using physical values as source of truth)
+    if expected_name is not None:
+        if physical_name != expected_name:
+            errors.append(
+                f"user.name mismatch: expected '{expected_name}' but git has '{physical_name}'"
+            )
+
+    if expected_email is not None:
+        if physical_email != expected_email:
+            errors.append(
+                f"user.email mismatch: expected '{expected_email}' but git has '{physical_email}'"
+            )
+
+    return errors
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """
+    Main entry point for git identity check.
+
+    Args:
+        argv: Command line arguments (uses sys.argv[1:] if None)
+
+    Returns:
+        Exit code: 0 on success or --warn, 1 on validation failure in --fail mode
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+
+    # Parse arguments
+    repo_path = None
+    config_path = None
+    mode = "warn"  # default mode
+    expect_name = None
+    expect_email = None
+
+    i = 0
+    while i < len(argv):
+        if argv[i] == "--repo" and i + 1 < len(argv):
+            repo_path = argv[i + 1]
+            i += 2
+        elif argv[i] == "--config" and i + 1 < len(argv):
+            config_path = argv[i + 1]
+            i += 2
+        elif argv[i] == "--mode" and i + 1 < len(argv):
+            mode = argv[i + 1]
+            i += 2
+        elif argv[i] == "--expect-name" and i + 1 < len(argv):
+            expect_name = argv[i + 1]
+            i += 2
+        elif argv[i] == "--expect-email" and i + 1 < len(argv):
+            expect_email = argv[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    # Validate required arguments
+    if not repo_path:
+        print("Error: --repo is required", file=sys.stderr)
+        return 2
+
+    # Read expectations: CLI args take precedence over config file
+    cli_name, cli_email = get_identity_from_args(argv)
+    if cli_name is not None or cli_email is not None:
+        expect_name = cli_name if cli_name is not None else expect_name
+        expect_email = cli_email if cli_email is not None else expect_email
+    elif config_path:
+        config_name, config_email = get_identity_from_config_file(config_path)
+        expect_name = config_name if config_name is not None else expect_name
+        expect_email = config_email if config_email is not None else expect_email
+
+    # If still no expectations, nothing to validate
+    if expect_name is None and expect_email is None:
+        print("Error: Must provide --expect-name/--expect-email or --config", file=sys.stderr)
+        return 2
+
+    # Validate
+    errors = validate_identity(repo_path, expect_name, expect_email)
+
+    # Report results
+    if errors:
+        print(f"Git identity validation failed for {repo_path}:", file=sys.stderr)
+        for error in errors:
+            print(f"  - {error}", file=sys.stderr)
+
+        if mode == "fail":
+            return 1
+        else:  # warn mode
+            return 0
+    else:
+        print(f"Git identity validation passed for {repo_path}")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/health-score.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+/**
+ * Aesop health-score — readiness score for primed projects
+ *
+ * Calculates a weighted 0-100 score based on:
+ * - Config validity (15 points)
+ * - Git pre-push hook installed (15 points)
+ * - CLAUDE.md present (15 points)
+ * - State directory writable (10 points)
+ * - Daemon heartbeats fresh (15 points)
+ * - Git identity configured (15 points)
+ * - Secret-scan runnable (15 points)
+ *
+ * Exit code 0 = success (always produces a score).
+ */
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const pythonScript = path.join(__dirname, 'health_score.py');
+
+// Get arguments: process.argv includes [node, script, health-score, --cwd, .]
+let args = process.argv.slice(2);
+
+// If first arg is 'health-score' (command name), remove it
+if (args[0] === 'health-score') {
+  args = args.slice(1);
+}
+
+const result = spawnSync('python3', [pythonScript, ...args], {
+  stdio: 'inherit',
+  timeout: 30000
+});
+
+if (result.error) {
+  console.error(`Error running health-score: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exitCode = result.status || 0;