gator-command 1.0.0__py3-none-any.whl

gator_command/templates/gator-starter/scripts/gator-approve.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""
+gator-approve.py — Architect-only override approval for blocked commits.
+
+When the pre-commit hook blocks a commit, it writes an override request
+to .gator/override-request.json with a unique block ID. The Architect reviews
+the findings, then runs this script to approve the override.
+
+The agent must NOT run this script. The constitution forbids it.
+Unauthorized self-approval is an auditable governance violation.
+
+Usage:
+    python .gator/scripts/gator-approve.py
+    python .gator/scripts/gator-approve.py --reason "trivial whitespace change"
+    python .gator/scripts/gator-approve.py --reason "bug fix" --name "Architect"
+
+The script reads the pending override request, confirms with the Architect,
+and writes .gator/override-approved.json. The next git commit attempt
+will accept the override if the block IDs match and the approval is
+newer than the request.
+"""
+
+import io
+import json
+import sys
+import time
+from pathlib import Path
+
+
+def _ensure_utf8_stdout():
+    """Ensure stdout uses UTF-8 encoding (needed on Windows)."""
+    if sys.stdout.encoding and sys.stdout.encoding.lower() not in ("utf-8", "utf8"):
+        sys.stdout = io.TextIOWrapper(
+            sys.stdout.buffer, encoding="utf-8", errors="replace"
+        )
+
+
+def find_gator_dir():
+    """Walk up from cwd to find .gator/."""
+    d = Path.cwd().resolve()
+    for _ in range(10):
+        if (d / ".gator").is_dir():
+            return d / ".gator"
+        d = d.parent
+    return None
+
+
+def main():
+    _ensure_utf8_stdout()
+
+    gator_dir = find_gator_dir()
+    if not gator_dir:
+        print("  Error: no .gator/ found.", file=sys.stderr)
+        sys.exit(1)
+
+    request_file = gator_dir / "override-request.json"
+    if not request_file.exists():
+        print("  No pending override request.")
+        print("  Override requests are created when the pre-commit hook blocks a commit.")
+        sys.exit(1)
+
+    request = json.loads(request_file.read_text(encoding="utf-8"))
+    block_id = request.get("block_id", "unknown")
+    failure_type = request.get("failure_type", "unknown")
+    files = request.get("files", [])
+    override_type = request.get("override_type", "charter-skip")
+    timestamp = request.get("timestamp", "unknown")
+
+    print()
+    print("  gator override approval")
+    print()
+    print(f"    Block ID:     {block_id}")
+    print(f"    Failure:      {failure_type}")
+    print(f"    Override:     {override_type}")
+    print(f"    Blocked at:   {timestamp}")
+    if files:
+        print(f"    Files:        {', '.join(files[:5])}")
+    print()
+
+    # Parse --reason and --name from args
+    reason = ""
+    pi_name = ""
+    args = sys.argv[1:]
+    for i, arg in enumerate(args):
+        if arg == "--reason" and i + 1 < len(args):
+            reason = args[i + 1]
+        elif arg == "--name" and i + 1 < len(args):
+            pi_name = args[i + 1]
+
+    # Prompt for missing values
+    if not reason:
+        try:
+            reason = input("  Reason for override (required): ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\n  Cancelled.")
+            sys.exit(1)
+
+    if not reason:
+        print("  Error: reason is required for override approval.")
+        sys.exit(1)
+
+    if not pi_name:
+        try:
+            pi_name = input("  Your name (Architect): ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\n  Cancelled.")
+            sys.exit(1)
+
+    if not pi_name:
+        print("  Error: Architect name is required.")
+        sys.exit(1)
+
+    # Write approval
+    approval = {
+        "block_id": block_id,
+        "override_type": override_type,
+        "approved_by": pi_name,
+        "reason": reason,
+        "approved_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "request_timestamp": timestamp,
+    }
+
+    approved_file = gator_dir / "override-approved.json"
+    approved_file.write_text(
+        json.dumps(approval, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+    print()
+    print(f"  \u2713 Override approved by {pi_name}")
+    print(f"    Block ID: {block_id}")
+    print(f"    Reason: {reason}")
+    print()
+    print("  Now retry: git commit")
+    print()
+
+
+if __name__ == "__main__":
+    main()

gator_command/templates/gator-starter/scripts/gator-enforce.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""
+gator-enforce.py — Set the enforcement level for a Gator-governed repo.
+
+Usage:
+  python gator-enforce.py --level strict|warn|off [--repo /path/to/repo]
+
+Levels:
+  strict  — CRITICAL/HIGH findings block commits (default)
+  warn    — all findings reported but nothing blocks
+  off     — governance checks skipped, trailers still written
+
+Writes to .gator/config.json in the target repo.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+VALID_LEVELS = {"strict", "warn", "off"}
+
+
+def find_gator_dir(repo_path=None):
+    """Find .gator/ directory from the given path or cwd."""
+    start = Path(repo_path) if repo_path else Path.cwd()
+    start = start.resolve()
+
+    if (start / ".gator").is_dir():
+        return start / ".gator"
+    for parent in start.parents:
+        if (parent / ".gator").is_dir():
+            return parent / ".gator"
+    return None
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Set Gator enforcement level")
+    parser.add_argument("--level", required=True, choices=sorted(VALID_LEVELS),
+                        help="Enforcement level: strict, warn, or off")
+    parser.add_argument("--repo", default=None,
+                        help="Path to the repo (default: current directory)")
+    args = parser.parse_args()
+
+    gator_dir = find_gator_dir(args.repo)
+    if not gator_dir:
+        print("Error: No .gator/ directory found.", file=sys.stderr)
+        print("Are you in a Gator-governed repo?", file=sys.stderr)
+        sys.exit(1)
+
+    config_path = gator_dir / "config.json"
+
+    # Read existing config or start fresh
+    config = {}
+    if config_path.exists():
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            config = {}
+
+    old_level = config.get("enforcement_level", "strict")
+    config["enforcement_level"] = args.level
+
+    config_path.write_text(
+        json.dumps(config, indent=2) + "\n", encoding="utf-8"
+    )
+
+    if old_level == args.level:
+        print(f"  Enforcement level unchanged: {args.level}")
+    else:
+        print(f"  Enforcement level: {old_level} -> {args.level}")
+
+    if args.level == "strict":
+        print("  CRITICAL/HIGH findings will block commits.")
+    elif args.level == "warn":
+        print("  Findings will be reported but commits will not be blocked.")
+    else:
+        print("  Governance checks disabled. Trailers still written.")
+
+
+if __name__ == "__main__":
+    main()

gator_command/templates/gator-starter/scripts/gator-init.py

@@ -0,0 +1,434 @@
+#!/usr/bin/env python3
+"""
+gator init — Branded boot sequence for Gator-governed repos.
+
+Detects .gator/ in the current directory (or a specified path), reads
+the knowledge layer, and prints a formatted status display. Designed
+to run at session open in any AI CLI (Claude Code, Codex, Gemini).
+
+Usage:
+    python .gator/scripts/gator-init.py
+    python .gator/scripts/gator-init.py --path /some/repo
+    python .gator/scripts/gator-init.py --json
+
+@reads: .gator/ directory structure, constitution.md, charters/, threads/, command-post.md
+@writes: .git/hooks/ (self-heal only when hooks are missing or stale)
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+from gator_core import (
+    get_version, find_gator_root, ensure_utf8_stdout, GATOR_MARK_LINES,
+    import_sibling,
+)
+
+VERSION = get_version()
+
+TAGLINE = "oriented. the terrain is mapped."
+
+
+# --- Detection and counting ---
+
+def count_constitution_rules(gator_dir):
+    """Count enforceable rules in the constitution.
+
+    Counts numbered list items, table rows with content, and bold-prefixed
+    rules. This is a heuristic — not a parser.
+
+    @reads: .gator/constitution.md
+    """
+    constitution = gator_dir / "constitution.md"
+    if not constitution.exists():
+        return 0
+
+    text = constitution.read_text(encoding="utf-8", errors="replace")
+    count = 0
+
+    for line in text.splitlines():
+        stripped = line.strip()
+        # Numbered steps (1. **Before changing code**: ...)
+        if re.match(r'^\d+\.?\s+\*\*', stripped):
+            count += 1
+        # Bold-prefixed rules (- **BRANCHING**: ...)
+        elif re.match(r'^-\s+\*\*[A-Z]', stripped):
+            count += 1
+        # Standalone bold imperatives (**The agent always asks before committing**)
+        elif re.match(r'^\*\*The (agent|Architect|PI|enforcer)', stripped):
+            count += 1
+
+    return count
+
+
+def count_charters(gator_dir):
+    """Count charter files and estimate mapping coverage.
+
+    @reads: .gator/charters/
+    """
+    charters_dir = gator_dir / "charters"
+    if not charters_dir.is_dir():
+        return 0, 0, 0.0
+
+    skip = {"_template.md", "README.md", "INDEX.md"}
+    charter_files = [
+        f for f in charters_dir.iterdir()
+        if f.suffix == ".md" and f.name not in skip
+    ]
+
+    # Count function entries across all charters (lines starting with ### )
+    function_count = 0
+    for cf in charter_files:
+        text = cf.read_text(encoding="utf-8", errors="replace")
+        for line in text.splitlines():
+            if line.strip().startswith("### ") and "(" in line:
+                function_count += 1
+
+    # Estimate total functions in the repo (count def/func/function declarations)
+    repo_root = gator_dir.parent
+    total_functions = 0
+    for ext in ("*.py", "*.gd", "*.js", "*.ts", "*.go", "*.rs", "*.java"):
+        for code_file in repo_root.rglob(ext):
+            # Skip .gator/ itself
+            if ".gator" in str(code_file):
+                continue
+            try:
+                text = code_file.read_text(encoding="utf-8", errors="replace")
+                for line in text.splitlines():
+                    stripped = line.strip()
+                    if (stripped.startswith("def ") or
+                        stripped.startswith("func ") or
+                        stripped.startswith("function ") or
+                        re.match(r'^(pub\s+)?(fn|func)\s+', stripped) or
+                        re.match(r'^(export\s+)?(async\s+)?function\s+', stripped)):
+                        total_functions += 1
+            except (OSError, UnicodeDecodeError):
+                continue
+
+    coverage = (function_count / total_functions * 100) if total_functions > 0 else 0.0
+
+    return len(charter_files), function_count, coverage
+
+
+def count_working_set(gator_dir):
+    """Count threads and their total line count.
+
+    @reads: .gator/threads/, .gator/active-threads/ (if present)
+    """
+    total_threads = 0
+    total_lines = 0
+
+    for subdir_name in ("active-threads", "threads"):
+        subdir = gator_dir / subdir_name
+        if not subdir.is_dir():
+            continue
+        for f in subdir.iterdir():
+            if f.suffix == ".md" and f.name != ".gitkeep":
+                total_threads += 1
+                try:
+                    total_lines += len(f.read_text(encoding="utf-8", errors="replace").splitlines())
+                except (OSError, UnicodeDecodeError):
+                    pass
+
+    return total_threads, total_lines
+
+
+def detect_enforcer(gator_dir):
+    """Detect enforcer configuration.
+
+    @reads: .gator/scripts/enforcer-prompt.md, .gator/scripts/enforcer-review.py
+    """
+    has_prompt = (gator_dir / "scripts" / "enforcer-prompt.md").exists()
+    has_script = (gator_dir / "scripts" / "enforcer-review.py").exists()
+
+    if has_prompt and has_script:
+        return "ready"
+    elif has_prompt or has_script:
+        return "partial"
+    else:
+        return "not configured"
+
+
+def count_field_guides(gator_dir):
+    """Count field guide languages from pattern files.
+
+    Field guides use two files per language: {lang}-patterns.md and
+    {lang}-tutorial.md. Count languages from pattern files.
+
+    @reads: .gator/field-guides/
+    """
+    guides_dir = gator_dir / "field-guides"
+    if not guides_dir.is_dir():
+        return 0, []
+
+    guides = [
+        f.name.removesuffix("-patterns.md")
+        for f in guides_dir.iterdir()
+        if f.name.endswith("-patterns.md")
+    ]
+    return len(guides), sorted(guides)
+
+
+def detect_command_post(gator_dir):
+    """Check for command-post thin link.
+
+    @reads: .gator/command-post.md
+    """
+    cp_file = gator_dir / "command-post.md"
+    if not cp_file.exists():
+        return None
+
+    text = cp_file.read_text(encoding="utf-8", errors="replace")
+    for line in text.splitlines():
+        if line.startswith("command-post:"):
+            return line.split(":", 1)[1].strip()
+    return "linked"
+
+
+def read_version(gator_dir):
+    """Read generation from .gator-version.
+
+    @reads: .gator/.gator-version
+    """
+    version_file = gator_dir / ".gator-version"
+    if not version_file.exists():
+        return None
+
+    text = version_file.read_text(encoding="utf-8", errors="replace")
+    info = {}
+    for line in text.splitlines():
+        if ":" in line:
+            key, val = line.split(":", 1)
+            info[key.strip()] = val.strip()
+    return info
+
+
+def ensure_git_hooks(repo_root, gator_dir):
+    """Self-heal git hooks at session start.
+
+    Uses gator-update's hook planning and installation logic so there is
+    exactly one definition of what "correctly installed hooks" means.
+    """
+    try:
+        gator_update = import_sibling("gator-update")
+    except ImportError as e:
+        return {
+            "status": "error",
+            "detail": f"hook repair unavailable: {e}",
+            "adds": 0,
+            "updates": 0,
+        }
+    if gator_update is None:
+        return {
+            "status": "error",
+            "detail": "gator-update.py not found",
+            "adds": 0,
+            "updates": 0,
+        }
+
+    if not (repo_root / ".git").exists():
+        return {
+            "status": "unavailable",
+            "detail": "no .git directory",
+            "adds": 0,
+            "updates": 0,
+        }
+
+    # Check that the hook target script exists — without it, hooks can't work
+    # even if they're installed, and plan_hook_updates returns [] (masking the problem).
+    gator_script = gator_dir / "scripts" / "gator-pre-commit.py"
+    if not gator_script.exists():
+        return {
+            "status": "degraded",
+            "detail": "gator-pre-commit.py missing",
+            "adds": 0,
+            "updates": 0,
+        }
+
+    plan = gator_update.plan_hook_updates(gator_dir, repo_root)
+    adds = sum(1 for _, action in plan if action == "add")
+    updates = sum(1 for _, action in plan if action == "update")
+
+    if adds or updates:
+        installed = gator_update.install_git_hooks(gator_dir, repo_root)
+        if updates:
+            detail = f"refreshed ({installed} hooks)"
+            status = "refreshed"
+        else:
+            detail = f"installed ({installed} hooks)"
+            status = "installed"
+    else:
+        detail = "ok"
+        status = "ok"
+
+    return {
+        "status": status,
+        "detail": detail,
+        "adds": adds,
+        "updates": updates,
+    }
+
+
+# --- Output formatting ---
+
+def format_check(label, value, width=16):
+    """Format a single status line."""
+    return f"  \u2713 {label:<{width}}{value}"
+
+
+def print_boot_sequence(repo_root, gator_dir, hook_status):
+    """Print the branded boot sequence.
+
+    @reads: all detection functions above
+    @writes: stdout
+    """
+    repo_name = repo_root.name
+
+    # Header
+    print()
+    for line in GATOR_MARK_LINES:
+        print(f"  {line}")
+    print()
+    print(f"  {VERSION}  ·  navigation coding, governed")
+    print()
+    print(f"  $ gator init")
+    print()
+
+    # Detection
+    print(f"    found .gator/")
+    print()
+
+    # Constitution
+    rule_count = count_constitution_rules(gator_dir)
+    print(format_check("constitution", f"{rule_count} rules in force"))
+
+    # Charters
+    charter_count, func_count, coverage = count_charters(gator_dir)
+    if charter_count > 0:
+        detail = f"{charter_count} modules \u00b7 {func_count} functions documented"
+        print(format_check("charters", detail))
+    else:
+        print(format_check("charters", "empty \u00b7 ready for bootstrap"))
+
+    # Working set
+    thread_count, line_count = count_working_set(gator_dir)
+    if thread_count > 0:
+        print(format_check("working set", f"{thread_count} threads \u00b7 {line_count:,} lines"))
+    else:
+        print(format_check("working set", "empty \u00b7 threads emerge from work"))
+
+    # Field guides (only show when present)
+    guide_count, guide_langs = count_field_guides(gator_dir)
+    if guide_count > 0:
+        lang_list = ", ".join(guide_langs)
+        print(format_check("field guides", f"{guide_count} languages ({lang_list})"))
+
+    # Enforcer
+    enforcer_status = detect_enforcer(gator_dir)
+    print(format_check("enforcer", enforcer_status))
+
+    # Git hooks
+    print(format_check("hooks", hook_status["detail"]))
+
+    # Command post
+    cp = detect_command_post(gator_dir)
+    if cp:
+        print(format_check("command post", "linked"))
+
+    # Tagline
+    print()
+    print(f"  {TAGLINE}")
+    print(f"  \u25b8")
+    print()
+
+
+def print_json(repo_root, gator_dir, hook_status):
+    """Print status as JSON for programmatic consumption."""
+    rule_count = count_constitution_rules(gator_dir)
+    charter_count, func_count, coverage = count_charters(gator_dir)
+    thread_count, line_count = count_working_set(gator_dir)
+    guide_count, guide_langs = count_field_guides(gator_dir)
+    enforcer_status = detect_enforcer(gator_dir)
+    cp = detect_command_post(gator_dir)
+    version_info = read_version(gator_dir)
+
+    data = {
+        "version": VERSION,
+        "repo": repo_root.name,
+        "repo_path": str(repo_root),
+        "constitution_rules": rule_count,
+        "charters": {
+            "modules": charter_count,
+            "functions_mapped": func_count,
+            "coverage_pct": round(coverage, 1),
+        },
+        "working_set": {
+            "threads": thread_count,
+            "lines": line_count,
+        },
+        "field_guides": {
+            "count": guide_count,
+            "languages": guide_langs,
+        },
+        "enforcer": enforcer_status,
+        "hooks": hook_status,
+        "command_post": cp,
+        "gator_version": version_info,
+    }
+
+    print(json.dumps(data, indent=2))
+
+
+def print_not_found():
+    """Print message when .gator/ is not found."""
+    print()
+    for line in GATOR_MARK_LINES:
+        print(f"  {line}")
+    print()
+    print(f"  {VERSION}  ·  navigation coding, governed")
+    print()
+    print("  no .gator/ found.")
+    print()
+    print("  to gatorize this repo:")
+    print("    bash gator-command/scripts/gatorize.sh .")
+    print()
+
+
+# --- Entry point ---
+
+def main():
+    ensure_utf8_stdout()
+
+    parser = argparse.ArgumentParser(
+        description="Gator init — branded boot sequence for governed repos."
+    )
+    parser.add_argument(
+        "--path", "-p",
+        help="Path to search for .gator/ (default: current directory)",
+    )
+    parser.add_argument(
+        "--json", "-j",
+        action="store_true",
+        help="Output as JSON instead of formatted display",
+    )
+    args = parser.parse_args()
+
+    repo_root = find_gator_root(args.path)
+
+    if not repo_root:
+        print_not_found()
+        sys.exit(1)
+
+    gator_dir = repo_root / ".gator"
+    hook_status = ensure_git_hooks(repo_root, gator_dir)
+
+    if args.json:
+        print_json(repo_root, gator_dir, hook_status)
+    else:
+        print_boot_sequence(repo_root, gator_dir, hook_status)
+
+
+if __name__ == "__main__":
+    main()