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

package/tools/buildlog.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+r"""
+Append uniform BUILDLOG entries with optional git HEAD reference.
+
+Usage:
+    python buildlog.py "<message>" [--state-dir DIR] [--head] [--repo-path PATH]
+
+Purpose:
+    Ensures consistent BUILDLOG.md formatting across agents: one line per entry,
+    timestamped, with optional git HEAD reference. Prevents hand-formatting variance.
+
+Args:
+    message: Entry text to append (positional, required).
+    --state-dir: Path to state directory for BUILDLOG.md (default: AESOP_STATE_ROOT or ./state).
+    --head: Include git HEAD (short-hash subject) from specified repo or current directory.
+    --repo-path: Path to git repo for HEAD extraction (default: current working directory).
+
+Output:
+    Prints the exact line appended to stderr; exit 0 always.
+
+Behavior:
+    - Appends ONE line formatted: ### [YYYY-MM-DD HH:MM] <message>
+    - With --head, appends: | HEAD: <short-hash> <subject>
+    - If repo not found or not a git repo, omits HEAD and notes "(no-repo)".
+    - Creates BUILDLOG.md with append-only header if missing.
+    - Never overwrites; always returns the line appended.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+def get_state_dir():
+    """Resolve state directory from env var or current working directory."""
+    if os.environ.get("AESOP_STATE_ROOT"):
+        return Path(os.environ["AESOP_STATE_ROOT"])
+    # Default to ./state (relative to cwd)
+    return Path.cwd() / "state"
+
+
+def get_git_head(repo_path):
+    """Get short hash and subject from git HEAD.
+
+    Args:
+        repo_path: Path to git repository.
+
+    Returns:
+        Tuple of (short_hash, subject) or (None, None) if not a git repo.
+    """
+    try:
+        if not Path(repo_path / ".git").exists():
+            return None, None
+
+        result = subprocess.run(
+            ["git", "log", "-1", "--pretty=%h %s"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            parts = result.stdout.strip().split(None, 1)
+            if len(parts) == 2:
+                return parts[0], parts[1]
+            elif len(parts) == 1:
+                return parts[0], "(no subject)"
+    except Exception:
+        pass
+
+    return None, None
+
+
+def build_entry_line(message, short_hash=None, subject=None):
+    """Format BUILDLOG entry line.
+
+    Args:
+        message: Entry message.
+        short_hash: Git short hash (optional).
+        subject: Git subject (optional).
+
+    Returns:
+        Formatted entry line.
+    """
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+    line = f"### [{timestamp}] {message}"
+
+    if short_hash and subject:
+        line += f" | HEAD: {short_hash} {subject}"
+    elif short_hash:
+        line += f" | HEAD: {short_hash} (no subject)"
+
+    return line
+
+
+def ensure_buildlog_header(buildlog_path):
+    """Create BUILDLOG.md with header if missing.
+
+    Args:
+        buildlog_path: Path to BUILDLOG.md file.
+    """
+    if buildlog_path.exists():
+        return
+
+    header = "# Build Log (append-only)\n"
+    buildlog_path.parent.mkdir(parents=True, exist_ok=True)
+    buildlog_path.write_text(header)
+
+
+def append_entry(buildlog_path, line):
+    """Append line to BUILDLOG.md.
+
+    Args:
+        buildlog_path: Path to BUILDLOG.md file.
+        line: Entry line to append.
+    """
+    ensure_buildlog_header(buildlog_path)
+
+    with open(buildlog_path, "a", encoding="utf-8") as f:
+        f.write(line + "\n")
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Append uniform BUILDLOG entries with optional git HEAD reference.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("message", help="Entry message to append")
+    parser.add_argument(
+        "--state-dir",
+        default=None,
+        help="Path to state directory (default: AESOP_STATE_ROOT or ./state)",
+    )
+    parser.add_argument(
+        "--head",
+        action="store_true",
+        help="Include git HEAD (short-hash subject) reference",
+    )
+    parser.add_argument(
+        "--repo-path",
+        default=None,
+        help="Path to git repo for HEAD extraction (default: current working directory)",
+    )
+
+    args = parser.parse_args()
+
+    # Resolve state directory
+    if args.state_dir:
+        state_dir = Path(args.state_dir)
+    else:
+        state_dir = get_state_dir()
+
+    # Derive repo path and get git HEAD if requested
+    short_hash = None
+    subject = None
+    repo_note = ""
+
+    if args.head:
+        repo_path = Path(args.repo_path) if args.repo_path else Path.cwd()
+        short_hash, subject = get_git_head(repo_path)
+
+        if not short_hash:
+            repo_note = " (no-repo)"
+
+    # Build and format entry
+    line = build_entry_line(args.message, short_hash, subject)
+
+    # Append to BUILDLOG.md
+    buildlog_path = state_dir / "BUILDLOG.md"
+    append_entry(buildlog_path, line)
+
+    # Print the exact line appended (with repo note if --head requested and failed)
+    output_line = line + repo_note if repo_note else line
+    print(output_line, file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/tools/ci_merge_wait.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""
+ci_merge_wait.py — CI-gated merge helper: wait for PR checks to conclude, then merge.
+
+Polls gh pr view until all status checks conclude (SUCCESS/FAILURE), then merges ONLY
+if all checks are SUCCESS. The gh pr merge call is STRUCTURALLY UNREACHABLE unless the
+status is SUCCESS — this is the whole point (prevents merge-on-CI-failure edge cases).
+
+Usage:
+  python ci_merge_wait.py <PR-number> [--timeout SECONDS] [--poll SECONDS] [--merge-method merge|squash|rebase]
+
+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)
+
+Exit codes:
+  0 = PR merged successfully
+  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.
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+
+
+def run_gh_command(args):
+    """
+    Run gh CLI command; return parsed JSON or None if gh missing/error.
+    Raises subprocess.CalledProcessError on non-zero exit.
+    """
+    try:
+        result = subprocess.run(
+            args,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            if "not found" in result.stderr or "No such file" in result.stderr:
+                return None
+            # Re-raise for non-zero return (will be caught by caller)
+            result.check_returncode()
+        return json.loads(result.stdout) if result.stdout.strip() else None
+    except subprocess.TimeoutExpired:
+        print("ERROR: gh command timed out")
+        sys.exit(1)
+    except FileNotFoundError:
+        print("ERROR: gh CLI not found on PATH")
+        sys.exit(1)
+
+
+def get_pr_status(pr_number):
+    """
+    Fetch PR status via gh pr view.
+    Returns dict with 'mergeable' and 'statusCheckRollup' keys.
+    Returns None if gh is missing.
+    """
+    data = run_gh_command([
+        "gh", "pr", "view", str(pr_number),
+        "--json", "mergeable,statusCheckRollup"
+    ])
+    return data
+
+
+def check_ci_status(status_rollup):
+    """
+    Analyze status check rollup.
+    Returns: ("pending", None), ("success", None), or ("failure", check_name)
+    """
+    if not status_rollup:
+        # No checks (unusual but treat as success)
+        return ("success", None)
+
+    # Collect statuses
+    pending_checks = []
+    failed_checks = []
+
+    for check in status_rollup:
+        status = check.get("status", "").upper()
+        if status == "PENDING":
+            pending_checks.append(check.get("name", "unknown"))
+        elif status == "FAILURE":
+            failed_checks.append(check.get("name", "unknown"))
+
+    # Determine overall status
+    if failed_checks:
+        return ("failure", failed_checks[0])
+    elif pending_checks:
+        return ("pending", None)
+    else:
+        return ("success", None)
+
+
+def merge_pr(pr_number, merge_method):
+    """
+    Merge the PR using gh pr merge.
+    This call is STRUCTURALLY UNREACHABLE unless CI is SUCCESS.
+    Returns True on success, False on error.
+    """
+    result = subprocess.run(
+        ["gh", "pr", "merge", str(pr_number), f"--{merge_method}"],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    return result.returncode == 0
+
+
+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(
+        "--timeout",
+        type=int,
+        default=3600,
+        help="Max seconds to wait for CI (default: 3600)"
+    )
+    parser.add_argument(
+        "--poll",
+        type=int,
+        default=10,
+        help="Poll interval in seconds (default: 10)"
+    )
+    parser.add_argument(
+        "--merge-method",
+        choices=["merge", "squash", "rebase"],
+        default="merge",
+        help="Merge strategy (default: merge)"
+    )
+
+    args = parser.parse_args()
+
+    # Validate inputs
+    if args.pr_number <= 0:
+        print("ERROR: PR number must be positive")
+        sys.exit(1)
+
+    if args.timeout <= 0 or args.poll <= 0:
+        print("ERROR: timeout and poll must be positive")
+        sys.exit(1)
+
+    # Fetch initial PR status
+    print(f"Checking PR #{args.pr_number} status...")
+    status = get_pr_status(args.pr_number)
+    if status is None:
+        print("ERROR: gh CLI not available or PR not found")
+        sys.exit(1)
+
+    mergeable = status.get("mergeable", "").upper()
+    if mergeable == "CONFLICTED":
+        print(f"MERGE CONFLICT: PR #{args.pr_number} has conflicts")
+        sys.exit(4)
+    elif mergeable not in ("MERGEABLE", "UNKNOWN"):
+        # Also treat UNKNOWN conservatively as non-mergeable until we have clarity
+        print(f"NOT MERGEABLE: PR #{args.pr_number} status={mergeable}")
+        sys.exit(4)
+
+    # Poll until CI concludes
+    start_time = time.time()
+    while True:
+        elapsed = time.time() - start_time
+        if elapsed > args.timeout:
+            print(f"TIMEOUT: CI did not conclude within {args.timeout}s")
+            sys.exit(3)
+
+        status = get_pr_status(args.pr_number)
+        if status is None:
+            print("ERROR: gh CLI check failed")
+            sys.exit(1)
+
+        status_rollup = status.get("statusCheckRollup", [])
+        ci_status, failed_check = check_ci_status(status_rollup)
+
+        if ci_status == "failure":
+            print(f"CI FAILED: {failed_check}")
+            sys.exit(2)
+        elif ci_status == "success":
+            # SUCCESS: CI is 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")
+                sys.exit(0)
+            else:
+                print("ERROR: merge failed (PR state changed?)")
+                sys.exit(1)
+
+        # Still pending: wait and retry
+        print(f"CI PENDING ({elapsed:.0f}s elapsed)... waiting {args.poll}s")
+        time.sleep(args.poll)
+
+
+if __name__ == "__main__":
+    main()

package/tools/ensure_state.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""
+Scaffold durable checkpointing directories for project orchestration.
+
+Usage: ensure_state.py --state-dir DIR
+
+Creates STATE.md and BUILDLOG.md templates in the state directory
+if they do not already exist. Never overwrites existing files.
+"""
+# secretscan: allow-pattern-docs
+
+import sys
+import os
+import argparse
+import datetime
+from pathlib import Path
+
+
+STATE_TEMPLATE = """# STATE — authoritative project checkpoint
+
+## Intent
+One-line summary of the project's current phase and goal.
+
+## Stack & locked decisions
+- Key technology choices and constraints.
+- Data model contracts and API signatures.
+
+## Current status
+- Phase summary and completion %.
+- Major blockers or decisions pending.
+
+## Gotchas
+- Known issues, workarounds, environment quirks.
+
+## NEXT STEPS
+- Explicit ordered list of what comes next.
+- Assigned owners if coordinating multiple agents.
+"""
+
+BUILDLOG_HEADER = "# BUILDLOG — append-only progress log"
+
+
+def ensure_state_files(state_dir):
+    """
+    Create state directory with STATE.md and BUILDLOG.md if missing.
+    Returns list of (filename, status) tuples: ('STATE.md', 'CREATED'), etc.
+    """
+    state_path = Path(state_dir)
+    state_path.mkdir(parents=True, exist_ok=True)
+
+    results = []
+
+    # STATE.md
+    state_file = state_path / 'STATE.md'
+    if state_file.exists():
+        results.append(('STATE.md', 'EXISTS'))
+    else:
+        with open(state_file, 'w', encoding='utf-8') as f:
+            f.write(STATE_TEMPLATE)
+        results.append(('STATE.md', 'CREATED'))
+
+    # BUILDLOG.md
+    buildlog_file = state_path / 'BUILDLOG.md'
+    if buildlog_file.exists():
+        results.append(('BUILDLOG.md', 'EXISTS'))
+    else:
+        timestamp = datetime.datetime.now().isoformat()
+        with open(buildlog_file, 'w', encoding='utf-8') as f:
+            f.write(f'{BUILDLOG_HEADER}\n')
+            f.write(f'created {timestamp}\n')
+        results.append(('BUILDLOG.md', 'CREATED'))
+
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Scaffold durable checkpointing directories.'
+    )
+    parser.add_argument('--state-dir', required=True,
+                        help='State directory')
+
+    args = parser.parse_args()
+
+    state_dir = args.state_dir
+
+    results = ensure_state_files(state_dir)
+
+    for filename, status in results:
+        print(f'{status} {filename}')
+
+
+if __name__ == '__main__':
+    main()