collab-runtime 0.9.2__tar.gz → 0.10.0__tar.gz

{collab_runtime-0.9.2/collab_runtime.egg-info → collab_runtime-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: collab-runtime
-Version: 0.9.2
+Version: 0.10.0
 Summary: Collaborative file locking runtime
 Author-email: KirilMT <kiril.mt95@gmail.com>
 License-Expression: MIT
@@ -197,6 +197,11 @@ collab init-hooks --force
 
 # Reconcile local and remote lock state
 collab reconcile
+collab reconcile --prune-orphans
+
+# Release orphan locks left by dead worktrees / killed daemons
+collab prune-orphans
+collab prune-orphans --dry-run
 
 # Lock history and retention
 collab history
@@ -215,7 +220,7 @@ collab watch --interval 5 --timeout 0
 # Web dashboard (opens in browser)
 collab dashboard
 
-# Cleanup orphaned watcher processes
+# Cleanup orphaned watcher processes (preserves lock rows)
 collab cleanup
 ```
 

{collab_runtime-0.9.2 → collab_runtime-0.10.0}/README.md

@@ -218,13 +218,19 @@ collab release-batch path/to/a.py path/to/b.py
 
 # Reconcile local and remote lock state
 collab reconcile
+collab reconcile --prune-orphans   # also release orphan lock rows (#182)
+
+# Release orphan locks left by dead worktrees / killed daemons
+collab prune-orphans
+collab prune-orphans --dry-run
+collab prune-orphans --aggressive
 
 # Lock history and retention
 collab history
 collab history path/to/file.py --limit 50
 collab history-prune --days 30
 
-# Cleanup orphaned watcher processes
+# Cleanup orphaned watcher processes (preserves lock rows)
 collab cleanup
 
 # Start background watcher

{collab_runtime-0.9.2 → collab_runtime-0.10.0}/collab/dashboard/index.html

@@ -1986,6 +1986,12 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
                 .replace(/'/g, "&#39;");
         }
 
+        function escapeAttr(value) {
+            return String(value == null ? "" : value)
+                .replace(/\\/g, "\\\\")
+                .replace(/'/g, "\\'");
+        }
+
         function isAgentLock(lock) {
             if (lock.origin === "agent") {
                 return true;
@@ -2445,7 +2451,7 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
                     const canRelease = isMyDeveloper || IS_ADMIN;
                     const reason = lock.reason || "No reason";
                     const branch = lock.branch_name || "main";
-                    const safePath = String(lock.file_path || "").replace(/'/g, "\\'");
+                    const safePath = escapeAttr(String(lock.file_path || ""));
 
                     const action = canRelease
                         ? '<button class="btn btn-sm btn-outline-danger" onclick="initRelease(\'' + safePath + '\',' + (isMine ? "true" : "false") + ')">' +
@@ -2477,7 +2483,7 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
                 if (stillPresent) {
                     var detailId = "detail-" + expandedRowPath.replace(/[^a-zA-Z0-9]/g, "-");
                     var row = document.querySelector(
-                        "tr[data-file='" + expandedRowPath.replace(/'/g, "\\'") + "']"
+                        "tr[data-file='" + escapeAttr(expandedRowPath) + "']"
                     );
                     if (row && !document.getElementById(detailId)) {
                         var detailRow = document.createElement("tr");
@@ -2613,7 +2619,7 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
                         ? formatDurationMinutes(Math.max(0, Math.round((rel - acq) / 60000)))
                         : "-";
                     const isMine = lockOwnedByMe(h);
-                    const safePath = String(h.file_path || "").replace(/'/g, "\\'");
+                    const safePath = escapeAttr(String(h.file_path || ""));
 
                     return (
                         '<tr data-file="' + safePath + '" class="row-expandable">' +
@@ -3362,7 +3368,7 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
             }
 
             // Build a detail panel
-            var row = document.querySelector("tr[data-file='" + filePath.replace(/'/g, "\\'") + "']");
+            var row = document.querySelector("tr[data-file='" + escapeAttr(filePath) + "']");
             if (!row) return;
 
             var detailRow = document.createElement("tr");
@@ -3375,11 +3381,14 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
                 else if (typeof val === "object") val = JSON.stringify(val);
                 return '<div class="detail-label">' + k + '</div><div class="detail-value">' + String(val) + '</div>';
             }).join("");
-            var jsonHtml = '<div class="detail-json">' + JSON.stringify(lockJson, null, 2) + '</div>';
+            var jsonText = JSON.stringify(lockJson, null, 2);
             var copyBtn = '<button class="detail-copy-btn" title="Copy JSON" onclick="copyDetailJson(this)"><i class="fas fa-copy"></i></button>';
             detailRow.innerHTML = '<td colspan="6">' +
                 copyBtn +
-                '<div class="detail-grid">' + gridHtml + '</div>' + jsonHtml + '</td>';
+                '<div class="detail-grid">' + gridHtml + '</div>' +
+                '<div class="detail-json"></div></td>';
+            var jsonDiv = detailRow.querySelector('.detail-json');
+            if (jsonDiv) { jsonDiv.textContent = jsonText; }
             row.parentNode.insertBefore(detailRow, row.nextSibling);
             expandedRowPath = filePath;
         }

{collab_runtime-0.9.2 → collab_runtime-0.10.0}/collab/dashboard_server.py

@@ -230,9 +230,11 @@ def load_runtime_supabase_config(project_root: str) -> dict[str, Any]:
             val = os.getenv(name)
         return val
 
+    from .env_secrets import effective_anon_key, effective_service_role_key
+
     url = pick("SUPABASE_URL") or ""
-    anon = pick("SUPABASE_ANON_KEY") or ""
-    service = pick("SUPABASE_SERVICE_ROLE_KEY") or None
+    anon = effective_anon_key(pick("SUPABASE_ANON_KEY")) or ""
+    service = effective_service_role_key(pick("SUPABASE_SERVICE_ROLE_KEY"))
     user = _resolve_developer_name(project_root, file_vals)
     from . import agent_identity
 

collab_runtime-0.10.0/collab/env_secrets.py

@@ -0,0 +1,45 @@
+"""Resolve effective Supabase credentials from environment variables."""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Optional
+
+# Placeholder patterns copied from scripts/setup.ps1 (Test-IsPlaceholderValue).
+_PLACEHOLDER_ENV_RE = re.compile(
+    r"^(?:your[_-]|your[_-]?project|example|CHANGE_ME|change[_-]?me|"
+    r"replace[_-]?me|TODO|<team-)",
+    re.IGNORECASE,
+)
+
+
+def is_placeholder_env_value(value: Optional[str]) -> bool:
+    """Return True when *value* is unset or still a template placeholder."""
+    if value is None:
+        return True
+    stripped = value.strip()
+    if not stripped:
+        return True
+    return bool(_PLACEHOLDER_ENV_RE.match(stripped))
+
+
+def effective_env_secret(value: Optional[str]) -> Optional[str]:
+    """Return a usable secret or None when *value* is blank/placeholder."""
+    if is_placeholder_env_value(value):
+        return None
+    return value.strip() if value else None
+
+
+def effective_service_role_key(raw: Optional[str] = None) -> Optional[str]:
+    """Service role key for API calls, or None when placeholder/unset."""
+    if raw is None:
+        raw = os.getenv("SUPABASE_SERVICE_ROLE_KEY")
+    return effective_env_secret(raw)
+
+
+def effective_anon_key(raw: Optional[str] = None) -> Optional[str]:
+    """Anon key for API calls, or None when placeholder/unset."""
+    if raw is None:
+        raw = os.getenv("SUPABASE_ANON_KEY")
+    return effective_env_secret(raw)

{collab_runtime-0.9.2 → collab_runtime-0.10.0}/collab/githooks.py

@@ -18,8 +18,10 @@ repository top level), so the same module works for any consumer repository.
 
 from __future__ import annotations
 
+import hashlib
 import json
 import os
+import re
 import sys
 from importlib import resources
 from pathlib import Path
@@ -251,6 +253,15 @@ def _release_retaining_pr_claims(client, root: Path) -> int:
     briefly exist for a branch that did not reach the remote if the push then fails;
     the next reconcile (branch-gone) or the DB-side expiry releases those.
     """
+    if not client.claims_supported():
+        _hook_log(
+            "[collab] WARNING: COLLAB_PR_CLAIMS=1 but the Supabase claim migration "
+            "is not applied (missing 'is_pr_claim' column). Locks will be RELEASED "
+            "on push, not retained as claims. Apply supabase/schema.sql to enable "
+            "PR claims, then re-run setup."
+        )
+        return int(client.release_all())
+
     try:
         stale = client.reconcile_pr_claims()
         if stale:
@@ -296,50 +307,172 @@ def _is_collab_hook(text: str) -> bool:
     return "collab" in text.lower()
 
 
+# Marker written into every installed hook so a later ``install_hooks`` run can tell
+# whether the on-disk hook matches the packaged template (content fingerprint) and
+# auto-reinstall stale hooks WITHOUT a manual --force flag (#181).
+_HOOK_MARKER_RE = re.compile(r"# collab-hook v=\S+ fp=([0-9a-f]+)")
+
+
+def _package_version() -> str:
+    """Return the installed collab-runtime version (best-effort)."""
+    try:
+        from collab import __version__
+
+        return str(__version__)
+    except Exception:
+        return "0.0.0"
+
+
+def _template_fingerprint(raw_template: str) -> str:
+    """Return a short content fingerprint (sha256) of a raw hook template."""
+    normalized = raw_template.replace("\r\n", "\n")
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:12]
+
+
+def _stamp_template(raw_template: str, fingerprint: str) -> str:
+    """Insert the collab-hook marker line after the shebang (or at the top)."""
+    marker = f"# collab-hook v={_package_version()} fp={fingerprint}"
+    lines = raw_template.replace("\r\n", "\n").split("\n")
+    if lines and lines[0].startswith("#!"):
+        lines.insert(1, marker)
+    else:
+        lines.insert(0, marker)
+    return "\n".join(lines)
+
+
+def _installed_fingerprint(text: str) -> Optional[str]:
+    """Return the fingerprint recorded in an installed collab hook, if present."""
+    match = _HOOK_MARKER_RE.search(text)
+    return match.group(1) if match else None
+
+
+def _is_precommit_hook(text: str) -> bool:
+    """Return True when a hook is managed by the pre-commit framework.
+
+    Collab hooks may legitimately mention ``pre-commit`` (they invoke it), so callers
+    must check :func:`_is_collab_hook` first; this only matches the framework's own
+    generated hooks so ``install_hooks`` never clobbers the pre-commit slot.
+    """
+    lowered = text.lower()
+    return "hook-impl" in lowered or "generated by pre-commit" in lowered
+
+
+def _backup_hook(target: Path) -> Optional[str]:
+    """Back up an existing hook to ``<hook>.bak`` before overwriting.
+
+    Returns name.
+    """
+    backup = (
+        target.with_suffix(target.suffix + ".bak")
+        if target.suffix
+        else Path(str(target) + ".bak")
+    )
+    try:
+        backup.write_bytes(target.read_bytes())
+        return backup.name
+    except OSError:
+        return None
+
+
+def _write_hook(target: Path, content: str) -> None:
+    """Write hook *content* with LF endings and best-effort exec bit."""
+    with open(target, "w", encoding="utf-8", newline="\n") as handle:
+        handle.write(content)
+    try:
+        mode = target.stat().st_mode
+        target.chmod(mode | 0o755)
+    except OSError:
+        pass
+
+
 def install_hooks(
     project_root: Optional[Path] = None,
     force: bool = False,
 ) -> dict[str, list[str] | str]:
-    """Install bundled collab git hooks into the target repository.
-
-    Existing non-collab hooks are preserved unless ``force`` is set, so a developer's
-    custom hooks are never silently overwritten.
-
-    Returns a summary dict with ``installed``, ``skipped`` and ``hooks_dir``.
+    """Install (or update) the bundled collab git hooks into the target repository.
+
+    Behavior (#181):
+
+    * **Fresh** hooks are installed and content-stamped with a fingerprint marker.
+    * **Collab-managed** hooks are auto-updated when their fingerprint no longer
+      matches the packaged template -- so template changes reach existing clones on
+      the next ``setup-dev`` / ``collab init-hooks`` run, with no manual flag.
+    * **Up-to-date** collab hooks are left untouched.
+    * **pre-commit-managed** hooks are never clobbered -- **even with ``force``** --
+      because the framework owns that slot and re-claims it on ``pre-commit install``.
+      The collab lock lifecycle runs through ``.pre-commit-config.yaml`` instead, so
+      these are reported under ``precommit_managed`` (not an error, not actionable).
+    * **Custom** (non-collab) hooks are preserved unless ``force`` is set; with
+      ``force`` the original is backed up to ``<hook>.bak`` before overwriting, so a
+      developer's custom hook is never destroyed silently.
+
+    Returns a summary dict with ``installed`` (all written: fresh + updated),
+    ``updated``, ``up_to_date``, ``skipped`` (custom hooks left in place),
+    ``precommit_managed`` (framework-owned slots), ``backed_up`` and ``hooks_dir``.
     """
     root = Path(project_root) if project_root is not None else _git_toplevel()
     hooks_dir = _hooks_dir(root)
     hooks_dir.mkdir(parents=True, exist_ok=True)
 
     installed: list[str] = []
+    updated: list[str] = []
+    up_to_date: list[str] = []
     skipped: list[str] = []
+    precommit_managed: list[str] = []
+    backed_up: list[str] = []
 
     for name in HOOK_NAMES:
         target = hooks_dir / name
-        if target.exists() and not force:
+        raw = _read_template(name).replace("\r\n", "\n")
+        fingerprint = _template_fingerprint(raw)
+        content = _stamp_template(raw, fingerprint)
+
+        if target.exists():
             try:
                 existing = target.read_text(encoding="utf-8", errors="ignore")
             except OSError:
-                existing = ""
-            if not _is_collab_hook(existing):
+                # Cannot read -> do not risk clobbering something unknown.
                 skipped.append(name)
                 continue
 
-        # Normalize to LF so POSIX `sh` (incl. Git Bash on Windows) can parse
-        # the shebang and body regardless of how the template was checked out.
-        content = _read_template(name).replace("\r\n", "\n")
-        with open(target, "w", encoding="utf-8", newline="\n") as handle:
-            handle.write(content)
-        try:
-            mode = target.stat().st_mode
-            target.chmod(mode | 0o755)
-        except OSError:
-            pass
+            if _is_collab_hook(existing):
+                # Auto-update only when the fingerprint drifted from the package.
+                if _installed_fingerprint(existing) == fingerprint:
+                    up_to_date.append(name)
+                    continue
+                _write_hook(target, content)
+                installed.append(name)
+                updated.append(name)
+                continue
+
+            # The pre-commit framework owns this slot: never clobber it (even with
+            # --force). The collab lock lifecycle runs via .pre-commit-config.yaml,
+            # so this is expected coverage -- reported separately from custom skips.
+            if _is_precommit_hook(existing):
+                precommit_managed.append(name)
+                continue
+
+            # Custom (non-collab) hook: preserve unless forced; back up on force.
+            if not force:
+                skipped.append(name)
+                continue
+            backup_name = _backup_hook(target)
+            if backup_name:
+                backed_up.append(backup_name)
+            _write_hook(target, content)
+            installed.append(name)
+            continue
+
+        _write_hook(target, content)
         installed.append(name)
 
     return {
         "installed": installed,
+        "updated": updated,
+        "up_to_date": up_to_date,
         "skipped": skipped,
+        "precommit_managed": precommit_managed,
+        "backed_up": backed_up,
         "hooks_dir": str(hooks_dir),
     }
 
@@ -367,15 +500,28 @@ def main(argv: Optional[list[str]] = None) -> int:
     if command == "init":
         force = "--force" in args[1:]
         summary = install_hooks(force=force)
-        installed = summary["installed"]
-        skipped = summary["skipped"]
+        installed = summary.get("installed") or []
+        updated = summary.get("updated") or []
+        skipped = summary.get("skipped") or []
+        precommit_managed = summary.get("precommit_managed") or []
+        backed_up = summary.get("backed_up") or []
+        fresh = [name for name in installed if name not in updated]
         print(f"[collab] Installed git hooks into {summary['hooks_dir']}")
-        if installed:
-            print(f"[collab] Installed: {', '.join(installed)}")
+        if fresh:
+            print(f"[collab] Installed: {', '.join(fresh)}")
+        if updated:
+            print(f"[collab] Updated (template changed): {', '.join(updated)}")
+        if backed_up:
+            print(f"[collab] Backed up before overwrite: {', '.join(backed_up)}")
+        if precommit_managed:
+            print(
+                "[collab] Managed by pre-commit (.pre-commit-config.yaml), left as-is: "
+                f"{', '.join(precommit_managed)}"
+            )
         if skipped:
             print(
-                "[collab] Skipped (existing non-collab hooks, use --force): "
-                f"{', '.join(skipped)}"
+                "[collab] Skipped existing custom hooks (rerun with --force to back "
+                f"up & replace): {', '.join(skipped)}"
             )
         return 0
 

{collab_runtime-0.9.2 → collab_runtime-0.10.0}/collab/hook_templates/pre-push

@@ -66,7 +66,18 @@ elif [ $OVERLAP_EXIT -ne 0 ]; then
     exit $OVERLAP_EXIT
 fi
 
-echo "[collab] Releasing all locks after successful pre-push validation..." >&2
+# Message reflects retain-vs-release: when COLLAB_PR_CLAIMS is enabled the pushed
+# branch's files are retained as persistent claims (the rest are released); the
+# Python runtime prints the exact per-file outcome.
+PR_CLAIMS_LOWER="$(printf '%s' "${COLLAB_PR_CLAIMS:-0}" | tr '[:upper:]' '[:lower:]')"
+case "$PR_CLAIMS_LOWER" in
+    1 | true | yes | on)
+        echo "[collab] Retaining pushed-branch files as PR claims (COLLAB_PR_CLAIMS enabled); releasing other locks..." >&2
+        ;;
+    *)
+        echo "[collab] Releasing all locks after successful pre-push validation..." >&2
+        ;;
+esac
 "$PYTHON" -m collab.githooks release-all
 
 exit 0