collab-runtime 0.6.2__tar.gz → 0.8.0__tar.gz

{collab_runtime-0.6.2/collab_runtime.egg-info → collab_runtime-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: collab-runtime
-Version: 0.6.2
+Version: 0.8.0
 Summary: Collaborative file locking runtime
 Author-email: KirilMT <kiril.mt95@gmail.com>
 License-Expression: MIT
@@ -94,6 +94,11 @@ LOCK_STRICT=0                                      # 1 = block on lock errors, 0
 COLLAB_AGENT_ID=agent-my-task                      # Optional: unique id per AI agent session
 COLLAB_AGENT_LABEL=refactor-auth                   # Optional display label
 COLLAB_AGENT_MODE=1                                # Auto-generate/persist agent id when unset
+COLLAB_OVERLAP_STRICT=0                            # 1 = block git push on cross-branch overlaps (fail-closed)
+COLLAB_OVERLAP_FETCH=auto                          # auto = fetch only in strict; 1/0 to force/skip
+COLLAB_OVERLAP_LINE_LEVEL=1                        # 0 = file-level instead of git merge-tree (line-level)
+COLLAB_OVERLAP_REMOTE=                             # override the auto-detected remote (e.g. upstream)
+COLLAB_PR_CLAIMS=0                                 # 1 = keep a pushed branch's files claimed until merged
 ```
 
 > **Keep `SUPABASE_SERVICE_ROLE_KEY` private — never commit it to version control.**
@@ -138,7 +143,17 @@ collab init-hooks
 
 This installs `pre-commit`, `post-commit`, `pre-push`, and `commit-msg` hooks into the current
 repository. The hooks acquire locks for staged files, block commits that conflict with another
-developer's lock, and release locks after a successful push. They resolve the project `.venv` first,
+developer's lock, and release locks after a successful push. By default, Collab warns about
+overlaps across unmerged branches during push; set `COLLAB_OVERLAP_STRICT=1` to block the push
+when overlaps are detected (fail-closed, and the hook first runs `git fetch` so branches pushed
+from other clones are seen). Overlap is confirmed at line level via `git merge-tree`, so edits to
+different regions of the same file are not flagged, and the comparison remote is auto-detected.
+For enforcement that cannot be bypassed with `git push --no-verify`,
+add the `PR Overlap Guard` GitHub Action to your branch-protection required checks.
+For **edit-time** protection across open PRs, set `COLLAB_PR_CLAIMS=1`: a pushed branch's
+files stay claimed (so other developers are warned/blocked as they edit) until the branch is
+merged or deleted — this requires re-running `supabase/schema.sql` (idempotent migration). The hooks
+resolve the project `.venv` first,
 so **commits from VS Code / Cursor Source Control behave the same as a venv-activated terminal**.
 
 Existing non-collab hooks are preserved; pass `--force` to overwrite them.

{collab_runtime-0.6.2 → collab_runtime-0.8.0}/README.md

@@ -77,18 +77,24 @@ The setup script automatically:
 After setup, your `.env` at the project root is ready to use. The team Supabase URL and
 anon key come pre-configured from `.env.example`:
 
-| Variable                    | Description                                                         |
-| --------------------------- | ------------------------------------------------------------------- |
-| `SUPABASE_URL`              | Your Supabase project URL (pre-configured from `.env.example`)      |
-| `SUPABASE_ANON_KEY`         | Anonymous/public key (pre-configured; safe to commit — see below)   |
-| `SUPABASE_SERVICE_ROLE_KEY` | Service role key (**required** for dashboard force-release)         |
-| `LOCK_STRICT`               | If `1`, git hooks block on lock errors. Default `0` (warn only)     |
-| `COLLAB_AGENT_ID`           | Optional stable id for an AI agent session (multi-agent locking)    |
-| `COLLAB_AGENT_LABEL`        | Optional task label shown on the dashboard (e.g. `refactor-auth`)   |
-| `COLLAB_AGENT_KIND`         | Optional AI runtime for the dashboard icon (auto-detected)          |
-| `COLLAB_AGENT_MODE`         | Set to `1` to auto-generate/persist an agent id when unset          |
-| `COLLAB_AGENT_HOOKS`        | Set to `1` to enable the IDE edit hook that auto-claims agent edits |
-| `COLLAB_WATCHER_AGENT_ID`   | Opt in to a dedicated agent watcher (default: watcher = human)      |
+| Variable                    | Description                                                           |
+| --------------------------- | --------------------------------------------------------------------- |
+| `SUPABASE_URL`              | Your Supabase project URL (pre-configured from `.env.example`)        |
+| `SUPABASE_ANON_KEY`         | Anonymous/public key (pre-configured; safe to commit — see below)     |
+| `SUPABASE_SERVICE_ROLE_KEY` | Service role key (**required** for dashboard force-release)           |
+| `LOCK_STRICT`               | If `1`, git hooks block on lock errors. Default `0` (warn only)       |
+| `COLLAB_AGENT_ID`           | Optional stable id for an AI agent session (multi-agent locking)      |
+| `COLLAB_AGENT_LABEL`        | Optional task label shown on the dashboard (e.g. `refactor-auth`)     |
+| `COLLAB_AGENT_KIND`         | Optional AI runtime for the dashboard icon (auto-detected)            |
+| `COLLAB_AGENT_MODE`         | Set to `1` to auto-generate/persist an agent id when unset            |
+| `COLLAB_AGENT_HOOKS`        | Set to `1` to enable the IDE edit hook that auto-claims agent edits   |
+| `COLLAB_WATCHER_AGENT_ID`   | Opt in to a dedicated agent watcher (default: watcher = human)        |
+| `COLLAB_OVERLAP_STRICT`     | If `1`, git push blocks on cross-branch overlap (implies the check)   |
+| `COLLAB_OVERLAP_CHECK`      | If `0`, disable overlap warnings entirely (ignored when strict)       |
+| `COLLAB_OVERLAP_FETCH`      | `auto` (default: fetch only in strict), or `1`/`0` to force/skip      |
+| `COLLAB_OVERLAP_LINE_LEVEL` | If `0`, use file-level overlap instead of `git merge-tree` (line)     |
+| `COLLAB_OVERLAP_REMOTE`     | Remote to compare against (default: auto-detected, e.g. `origin`)     |
+| `COLLAB_PR_CLAIMS`          | If `1`, keep a pushed branch's files claimed until merged (see below) |
 
 > **Important:** `SUPABASE_SERVICE_ROLE_KEY` is needed for the dashboard's Force Release button.
 > Without it, only your own locks can be released. Obtain it from a maintainer — **never commit it**.
@@ -479,9 +485,17 @@ collab daemon-status
 
 ### Conflict Prevention
 
-- File locks use a unique key on `file_path`
-- Only one developer can hold a lock per file
-- Merge conflicts prevented by design
+- File locks use a unique key on `file_path`.
+- Only one developer can hold a lock per file simultaneously.
+- **Lock Lifecycle**: Locks are held during local editing and committed changes. They are automatically released after a successful `git push` via the pre-push hook.
+- **Cross-Branch Overlap (client)**: By default, Collab warns if a change you are pushing would conflict with another unmerged branch. To **block** the push in this case, set `COLLAB_OVERLAP_STRICT=1`.
+  - **Line-level accuracy**: overlap is confirmed with a real in-memory merge (`git merge-tree`), so two branches editing **different regions** of the same file are not flagged. On git older than 2.38 it falls back to file-level. Force file-level with `COLLAB_OVERLAP_LINE_LEVEL=0`.
+  - **Remote-aware**: the remote to compare against is auto-detected (the push target, the branch upstream, `origin`, or the sole remote); override with `COLLAB_OVERLAP_REMOTE`.
+  - **Fresh state**: in strict mode the pre-push hook runs `git fetch` first so branches pushed from **other** clones are visible. This is **fail-closed** — if the fetch or check cannot complete, the push is blocked. `COLLAB_OVERLAP_FETCH` is `auto` by default (fetch only in strict, to avoid adding a fetch to every advisory push); set `1`/`0` to force or skip.
+  - Branches you are stacked on top of (ancestors of `HEAD`) are not flagged.
+  - When strict mode blocks you: rebase onto / coordinate merge order with the other branch, or override for a single push with `COLLAB_OVERLAP_STRICT=0` (last resort: `git push --no-verify`).
+- **Cross-PR Overlap (server, bulletproof)**: The [`PR Overlap Guard`](.github/workflows/pr-overlap-guard.yml) workflow fails a PR check when its changed files overlap another open PR targeting the same base. Because git hooks can be bypassed with `--no-verify`, add this check to your branch-protection **required status checks** for enforcement that cannot be skipped.
+- **Edit-time protection across open PRs (`COLLAB_PR_CLAIMS=1`, opt-in)**: Normally locks are released on push. With this enabled, the files changed on the pushed branch are instead **retained as persistent claims** until that branch is merged or deleted on the remote. Because a claim is an ordinary lock, another developer who edits those files gets the **existing edit-time warning** (watcher) and **commit block** (pre-commit) immediately — not a surprise conflict at merge time. Lifecycle: claim on push → released by the client reconciler when the branch is merged/deleted → guaranteed `release_stale_claims` expiry (default 30 days) as a safety net. **Requires the Supabase migration** (re-run [`supabase/schema.sql`](supabase/schema.sql); the columns/RPCs are added idempotently, and the runtime degrades to today's behavior if absent). Known limits: one owner per file (last push wins if you claim the same file from two branches); squash-merge relies on "delete branch on merge"; a PR closed without deleting its branch falls to the expiry.
 
 ### Dashboard
 

collab_runtime-0.8.0/collab/dashboard/dashboard-charts.js

@@ -0,0 +1,248 @@
+/**
+ * Chart helpers for the Collaborative Lock Dashboard.
+ * Loaded in the browser (global DashboardCharts) and in Jest (module.exports).
+ *
+ * Uses Chart.js (loaded via CDN) for lock activity timeline visualization.
+ */
+(function (root, factory) {
+  var api = factory();
+  if (typeof module === "object" && module.exports) {
+    module.exports = api;
+  } else {
+    root.DashboardCharts = api;
+  }
+})(typeof globalThis !== "undefined" ? globalThis : this, function () {
+  // ---------------------------------------------------------------------------
+  // Constants
+  // ---------------------------------------------------------------------------
+
+  var CHART_COLORS = {
+    acquisitions: "rgba(79, 70, 229, 0.75)", // primary
+    acquisitionsBorder: "rgba(79, 70, 229, 1)",
+    releases: "rgba(34, 197, 94, 0.75)", // green
+    releasesBorder: "rgba(34, 197, 94, 1)",
+    grid: "rgba(226, 232, 240, 0.6)",
+    text: "#64748b",
+  };
+
+  /**
+   * Compute bucket label and boundaries for a time range.
+   *
+   * @param {string} range  "1h" | "24h" | "7d"
+   * @returns {{ bucketMs: number, bucketLabel: string, totalBuckets: number }}
+   */
+  function _bucketConfig(range) {
+    switch (range) {
+      case "1h":
+        return { bucketMs: 5 * 60 * 1000, bucketLabel: "5m", totalBuckets: 12 };
+      case "7d":
+        return {
+          bucketMs: 24 * 60 * 60 * 1000,
+          bucketLabel: "1d",
+          totalBuckets: 7,
+        };
+      case "24h":
+      default:
+        return {
+          bucketMs: 60 * 60 * 1000,
+          bucketLabel: "1h",
+          totalBuckets: 24,
+        };
+    }
+  }
+
+  /**
+   * Bucket history rows into time-series counts.
+   *
+   * @param {Array<object>} history  Array of lock history rows.
+   * @param {string}        range    "1h" | "24h" | "7d"
+   * @returns {{ labels: Array<string>, acquired: Array<number>, released: Array<number> }}
+   */
+  function buildTimelineData(history, range) {
+    var cfg = _bucketConfig(range);
+    var now = Date.now();
+    var start = now - cfg.totalBuckets * cfg.bucketMs;
+
+    // Initialize buckets
+    var labels = [];
+    var acquired = [];
+    var released = [];
+    for (var i = 0; i < cfg.totalBuckets; i++) {
+      var bucketTime = start + i * cfg.bucketMs;
+      labels.push(_formatBucketLabel(bucketTime, range));
+      acquired.push(0);
+      released.push(0);
+    }
+
+    // Fill buckets from history data
+    (history || []).forEach(function (row) {
+      if (row.acquired_at) {
+        var acqTs = new Date(row.acquired_at).getTime();
+        var acqIdx = Math.floor((acqTs - start) / cfg.bucketMs);
+        if (acqIdx >= 0 && acqIdx < cfg.totalBuckets) {
+          acquired[acqIdx]++;
+        }
+      }
+      if (row.released_at) {
+        var relTs = new Date(row.released_at).getTime();
+        var relIdx = Math.floor((relTs - start) / cfg.bucketMs);
+        if (relIdx >= 0 && relIdx < cfg.totalBuckets) {
+          released[relIdx]++;
+        }
+      }
+    });
+
+    return { labels: labels, acquired: acquired, released: released };
+  }
+
+  /**
+   * Format a bucket timestamp into a human-readable label.
+   */
+  function _formatBucketLabel(ts, range) {
+    var d = new Date(ts);
+    switch (range) {
+      case "1h":
+        return (
+          String(d.getHours()).padStart(2, "0") +
+          ":" +
+          String(d.getMinutes()).padStart(2, "0")
+        );
+      case "7d":
+        return d.toLocaleDateString([], { month: "short", day: "numeric" });
+      case "24h":
+      default:
+        return String(d.getHours()).padStart(2, "0") + ":00";
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Chart initialization
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Create or return an existing Chart.js bar chart for lock activity.
+   *
+   * @param {string} canvasId  ID of the <canvas> element.
+   * @returns {object|null}    Chart.js instance, or null if Chart.js unavailable.
+   */
+  function initActivityChart(canvasId) {
+    if (typeof document === "undefined") return null;
+
+    var ChartCtor = (typeof window !== "undefined" && window.Chart) || null;
+    if (!ChartCtor) return null;
+
+    var canvas = document.getElementById(canvasId);
+    if (!canvas) return null;
+
+    // Destroy existing chart if re-initializing
+    var existing = ChartCtor.getChart(canvas);
+    if (existing) existing.destroy();
+
+    return new ChartCtor(canvas, {
+      type: "bar",
+      data: {
+        labels: [],
+        datasets: [
+          {
+            label: "Acquired",
+            data: [],
+            backgroundColor: CHART_COLORS.acquisitions,
+            borderColor: CHART_COLORS.acquisitionsBorder,
+            borderWidth: 1,
+            borderRadius: 4,
+          },
+          {
+            label: "Released",
+            data: [],
+            backgroundColor: CHART_COLORS.releases,
+            borderColor: CHART_COLORS.releasesBorder,
+            borderWidth: 1,
+            borderRadius: 4,
+          },
+        ],
+      },
+      options: {
+        animation: false,
+        responsive: true,
+        maintainAspectRatio: false,
+        interaction: {
+          mode: "index",
+          intersect: false,
+        },
+        hover: {
+          mode: "index",
+          intersect: false,
+        },
+        plugins: {
+          legend: {
+            labels: {
+              usePointStyle: true,
+              padding: 8,
+              color: CHART_COLORS.text,
+              font: { size: 12, weight: "600" },
+            },
+          },
+          tooltip: {
+            backgroundColor: "#1e293b",
+            titleFont: { size: 13, weight: "700" },
+            bodyFont: { size: 12 },
+            padding: 10,
+            cornerRadius: 8,
+          },
+        },
+        scales: {
+          x: {
+            grid: { color: CHART_COLORS.grid },
+            ticks: {
+              color: CHART_COLORS.text,
+              font: { size: 11 },
+              maxRotation: 45,
+            },
+          },
+          y: {
+            beginAtZero: true,
+            grid: { color: CHART_COLORS.grid },
+            ticks: {
+              color: CHART_COLORS.text,
+              font: { size: 11 },
+              stepSize: 1,
+            },
+            title: {
+              display: true,
+              text: "Lock Events",
+              color: CHART_COLORS.text,
+              font: { size: 11, weight: "600" },
+            },
+          },
+        },
+      },
+    });
+  }
+
+  /**
+   * Update an existing Chart.js instance with new timeline data.
+   *
+   * @param {object}        chart    Chart.js instance.
+   * @param {Array<object>} history  Array of lock history rows.
+   * @param {string}        range    "1h" | "24h" | "7d"
+   */
+  function updateActivityChart(chart, history, range) {
+    if (!chart) return;
+
+    var data = buildTimelineData(history, range);
+    chart.data.labels = data.labels;
+    chart.data.datasets[0].data = data.acquired;
+    chart.data.datasets[1].data = data.released;
+    chart.update("none"); // no animation on data update for performance
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  return {
+    initActivityChart: initActivityChart,
+    updateActivityChart: updateActivityChart,
+    buildTimelineData: buildTimelineData,
+  };
+});