gator-command 1.2.2__tar.gz → 1.3.0__tar.gz

{gator_command-1.2.2/src/gator_command.egg-info → gator_command-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gator-command
-Version: 1.2.2
+Version: 1.3.0
 Summary: Git-native governance for AI-assisted engineering
 Author-email: Cumberland Laboratories <support@cumberlandlaboratories.com>
 License: MIT

{gator_command-1.2.2 → gator_command-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gator-command"
-version = "1.2.2"
+version = "1.3.0"
 description = "Git-native governance for AI-assisted engineering"
 readme = "PYPI_README.md"
 license = {text = "MIT"}

{gator_command-1.2.2 → gator_command-1.3.0}/src/gator_command/scripts/gator-deploy.py

@@ -160,6 +160,7 @@ ROOT_GITIGNORE = (
     "\n"
     "# Machine-local state (not portable)\n"
     ".gator/product-source.json\n"
+    ".gator/active-vendor-session.json\n"
 )
 
 

{gator_command-1.2.2 → gator_command-1.3.0}/src/gator_command/scripts/gator-session-aggregator.py

@@ -8,7 +8,7 @@ entry point. Dashboard and CLI scripts import this.
 
 @reads: .gator/session-snippets/*.json (per repo)
 @reads: ~/.gator/dashboard-repos.json (fleet queries)
-@writes: ~/.gator/sessions/<path-hash>/<session_id>.json (cached summaries)
+@writes: ~/.gator/sessions/<path-hash>/<esk-hash>.json (cached summaries)
 @writes: ~/.gator/sessions/<path-hash>/_repo.json (repo metadata)
 """
 
@@ -33,6 +33,28 @@ SIGNIFICANCE_ORDER = {"routine": 0, "minor": 1, "high": 2}
 SKIP_CHANGE_TYPES_FOR_GOAL = {"release", "merge", "cleanup"}
 
 
+# ---------------------------------------------------------------------------
+# Session Identity
+# ---------------------------------------------------------------------------
+
+def effective_session_key(snippet):
+    """Return the canonical grouping key for a snippet.
+
+    Uses vendor session identity when available, falls back to legacy
+    Gator session_id. The returned string is used for aggregation grouping,
+    cache filenames, and fingerprint lookups.
+
+    Returns:
+        "group:<repo>:<session_group_key>" when session_group_key is truthy
+        "legacy:<repo>:<session_id>" otherwise
+    """
+    repo = snippet.get("repo", "")
+    sgk = snippet.get("session_group_key")
+    if sgk:
+        return f"group:{repo}:{sgk}"
+    return f"legacy:{repo}:{snippet.get('session_id', '')}"
+
+
 # ---------------------------------------------------------------------------
 # 1a. Snippet Reader
 # ---------------------------------------------------------------------------
@@ -75,7 +97,11 @@ def read_snippets(repo_path):
 # ---------------------------------------------------------------------------
 
 def aggregate_sessions(snippets, repo_path):
-    """Group snippets by (repo, session_id) and aggregate into summaries.
+    """Group snippets by effective_session_key() and aggregate into summaries.
+
+    Uses vendor session_group_key when present, falls back to legacy
+    Gator session_id. Snippets with different effective keys are never
+    merged, even if timestamps or transcript IDs look similar.
 
     Args:
         snippets: list of parsed snippet dicts (the "data" from SnippetRecords)
@@ -83,10 +109,10 @@ def aggregate_sessions(snippets, repo_path):
 
     Returns list of summary dicts matching gator-session-summary-v1 schema.
     """
-    # Group by (repo, session_id)
+    # Group by effective_session_key
     groups = {}
     for s in snippets:
-        key = (s.get("repo", ""), s.get("session_id", ""))
+        key = effective_session_key(s)
         if key not in groups:
             groups[key] = []
         groups[key].append(s)
@@ -94,7 +120,7 @@ def aggregate_sessions(snippets, repo_path):
     repo_key = session_cache_key(repo_path)
     summaries = []
 
-    for (repo, session_id), group in groups.items():
+    for esk, group in groups.items():
         # Sort within group
         group.sort(key=lambda s: (
             s.get("started_at", ""),
@@ -110,6 +136,7 @@ def aggregate_sessions(snippets, repo_path):
         all_intents = []
         all_notes = []
         all_change_types = set()
+        all_models = set()
         max_sig = "routine"
         architect = ""
         transcript_session_id = None
@@ -150,6 +177,11 @@ def aggregate_sessions(snippets, repo_path):
             if ct:
                 all_change_types.add(ct)
 
+            # Models — distinct
+            model = s.get("model_inferred", "")
+            if model:
+                all_models.add(model)
+
             # Max significance
             sig = s.get("significance", "routine")
             if SIGNIFICANCE_ORDER.get(sig, 0) > SIGNIFICANCE_ORDER.get(max_sig, 0):
@@ -165,14 +197,24 @@ def aggregate_sessions(snippets, repo_path):
             if not transcript_ref:
                 transcript_ref = s.get("transcript_ref")
 
+        # session_group_key: first non-null from the group (all should agree)
+        session_group_key = None
+        for s in group:
+            sgk = s.get("session_group_key")
+            if sgk:
+                session_group_key = sgk
+                break
+
         summary = {
             "schema": "gator-session-summary-v1",
-            "session_id": session_id,
-            "repo": repo,
+            "session_id": first.get("session_id", ""),
+            "session_group_key": session_group_key,
+            "repo": first.get("repo", ""),
             "repo_key": repo_key,
             "branch": first.get("branch", ""),
             "vendor": first.get("vendor_inferred", ""),
             "model": first.get("model_inferred", ""),
+            "models": sorted(all_models),
             "agent": first.get("agent", ""),
             "architect": architect,
             "started_at": min(s.get("started_at", "") for s in group),
@@ -273,21 +315,32 @@ def write_repo_metadata(cache_path, repo_name, repo_path):
     _atomic_write(meta_path, json.dumps(meta, indent=2) + "\n")
 
 
-def _summary_cache_filename(repo, session_id):
-    """Build a cache filename from the (repo, session_id) compound key.
+def _esk_from_summary(summary):
+    """Reconstruct the effective session key from a summary dict.
+
+    Mirrors effective_session_key() but reads from summary fields
+    instead of snippet fields.
+    """
+    repo = summary.get("repo", "")
+    sgk = summary.get("session_group_key")
+    if sgk:
+        return f"group:{repo}:{sgk}"
+    return f"legacy:{repo}:{summary.get('session_id', '')}"
+
+
+def _summary_cache_filename(esk):
+    """Build a cache filename from the effective session key.
 
-    Uses a short hash prefix of the repo name to avoid filename collisions
-    when two repos share a session_id in the same cache directory.
+    Hashes the full effective_session_key string to produce a stable,
+    filesystem-safe filename. The key already encodes repo + identity.
     """
-    if repo:
-        repo_prefix = hashlib.sha256(repo.encode()).hexdigest()[:6]
-        return f"{repo_prefix}-{session_id}.json"
-    return f"{session_id}.json"
+    h = hashlib.sha256(esk.encode()).hexdigest()[:16]
+    return f"{h}.json"
 
 
-def read_cached_summary(cache_path, repo, session_id):
+def read_cached_summary(cache_path, esk):
     """Read a cached session summary, or return None."""
-    summary_path = cache_path / _summary_cache_filename(repo, session_id)
+    summary_path = cache_path / _summary_cache_filename(esk)
     if not summary_path.exists():
         return None
     try:
@@ -296,10 +349,10 @@ def read_cached_summary(cache_path, repo, session_id):
         return None
 
 
-def write_cached_summary(cache_path, summary):
+def write_cached_summary(cache_path, summary, esk):
     """Write a session summary to cache."""
     cache_path.mkdir(parents=True, exist_ok=True)
-    filename = _summary_cache_filename(summary.get("repo", ""), summary["session_id"])
+    filename = _summary_cache_filename(esk)
     summary_path = cache_path / filename
     _atomic_write(summary_path, json.dumps(summary, indent=2) + "\n")
 
@@ -349,10 +402,10 @@ def get_session_summaries(repo_path, force_refresh=False):
     snippets_data = [r["data"] for r in records]
     sessions = aggregate_sessions(snippets_data, repo_path)
 
-    # Build a lookup: (repo, session_id) -> list of records (for fingerprinting)
+    # Build a lookup: effective_session_key -> list of records (for fingerprinting)
     session_records = {}
     for r in records:
-        key = (r["data"].get("repo", ""), r["data"].get("session_id", ""))
+        key = effective_session_key(r["data"])
         if key not in session_records:
             session_records[key] = []
         session_records[key].append(r)
@@ -362,13 +415,13 @@ def get_session_summaries(repo_path, force_refresh=False):
     wrote_any = False
 
     for summary in sessions:
-        repo = summary["repo"]
-        sid = summary["session_id"]
-        recs = session_records.get((repo, sid), [])
+        # Reconstruct the effective key from the summary's first snippet identity
+        esk = _esk_from_summary(summary)
+        recs = session_records.get(esk, [])
         fp = snippet_fingerprint(recs)
 
         if not force_refresh:
-            cached = read_cached_summary(cpath, repo, sid)
+            cached = read_cached_summary(cpath, esk)
             if cached and is_fresh(cached, fp):
                 results.append(cached)
                 continue
@@ -376,7 +429,7 @@ def get_session_summaries(repo_path, force_refresh=False):
         # Generate and cache
         summary["generated_at"] = datetime.now(timezone.utc).isoformat()
         summary["snippet_fingerprint"] = fp
-        write_cached_summary(cpath, summary)
+        write_cached_summary(cpath, summary, esk)
         results.append(summary)
         wrote_any = True
 

{gator_command-1.2.2/src/gator_command/templates/gator-starter → gator_command-1.3.0/src/gator_command}/scripts/gator-update.py

@@ -237,6 +237,98 @@ def bump_policy_version(gator_dir, command_post):
     return policy_date, changed
 
 
+def merge_hooks_into_settings(settings_path, hooks_template_path):
+    """Merge Gator hooks into a vendor settings JSON file without clobbering.
+
+    If the settings file doesn't exist, writes the hooks template as-is.
+    If it exists, deep-merges the hooks block: for each hook event,
+    appends Gator hook groups that aren't already present (identified by
+    the gator-session-start.py command string).
+
+    Returns: 'add', 'update', or 'unchanged'.
+    """
+    GATOR_HOOK_MARKER = "gator-session-start.py"
+
+    hooks_template = json.loads(hooks_template_path.read_text(encoding="utf-8"))
+    template_hooks = hooks_template.get("hooks", {})
+
+    if not settings_path.exists():
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        settings_path.write_text(
+            json.dumps(hooks_template, indent=2) + "\n", encoding="utf-8"
+        )
+        return "add"
+
+    # Read existing settings
+    try:
+        existing = json.loads(settings_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, ValueError):
+        # Corrupt file — don't clobber, skip
+        return "unchanged"
+
+    if not isinstance(existing, dict):
+        return "unchanged"
+
+    # Validate hooks shape — bail if it's not what we expect
+    existing_hooks = existing.get("hooks", {})
+    if not isinstance(existing_hooks, dict):
+        # hooks is present but wrong type (e.g., a list) — don't clobber
+        return "unchanged"
+
+    needs_update = False
+
+    for event_name, groups in template_hooks.items():
+        if event_name not in existing_hooks:
+            existing_hooks[event_name] = groups
+            needs_update = True
+        else:
+            event_value = existing_hooks[event_name]
+            if not isinstance(event_value, list):
+                # Event value is wrong shape — skip this event, don't corrupt
+                continue
+            existing_json = json.dumps(event_value)
+            if GATOR_HOOK_MARKER not in existing_json:
+                event_value.extend(groups)
+                needs_update = True
+
+    if not needs_update:
+        return "unchanged"
+
+    existing["hooks"] = existing_hooks
+    settings_path.write_text(
+        json.dumps(existing, indent=2) + "\n", encoding="utf-8"
+    )
+    return "update"
+
+
+# Vendor hook config: (template_file, target_dir, target_filename)
+VENDOR_HOOK_CONFIGS = [
+    ("vendor-hooks/claude-settings.json", ".claude", "settings.json"),
+    ("vendor-hooks/codex-hooks.json", ".codex", "hooks.json"),
+    ("vendor-hooks/gemini-settings.json", ".gemini", "settings.json"),
+]
+
+
+def install_vendor_hooks(templates_dir, repo_root):
+    """Install vendor SessionStart hook configs into the repo.
+
+    Merge-safe: injects Gator hooks into existing settings files
+    without clobbering user content (permissions, env vars, other hooks).
+
+    Returns count of files added or updated.
+    """
+    changed = 0
+    for template_file, target_dir, target_name in VENDOR_HOOK_CONFIGS:
+        src = templates_dir / template_file
+        if not src.exists():
+            continue
+        dest = repo_root / target_dir / target_name
+        result = merge_hooks_into_settings(dest, src)
+        if result in ("add", "update"):
+            changed += 1
+    return changed
+
+
 def execute_updates(plan):
     """Execute the update plan — copy files that need adding or updating.
 
@@ -264,18 +356,18 @@ def execute_updates(plan):
 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
-    managed hook dir contents. This matches what install_git_hooks()
-    actually writes, so the plan is accurate on both Unix and Windows.
-    """
-    git_hooks = get_managed_hook_dir(repo_root)
+    Compares the generated cross-platform Python wrappers to the current
+    managed hook dir contents. This matches what install_git_hooks()
+    actually writes, so the plan is accurate on both Unix and Windows.
+    """
+    git_hooks = get_managed_hook_dir(repo_root)
     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()
-    config_needs_update = hooks_config_needs_update(repo_root)
+    expected_hooks = build_git_hook_wrappers()
+    config_needs_update = hooks_config_needs_update(repo_root)
     results = []
     for hook_name, expected_content in sorted(expected_hooks.items()):
         dest = git_hooks / hook_name
@@ -283,70 +375,70 @@ def plan_hook_updates(gator_dir, repo_root):
             results.append((hook_name, "add"))
             continue
         actual = dest.read_text(encoding="utf-8", errors="replace")
-        if actual != expected_content or config_needs_update:
-            results.append((hook_name, "update"))
-        else:
-            results.append((hook_name, "unchanged"))
+        if actual != expected_content or config_needs_update:
+            results.append((hook_name, "update"))
+        else:
+            results.append((hook_name, "unchanged"))
 
     return results
 
 
-def _hook_shebang():
-    """Return the platform-correct shebang for hook wrappers."""
-    return "#!C:/Windows/py.exe -3" if os.name == "nt" else "#!/usr/bin/env python3"
-
-
-def get_managed_hooks_path_value():
-    """Return the core.hooksPath value Gator manages on this platform."""
-    return ".git/gator-hooks" if os.name == "nt" else None
-
-
-def get_managed_hook_dir(repo_root):
-    """Return the hook directory Gator actively manages."""
-    hooks_path = get_managed_hooks_path_value()
-    if hooks_path:
-        return repo_root / Path(hooks_path)
-    return repo_root / ".git" / "hooks"
-
-
-def get_hook_probe_dirs(repo_root):
-    """Return installed-hook directories to probe, managed dir first."""
-    probe_dirs = [get_managed_hook_dir(repo_root)]
-    legacy = repo_root / ".git" / "hooks"
-    if legacy not in probe_dirs:
-        probe_dirs.append(legacy)
-    return probe_dirs
-
-
-def hooks_config_needs_update(repo_root):
-    """Return True when core.hooksPath is missing or wrong."""
-    expected = get_managed_hooks_path_value()
-    if not expected:
-        return False
-    actual, ok = git("config", "--local", "--get", "core.hooksPath", cwd=repo_root)
-    return not ok or actual.strip() != expected
-
-
-def _configure_managed_hooks_path(repo_root):
-    """Set core.hooksPath when this platform uses a non-default dir."""
-    expected = get_managed_hooks_path_value()
-    if not expected:
-        return True
-    _, ok = git("config", "--local", "core.hooksPath", expected, cwd=repo_root)
-    return ok
-
-
-def get_managed_hook_display_path():
-    """Return the human-readable relative hook path for output."""
-    return get_managed_hooks_path_value() or ".git/hooks"
-
-
-def build_git_hook_wrappers():
-    """Return the exact hook wrapper contents gator installs.
-
-    The subprocess.call inside uses the exact interpreter path — spaces are
-    safe there because it's a Python string argument, not a shebang.
-    """
+def _hook_shebang():
+    """Return the platform-correct shebang for hook wrappers."""
+    return "#!C:/Windows/py.exe -3" if os.name == "nt" else "#!/usr/bin/env python3"
+
+
+def get_managed_hooks_path_value():
+    """Return the core.hooksPath value Gator manages on this platform."""
+    return ".git/gator-hooks" if os.name == "nt" else None
+
+
+def get_managed_hook_dir(repo_root):
+    """Return the hook directory Gator actively manages."""
+    hooks_path = get_managed_hooks_path_value()
+    if hooks_path:
+        return repo_root / Path(hooks_path)
+    return repo_root / ".git" / "hooks"
+
+
+def get_hook_probe_dirs(repo_root):
+    """Return installed-hook directories to probe, managed dir first."""
+    probe_dirs = [get_managed_hook_dir(repo_root)]
+    legacy = repo_root / ".git" / "hooks"
+    if legacy not in probe_dirs:
+        probe_dirs.append(legacy)
+    return probe_dirs
+
+
+def hooks_config_needs_update(repo_root):
+    """Return True when core.hooksPath is missing or wrong."""
+    expected = get_managed_hooks_path_value()
+    if not expected:
+        return False
+    actual, ok = git("config", "--local", "--get", "core.hooksPath", cwd=repo_root)
+    return not ok or actual.strip() != expected
+
+
+def _configure_managed_hooks_path(repo_root):
+    """Set core.hooksPath when this platform uses a non-default dir."""
+    expected = get_managed_hooks_path_value()
+    if not expected:
+        return True
+    _, ok = git("config", "--local", "core.hooksPath", expected, cwd=repo_root)
+    return ok
+
+
+def get_managed_hook_display_path():
+    """Return the human-readable relative hook path for output."""
+    return get_managed_hooks_path_value() or ".git/hooks"
+
+
+def build_git_hook_wrappers():
+    """Return the exact hook wrapper contents gator installs.
+
+    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()
@@ -370,19 +462,19 @@ def build_git_hook_wrappers():
     }
 
 
-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.
-    Windows installs into `.git/gator-hooks/` and sets `core.hooksPath`
-    to bypass the Git-for-Windows/MSYS launcher path. Unix installs into
-    the normal `.git/hooks/` directory.
-
-    @writes: managed git hook dir, git config core.hooksPath (Windows only)
-    """
-    git_hooks = get_managed_hook_dir(repo_root)
-    if not git_hooks.parent.is_dir():
-        return 0
+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.
+    Windows installs into `.git/gator-hooks/` and sets `core.hooksPath`
+    to bypass the Git-for-Windows/MSYS launcher path. Unix installs into
+    the normal `.git/hooks/` directory.
+
+    @writes: managed git hook dir, git config core.hooksPath (Windows only)
+    """
+    git_hooks = get_managed_hook_dir(repo_root)
+    if not git_hooks.parent.is_dir():
+        return 0
 
     git_hooks.mkdir(parents=True, exist_ok=True)
     installed = 0
@@ -393,12 +485,12 @@ def install_git_hooks(gator_dir, repo_root):
         try:
             import stat
             dest.chmod(dest.stat().st_mode | stat.S_IEXEC)
-        except (OSError, AttributeError):
-            pass
-        installed += 1
-
-    _configure_managed_hooks_path(repo_root)
-    return installed
+        except (OSError, AttributeError):
+            pass
+        installed += 1
+
+    _configure_managed_hooks_path(repo_root)
+    return installed
 
 
 # --- Output ---
@@ -429,15 +521,15 @@ def print_plan(plan, dry_run=False, hooks=None):
             print(f"    ~ {dest.name}")
         print()
 
-    if hook_adds or hook_updates:
-        print(f"  Git hooks ({len(hook_adds)} new, {len(hook_updates)} updated):")
-        hook_dir = get_managed_hook_display_path()
-        for name, action in (hooks or []):
-            if action == "add":
-                print(f"    + {hook_dir}/{name}")
-            elif action == "update":
-                print(f"    ~ {hook_dir}/{name}")
-        print()
+    if hook_adds or hook_updates:
+        print(f"  Git hooks ({len(hook_adds)} new, {len(hook_updates)} updated):")
+        hook_dir = get_managed_hook_display_path()
+        for name, action in (hooks or []):
+            if action == "add":
+                print(f"    + {hook_dir}/{name}")
+            elif action == "update":
+                print(f"    ~ {hook_dir}/{name}")
+        print()
 
     if not adds and not updates and not hook_adds and not hook_updates:
         print(f"  Everything is current. No updates needed.")
@@ -466,14 +558,14 @@ def print_json_plan(plan, command_post, templates_dir, hooks=None):
             "filename": dest.name,
         })
 
-    hook_items = []
-    hook_dir = get_managed_hook_display_path()
-    for name, action in (hooks or []):
-        hook_items.append({
-            "hook": name,
-            "action": action,
-            "destination": f"{hook_dir}/{name}",
-        })
+    hook_items = []
+    hook_dir = get_managed_hook_display_path()
+    for name, action in (hooks or []):
+        hook_items.append({
+            "hook": name,
+            "action": action,
+            "destination": f"{hook_dir}/{name}",
+        })
 
     output = {
         "version": VERSION,
@@ -594,6 +686,11 @@ def main():
     if hooks_installed > 0:
         print(f"  Git hooks: {hooks_installed} installed/refreshed")
 
+    # Install/merge vendor SessionStart hook configs
+    vendor_hooks_changed = install_vendor_hooks(templates_dir, repo_root)
+    if vendor_hooks_changed > 0:
+        print(f"  Vendor hooks: {vendor_hooks_changed} config(s) installed/updated")
+
     # Channel 2: policy sync (only for policy-synced repos, unless --no-policy)
     if args.no_policy:
         pass  # Skip channel 2 entirely