gator-command 1.0.0__py3-none-any.whl

gator_command/scripts/gator-update.py

@@ -0,0 +1,615 @@
+#!/usr/bin/env python3
+"""
+gator update — Refresh templates from the command post.
+
+Reads the command-post thin link to find the gator-command repo, then
+overlays template-derived files (constitution, procedures, scripts,
+reference-notes, charter templates) from the gator-starter template
+into the current repo's .gator/. User content (charters, threads,
+artifacts, mission, roadmap, inbox, etc.) is never touched.
+
+Overlay-not-replace: template files overwrite same-named files; files
+that exist only in the target are left untouched.
+
+Usage:
+    python .gator/scripts/gator-update.py              # interactive
+    python .gator/scripts/gator-update.py --dry-run     # show what would change
+    python .gator/scripts/gator-update.py --json         # output plan as JSON
+
+@reads: .gator/command-post.md, gator-command/templates/gator-starter/
+@writes: .gator/ template-derived files (overlay, never deletes)
+@does-not-own: user content (charters, threads, artifacts, mission, roadmap, etc.)
+"""
+
+import argparse
+import filecmp
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from gator_core import (
+    get_version, find_gator_root, normalize_path, resolve_thin_link,
+    ensure_utf8_stdout, git, import_sibling,
+    resolve_template_source, read_product_source, get_repo_topology,
+)
+
+VERSION = get_version()
+
+# Policy sync integration — graceful degradation if module unavailable
+try:
+    _ps = import_sibling("gator-policy-status")
+    if _ps:
+        _sync_policy = _ps.sync_policy
+        _get_governance_source = _ps.get_governance_source
+        _init_governance_source = _ps.init_governance_source
+        _HAS_POLICY_STATUS = True
+    else:
+        _HAS_POLICY_STATUS = False
+except Exception:
+    _HAS_POLICY_STATUS = False
+
+# Files that are template-derived (safe to overwrite)
+TEMPLATE_FILES = [
+    "constitution.md",
+    "gator-start-up.md",
+]
+
+# Dotfiles that need renaming from template (stored without dot to avoid git issues)
+TEMPLATE_DOTFILES = {
+    "charterignore": ".charterignore",
+}
+
+# Directories where templates overlay (add/update, never delete)
+TEMPLATE_DIRS = {
+    "procedures": "procedures",
+    "reference-notes": "reference-notes",
+    "scripts": "scripts",
+    "sessions": "sessions",
+}
+
+# Charter scaffolding files (not user charters)
+CHARTER_TEMPLATE_FILES = ["README.md", "_template.md"]
+
+# Blueprint scaffolding files (not user blueprints)
+BLUEPRINT_TEMPLATE_FILES = ["README.md"]
+
+# Slash commands
+CLAUDE_COMMANDS_DIR = "commands"
+
+
+# --- Path resolution ---
+
+
+def find_templates(command_post):
+    """Find the gator-starter template directory in the command post.
+
+    Checks both gator-command/ (dev layout) and gator-engine/ (public
+    distribution layout).
+    """
+    for parent_dir in ["gator-command", "gator-engine"]:
+        templates = command_post / parent_dir / "templates" / "gator-starter"
+        if templates.is_dir():
+            return templates
+    return None
+
+
+# --- Diff and overlay ---
+
+def plan_file_update(src, dest):
+    """Compare a template file to the installed version.
+
+    Returns: (action, src, dest) where action is 'add', 'update', 'unchanged', or 'skip'
+    """
+    if not dest.exists():
+        return "add", src, dest
+    if filecmp.cmp(src, dest, shallow=False):
+        return "unchanged", src, dest
+    return "update", src, dest
+
+
+def plan_updates(templates_dir, gator_dir, repo_root):
+    """Build the full update plan.
+
+    @reads: templates_dir, gator_dir
+    @does-not-own: executing the updates
+    """
+    plan = []
+
+    # Top-level template files
+    for filename in TEMPLATE_FILES:
+        src = templates_dir / filename
+        dest = gator_dir / filename
+        if src.exists():
+            plan.append(plan_file_update(src, dest))
+
+    # Dotfiles (stored without dot in template, installed with dot)
+    for src_name, dest_name in TEMPLATE_DOTFILES.items():
+        src = templates_dir / src_name
+        dest = gator_dir / dest_name
+        if src.exists():
+            plan.append(plan_file_update(src, dest))
+
+    # Charter scaffolding
+    for filename in CHARTER_TEMPLATE_FILES:
+        src = templates_dir / "charters" / filename
+        dest = gator_dir / "charters" / filename
+        if src.exists():
+            plan.append(plan_file_update(src, dest))
+
+    # Blueprint scaffolding
+    for filename in BLUEPRINT_TEMPLATE_FILES:
+        src = templates_dir / "blueprints" / filename
+        dest = gator_dir / "blueprints" / filename
+        if src.exists():
+            plan.append(plan_file_update(src, dest))
+
+    # Template directories (overlay)
+    # Note: no mkdir here — plan_updates is read-only. Directories are
+    # created by execute_updates() when files are actually written.
+    for src_subdir, dest_subdir in TEMPLATE_DIRS.items():
+        src_dir = templates_dir / src_subdir
+        dest_dir = gator_dir / dest_subdir
+        if not src_dir.is_dir():
+            continue
+        for src_file in sorted(src_dir.iterdir()):
+            if src_file.is_file():
+                dest_file = dest_dir / src_file.name
+                plan.append(plan_file_update(src_file, dest_file))
+
+    # Nested template subdirectories (e.g., scripts/hooks/)
+    for src_subdir, dest_subdir in TEMPLATE_DIRS.items():
+        src_dir = templates_dir / src_subdir
+        if not src_dir.is_dir():
+            continue
+        for sub in sorted(src_dir.iterdir()):
+            if sub.is_dir():
+                dest_sub = gator_dir / dest_subdir / sub.name
+                for src_file in sorted(sub.iterdir()):
+                    if src_file.is_file():
+                        dest_file = dest_sub / src_file.name
+                        plan.append(plan_file_update(src_file, dest_file))
+
+    # Claude Code slash commands
+    src_commands = templates_dir / CLAUDE_COMMANDS_DIR
+    if src_commands.is_dir():
+        dest_commands = repo_root / ".claude" / "commands"
+        for src_file in sorted(src_commands.iterdir()):
+            if src_file.is_file():
+                dest_file = dest_commands / src_file.name
+                plan.append(plan_file_update(src_file, dest_file))
+
+    return plan
+
+
+def get_command_post_policy_date(command_post):
+    """Return the policy date from the command post's org-policy.md git history.
+
+    Uses the same logic as gator-drift.py: last commit date of org-policy.md,
+    falling back to None if git fails.
+    """
+    policy_date, ok = git(
+        "log", "-1", "--format=%ci", "--", "gator-command/org-policy.md",
+        cwd=command_post,
+    )
+    if ok and policy_date:
+        return policy_date[:10]  # YYYY-MM-DD
+    return None
+
+
+def bump_policy_version(gator_dir, command_post):
+    """Update the version: field in .gator/command-post.md to match the
+    command post's current org-policy.md date.
+
+    Returns (new_version, changed) where changed is True if the file was
+    actually rewritten, False if it was already current or could not be read.
+
+    @reads: command post git history (org-policy.md last commit date)
+    @writes: .gator/command-post.md (version: line only)
+    """
+    policy_date = get_command_post_policy_date(command_post)
+    if not policy_date:
+        return None, False
+
+    cp_file = gator_dir / "command-post.md"
+    if not cp_file.exists():
+        return policy_date, False
+
+    text = cp_file.read_text(encoding="utf-8", errors="replace")
+    lines = text.splitlines(keepends=True)
+    new_lines = []
+    changed = False
+    for line in lines:
+        if line.startswith("version:"):
+            current = line.split(":", 1)[1].strip().rstrip("\n")
+            if current != policy_date:
+                new_lines.append(f"version: {policy_date}\n")
+                changed = True
+            else:
+                new_lines.append(line)
+        else:
+            new_lines.append(line)
+
+    if changed:
+        cp_file.write_text("".join(new_lines), encoding="utf-8")
+
+    return policy_date, changed
+
+
+def execute_updates(plan):
+    """Execute the update plan — copy files that need adding or updating.
+
+    @writes: .gator/ template-derived files
+    @does-not-own: user content
+    """
+    added = 0
+    updated = 0
+    unchanged = 0
+
+    for action, src, dest in plan:
+        if action == "add":
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dest)
+            added += 1
+        elif action == "update":
+            shutil.copy2(src, dest)
+            updated += 1
+        else:
+            unchanged += 1
+
+    return added, updated, unchanged
+
+
+def plan_hook_updates(gator_dir, repo_root):
+    """Plan git hook installations. Returns list of (hook_name, action).
+
+    Compares the generated cross-platform Python wrappers to the current
+    .git/hooks/ contents. This matches what install_git_hooks() actually
+    writes, so the plan is accurate on both Unix and Windows.
+    """
+    git_hooks = repo_root / ".git" / "hooks"
+    gator_script = gator_dir / "scripts" / "gator-pre-commit.py"
+
+    if not git_hooks.parent.is_dir() or not gator_script.exists():
+        return []
+
+    expected_hooks = build_git_hook_wrappers()
+    results = []
+    for hook_name, expected_content in sorted(expected_hooks.items()):
+        dest = git_hooks / hook_name
+        if not dest.exists():
+            results.append((hook_name, "add"))
+            continue
+        actual = dest.read_text(encoding="utf-8", errors="replace")
+        if actual != expected_content:
+            results.append((hook_name, "update"))
+        else:
+            results.append((hook_name, "unchanged"))
+
+    return results
+
+
+def _hook_shebang():
+    """Return the platform-correct shebang for hook wrappers.
+
+    Windows: `python` — the standard executable name; `python3` often absent.
+    Unix: `python3` — the guaranteed Python 3 command; `python` may be absent
+    or point to Python 2 on older systems.
+    """
+    return "#!/usr/bin/env python" if os.name == "nt" else "#!/usr/bin/env python3"
+
+
+def build_git_hook_wrappers():
+    """Return the exact hook wrapper contents gator installs.
+
+    Shebang uses env dispatch (platform-selected) so hook launch works even
+    when sys.executable contains spaces (e.g. C:/Program Files/Python313/).
+    The subprocess.call inside uses the exact interpreter path — spaces are
+    safe there because it's a Python string argument, not a shebang.
+    """
+    python_path = sys.executable.replace("\\", "/")
+    gator_script = ".gator/scripts/gator-pre-commit.py"
+    shebang = _hook_shebang()
+
+    return {
+        "pre-commit": (
+            f'{shebang}\n'
+            'import subprocess, sys\n'
+            f'sys.exit(subprocess.call([r"{python_path}", "{gator_script}", "--phase", "validate"]))\n'
+        ),
+        "commit-msg": (
+            f'{shebang}\n'
+            'import subprocess, sys\n'
+            f'sys.exit(subprocess.call([r"{python_path}", "{gator_script}", "--phase", "trailers", sys.argv[1]]))\n'
+        ),
+        "post-commit": (
+            f'{shebang}\n'
+            'import subprocess, sys\n'
+            f'sys.exit(subprocess.call([r"{python_path}", "{gator_script}", "--phase", "cleanup"]))\n'
+        ),
+    }
+
+
+def install_git_hooks(gator_dir, repo_root):
+    """Install/refresh git hooks as cross-platform Python wrappers.
+
+    Writes Python-shebang hooks that call gator-pre-commit.py directly.
+    Works on Windows CMD/PowerShell (no bash dependency) and Unix.
+
+    @writes: .git/hooks/pre-commit, .git/hooks/commit-msg, .git/hooks/post-commit
+    """
+    git_hooks = repo_root / ".git" / "hooks"
+    if not git_hooks.parent.is_dir():
+        return 0
+
+    git_hooks.mkdir(parents=True, exist_ok=True)
+    installed = 0
+
+    for name, content in build_git_hook_wrappers().items():
+        dest = git_hooks / name
+        dest.write_text(content, encoding="utf-8")
+        try:
+            import stat
+            dest.chmod(dest.stat().st_mode | stat.S_IEXEC)
+        except (OSError, AttributeError):
+            pass
+        installed += 1
+
+    return installed
+
+
+# --- Output ---
+
+def print_plan(plan, dry_run=False, hooks=None):
+    """Print the update plan."""
+    adds = [(a, s, d) for a, s, d in plan if a == "add"]
+    updates = [(a, s, d) for a, s, d in plan if a == "update"]
+    unchanged = [(a, s, d) for a, s, d in plan if a == "unchanged"]
+
+    hook_adds = [h for h in (hooks or []) if h[1] == "add"]
+    hook_updates = [h for h in (hooks or []) if h[1] == "update"]
+
+    mode = " (dry run)" if dry_run else ""
+    print()
+    print(f"  gator update{mode}")
+    print()
+
+    if adds:
+        print(f"  New files ({len(adds)}):")
+        for _, _, dest in adds:
+            print(f"    + {dest.name}")
+        print()
+
+    if updates:
+        print(f"  Updated files ({len(updates)}):")
+        for _, _, dest in updates:
+            print(f"    ~ {dest.name}")
+        print()
+
+    if hook_adds or hook_updates:
+        print(f"  Git hooks ({len(hook_adds)} new, {len(hook_updates)} updated):")
+        for name, action in (hooks or []):
+            if action == "add":
+                print(f"    + .git/hooks/{name}")
+            elif action == "update":
+                print(f"    ~ .git/hooks/{name}")
+        print()
+
+    if not adds and not updates and not hook_adds and not hook_updates:
+        print(f"  Everything is current. No updates needed.")
+        print()
+        return
+
+    print(f"  Unchanged: {len(unchanged)} files")
+    print(f"  Total: {len(adds)} new, {len(updates)} updated, {len(unchanged)} unchanged")
+    print()
+
+
+def print_result(added, updated, unchanged):
+    """Print the result after executing updates."""
+    print(f"  Done: {added} added, {updated} updated, {unchanged} unchanged")
+    print()
+
+
+def print_json_plan(plan, command_post, templates_dir, hooks=None):
+    """Output the plan as JSON."""
+    items = []
+    for action, src, dest in plan:
+        items.append({
+            "action": action,
+            "source": str(src),
+            "destination": str(dest),
+            "filename": dest.name,
+        })
+
+    hook_items = []
+    for name, action in (hooks or []):
+        hook_items.append({
+            "hook": name,
+            "action": action,
+            "destination": f".git/hooks/{name}",
+        })
+
+    output = {
+        "version": VERSION,
+        "command_post": str(command_post),
+        "templates": str(templates_dir),
+        "plan": items,
+        "hooks": hook_items,
+        "summary": {
+            "add": sum(1 for i in items if i["action"] == "add"),
+            "update": sum(1 for i in items if i["action"] == "update"),
+            "unchanged": sum(1 for i in items if i["action"] == "unchanged"),
+            "hooks_add": sum(1 for h in hook_items if h["action"] == "add"),
+            "hooks_update": sum(1 for h in hook_items if h["action"] == "update"),
+        }
+    }
+    print(json.dumps(output, indent=2))
+
+
+# --- Entry point ---
+
+def main():
+    ensure_utf8_stdout()
+
+    parser = argparse.ArgumentParser(
+        description="Gator update — refresh templates and optionally sync org policy."
+    )
+    parser.add_argument(
+        "--dry-run", "-n",
+        action="store_true",
+        help="Show what would be updated without changing anything"
+    )
+    parser.add_argument(
+        "--json", "-j",
+        action="store_true",
+        help="Output update plan as JSON"
+    )
+    parser.add_argument(
+        "--path", "-p",
+        help="Path to search for .gator/ (default: current directory)"
+    )
+    parser.add_argument(
+        "--source", "-s",
+        help="Path to the Gator clone (rebinds product-source.json)"
+    )
+    parser.add_argument(
+        "--no-policy",
+        action="store_true",
+        help="Skip org-policy sync (channel 1 template updates only)"
+    )
+    args = parser.parse_args()
+
+    # Find the repo
+    repo_root = find_gator_root(args.path)
+    if not repo_root:
+        print("  Error: no .gator/ found. Run from a gatorized repo.", file=sys.stderr)
+        sys.exit(1)
+
+    gator_dir = repo_root / ".gator"
+
+    # Channel 1: resolve template source (product-source.json, --source, or thin link fallback)
+    templates_dir, gator_root = resolve_template_source(gator_dir, args.source)
+    if not templates_dir:
+        ps = read_product_source(gator_dir)
+        stale_path = ps.get("gator_root", "?") if ps else "not configured"
+        print(f"  Error: product template source not found.", file=sys.stderr)
+        print(f"  Last known source: {stale_path}", file=sys.stderr)
+        print(f"  Run: gator update --source /path/to/gator   to rebind", file=sys.stderr)
+        sys.exit(1)
+
+    # Update product-source.json if --source was given (rebind)
+    if args.source:
+        import json as _json
+        ps_file = gator_dir / "product-source.json"
+        tpl_rel = str(templates_dir.relative_to(gator_root))
+        ps_data = {
+            "gator_root": str(gator_root),
+            "template_dir": tpl_rel,
+            "installed": "",
+            "updated": "",
+        }
+        # Preserve installed date if existing
+        old_ps = read_product_source(gator_dir)
+        if old_ps:
+            ps_data["installed"] = old_ps.get("installed", "")
+        from datetime import date
+        ps_data["updated"] = str(date.today())
+        if not ps_data["installed"]:
+            ps_data["installed"] = ps_data["updated"]
+        ps_file.write_text(_json.dumps(ps_data, indent=2) + "\n", encoding="utf-8")
+        print(f"  Product source rebound to: {gator_root}")
+
+    # Channel 2: resolve command post for policy sync (only if policy-synced)
+    command_post = resolve_thin_link(gator_dir)
+    topology = get_repo_topology(gator_dir)
+
+    # Build plan
+    plan = plan_updates(templates_dir, gator_dir, repo_root)
+
+    # Plan git hook installation
+    hooks_to_install = plan_hook_updates(gator_dir, repo_root)
+
+    # JSON mode
+    if args.json:
+        print_json_plan(plan, command_post, templates_dir, hooks_to_install)
+        return
+
+    # Dry run
+    if args.dry_run:
+        print_plan(plan, dry_run=True, hooks=hooks_to_install)
+        return
+
+    # Execute
+    print_plan(plan, hooks=hooks_to_install)
+    added, updated, unchanged = execute_updates(plan)
+
+    # Install/refresh git hooks
+    hooks_installed = install_git_hooks(gator_dir, repo_root)
+    if hooks_installed > 0:
+        print(f"  Git hooks: {hooks_installed} installed/refreshed")
+
+    # Channel 2: policy sync (only for policy-synced repos, unless --no-policy)
+    if args.no_policy:
+        pass  # Skip channel 2 entirely
+    elif topology == "policy-synced" and command_post:
+        # Bump policy version in command-post.md
+        policy_date, bumped = bump_policy_version(gator_dir, command_post)
+        if bumped:
+            print(f"  Policy version: bumped to {policy_date}")
+
+        # Sync policy cache from source
+        if _HAS_POLICY_STATUS:
+            try:
+                source, is_derived = _get_governance_source(gator_dir)
+                if not source:
+                    pass
+                else:
+                    if is_derived:
+                        init_result = _init_governance_source(gator_dir, source)
+                        if init_result.get("status") == "ok":
+                            print(f"  Policy source: created governance-source.json")
+                            source, _ = _get_governance_source(gator_dir)
+
+                    result = _sync_policy(gator_dir, source, repo_root)
+                    if result.get("status") == "ok":
+                        print(f"  Policy cache: synced ({result.get('source_type', '?')}, {result['cached_at'][:10]})")
+                    elif result.get("error"):
+                        print(f"  Policy cache: {result['error']}")
+            except Exception as e:
+                print(f"  Policy cache: skipped ({e})")
+    elif topology == "standalone":
+        print(f"  Policy sync: skipped (standalone mode)")
+    elif topology == "inconsistent":
+        print(f"  Policy sync: skipped (inconsistent topology — repair with dashboard or re-gatorize)")
+
+    # Update product-source.json timestamp
+    ps = read_product_source(gator_dir)
+    if ps:
+        import json as _json
+        from datetime import date
+        ps["updated"] = str(date.today())
+        ps_file = gator_dir / "product-source.json"
+        ps_file.write_text(_json.dumps(ps, indent=2) + "\n", encoding="utf-8")
+
+    # Stamp .gator-version updated timestamp
+    if added > 0 or updated > 0:
+        version_file = gator_dir / ".gator-version"
+        if version_file.exists():
+            from datetime import datetime
+            now = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
+            lines = version_file.read_text(encoding="utf-8").splitlines()
+            new_lines = []
+            for line in lines:
+                if line.startswith("updated:"):
+                    new_lines.append(f"updated: {now}")
+                else:
+                    new_lines.append(line)
+            version_file.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
+
+    print_result(added, updated, unchanged)
+
+
+if __name__ == "__main__":
+    main()

gator_command/scripts/gator-version.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""
+gator-version.py — Git-native version resolution for Gator Command.
+
+The version IS the git state. Tagged releases (v0.1.0, v1.0.0) are the
+anchors. Between tags, git describe gives the full picture:
+  v0.1.0-14-g8ea4749 = 14 commits after v0.1.0, at commit 8ea4749.
+
+Usage as a module:
+    from gator_core import get_version
+    version = get_version()  # "v0.1.0-14-g8ea4749" or "v0.1.0" or "dev"
+
+Usage as a script:
+    python gator-command/scripts/gator-version.py
+    python gator-command/scripts/gator-version.py --short
+
+No hardcoded version strings. The repo is the source of truth.
+"""
+
+import argparse
+import sys
+
+from gator_core import get_version, get_version_short
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Gator version from git tags")
+    parser.add_argument("--short", action="store_true", help="Tag only, no commit count")
+    args = parser.parse_args()
+
+    if args.short:
+        print(get_version_short())
+    else:
+        print(get_version())
+
+
+if __name__ == "__main__":
+    main()