collab-runtime 0.2.9__tar.gz → 0.3.1__tar.gz

{collab_runtime-0.2.9/collab_runtime.egg-info → collab_runtime-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: collab-runtime
-Version: 0.2.9
+Version: 0.3.1
 Summary: Collaborative file locking runtime
 Author-email: KirilMT <kiril.mt95@gmail.com>
 License-Expression: MIT
@@ -77,7 +77,7 @@ pip install "collab-runtime>=0.2.2"
 
 ### 1 — Create the Database Schema
 
-In your Supabase project, open **SQL Editor** and run the contents of [`schema.sql`](https://github.com/KirilMT/collab/blob/main/schema.sql).
+In your Supabase project, open **SQL Editor** and run the contents of [`supabase/schema.sql`](https://github.com/KirilMT/collab/blob/main/supabase/schema.sql).
 
 This creates the `file_locks` table, `file_locks_history` audit table, the atomic `acquire_lock()` RPC, Row Level Security policies, and Realtime publication.
 
@@ -164,7 +164,7 @@ The optional VS Code extension provides lock-on-open warnings, a status bar indi
 **Install from source** (extension is bundled in the [GitHub repository](https://github.com/KirilMT/collab)):
 
 1. Press `F1` → **Developer: Install Extension from Location...**
-2. Select the `vscode-extension/collab-locks/` directory
+2. Select the `editors/vscode/collab-locks/` directory
 3. Reload VS Code
 
 Once installed, the extension automatically starts and stops the background daemon with your VS Code window.
@@ -198,7 +198,7 @@ Lock release follows the same path in reverse and writes an entry to `file_locks
 
 - Lock correctness is enforced at the database level via atomic RPC — no client-side race conditions.
 - Force-release requires `SUPABASE_SERVICE_ROLE_KEY`; regular releases are scoped to the owning developer.
-- Row Level Security (RLS) is configured on all tables via `schema.sql`.
+- Row Level Security (RLS) is configured on all tables via `supabase/schema.sql`.
 - Never commit secrets; use `.env` for local configuration only.
 
 ---

{collab_runtime-0.2.9 → collab_runtime-0.3.1}/README.md

@@ -17,14 +17,14 @@ Prevents merge conflicts by automatically locking files when a developer starts
 
 ### 1. Create the Database Schema
 
-Open your Supabase project's **SQL Editor** and run the contents of `schema.sql`:
+Open your Supabase project's **SQL Editor** and run the contents of `supabase/schema.sql`:
 
 **Steps:**
 
 1. Open your Supabase project dashboard
 2. Navigate to **SQL Editor** (left sidebar)
 3. Click **New Query**
-4. Copy-paste the full contents of [schema.sql](schema.sql) from this repository
+4. Copy-paste the full contents of [supabase/schema.sql](supabase/schema.sql) from this repository
 5. Click **Run**
 
 This creates:
@@ -53,7 +53,7 @@ One command handles everything — dependencies, `.env` configuration, and IDE i
 **Linux/macOS (Bash):**
 
 ```bash
-./scripts/setup.sh
+./scripts/setup-dev.sh
 ```
 
 **End-User Install (via pip):**
@@ -102,8 +102,8 @@ Once setup is complete, test the locking system:
 **Terminal 1 (Lock a file):**
 
 ```bash
-collab acquire src/main.py --reason "Testing locking system"
-collab status src/main.py
+collab acquire collab/main.py --reason "Testing locking system"
+collab status collab/main.py
 ```
 
 **Terminal 2 (View lock in another session):**
@@ -115,7 +115,7 @@ collab active
 **Then release the lock:**
 
 ```bash
-collab release src/main.py
+collab release collab/main.py
 ```
 
 **View real-time lock changes:**
@@ -202,11 +202,11 @@ The extension is primarily distributed via the **Collab Runtime** Python package
 **Manual Install (from source):**
 
 1. Press `F1` -> `Developer: Install Extension from Location...`
-2. Select `vscode-extension/collab-locks/`
+2. Select `editors/vscode/collab-locks/`
 3. Reload VS Code
 
 **CLI Install:**
-If you have the `collab` CLI installed, the extension is often provisioned automatically by `scripts/setup-dev.ps1`.
+Production `scripts/setup.ps1` / `scripts/setup.sh` download the latest release `.vsix` and install it when a supported editor CLI is on `PATH`. **Development setup** (`scripts/setup-dev.ps1` / `scripts/setup-dev.sh`) repeats this with stronger IDE detection and resolves `code` / `cursor` (and siblings) from common install locations on Windows and macOS when they are not on `PATH`, which fixes installs from integrated terminals (for example **Cursor**).
 
 ### Features
 
@@ -279,7 +279,7 @@ if (Test-Path $pidPath) {
 
 ## Database Schema
 
-The full schema is in `schema.sql` and includes:
+The full schema is in `supabase/schema.sql` and includes:
 
 - `file_locks` for active locks.
 - `file_locks_history` for audit/history.
@@ -302,7 +302,7 @@ The full schema is in `schema.sql` and includes:
 
 ```
 collab/
-├── src/
+├── collab/
 │   ├── lock_client.py          # CLI entry point
 │   ├── live_locks_watcher.py   # Background watcher
 │   ├── main.py                 # CLI orchestration + module entry point
@@ -315,18 +315,24 @@ collab/
 │   │   ├── functional/         # Functional tests
 │   │   ├── integration/        # Integration tests
 │   │   ├── security/           # Security tests
-│   │   ├── performance/        # Performance tests
-│   │   └── reliability/        # Reliability tests
+│   │   └── (performance/ and reliability/ removed — empty placeholders deleted for clean/optimized structure)
 │   └── frontend/
-│       ├── jest/               # Frontend unit placeholder
-│       └── playwright/         # Frontend e2e placeholder
+│       └── playwright/         # E2E + visual regression (config, CI job, helpers, snapshots, deterministic fixtures)
 ├── scripts/
-│   ├── setup-dev.ps1           # Windows setup
+│   ├── setup-dev.ps1           # Windows dev setup
 │   ├── setup.sh                # Linux/macOS setup
+│   ├── git-hooks/              # Collab git hook templates
+│   ├── install_hooks.sh        # Installs templates into .git/hooks
 │   ├── format_code.py          # Code formatter
 │   ├── validate_code.py        # CI validator
 │   └── cleanup.py              # Cache cleanup
-├── schema.sql                  # Supabase database schema
+├── supabase/
+│   └── schema.sql              # Supabase database schema
+├── editors/
+│   ├── vscode/collab-locks/    # VS Code / Cursor extension
+│   └── pycharm/                # PyCharm run configuration template
+├── docs/
+│   └── pypi/README.md          # PyPI package readme
 ├── pyproject.toml              # Package configuration
 └── README.md                   # This file
 ```
@@ -463,6 +469,20 @@ MIT License — see LICENSE file for details.
 
 ---
 
+## Documentation
+
+| Document                                      | Description                              |
+| --------------------------------------------- | ---------------------------------------- |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md)       | System design and data flow              |
+| [API.md](docs/API.md)                         | CLI overview and environment variables   |
+| [CLI_REFERENCE.md](docs/CLI_REFERENCE.md)     | Full command reference                   |
+| [SECURITY.md](docs/SECURITY.md)               | Subprocess hardening and secret handling |
+| [PERFORMANCE.md](docs/PERFORMANCE.md)         | Validation and watcher tuning            |
+| [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common issues and fixes                  |
+| [collab_roadmap.md](docs/collab_roadmap.md)   | Future enhancements                      |
+
+---
+
 ## Support
 
 For issues, questions, or feature requests:

collab_runtime-0.3.1/collab/__init__.py

@@ -0,0 +1,24 @@
+"""Collab runtime package (published on PyPI as ``collab-runtime``)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+__all__ = ["__version__"]
+
+
+def _installed_version(dist_name: str = "collab-runtime") -> Optional[str]:
+    try:
+        from importlib.metadata import version as _ver
+    except Exception:
+        try:
+            from importlib_metadata import version as _ver  # type: ignore
+        except Exception:
+            return None
+    try:
+        return _ver(dist_name)
+    except Exception:
+        return None
+
+
+__version__ = _installed_version("collab-runtime") or "0.0.0"

collab_runtime-0.3.1/collab/__main__.py

@@ -0,0 +1,8 @@
+"""Entrypoint for ``python -m collab`` and the ``collab`` console script."""
+
+from __future__ import annotations
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

{collab_runtime-0.2.9/src → collab_runtime-0.3.1/collab}/dashboard/index.html

@@ -489,53 +489,74 @@
                 <span>Collaborative Explorer</span>
             </div>
             <div class="nav-right">
-                <span id="last-update" class="chip">Not synced yet</span>
-                <span id="user-info" class="chip hidden"></span>
-                <button id="nav-locks" class="btn btn-sm btn-primary" type="button">Active Locks</button>
-                <button id="nav-history" class="btn btn-sm btn-outline-primary" type="button">History Locks</button>
-                <button id="sync-btn" class="btn btn-sm btn-outline-secondary" type="button">
+                <span id="last-update" class="chip" data-testid="last-update">Not synced yet</span>
+                <span id="project-info"
+                      class="chip hidden text-muted small"
+                      data-testid="project-info"></span>
+                <span id="user-info" class="chip hidden" data-testid="user-info"></span>
+                <button id="nav-locks"
+                        class="btn btn-sm btn-primary"
+                        type="button"
+                        data-testid="nav-locks">Active Locks</button>
+                <button id="nav-history"
+                        class="btn btn-sm btn-outline-primary"
+                        type="button"
+                        data-testid="nav-history">History Locks</button>
+                <button id="sync-btn"
+                        class="btn btn-sm btn-outline-secondary"
+                        type="button"
+                        data-testid="sync-btn">
                     <i class="fas fa-sync-alt me-1"></i>Sync
                 </button>
             </div>
         </header>
         <main class="app-main">
-            <section id="setup-view" class="setup-view hidden">
+            <section id="setup-view" class="setup-view hidden" data-testid="setup-view">
                 <h4 class="mb-2">Connect To Supabase</h4>
                 <p class="text-muted mb-3">Configure credentials in .env and restart the dashboard server.</p>
                 <pre class="bg-light border rounded p-3 mb-0">SUPABASE_URL=https://your-project.supabase.co
 SUPABASE_ANON_KEY=your_anon_key</pre>
             </section>
-            <section id="locks-page" class="page-view hidden" aria-label="locks view">
+            <section id="locks-page"
+                     class="page-view hidden"
+                     aria-label="locks view"
+                     data-testid="locks-page">
                 <div class="page-head">
                     <h2 class="page-title">
                         <i class="fas fa-lock"></i>Active Locks
                     </h2>
                 </div>
-                <div class="stats-grid" aria-label="dashboard stats">
-                    <article class="stat-card">
+                <div class="stats-grid"
+                     aria-label="dashboard stats"
+                     data-testid="stats-grid">
+                    <article class="stat-card" data-testid="stat-card-active">
                         <div class="stat-shell">
                             <span class="stat-icon stat-icon-lock"><i class="fas fa-lock"></i></span>
                             <div>
                                 <p class="stat-label">Active Locks</p>
-                                <p class="stat-value" id="stat-active">0</p>
+                                <p class="stat-value" id="stat-active" data-testid="stat-active">0</p>
                             </div>
                         </div>
                     </article>
-                    <article class="stat-card">
+                    <article class="stat-card" data-testid="stat-card-releases">
                         <div class="stat-shell">
                             <span class="stat-icon stat-icon-release"><i class="fas fa-check-double"></i></span>
                             <div>
                                 <p class="stat-label">Releases Today</p>
-                                <p class="stat-value stat-value-success" id="stat-releases">0</p>
+                                <p class="stat-value stat-value-success"
+                                   id="stat-releases"
+                                   data-testid="stat-releases">0</p>
                             </div>
                         </div>
                     </article>
-                    <article class="stat-card">
+                    <article class="stat-card" data-testid="stat-card-avg">
                         <div class="stat-shell">
                             <span class="stat-icon stat-icon-avg"><i class="fas fa-bolt"></i></span>
                             <div>
                                 <p class="stat-label">Avg Hold Time</p>
-                                <p class="stat-value stat-value-info" id="stat-avg">0m</p>
+                                <p class="stat-value stat-value-info"
+                                   id="stat-avg"
+                                   data-testid="stat-avg">0m</p>
                             </div>
                         </div>
                     </article>
@@ -553,7 +574,7 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
                                     <th class="text-end">Action</th>
                                 </tr>
                             </thead>
-                            <tbody id="active-locks-body">
+                            <tbody id="active-locks-body" data-testid="active-locks-body">
                                 <tr>
                                     <td colspan="6" class="text-center py-4 text-muted">Connecting...</td>
                                 </tr>
@@ -562,7 +583,10 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
                     </div>
                 </div>
             </section>
-            <section id="history-page" class="page-view hidden" aria-label="history view">
+            <section id="history-page"
+                     class="page-view hidden"
+                     aria-label="history view"
+                     data-testid="history-page">
                 <div class="page-head">
                     <h2 class="page-title">
                         <i class="fas fa-clock-rotate-left"></i>Lock History
@@ -583,7 +607,7 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
                                     <th>Outcome</th>
                                 </tr>
                             </thead>
-                            <tbody id="history-body">
+                            <tbody id="history-body" data-testid="history-body">
                                 <tr>
                                     <td colspan="8" class="text-center py-4 text-muted">Loading history...</td>
                                 </tr>
@@ -626,13 +650,16 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
             </div>
         </div>
         <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
+        <script src="dashboard-format.js"></script>
         <script>
-        const serverCfg = window.__SUPABASE_CONFIG__ || {};
-        const SUPABASE_URL = serverCfg.url || "";
-        const SUPABASE_KEY = serverCfg.serviceKey || serverCfg.anonKey || "";
-        const SUPABASE_USER = serverCfg.user || null;
-        const IS_ADMIN = !!serverCfg.serviceKey;
-        const SUPABASE_MODE = !!(SUPABASE_URL && SUPABASE_KEY);
+        let runtimeCfg = window.__SUPABASE_CONFIG__ || {};
+        let SUPABASE_URL = "";
+        let SUPABASE_KEY = "";
+        let SUPABASE_USER = null;
+        let IS_ADMIN = false;
+        let SUPABASE_MODE = false;
+        let supabaseClientFingerprint = "";
+        const RUNTIME_CONFIG_PATH = "/collab-runtime-config.json";
 
         const PAGE_SIZE = 25;
         const HISTORY_PREFETCH_GAP_PX = 120;
@@ -665,56 +692,14 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
             }
         }
 
-        function formatDateLong(dt) {
-            return dt.toLocaleDateString([], {
-                year: "numeric",
-                month: "long",
-                day: "numeric"
-            });
-        }
-
-        function formatTime24(dt) {
-            return dt.toLocaleTimeString([], {
-                hour: "2-digit",
-                minute: "2-digit",
-                hour12: false
-            });
-        }
-
-        function formatDateTime24(dt) {
-            return formatDateLong(dt) + " " + formatTime24(dt);
-        }
-
-        function formatDurationMinutes(totalMinutes) {
-            const rounded = Math.max(0, Math.round(Number(totalMinutes) || 0));
-            if (!Number.isFinite(rounded) || rounded <= 0) {
-                return "0m";
-            }
-
-            const units = [
-                { label: "mo", minutes: 30 * 24 * 60 },
-                { label: "d", minutes: 24 * 60 },
-                { label: "h", minutes: 60 },
-                { label: "m", minutes: 1 }
-            ];
-
-            let remaining = rounded;
-            const parts = [];
-
-            units.forEach((unit) => {
-                if (remaining >= unit.minutes) {
-                    const value = Math.floor(remaining / unit.minutes);
-                    remaining -= value * unit.minutes;
-                    parts.push(String(value) + unit.label);
-                }
-            });
-
-            return parts.length ? parts.join(" ") : "0m";
-        }
+        const fmt = window.DashboardFormat;
+        const formatDateLong = fmt.formatDateLong;
+        const formatTime24 = fmt.formatTime24;
+        const formatDateTime24 = fmt.formatDateTime24;
+        const formatDurationMinutes = fmt.formatDurationMinutes;
 
         function routeFromHash() {
-            const h = window.location.hash.replace("#", "").toLowerCase();
-            return h === "history" ? "history" : "locks";
+            return fmt.routeFromHash(window.location.hash);
         }
 
         function navigate(page) {
@@ -764,14 +749,57 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
             document.getElementById("nav-history").disabled = true;
         }
 
+        function applyRuntimeConfig() {
+            SUPABASE_URL = runtimeCfg.url || "";
+            SUPABASE_KEY = runtimeCfg.serviceKey || runtimeCfg.anonKey || "";
+            SUPABASE_USER = runtimeCfg.user || null;
+            IS_ADMIN = !!runtimeCfg.serviceKey;
+            SUPABASE_MODE = !!(SUPABASE_URL && SUPABASE_KEY);
+            updateProjectInfo();
+        }
+
+        function updateProjectInfo() {
+            const el = document.getElementById("project-info");
+            if (!SUPABASE_URL) {
+                el.classList.add("hidden");
+                el.textContent = "";
+                return;
+            }
+            try {
+                const host = new URL(SUPABASE_URL).hostname.replace(".supabase.co", "");
+                el.textContent = host;
+                el.title = "Supabase project: " + SUPABASE_URL;
+                el.classList.remove("hidden");
+            } catch (e) {
+                el.classList.add("hidden");
+            }
+        }
+
+        async function syncRuntimeConfig() {
+            try {
+                const resp = await fetch(RUNTIME_CONFIG_PATH, { cache: "no-store" });
+                if (resp.ok) {
+                    const live = await resp.json();
+                    if (live && live.url) {
+                        runtimeCfg = live;
+                    }
+                }
+            } catch (e) {
+                console.debug("Runtime config fetch skipped", e);
+            }
+            applyRuntimeConfig();
+        }
+
         function showMain() {
             document.getElementById("setup-view").classList.add("hidden");
             document.getElementById("locks-page").classList.remove("hidden");
             document.getElementById("history-page").classList.remove("hidden");
+            const userInfo = document.getElementById("user-info");
             if (SUPABASE_USER) {
-                const userInfo = document.getElementById("user-info");
                 userInfo.classList.remove("hidden");
                 userInfo.innerHTML = '<i class="fab fa-github me-1"></i>' + SUPABASE_USER;
+            } else {
+                userInfo.classList.add("hidden");
             }
         }
 
@@ -783,33 +811,40 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
                 '</td></tr>';
         }
 
-        function loadSupabaseClient() {
+        function loadSupabaseLibrary() {
             return new Promise((resolve, reject) => {
                 if (window.supabase) {
-                    try {
-                        supabaseClient = window.supabase.createClient(SUPABASE_URL, SUPABASE_KEY);
-                        resolve();
-                    } catch (e) {
-                        reject(e);
-                    }
+                    resolve();
                     return;
                 }
-
                 const script = document.createElement("script");
                 script.src = "https://cdn.jsdelivr.net/npm/@supabase/supabase-js/dist/umd/supabase.min.js";
-                script.onload = () => {
-                    try {
-                        supabaseClient = window.supabase.createClient(SUPABASE_URL, SUPABASE_KEY);
-                        resolve();
-                    } catch (e) {
-                        reject(e);
-                    }
-                };
+                script.onload = () => resolve();
                 script.onerror = reject;
                 document.head.appendChild(script);
             });
         }
 
+        function buildSupabaseClient() {
+            return window.supabase.createClient(SUPABASE_URL, SUPABASE_KEY);
+        }
+
+        async function ensureSupabaseClient() {
+            await syncRuntimeConfig();
+            if (!SUPABASE_MODE) {
+                return false;
+            }
+            const fingerprint =
+                SUPABASE_URL + "|" + (runtimeCfg.serviceKey ? "service" : "anon");
+            if (supabaseClient && supabaseClientFingerprint === fingerprint) {
+                return true;
+            }
+            await loadSupabaseLibrary();
+            supabaseClient = buildSupabaseClient();
+            supabaseClientFingerprint = fingerprint;
+            return true;
+        }
+
         function subscribeRealtime() {
             if (!supabaseClient) {
                 return;
@@ -840,6 +875,10 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
             const syncBtn = document.getElementById("sync-btn");
             syncBtn.disabled = true;
             try {
+                if (!(await ensureSupabaseClient())) {
+                    showSetup();
+                    return;
+                }
                 const { data, error } = await supabaseClient
                     .from("file_locks")
                     .select("*")
@@ -864,7 +903,7 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
                 console.error(e);
                 showLocksError("Unable to fetch active locks.");
             } finally {
-                syncBtn.disabled = false;
+                syncBtn.disabled = !SUPABASE_MODE;
             }
         }
 
@@ -949,6 +988,9 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
 
             historyLoading = true;
             try {
+                if (!(await ensureSupabaseClient())) {
+                    return;
+                }
                 const from = historyOffset;
                 const to = historyOffset + PAGE_SIZE - 1;
                 const { data, error } = await supabaseClient
@@ -1102,17 +1144,15 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
         async function init() {
             releaseModal = new bootstrap.Modal(document.getElementById("releaseModal"));
             wireEvents();
-
-            if (!SUPABASE_MODE) {
-                showSetup();
-                return;
-            }
-
-            showMain();
-            applyRoute();
+            applyRuntimeConfig();
 
             try {
-                await loadSupabaseClient();
+                if (!(await ensureSupabaseClient())) {
+                    showSetup();
+                    return;
+                }
+                showMain();
+                applyRoute();
                 await refreshLocks();
                 if (routeFromHash() === "history") {
                     resetHistory();