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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: collab-runtime
-Version: 0.2.9
+Version: 0.3.0
 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.0}/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.0/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.0/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.0/collab}/dashboard/index.html

@@ -489,53 +489,71 @@
                 <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="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 +571,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 +580,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 +604,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,6 +647,7 @@ 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 || "";
@@ -665,56 +687,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) {

collab_runtime-0.3.0/collab/dashboard_server.py

@@ -0,0 +1,171 @@
+"""Local HTTP server for the collaborative dashboard static assets.
+
+The dashboard HTML references sibling static files (e.g. ``dashboard-format.js``). The
+injected config HTML must therefore be written *inside* ``collab/dashboard/`` and served
+from that directory — not from a lone temp file in ``/tmp``.
+"""
+
+from __future__ import annotations
+
+import atexit
+import http.server
+import json
+import logging
+import os
+import tempfile
+import threading
+import time
+from functools import partial
+from typing import Any, Callable, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+DASHBOARD_TEMP_PREFIX = ".collab-dashboard-"
+
+
+class _QuietDashboardHandler(http.server.SimpleHTTPRequestHandler):
+    """Serve dashboard static files without per-request stderr logging."""
+
+    def log_message(self, format: str, *args: Any) -> None:
+        """Suppress default SimpleHTTPRequestHandler request log lines."""
+
+
+def dashboard_directory(resource_root: str) -> str:
+    """Return the path to packaged dashboard static assets."""
+    return os.path.join(resource_root, "dashboard")
+
+
+def read_dashboard_template(resource_root: str) -> Optional[str]:
+    """Read ``index.html`` from the dashboard package directory."""
+    html_path = os.path.join(dashboard_directory(resource_root), "index.html")
+    if not os.path.exists(html_path):
+        logger.error("Dashboard file not found at %s", html_path)
+        return None
+    try:
+        with open(html_path, "r", encoding="utf-8") as fh:
+            return fh.read()
+    except OSError as exc:
+        logger.error("Error reading dashboard template: %s", exc)
+        return None
+
+
+def write_injected_dashboard_html(
+    resource_root: str, injected: dict[str, Any]
+) -> Optional[str]:
+    """Write config-injected HTML next to static assets; return path or None."""
+    content = read_dashboard_template(resource_root)
+    if content is None:
+        return None
+
+    dash_dir = dashboard_directory(resource_root)
+    inject_script = (
+        f"<script>window.__SUPABASE_CONFIG__ = {json.dumps(injected)};</script>\n"
+    )
+    try:
+        tmp = tempfile.NamedTemporaryFile(
+            mode="w",
+            delete=False,
+            suffix=".html",
+            prefix=DASHBOARD_TEMP_PREFIX,
+            dir=dash_dir,
+            encoding="utf-8",
+        )
+        tmp.write(inject_script)
+        tmp.write(content)
+        tmp.flush()
+        tmp.close()
+        return tmp.name
+    except OSError as exc:
+        logger.error("Error creating temp dashboard file: %s", exc)
+        return None
+
+
+def _register_temp_html_cleanup(html_path: str) -> None:
+    """Remove generated dashboard HTML on process exit."""
+
+    def _unlink() -> None:
+        try:
+            os.unlink(html_path)
+        except OSError:
+            pass
+
+    atexit.register(_unlink)
+
+
+def start_dashboard_http_server(
+    resource_root: str,
+    injected_html_path: str,
+    *,
+    log_error: Callable[[str, Any], None] = logger.error,
+    log_warning: Callable[[str, Any], None] = logger.warning,
+) -> Optional[str]:
+    """Serve ``collab/dashboard`` and return the URL to the injected HTML file."""
+    dash_dir = dashboard_directory(resource_root)
+    filename = os.path.basename(injected_html_path)
+
+    try:
+        handler = partial(_QuietDashboardHandler, directory=dash_dir)
+
+        server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), handler)
+        port = server.server_address[1]
+
+        thread = threading.Thread(target=server.serve_forever, daemon=True)
+        thread.start()
+
+        def _safe_shutdown() -> None:
+            try:
+                server.shutdown()
+            except BaseException:
+                pass
+            close = getattr(server, "server_close", None)
+            if callable(close):
+                try:
+                    close()
+                except OSError:
+                    pass
+
+        atexit.register(_safe_shutdown)
+        _register_temp_html_cleanup(injected_html_path)
+
+        url = f"http://127.0.0.1:{port}/{filename}"
+
+        import socket
+
+        for _ in range(20):
+            try:
+                with socket.create_connection(("127.0.0.1", port), timeout=0.3):
+                    break
+            except OSError:
+                time.sleep(0.05)
+
+        return url
+    except OSError as exc:
+        log_error("Failed to start local dashboard server: %s", exc)
+        try:
+            os.unlink(injected_html_path)
+        except OSError as cleanup_exc:
+            log_warning("Dashboard temp-file cleanup failed: %s", cleanup_exc)
+        return None
+
+
+def prepare_dashboard_server(
+    resource_root: str,
+    injected: dict[str, Any],
+    *,
+    log_error: Callable[[str, Any], None] = logger.error,
+    log_warning: Callable[[str, Any], None] = logger.warning,
+) -> Tuple[Optional[str], Optional[str]]:
+    """Write injected HTML, start server from dashboard dir; return (url, path)."""
+    html_path = write_injected_dashboard_html(resource_root, injected)
+    if not html_path:
+        return None, None
+
+    url = start_dashboard_http_server(
+        resource_root,
+        html_path,
+        log_error=log_error,
+        log_warning=log_warning,
+    )
+    if not url:
+        return None, None
+    return url, html_path

