collab-runtime 0.2.9__tar.gz

collab_runtime-0.2.9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KirilMT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

collab_runtime-0.2.9/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: collab-runtime
+Version: 0.2.9
+Summary: Collaborative file locking runtime
+Author-email: KirilMT <kiril.mt95@gmail.com>
+License-Expression: MIT
+Keywords: collaboration,file-locking,supabase,cli,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: supabase>=2.30.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: psutil>=5.9.8
+Requires-Dist: plyer>=2.1.0
+Dynamic: license-file
+
+# collab-runtime — Collaborative File Locking
+
+> Prevent merge conflicts by automatically locking files when a developer starts editing them, using **Supabase Realtime** as the backend.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/KirilMT/collab/blob/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/collab-runtime)](https://pypi.org/project/collab-runtime/)
+
+---
+
+## What It Does
+
+`collab-runtime` provides a CLI and background daemon that coordinate file-level locking across a development team in real time.
+When a developer opens a file, a lock is acquired in Supabase. Other developers are immediately notified — via desktop notifications, VS Code warnings, or the web dashboard — that the file is in use.
+
+**Key features:**
+
+- ⚡ **Atomic lock acquisition** — Supabase RPC prevents two developers locking the same file simultaneously
+- 📡 **Real-time broadcast** — Supabase Realtime pushes lock events to all connected clients instantly
+- 🖥️ **Web dashboard** — Live lock status view, force-release controls
+- 🔔 **VS Code extension** — Lock warnings, status bar, output channel
+- 🪝 **Git hooks** — Pre-commit and pre-push hooks block commits of locked files
+- 📋 **Audit trail** — Full lock history with configurable retention
+
+---
+
+## Prerequisites
+
+| Requirement      | Version / Notes                                        |
+| ---------------- | ------------------------------------------------------ |
+| Python           | 3.10 or higher                                         |
+| Supabase account | [supabase.com](https://supabase.com) — free tier works |
+| Node.js          | Only required for the VS Code extension                |
+
+---
+
+## Installation
+
+```bash
+pip install collab-runtime
+```
+
+For a minimum-version install (ensures you get the latest compatible release):
+
+```bash
+pip install "collab-runtime>=0.2.2"
+```
+
+---
+
+## Quick Start
+
+### 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).
+
+This creates the `file_locks` table, `file_locks_history` audit table, the atomic `acquire_lock()` RPC, Row Level Security policies, and Realtime publication.
+
+### 2 — Configure Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=your_anon_key_here
+SUPABASE_SERVICE_ROLE_KEY=your_service_role_key   # Required for force-release
+DEVELOPER_ID=your_name                             # Optional, defaults to git user.name
+LOCK_STRICT=0                                      # 1 = block on lock errors, 0 = warn only
+```
+
+> **Keep `SUPABASE_SERVICE_ROLE_KEY` private — never commit it to version control.**
+
+### 3 — Verify Connection
+
+```bash
+collab active
+```
+
+If connected, this lists all currently active locks (empty on a fresh setup).
+
+---
+
+## CLI Reference
+
+```bash
+# Show all active locks across the team
+collab active
+
+# Lock a file before editing
+collab acquire path/to/file.py --reason "Implementing feature X"
+
+# Release a lock when done
+collab release path/to/file.py
+
+# Check lock status for a specific file
+collab status path/to/file.py
+
+# Release all locks held by you
+collab release-all
+
+# Force release (requires SUPABASE_SERVICE_ROLE_KEY)
+collab force-release path/to/file.py
+collab force-release-all
+
+# Batch operations
+collab acquire-batch path/to/a.py path/to/b.py --reason "Refactoring"
+collab release-batch path/to/a.py path/to/b.py
+
+# Reconcile local and remote lock state
+collab reconcile
+
+# Lock history and retention
+collab history
+collab history path/to/file.py --limit 50
+collab history-prune --days 30
+
+# Background watcher daemon
+collab daemon-start
+collab daemon-start --interval 10 --timeout 480
+collab daemon-status
+collab daemon-stop
+
+# Foreground watcher (diagnostics)
+collab watch --interval 5 --timeout 0
+
+# Web dashboard (opens in browser)
+collab dashboard
+
+# Cleanup orphaned watcher processes
+collab cleanup
+```
+
+---
+
+## VS Code Extension
+
+The optional VS Code extension provides lock-on-open warnings, a status bar indicator, and one-click dashboard access.
+
+**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
+3. Reload VS Code
+
+Once installed, the extension automatically starts and stops the background daemon with your VS Code window.
+
+---
+
+## How It Works
+
+```
+Developer opens file
+      │
+      ▼
+collab acquire (CLI or extension)
+      │
+      ▼
+Supabase RPC: acquire_lock()   ◄─── atomic, unique constraint
+      │                                prevents double-locking
+      ▼
+Supabase Realtime broadcast
+      │
+      ├─► VS Code extension  →  lock warning popup
+      ├─► Web dashboard      →  live status update
+      └─► Desktop notification (via plyer)
+```
+
+Lock release follows the same path in reverse and writes an entry to `file_locks_history` for audit.
+
+---
+
+## Security
+
+- 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`.
+- Never commit secrets; use `.env` for local configuration only.
+
+---
+
+## Links
+
+- 📦 **PyPI:** [pypi.org/project/collab-runtime](https://pypi.org/project/collab-runtime/)
+- 🐙 **GitHub:** [github.com/KirilMT/collab](https://github.com/KirilMT/collab)
+- 🐛 **Issues:** [github.com/KirilMT/collab/issues](https://github.com/KirilMT/collab/issues)
+- 📖 **Full docs:** [github.com/KirilMT/collab/tree/main/docs](https://github.com/KirilMT/collab/tree/main/docs)
+- 🗺️ **Roadmap:** [docs/collab_roadmap.md](https://github.com/KirilMT/collab/blob/main/docs/collab_roadmap.md)
+
+---
+
+## License
+
+MIT — see [LICENSE](https://github.com/KirilMT/collab/blob/main/LICENSE) for details.

collab_runtime-0.2.9/README.md

@@ -0,0 +1,472 @@
+# Collab Runtime — Collaborative File Locking
+
+Prevents merge conflicts by automatically locking files when a developer starts editing them, using Supabase Realtime as the backend.
+
+---
+
+## Prerequisites
+
+- **Python** 3.10+
+- **Supabase** account with a project ([supabase.com](https://supabase.com))
+- **Node.js** (only for the VS Code extension)
+- **Git** (for pre-commit hooks integration)
+
+---
+
+## 5-Minute Setup Guide
+
+### 1. Create the Database Schema
+
+Open your Supabase project's **SQL Editor** and run the contents of `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
+5. Click **Run**
+
+This creates:
+
+- `file_locks` table (active locks)
+- `file_locks_history` table (audit trail)
+- `acquire_lock()` RPC function (atomic lock acquisition)
+- Row Level Security policies
+- Realtime publication
+- Auto-history trigger on lock release
+- Automatic history retention (30 days by default)
+
+### 2. Install the Package
+
+The `collab` command-line tool is distributed as `collab-runtime` on PyPI.
+
+**Development Setup (from source):**
+One command handles everything — dependencies, `.env` configuration, and IDE integration:
+
+**Windows (PowerShell):**
+
+```powershell
+.\scripts\setup-dev.ps1
+```
+
+**Linux/macOS (Bash):**
+
+```bash
+./scripts/setup.sh
+```
+
+**End-User Install (via pip):**
+
+```bash
+pip install collab-runtime
+```
+
+The setup script automatically:
+
+- Creates a Python virtual environment (`.venv`)
+- Installs `collab-runtime` and its dependencies
+- Prompts for Supabase credentials if `.env` is missing
+- Copies git pre-commit hooks
+- Installs IDE extensions (VS Code, etc.)
+
+### 3. Environment Variables
+
+After setup, verify your `.env` at the project root has these values:
+
+| Variable                    | Description                                                     |
+| --------------------------- | --------------------------------------------------------------- |
+| `SUPABASE_URL`              | Your Supabase project URL (from Project Settings → API)         |
+| `SUPABASE_ANON_KEY`         | Anonymous/public key (from Project Settings → API)              |
+| `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) |
+
+> **Important:** `SUPABASE_SERVICE_ROLE_KEY` is needed for the dashboard's Force Release button. Without it, only your own locks can be released.
+
+### 4. Verify Setup
+
+After setup, verify the connection:
+
+```bash
+collab active
+```
+
+If connected, this shows all active locks (initially empty).
+
+---
+
+## Quick Start — Testing the Locking System
+
+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
+```
+
+**Terminal 2 (View lock in another session):**
+
+```bash
+collab active
+```
+
+**Then release the lock:**
+
+```bash
+collab release src/main.py
+```
+
+**View real-time lock changes:**
+
+```bash
+collab dashboard
+```
+
+Opens in your default browser showing live lock status.
+
+---
+
+## CLI Reference
+
+The `collab` command is installed globally after setup:
+
+```bash
+# List all active locks
+collab active
+
+# Lock a file
+collab acquire path/to/file.py --reason "Feature implementation"
+
+# Release a file you locked
+collab release path/to/file.py
+
+# Check file status
+collab status path/to/file.py
+
+# Release all your locks
+collab release-all
+
+# Force release (admin only)
+collab force-release path/to/file.py
+collab force-release-all
+
+# Batch lock operations
+collab acquire-batch path/to/a.py path/to/b.py --reason "Batch work"
+collab release-batch path/to/a.py path/to/b.py
+
+# Reconcile local and remote lock state
+collab reconcile
+
+# Lock history and retention
+collab history
+collab history path/to/file.py --limit 50
+collab history-prune --days 30
+
+# Cleanup orphaned watcher processes
+collab cleanup
+
+# Start background watcher
+collab daemon-start
+collab daemon-start --interval 10 --timeout 480
+
+# Check daemon status
+collab daemon-status
+
+# Stop the daemon
+collab daemon-stop
+
+# Foreground watcher (internal/diagnostics)
+collab watch --interval 5 --timeout 0
+
+# View lock dashboard
+collab dashboard
+```
+
+---
+
+## VS Code Extension
+
+The extension warns you when a locked file is opened and provides dashboard access.
+
+### Installation
+
+The extension is primarily distributed via the **Collab Runtime** Python package. When you open a repository in VS Code, the extension will automatically check for the runtime and prompt you to install it if missing.
+
+**Automatic Install:**
+
+1. Open VS Code in a collab-enabled repository.
+2. If prompted, click **[Install via pip]**.
+
+**Manual Install (from source):**
+
+1. Press `F1` -> `Developer: Install Extension from Location...`
+2. Select `vscode-extension/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`.
+
+### Features
+
+- **Lock-on-Open Warning** — popup when opening a locked file
+- **Status Bar** — shows current file lock status
+- **Output Channel** — watcher logs in **View → Output → Collab Locks**
+- **Commands** — quick access via Command Palette
+
+### Notification Channels
+
+Notifications can come from two independent channels:
+
+- **VS Code extension notifications** (when extension is installed): lock warnings, status bar updates, output channel events.
+- **Watcher desktop notifications** (runtime via `plyer`): emitted by the watcher for lock/conflict lifecycle events.
+
+If the extension is not available, watcher notifications and CLI/dashboard behavior still work.
+
+### Extension Configuration
+
+Create or update `.env` in your workspace:
+
+```env
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=your_anon_key
+DEVELOPER_ID=your_name  # optional: defaults to git config user.name
+```
+
+---
+
+## Session Identity & Stability
+
+Collab uses a stable session identity derived from your developer id, host, and project root.
+This keeps lock ownership consistent across IDE terminals and avoids accidental token churn
+between restarts.
+
+---
+
+## Automatic Lifecycle
+
+- `collab daemon-start` creates a watcher process namespace tied to this repository.
+- `collab daemon-status` returns exit code `0` when watcher is running and `1` when not running.
+- `collab daemon-stop` requests graceful shutdown and releases process-state artifacts.
+
+If a stale PID marker exists, startup logic attempts cleanup and recovery before launching a
+replacement watcher.
+
+---
+
+## Kill the Daemon Manually
+
+If graceful shutdown fails, remove the watcher process manually:
+
+Windows PowerShell:
+
+```powershell
+$pidPath = ".daemon.pid"
+if (Test-Path $pidPath) {
+	$raw = Get-Content $pidPath -Raw
+	if ($raw.Trim().StartsWith("{")) {
+		$obj = $raw | ConvertFrom-Json
+		taskkill /F /PID $obj.pid
+	} else {
+		taskkill /F /PID [int]$raw
+	}
+	Remove-Item $pidPath -Force
+}
+```
+
+---
+
+## Database Schema
+
+The full schema is in `schema.sql` and includes:
+
+- `file_locks` for active locks.
+- `file_locks_history` for audit/history.
+- `acquire_lock(...)` RPC for atomic lock acquisition.
+- release trigger for automatic history writes.
+- optional retention pruning support.
+
+---
+
+## Security Model
+
+- Lock correctness is enforced in the application workflow plus atomic RPC behavior.
+- Force-release operations require service-role level credentials.
+- Keep `SUPABASE_SERVICE_ROLE_KEY` private; never commit it.
+- Use `.env` only for local secret storage.
+
+---
+
+## Directory Structure
+
+```
+collab/
+├── src/
+│   ├── lock_client.py          # CLI entry point
+│   ├── live_locks_watcher.py   # Background watcher
+│   ├── main.py                 # CLI orchestration + module entry point
+│   ├── dashboard/              # Web UI
+│   └── __init__.py             # Package marker
+├── logs/                       # Runtime logs (created dynamically)
+├── tests/
+│   ├── backend/
+│   │   ├── unit/               # Unit tests
+│   │   ├── functional/         # Functional tests
+│   │   ├── integration/        # Integration tests
+│   │   ├── security/           # Security tests
+│   │   ├── performance/        # Performance tests
+│   │   └── reliability/        # Reliability tests
+│   └── frontend/
+│       ├── jest/               # Frontend unit placeholder
+│       └── playwright/         # Frontend e2e placeholder
+├── scripts/
+│   ├── setup-dev.ps1           # Windows setup
+│   ├── setup.sh                # Linux/macOS setup
+│   ├── format_code.py          # Code formatter
+│   ├── validate_code.py        # CI validator
+│   └── cleanup.py              # Cache cleanup
+├── schema.sql                  # Supabase database schema
+├── pyproject.toml              # Package configuration
+└── README.md                   # This file
+```
+
+---
+
+## Runtime Logs
+
+Logs are stored in `logs/` and the directory is created dynamically at runtime:
+
+```
+logs/
+├── collab.log                  # Production logs
+└── test_collab.log             # Test logs
+```
+
+View logs in real-time:
+
+```bash
+# Linux/macOS
+tail -f logs/collab.log
+
+# Windows PowerShell
+Get-Content logs/collab.log -Tail 10 -Wait
+```
+
+---
+
+## Git Integration
+
+Pre-commit hooks prevent commits of locked files. To use:
+
+```bash
+collab acquire path/to/file.py --reason "Fixing bug #123"
+git add path/to/file.py
+git commit -m "fix: resolve issue"
+collab release path/to/file.py
+```
+
+---
+
+## Troubleshooting
+
+### `collab active` shows "Connection refused"
+
+**Fix:** Check credentials in `.env`:
+
+```bash
+cat .env  # Verify SUPABASE_URL and SUPABASE_ANON_KEY
+```
+
+### `collab` command not found
+
+**Fix:** Ensure your virtual environment is active or install the package:
+
+```bash
+pip install collab-runtime
+```
+
+### `python collab.py daemon-status` fails with file-not-found
+
+`collab.py` is not a file in this repository.
+
+Use:
+
+```bash
+collab daemon-status
+```
+
+### VS Code extension not loading
+
+**Fix:**
+
+1. Reload: `Ctrl+Shift+P` → "Developer: Reload Window"
+2. Check logs: **View → Output → Collab Locks**
+
+---
+
+## Architecture
+
+### Lock Acquisition
+
+1. `collab acquire file.py` sends lock request to Supabase
+2. Supabase atomically adds lock (unique constraint prevents conflicts)
+3. Realtime broadcasts lock to all connected clients
+4. VS Code shows lock warning if file is open
+
+### 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
+
+### Dashboard
+
+```bash
+collab dashboard  # Opens in browser with real-time lock view
+```
+
+---
+
+## Development
+
+### Install for Development
+
+```bash
+python -m pip install .
+```
+
+### Run Tests
+
+```bash
+pytest tests/backend tests/frontend
+```
+
+### Code Quality
+
+```bash
+python scripts/format_code.py
+python scripts/validate_code.py
+```
+
+### Create Distribution
+
+```bash
+python -m build
+```
+
+---
+
+## License
+
+MIT License — see LICENSE file for details.
+
+---
+
+## Support
+
+For issues, questions, or feature requests:
+
+1. Check [issues](../../issues)
+2. Open a [new issue](../../issues/new) with reproduction steps
+3. See [docs/collab_roadmap.md](docs/collab_roadmap.md) for planned features