gator-command 1.0.0__py3-none-any.whl

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

@@ -0,0 +1,487 @@
+#!/usr/bin/env python3
+"""
+gator_core.py — Shared infrastructure for Gator Command scripts.
+
+Centralizes utilities that were previously duplicated across 6+ scripts:
+version resolution, command-post discovery, registry parsing, path
+normalization, git helpers, and stdout setup.
+
+Usage (automatic — scripts/ is on sys.path when any sibling runs):
+    from gator_core import get_version, find_command_post, parse_registry, git
+
+Not a standalone script — imported by other gator-* scripts.
+
+@reads: filesystem, git tags, registry.md, .gator/command-post.md
+@writes: nothing (pure library)
+"""
+
+import io
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Version
+# ---------------------------------------------------------------------------
+
+def _read_version_file(start=None):
+    """Read VERSION file by walking up from start (or this script's dir)."""
+    d = start or Path(__file__).resolve().parent
+    for _ in range(5):
+        vf = d / "VERSION"
+        if vf.is_file():
+            text = vf.read_text(encoding="utf-8", errors="replace").strip()
+            if text:
+                return f"v{text}" if not text.startswith("v") else text
+        d = d.parent
+    return None
+
+
+def get_version(cwd=None):
+    """Get the current version from git tags, falling back to VERSION file.
+
+    Resolution order:
+        1. git describe --tags --always (exact tag or tag+offset)
+        2. VERSION file (for deployed repos without full git history)
+        3. git rev-parse --short HEAD (bare hash)
+        4. "dev"
+    """
+    if cwd is None:
+        cwd = Path(__file__).resolve().parent
+        for _ in range(5):
+            if (cwd / ".git").is_dir():
+                break
+            cwd = cwd.parent
+
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--always"],
+            capture_output=True, text=True, cwd=cwd, timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            version = result.stdout.strip()
+            if version.startswith("v"):
+                return version
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+    # No tagged version from git — try VERSION file
+    from_file = _read_version_file(cwd)
+    if from_file:
+        return from_file
+
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True, text=True, cwd=cwd, timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return f"dev-g{result.stdout.strip()}"
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+    return "dev"
+
+
+def get_version_short(cwd=None):
+    """Get just the tag version, without commit count or hash.
+
+    Returns "v0.1.0" whether on the tag or after it.
+    Falls back to "dev" if no tags.
+    """
+    version = get_version(cwd)
+    if version.startswith("v"):
+        return version.split("-")[0]
+    return version
+
+
+# ---------------------------------------------------------------------------
+# Path helpers
+# ---------------------------------------------------------------------------
+
+def normalize_path(raw_path):
+    """Normalize MSYS2/Git Bash paths (/c/Users/...) to native Windows.
+
+    Converts /c/Users/... to C:/Users/... for cross-platform compatibility.
+    No-op on paths that don't match the MSYS2 pattern.
+    """
+    if re.match(r'^/[a-zA-Z]/', raw_path):
+        raw_path = raw_path[1].upper() + ":" + raw_path[2:]
+    return raw_path
+
+
+def find_command_post(start_path=None):
+    """Find the gator-command repo root.
+
+    Walks up from start_path looking for a directory containing
+    gator-command/mission.md. Used by command-post scripts (fleet-report,
+    drift, audit, init-command-post).
+    """
+    path = Path(start_path) if start_path else Path.cwd()
+    path = path.resolve()
+
+    if (path / "gator-command" / "mission.md").exists():
+        return path
+    if (path / "mission.md").exists() and (path / "active-threads").is_dir():
+        return path.parent
+    for parent in path.parents:
+        if (parent / "gator-command" / "mission.md").exists():
+            return parent
+    return None
+
+
+def find_gator_root(start_path=None):
+    """Walk up from start_path looking for .gator/ directory.
+
+    Used by per-repo scripts (init, update) to find the governed repo root.
+    """
+    path = Path(start_path) if start_path else Path.cwd()
+    path = path.resolve()
+    if (path / ".gator").is_dir():
+        return path
+    for parent in path.parents:
+        if (parent / ".gator").is_dir():
+            return parent
+    return None
+
+
+def resolve_thin_link(gator_dir):
+    """Read the command-post thin link and resolve the path.
+
+    Used by per-repo scripts (update) to find the command post from
+    a governed repo's .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")
+
+    # Try command-post-absolute first (most reliable on same machine)
+    for line in text.splitlines():
+        if line.startswith("command-post-absolute:"):
+            raw = line.split(":", 1)[1].strip().split("#")[0].strip()
+            if raw:
+                resolved = Path(normalize_path(raw))
+                if resolved.is_dir():
+                    return resolved
+
+    # Fall back to command-post (relative or absolute)
+    for line in text.splitlines():
+        if line.startswith("command-post:") and not line.startswith("command-post-absolute:"):
+            raw = line.split(":", 1)[1].strip()
+            if raw:
+                # Try as relative from repo root
+                resolved = (gator_dir.parent / raw).resolve()
+                if resolved.is_dir():
+                    return resolved
+                # Try as absolute
+                resolved = Path(normalize_path(raw))
+                if resolved.is_dir():
+                    return resolved
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Product source and repo topology
+# ---------------------------------------------------------------------------
+
+def read_product_source(gator_dir):
+    """Read .gator/product-source.json. Returns dict or None if missing/corrupt."""
+    ps_file = Path(gator_dir) / "product-source.json"
+    if not ps_file.exists():
+        return None
+    try:
+        data = json.loads(ps_file.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else None
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def resolve_template_source(gator_dir, source_override=None):
+    """Resolve the template source directory for product updates.
+
+    Resolution order:
+    1. Explicit --source override
+    2. .gator/product-source.json (gator_root + template_dir)
+    3. Thin link -> command post -> templates (legacy fallback)
+    4. None (caller should fail with clear message)
+
+    Returns (template_path, gator_root) or (None, None).
+    """
+    # 1. Explicit override
+    if source_override:
+        root = Path(source_override).resolve()
+        for tpl_rel in ("gator-engine/templates/gator-starter",
+                        "gator-command/templates/gator-starter",
+                        "templates/gator-starter"):
+            tpl = root / tpl_rel
+            if tpl.is_dir():
+                return tpl, root
+        return None, None
+
+    gator_dir = Path(gator_dir)
+
+    # 2. product-source.json
+    ps = read_product_source(gator_dir)
+    if ps:
+        root = Path(ps.get("gator_root", ""))
+        tpl_rel = ps.get("template_dir", "")
+        if root.is_dir() and tpl_rel:
+            tpl = root / tpl_rel
+            if tpl.is_dir():
+                return tpl, root
+
+    # 3. Thin link fallback
+    cp = resolve_thin_link(gator_dir)
+    if cp:
+        for tpl_rel in ("gator-command/templates/gator-starter",
+                        "gator-engine/templates/gator-starter",
+                        "templates/gator-starter"):
+            tpl = Path(cp) / tpl_rel
+            if tpl.is_dir():
+                return tpl, Path(cp)
+
+    return None, None
+
+
+def get_repo_topology(gator_dir):
+    """Derive the governance topology of a repo.
+
+    Returns one of:
+      "policy-synced"  — active thin link, repo receives org policy
+      "standalone"     — no thin link, no policy artifacts, template updates only
+      "inconsistent"   — partial artifacts remain, needs repair
+    """
+    gator_dir = Path(gator_dir)
+    cp_file = gator_dir / "command-post.md"
+    gov_source = gator_dir / "governance-source.json"
+    policy_link = gator_dir / "policy-link.json"
+    policy_cache = gator_dir / "policy-cache"
+
+    has_thin_link = cp_file.exists()
+    has_policy_content = policy_link.exists() or (
+        policy_cache.is_dir() and any(policy_cache.iterdir())
+    )
+    has_gov_source = gov_source.exists()
+
+    # Thin link present and resolvable → policy-synced
+    if has_thin_link:
+        cp = resolve_thin_link(gator_dir)
+        if cp:
+            return "policy-synced"
+        # Thin link exists but points nowhere
+        return "inconsistent"
+
+    # No thin link — check for orphaned policy artifacts
+    if has_policy_content or has_gov_source:
+        return "inconsistent"
+
+    return "standalone"
+
+
+def clear_policy_artifacts(gator_dir):
+    """Remove all policy-source artifacts to make a repo standalone.
+
+    Clears: command-post.md, governance-source.json, policy-link.json, policy-cache/.
+    """
+    import shutil
+    gator_dir = Path(gator_dir)
+
+    for name in ("command-post.md", "governance-source.json", "policy-link.json"):
+        f = gator_dir / name
+        if f.exists():
+            f.unlink()
+
+    cache = gator_dir / "policy-cache"
+    if cache.is_dir():
+        shutil.rmtree(cache)
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+def parse_registry(command_post):
+    """Parse registry.md into a list of repo entries.
+
+    Each entry is a dict with: name, path, remote, registered, status.
+    """
+    registry_file = command_post / "gator-command" / "registry.md"
+    if not registry_file.exists():
+        return []
+
+    repos = []
+    text = registry_file.read_text(encoding="utf-8", errors="replace")
+    in_table = False
+
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("| Repo"):
+            in_table = True
+            continue
+        if stripped.startswith("|---"):
+            continue
+        if in_table and stripped.startswith("|"):
+            cells = [c.strip() for c in stripped.split("|")[1:-1]]
+            if len(cells) >= 5:
+                repos.append({
+                    "name": cells[0],
+                    "path": cells[1],
+                    "remote": cells[2],
+                    "registered": cells[3],
+                    "status": cells[4],
+                })
+
+    return repos
+
+
+# ---------------------------------------------------------------------------
+# Git helpers
+# ---------------------------------------------------------------------------
+
+def git(*args, cwd=None):
+    """Run a git command, return (stdout, success).
+
+    Returns a tuple so callers can distinguish 'git returned nothing'
+    from 'git failed'. Silent emptiness is the wrong failure mode for
+    a product whose claim is trustworthy governance telemetry.
+    """
+    try:
+        result = subprocess.run(
+            ["git"] + list(args),
+            capture_output=True, text=True, cwd=cwd, timeout=10,
+        )
+        return result.stdout.strip(), result.returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return "", False
+
+
+# ---------------------------------------------------------------------------
+# Stdout setup
+# ---------------------------------------------------------------------------
+
+def ensure_utf8_stdout():
+    """Ensure stdout uses UTF-8 encoding (needed on Windows)."""
+    if sys.stdout.encoding != "utf-8":
+        sys.stdout = io.TextIOWrapper(
+            sys.stdout.buffer, encoding="utf-8", errors="replace"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Script import helper
+# ---------------------------------------------------------------------------
+
+def import_sibling(name):
+    """Import a sibling script by filename (handles hyphens).
+
+    Example: import_sibling("gator-fleet-report") imports gator-fleet-report.py
+    from the same directory as the calling script.
+
+    Returns the module on success, None if the file doesn't exist.
+    Raises ImportError with diagnostic context if the file exists but
+    fails to load — callers should catch this if they want resilience.
+    """
+    import importlib.util
+
+    scripts_dir = Path(__file__).resolve().parent
+    path = scripts_dir / f"{name}.py"
+    if not path.exists():
+        return None
+
+    spec = importlib.util.spec_from_file_location(
+        name.replace("-", "_"), path
+    )
+    mod = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(mod)
+    except Exception as e:
+        raise ImportError(
+            f"Failed to load {path.name}: {type(e).__name__}: {e}"
+        ) from e
+    return mod
+
+
+# ---------------------------------------------------------------------------
+# Charter surface resolution
+# ---------------------------------------------------------------------------
+
+def resolve_charter_surface(repo_root=None):
+    """Return the authoritative charter surface for this repo.
+
+    Two modes:
+    - source-command-post: the gator-command development repo.
+      Charters at gator-command/charters/, cross-cutting is
+      scripts-cross-cutting.md.
+    - governed-repo: all other repos (fleet repos, deployed command posts).
+      Charters at .gator/charters/, cross-cutting is cross-cutting.md.
+
+    Returns dict with:
+      mode: "source-command-post" | "governed-repo"
+      charter_dir: Path to authoritative charter directory
+      cross_cutting: filename of the cross-cutting charter (or None)
+      index_file: Path to INDEX.md (or None if absent)
+    """
+    if repo_root is None:
+        repo_root = Path.cwd()
+    else:
+        repo_root = Path(repo_root)
+
+    # Detect source-command-post mode: gator-command/charters/ AND
+    # gator-command/scripts/ both exist. This is the development repo.
+    cp_charters = repo_root / "gator-command" / "charters"
+    cp_scripts = repo_root / "gator-command" / "scripts"
+    if cp_charters.is_dir() and cp_scripts.is_dir():
+        cross_cutting = None
+        for f in cp_charters.iterdir():
+            if "cross-cutting" in f.name and f.suffix == ".md":
+                cross_cutting = f.name
+                break
+        index_file = cp_charters / "INDEX.md"
+        return {
+            "mode": "source-command-post",
+            "charter_dir": cp_charters,
+            "cross_cutting": cross_cutting,
+            "index_file": index_file if index_file.is_file() else None,
+        }
+
+    # Default: governed-repo mode
+    charter_dir = repo_root / ".gator" / "charters"
+    cross_cutting = None
+    if charter_dir.is_dir():
+        for f in charter_dir.iterdir():
+            if "cross-cutting" in f.name and f.suffix == ".md":
+                cross_cutting = f.name
+                break
+    index_file = charter_dir / "INDEX.md"
+    return {
+        "mode": "governed-repo",
+        "charter_dir": charter_dir,
+        "cross_cutting": cross_cutting,
+        "index_file": index_file if index_file.is_file() else None,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Branding
+# ---------------------------------------------------------------------------
+
+# Template generation — single source of truth for Python scripts.
+# gatorize.sh reads this value at runtime via grep.
+# Gen 0: pre-gatorize.sh installs (no command-post.md, no .gator-version)
+# Gen 1: first gatorize.sh installs (has command-post.md, no .gator-version)
+# Gen 2: current (has .gator-version, overlay-not-replace upgrade logic)
+CURRENT_GENERATION = 2
+
+GATOR_MARK_LINES = [
+    r"  ....    .  .....  ...  ....  ",
+    r" / ___|  / \|_   _|/ _ \|  _ \    ....  ",
+    r"| |  _  / _ \ | | | | | | |_) | ./( o )\_______",
+    r"| |_/ \/ /_\ \| | | |_| |  _ <       _/vVvVvVvV",
+    r" \____/m/   \m\_|  \___/|m| \m\  \__.---------",
+]

gator_command/templates/gator-starter/scripts/hooks/commit-msg

@@ -0,0 +1,5 @@
+#!/bin/bash
+# Gator commit-msg hook — appends Gator-* trailers to the commit message.
+# Installed by gatorize.sh. Do not edit manually.
+
+python .gator/scripts/gator-pre-commit.py --phase trailers "$1"

gator_command/templates/gator-starter/scripts/hooks/post-commit

@@ -0,0 +1,7 @@
+#!/bin/bash
+# Gator post-commit hook — resets commit_draft.md after successful commit.
+# Installed by gatorize.sh. Do not edit manually.
+#
+# Cleanup now runs in Python so the shell wrapper stays minimal.
+
+python .gator/scripts/gator-pre-commit.py --phase cleanup

gator_command/templates/gator-starter/scripts/hooks/pre-commit

@@ -0,0 +1,5 @@
+#!/bin/bash
+# Gator pre-commit hook — deterministic governance gate.
+# Installed by gatorize.sh. Do not edit manually.
+
+python .gator/scripts/gator-pre-commit.py --phase validate

gator_command/templates/gator-starter/sessions/.gitignore

@@ -0,0 +1,7 @@
+# Rolling active session ledgers are local working artifacts.
+# They are NOT committed — only session snippets and summaries are git-tracked.
+_active/
+
+# NOTE: .gator/session-snippets/ is NOT gitignored. Snippets are durable
+# commit-linked artifacts that MUST be committed. They provide the traceability
+# bridge between session history and git history.

gator_command/templates/gator-starter/whiteboard.md

@@ -0,0 +1,5 @@
+
+
+## Review — 2026-06-04 15:31 UTC — enforcer-review.py (Layer 1)
+
+Enforcer review: clean. No findings.

gator_command-1.0.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: gator-command
+Version: 1.0.0
+Summary: Git-native governance for AI-assisted engineering
+Author-email: Cumberland Laboratories <support@cumberlandlaboratories.com>
+License: MIT
+Project-URL: Homepage, https://github.com/cumberland-laboratories/gator
+Project-URL: Repository, https://github.com/cumberland-laboratories/gator
+Keywords: governance,ai,git,charters,audit,compliance
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Gator Command
+
+The command post for [Gator](https://github.com/cumberland-laboratories/gator) — AI-assisted engineering governance.
+
+## How to Use This Repo
+
+**Open it in an AI coding assistant.** Claude Code, Codex, Gemini CLI, Cursor — whichever you use. The agent reads the constitution and acts as your concierge: it knows the architecture, the configuration options, the procedures, and the fleet state. Ask it what you need.
+
+Gator is designed to be operated *with* an AI agent, not studied as documentation. The governance layer is markdown that agents read natively. The concierge layer routes your questions to the right procedures and reference material. The agent is the interface.
+
+```
+You: "gator init"
+You: "Gatorize my project at ~/code/my-app"
+You: "Set up an enforcer using GPT as the reviewer"
+You: "Check if the charters still match the code"
+You: "What's the status of the fleet?"
+```
+
+## What Gator Does
+
+Gator governs AI-assisted coding. It keeps human comprehension synchronized with AI-generated code through constitutions, module charters, deterministic commit gates, and cross-model enforcement.
+
+### Use Cases
+
+**Solo developer with one repo** — You want the AI agent to maintain a map of your codebase (charters), enforce that the map stays current (commit gate), and preserve session context across conversations (knowledge layer). Install Gator, bootstrap charters, and the loop runs from there.
+
+**Solo developer with multiple repos** — Same as above, plus: this command post becomes your cross-repo control plane. One org policy propagated to every repo. Fleet status, drift detection, and audit dashboards from one place.
+
+**Team with shared repos** — Gator's knowledge layer travels with the repo via git. When a teammate (human or AI) opens the repo, they get the full architectural context — mission, charters, threads, decisions. The enforcer provides independent review from a different model than the one writing code.
+
+**Compliance and audit** — Every commit carries `Gator-*` trailers (change type, significance, charter status, agent identity). Session summaries provide durable evidence of what was decided and who was supervising. Fleet-wide audit reports aggregate governance health across repos.
+
+### Configurations
+
+Gator is model-neutral and modular. The PI chooses the configuration that fits their stack:
+
+| Decision | Options |
+|----------|---------|
+| **Primary agent** | Claude Code, Codex CLI, Gemini CLI, Cursor, any markdown-aware AI tool |
+| **Enforcer model** | Anthropic Sonnet, OpenAI GPT, Google Gemini, local via Ollama, or none |
+| **Review cadence** | Light (lint only), Standard (lint + model review on significant changes), Rigorous (pre-code + post-code review) |
+| **Fleet scope** | Single repo (no command post needed), multi-repo (this command post), remote repos (bare cache scanning) |
+| **Session archaeology** | Off, local spool, committed summaries (git-tracked audit trail) |
+
+The concierge agent walks you through these choices. You don't need to read configuration docs — tell the agent what you want and it configures the system.
+
+## Quick Start
+
+```bash
+# Gatorize an existing project repo
+bash gator-command/scripts/gatorize.sh /path/to/your/project
+
+# Then open that project in your AI assistant — the concierge bootstrap begins
+```
+
+For fleet operations (from within this command post):
+```bash
+# Fleet status
+python gator-command/scripts/gator-fleet-report.py
+
+# Policy drift across all governed repos
+python gator-command/scripts/gator-drift.py
+
+# Audit dashboard
+python gator-command/scripts/gator-audit.py
+```
+
+## Architecture at a Glance
+
+```
+This repo (command post):
+  constitution.md          Governance rules for this command post
+  gator-command/           Knowledge graph + machinery + fleet tooling
+    scripts/               CLI tooling (gatorize, fleet-report, drift, audit)
+    templates/             Starter kit deployed to project repos
+    procedures/            Standards and workflows
+    reference-notes/       Concierge knowledge (the agent reads these)
+
+Each governed repo:
+  .gator/
+    constitution.md        Per-repo governance rules
+    charters/              Module maps (the intelligent codebase layer)
+    scripts/               Hooks + enforcer
+    field-guides/          Language pattern references (optional)
+    command-post.md        Thin link back to this command post
+```
+
+## Multi-Model Architecture
+
+The constitutions are the interface contract. Any model that reads markdown and follows instructions can operate the system.
+
+- **Primary agent**: Reads charters, writes code, updates the knowledge layer
+- **Enforcer**: Different model, read-only, audits the agent's work against charters
+- **The architecture outlives any individual model** — switch tools mid-project without losing context
+
+## License
+
+MIT — [Cumberland Laboratories](https://github.com/cumberland-laboratories)