collab_runtime-0.3.0/collab/errors.py

@@ -0,0 +1,86 @@
+"""Structured error taxonomy for collab runtime lifecycle paths.
+
+Phase 5 (hardening) introduces stable exception types so daemon, watcher, PID, and
+subprocess failures can be classified without string matching in tests or operators.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class CollabError(Exception):
+    """Base exception for collab runtime failures."""
+
+    code: str = "collab_error"
+
+    def __init__(self, message: str, *, detail: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.detail = detail
+
+
+class ConfigurationError(CollabError):
+    """Missing or invalid runtime configuration (credentials, client, env)."""
+
+    code = "configuration_error"
+
+
+class LockServiceUnavailableError(CollabError):
+    """Lock service (Supabase) cannot be reached — DNS, network, or API outage."""
+
+    code = "lock_service_unavailable"
+
+
+class DaemonLifecycleError(CollabError):
+    """Daemon / background watcher lifecycle failure."""
+
+    code = "daemon_lifecycle_error"
+
+
+class DaemonStartError(DaemonLifecycleError):
+    """Watcher daemon failed to start or record a healthy PID."""
+
+    code = "daemon_start_error"
+
+
+class DaemonStopError(DaemonLifecycleError):
+    """Watcher daemon failed to stop cleanly."""
+
+    code = "daemon_stop_error"
+
+
+class PidError(CollabError):
+    """PID file or process identifier handling failure."""
+
+    code = "pid_error"
+
+
+class PidParseError(PidError):
+    """PID file contents are missing or malformed."""
+
+    code = "pid_parse_error"
+
+
+class WatcherDiscoveryError(CollabError):
+    """Could not discover or verify an existing watcher process."""
+
+    code = "watcher_discovery_error"
+
+
+class ParentMonitorError(CollabError):
+    """Parent IDE / terminal process monitoring failure."""
+
+    code = "parent_monitor_error"
+
+
+class SubprocessSecurityError(CollabError):
+    """Rejected subprocess invocation (unknown executable or disallowed args)."""
+
+    code = "subprocess_security_error"
+
+
+class SubprocessExecutionError(CollabError):
+    """Subprocess exited with failure or timed out."""
+
+    code = "subprocess_execution_error"