gator-command 1.0.0__py3-none-any.whl

gator_command/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()

gator_command/scripts/gator-machine-id.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""
+gator-machine-id.py — Stable machine identity for session audit trails.
+
+Generates and stores a persistent machine identifier at ~/.gator/machine-id.
+The ID is a UUID generated once, persists across sessions and repos,
+and is used in session summaries as the "where" pointer for audit trails.
+
+Why not hostname?
+  - Hostnames change (reimages, domain joins, laptop swaps)
+  - Hostnames can be meaningless in enterprise (DESKTOP-NKSU8RO)
+  - Hostnames can collide across machines
+
+The machine-id file also stores a human-readable label that the PI
+can set to make the audit trail legible:
+
+  ~/.gator/machine-id:
+    id: a1b2c3d4-5678-90ab-cdef-1234567890ab
+    hostname: DESKTOP-NKSU8RO
+    label: alan-home-desktop
+    created: 2026-05-30
+
+Usage:
+    python gator-command/scripts/gator-machine-id.py           # show or create
+    python gator-command/scripts/gator-machine-id.py --label "alan-home-desktop"
+    python gator-command/scripts/gator-machine-id.py --json
+
+As a module:
+    from gator_machine_id import get_machine_id
+    mid = get_machine_id()  # {"id": "...", "hostname": "...", "label": "..."}
+
+@reads: ~/.gator/machine-id
+@writes: ~/.gator/machine-id (on first run only, or --label update)
+"""
+
+import argparse
+import json
+import platform
+import sys
+import uuid
+from datetime import date
+from pathlib import Path
+
+
+GATOR_USER_DIR = Path.home() / ".gator"
+MACHINE_ID_FILE = GATOR_USER_DIR / "machine-id"
+
+
+def get_machine_id():
+    """Get or create the stable machine identity.
+
+    Returns dict with id, hostname, label, created.
+    Creates ~/.gator/machine-id on first call.
+    """
+    if MACHINE_ID_FILE.exists():
+        return _read_machine_id()
+
+    # First run — generate and store
+    return _create_machine_id()
+
+
+def _read_machine_id():
+    """Read existing machine-id file."""
+    data = {}
+    try:
+        for line in MACHINE_ID_FILE.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if ":" in line and not line.startswith("#"):
+                key, _, value = line.partition(":")
+                data[key.strip()] = value.strip()
+    except OSError:
+        return _create_machine_id()
+
+    if "id" not in data:
+        return _create_machine_id()
+
+    return data
+
+
+def _create_machine_id():
+    """Generate a new machine-id and write to file."""
+    GATOR_USER_DIR.mkdir(parents=True, exist_ok=True)
+
+    data = {
+        "id": str(uuid.uuid4()),
+        "hostname": platform.node(),
+        "label": platform.node(),  # default label = hostname, PI can change
+        "created": str(date.today()),
+    }
+
+    lines = [
+        f"id: {data['id']}",
+        f"hostname: {data['hostname']}",
+        f"label: {data['label']}",
+        f"created: {data['created']}",
+    ]
+    MACHINE_ID_FILE.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    return data
+
+
+def set_label(new_label):
+    """Update the human-readable label."""
+    data = get_machine_id()
+    data["label"] = new_label
+
+    lines = [
+        f"id: {data['id']}",
+        f"hostname: {data.get('hostname', platform.node())}",
+        f"label: {data['label']}",
+        f"created: {data.get('created', str(date.today()))}",
+    ]
+    MACHINE_ID_FILE.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    return data
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Gator machine identity for session audit trails."
+    )
+    parser.add_argument(
+        "--label", "-l",
+        help="Set a human-readable label for this machine",
+    )
+    parser.add_argument(
+        "--json", "-j",
+        action="store_true",
+        help="Output as JSON",
+    )
+    args = parser.parse_args()
+
+    if args.label:
+        data = set_label(args.label)
+        if args.json:
+            print(json.dumps(data, indent=2))
+        else:
+            print(f"  Machine label set to: {data['label']}")
+            print(f"  ID: {data['id']}")
+    else:
+        data = get_machine_id()
+        if args.json:
+            print(json.dumps(data, indent=2))
+        else:
+            print(f"  Machine ID: {data['id']}")
+            print(f"  Hostname:   {data.get('hostname', '?')}")
+            print(f"  Label:      {data.get('label', '?')}")
+            print(f"  Created:    {data.get('created', '?')}")
+            print(f"  Stored at:  {MACHINE_ID_FILE}")
+
+
+if __name__ == "__main__":
+    main()