letswork 0.1.0__py3-none-any.whl

letswork-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: letswork
+Version: 0.1.0
+Summary: Real-time collaborative coding via MCP — two developers, one codebase
+Author: Sai Charan Rajoju
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: textual[syntax]>=0.50.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LetsWork
+
+**Google Docs for AI-assisted coding** — real-time collaboration on a local codebase using two independent Claude subscriptions.
+
+## What is LetsWork?
+
+LetsWork is an MCP (Model Context Protocol) server that lets two developers work on the same local codebase simultaneously, each using their own Claude. One developer hosts, the other connects — with file-level locking to prevent conflicts.
+
+## How It Works
+
+1. Developer A (Host) runs `letswork start` in their project folder
+2. A secure HTTPS tunnel is created automatically via Cloudflare
+3. A one-time URL + secret token is generated
+4. Developer A shares both with Developer B (Guest)
+5. Developer B connects: `claude mcp add letswork --transport http <url>`
+6. Both can now read, write, and list files — with lock protection
+
+## Quick Start
+
+### Install
+```bash
+pip install letswork
+```
+
+### Requirements
+
+- Python >= 3.10
+- [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) installed and available in PATH
+- Git (recommended for conflict safety)
+
+### Host (Developer A)
+```bash
+cd /path/to/your/project
+letswork start
+```
+
+You'll see:
+╔══════════════════════════════════════════════════╗
+║  LetsWork Session Active                        ║
+║                                                 ║
+║  URL:   https://abc123.trycloudflare.com        ║
+║  Token: a1b2c3d4e5f6...                         ║
+║                                                 ║
+║  Share both with your collaborator.             ║
+║  Press Ctrl+C to end session.                   ║
+╚══════════════════════════════════════════════════╝
+
+Share the URL and token with your collaborator via Slack, Discord, or text.
+
+### Guest (Developer B)
+```bash
+claude mcp add letswork --transport http <URL_FROM_HOST>
+```
+
+Use the token when prompted. You now have full access to the shared codebase through your own Claude.
+
+## MCP Tools Available
+
+| Tool | Description |
+|------|-------------|
+| `list_files` | List files and directories with lock status |
+| `read_file` | Read file contents (1MB limit) |
+| `write_file` | Write to a file (auto-locks if needed) |
+| `lock_file` | Lock a file for exclusive editing |
+| `unlock_file` | Release a file lock |
+| `get_status` | Show session info and active locks |
+
+## Security
+
+- Unguessable tunnel URL (random Cloudflare subdomain)
+- Cryptographic secret token (second auth layer)
+- All traffic encrypted via HTTPS
+- Path traversal prevention (no access outside project root)
+- No accounts, no signup, no persistent credentials
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `letswork start [--port PORT]` | Start session (default port: 8000) |
+| `letswork stop` | Stop instructions (use Ctrl+C in v1) |
+| `letswork status` | Status instructions (use get_status tool in v1) |
+
+## Architecture
+Developer A's Machine:
+[Local Codebase] ← [MCP Server] ← [Cloudflare Tunnel] ← HTTPS URL
+↑
+Developer B connects here
+with secret token
+
+## Constraints (v1)
+
+- Maximum 2 users per session (Host + Guest)
+- Text files only (no binary support)
+- 1MB file size limit per operation
+- File operations only (no shell access for Guest)
+
+## License
+
+MIT
+
+---
+
+Built with the [Model Context Protocol](https://modelcontextprotocol.io).

letswork-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+src/__init__.py,sha256=V-C7MVI9SEarXdwLzTU79-D5BNdcJEZ3j_c-cXJoEaY,59
+src/approval.py,sha256=sUU00NUnSKHezX7dvbg1i1zvKboWE3_zkFnY0wvB1ug,2936
+src/auth.py,sha256=iqVHXp6LnSZ5laRNx7kP5DwAW-XmrouANWTTGKdGMbo,370
+src/cli.py,sha256=-yDc3C7pU8rpwHPLefugCuCoLQ-m4Ub6OXKWBGXowoU,4254
+src/events.py,sha256=ajXpZzVvoj3XccDUakUmow0KXGgVV2y-6H8ABnYChmU,2758
+src/filelock.py,sha256=eCgDvG9RkBb5E2IAQk0Vbf_r4kmcEuOmqu-o2S0cA6Q,1286
+src/launcher.py,sha256=j3viEHVw1iZX-T7fx0E6aHfaGdGdcypsho_Kz6cDIX8,2137
+src/remote_client.py,sha256=7ioO43Iqx0fDzBQKySZJ6xi6jXfhduFH-TNovk1r_HE,3429
+src/server.py,sha256=nNRV6Ii9Nyo_ZOwTXLnZ4v7C-UNbt-ZbvP1IJI--67o,7449
+src/tunnel.py,sha256=xjU9yq3EGV4gwEZSjGEPnRVmow_7t8Zf_Ek_0aB_2NY,1467
+src/tui/__init__.py,sha256=b4agVr1NW13jOLM19ubh7ka-D5NUGQkHSSJjkM_mGco,30
+src/tui/app.py,sha256=2SNSmKUmCkJ0PW5DwkngwNJMajmMLzOJxagc5i43wrU,10932
+src/tui/approval_panel.py,sha256=-gA8dlBuD_iM0--Lycx6NRFWaGLVOtBG3mvIZQsho0g,3318
+src/tui/chat.py,sha256=iaQPoiG5jlL2AazBJCwlrUWGhigH92lLLgr0MYL2i_4,1531
+src/tui/file_tree.py,sha256=9CdIZLlyX792t63sVP-pEvhJ79FyHFVZByP-Z4tqAdg,2293
+src/tui/file_viewer.py,sha256=iwqcGRbfxuk0NTKD50O7zrXKHuuWakviwy-euv5_jXM,5866
+src/tui/guest_app.py,sha256=9_YWwOjUHwiIhlZjtBRLdwAqXNCjQjnry0JuRnGDtw8,8011
+src/tui/terminal_panel.py,sha256=-h8wr5oQ6gdTLbkOPa8jkno6PbiFqHOgw3sGopgahXQ,2336
+letswork-0.1.0.dist-info/METADATA,sha256=yM7cWa4RS5Xdkib7b2RWLTDxxbYnUJ1WZS_ZRxfoIlE,3993
+letswork-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+letswork-0.1.0.dist-info/entry_points.txt,sha256=5Sbn4KIDeVd-hiKaNaOpTsR8cP9i_EG0Zew69hXxWAk,41
+letswork-0.1.0.dist-info/RECORD,,

letswork-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

letswork-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+letswork = src.cli:cli

src/__init__.py

@@ -0,0 +1 @@
+"""LetsWork — real-time collaborative coding via MCP."""

src/approval.py

@@ -0,0 +1,98 @@
+import os
+import uuid
+import difflib
+from enum import Enum
+from dataclasses import dataclass, field
+from datetime import datetime
+
+class ApprovalStatus(str, Enum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+@dataclass
+class PendingChange:
+    id: str
+    user_id: str
+    path: str
+    new_content: str
+    old_content: str
+    status: ApprovalStatus = ApprovalStatus.PENDING
+    timestamp: datetime = field(default_factory=datetime.now)
+
+class ApprovalQueue:
+    def __init__(self, project_root: str):
+        self.project_root = project_root
+        self._pending: dict[str, PendingChange] = {}
+        self._history: list[PendingChange] = []
+
+    def submit(self, user_id: str, path: str, new_content: str) -> PendingChange:
+        change_id = str(uuid.uuid4())[:8]
+        abs_path = os.path.join(self.project_root, path)
+        
+        if os.path.isfile(abs_path):
+            with open(abs_path, "r", encoding="utf-8") as f:
+                old_content = f.read()
+        else:
+            old_content = ""
+            
+        change = PendingChange(
+            id=change_id,
+            user_id=user_id,
+            path=path,
+            new_content=new_content,
+            old_content=old_content
+        )
+        self._pending[change_id] = change
+        return change
+
+    def approve(self, change_id: str) -> bool:
+        if change_id not in self._pending:
+            return False
+            
+        change = self._pending[change_id]
+        abs_path = os.path.join(self.project_root, change.path)
+        
+        dirname = os.path.dirname(abs_path)
+        if dirname:
+            os.makedirs(dirname, exist_ok=True)
+            
+        with open(abs_path, "w", encoding="utf-8") as f:
+            f.write(change.new_content)
+            
+        change.status = ApprovalStatus.APPROVED
+        self._history.append(change)
+        del self._pending[change_id]
+        return True
+
+    def reject(self, change_id: str) -> bool:
+        if change_id not in self._pending:
+            return False
+            
+        change = self._pending[change_id]
+        change.status = ApprovalStatus.REJECTED
+        self._history.append(change)
+        del self._pending[change_id]
+        return True
+
+    def get_pending(self) -> list[PendingChange]:
+        return list(self._pending.values())
+
+    def get_diff(self, change_id: str) -> str:
+        if change_id not in self._pending:
+            return "Change not found"
+            
+        change = self._pending[change_id]
+        diff_lines = list(difflib.unified_diff(
+            change.old_content.split("\n"),
+            change.new_content.split("\n"),
+            fromfile=f"a/{change.path}",
+            tofile=f"b/{change.path}",
+            lineterm=""
+        ))
+        
+        diff_str = "\n".join(diff_lines)
+        if not diff_str:
+            return "No changes detected"
+            
+        return diff_str

src/auth.py

@@ -0,0 +1,12 @@
+import secrets
+import hmac
+
+
+def generate_token() -> str:
+    """Generate a cryptographically secure URL-safe token for session auth."""
+    return secrets.token_urlsafe(32)
+
+
+def validate_token(provided: str, expected: str) -> bool:
+    """Validate a token using constant-time comparison to prevent timing attacks."""
+    return hmac.compare_digest(provided, expected)

src/cli.py

@@ -0,0 +1,132 @@
+import os
+import click
+import src.server as server_module
+from src.auth import generate_token
+from src.tunnel import start_tunnel, stop_tunnel
+
+
+@click.group()
+def cli():
+    """LetsWork — real-time collaborative coding via MCP."""
+    pass
+
+
+@cli.command()
+@click.option("--port", default=8000, type=int, help="Port for the MCP server")
+def start(port):
+    """Start a LetsWork collaboration session."""
+    import os
+    import threading
+    import src.server as server_module
+    from src.auth import generate_token
+    from src.tunnel import start_tunnel, stop_tunnel
+    from src.events import EventLog
+    from src.launcher import launch_with_claude_code
+
+    # Set up project root
+    project_root = os.getcwd()
+    server_module.project_root = project_root
+
+    # Generate token
+    token = generate_token()
+    server_module.session_token = token
+
+    # Set up event log
+    event_log = EventLog()
+    server_module.event_log = event_log
+
+    # Start tunnel
+    try:
+        url, tunnel_process = start_tunnel(port)
+    except RuntimeError as e:
+        click.echo(f"Error: {e}")
+        return
+
+    # Print session info
+    click.echo("")
+    click.echo("╔══════════════════════════════════════════════════╗")
+    click.echo("║  LetsWork Session Active                        ║")
+    click.echo("║                                                 ║")
+    click.echo(f"║  URL:   {url}/mcp")
+    click.echo(f"║  Token: {token}")
+    click.echo("║                                                 ║")
+    click.echo("║  Share both with your collaborator.             ║")
+    click.echo("╚══════════════════════════════════════════════════╝")
+    click.echo("")
+
+    # Start MCP server in a background thread
+    def run_server():
+        server_module.app.settings.host = "127.0.0.1"
+        server_module.app.settings.port = port
+        server_module.app.settings.stateless_http = True
+        if hasattr(server_module.app.settings, "transport_security") and server_module.app.settings.transport_security:
+            server_module.app.settings.transport_security.enable_dns_rebinding_protection = False
+        server_module.app.run(transport="streamable-http")
+
+    server_thread = threading.Thread(target=run_server, daemon=True)
+    server_thread.start()
+
+    # Give server a moment to start
+    import time
+    time.sleep(2)
+
+    # Launch tmux split with TUI + Claude Code
+    try:
+        launch_with_claude_code(project_root, url, token, port)
+    except KeyboardInterrupt:
+        click.echo("\nShutting down...")
+    finally:
+        stop_tunnel(tunnel_process)
+        click.echo("Session ended.")
+
+
+@cli.command()
+@click.argument("url")
+@click.option("--token", prompt="Enter session token", help="Secret token from the host")
+@click.option("--user", default="guest", help="Your username")
+def join(url, token, user):
+    """Join a LetsWork session as a guest."""
+    import os
+    from src.events import EventLog
+    from src.approval import ApprovalQueue
+    from src.filelock import LockManager
+    from src.tui.app import LetsWorkApp
+
+    click.echo(f"Connecting to {url}...")
+    click.echo(f"User: {user}")
+    click.echo("")
+
+    # Guest TUI uses a local event log for display
+    event_log = EventLog()
+    lock_manager = LockManager()
+    
+    # Guest doesn't have local project root — use a temp dir
+    # Files are accessed remotely through MCP tools
+    project_root = os.getcwd()
+
+    app = LetsWorkApp(
+        project_root=project_root,
+        lock_manager=lock_manager,
+        event_log=event_log,
+        approval_queue=None,
+        guest_mode=True,
+        mcp_url=url,
+        mcp_token=token,
+        user_id=user,
+    )
+    app.run()
+
+
+@cli.command()
+def stop():
+    click.echo("In v1, use Ctrl+C in the terminal running 'letswork start' to stop the session.")
+
+
+@cli.command()
+def status():
+    click.echo("In v1, use the get_status MCP tool to check session status.")
+    click.echo("A standalone status command will be available in v2.")
+
+
+if __name__ == "__main__":
+    cli()

src/events.py

@@ -0,0 +1,80 @@
+from enum import Enum
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Callable
+
+class EventType(str, Enum):
+    CONNECTION = "connection"
+    DISCONNECTION = "disconnection"
+    FILE_READ = "file_read"
+    FILE_WRITE = "file_write"
+    FILE_LOCK = "file_lock"
+    FILE_UNLOCK = "file_unlock"
+    CHAT_MESSAGE = "chat_message"
+    FILE_TREE_REQUEST = "file_tree_request"
+
+@dataclass
+class Event:
+    timestamp: datetime
+    event_type: EventType
+    user_id: str
+    data: dict = field(default_factory=dict)
+    message: str = ""
+
+class EventLog:
+    def __init__(self):
+        self._events: list[Event] = []
+        self._listeners: list[Callable] = []
+
+    def emit(self, event_type: EventType, user_id: str, data: dict | None = None) -> Event:
+        if data is None:
+            data = {}
+        
+        message = self.format_event(event_type, user_id, data)
+        event = Event(
+            timestamp=datetime.now(),
+            event_type=event_type,
+            user_id=user_id,
+            data=data,
+            message=message
+        )
+        self._events.append(event)
+        
+        for listener in self._listeners:
+            try:
+                listener(event)
+            except Exception:
+                pass
+                
+        return event
+
+    def on_event(self, callback: Callable) -> None:
+        self._listeners.append(callback)
+
+    def get_recent(self, count: int = 50) -> list[Event]:
+        return self._events[-count:]
+
+    def format_event(self, event_type: EventType, user_id: str, data: dict | None = None) -> str:
+        if data is None:
+            data = {}
+            
+        time = datetime.now().strftime("%H:%M:%S")
+        
+        if event_type == EventType.CONNECTION:
+            return f"[{time}] ✅ {user_id} connected"
+        elif event_type == EventType.DISCONNECTION:
+            return f"[{time}] ❌ {user_id} disconnected"
+        elif event_type == EventType.FILE_READ:
+            return f"[{time}] 📖 {user_id} read {data.get('path', '?')}"
+        elif event_type == EventType.FILE_WRITE:
+            return f"[{time}] ✏️  {user_id} wrote {data.get('path', '?')}"
+        elif event_type == EventType.FILE_LOCK:
+            return f"[{time}] 🔒 {user_id} locked {data.get('path', '?')}"
+        elif event_type == EventType.FILE_UNLOCK:
+            return f"[{time}] 🔓 {user_id} unlocked {data.get('path', '?')}"
+        elif event_type == EventType.CHAT_MESSAGE:
+            return f"[{time}] 💬 {user_id}: {data.get('message', '')}"
+        elif event_type == EventType.FILE_TREE_REQUEST:
+            return f"[{time}] 📁 {user_id} viewed file tree"
+            
+        return f"[{time}] {event_type} event by {user_id}"

src/filelock.py

@@ -0,0 +1,37 @@
+class LockManager:
+    """Manages file-level locks for collaborative editing. Maps file paths to user IDs."""
+
+    def __init__(self):
+        self._locks: dict[str, str] = {}
+
+    def acquire_lock(self, path: str, user_id: str) -> bool:
+        """Acquire a lock on a file for the given user."""
+        if path not in self._locks:
+            self._locks[path] = user_id
+            return True
+        if self._locks[path] == user_id:
+            return True
+        return False
+
+    def release_lock(self, path: str, user_id: str) -> bool:
+        """Release a lock only if the user is the current owner."""
+        if path not in self._locks:
+            return False
+        if self._locks[path] != user_id:
+            return False
+        del self._locks[path]
+        return True
+
+    def get_locks(self) -> dict[str, str]:
+        """Return a copy of all active locks."""
+        return self._locks.copy()
+
+    def is_locked(self, path: str) -> tuple[bool, str | None]:
+        """Check if a file is locked. Returns (is_locked, holder_user_id)."""
+        if path in self._locks:
+            return (True, self._locks[path])
+        return (False, None)
+
+    def release_all(self) -> None:
+        """Release all locks. Used when session ends."""
+        self._locks.clear()

src/launcher.py

@@ -0,0 +1,45 @@
+import subprocess
+import shutil
+import os
+import sys
+
+
+def launch_with_claude_code(project_root: str, tunnel_url: str, token: str, port: int) -> None:
+    """Open a new Terminal tab with Claude Code, then launch TUI in current terminal."""
+
+    if sys.platform == "darwin":
+        # Mac: open new Terminal tab with Claude Code
+        claude_path = shutil.which("claude")
+        if claude_path:
+            apple_script = f'''
+            tell application "Terminal"
+                activate
+                do script "cd {project_root} && clear && echo '╔══════════════════════════════════════════════════╗' && echo '║  🤖 Claude Code — Connected to LetsWork          ║' && echo '║                                                  ║' && echo '║  MCP URL: {tunnel_url}/mcp' && echo '║  Token: {token}' && echo '║                                                  ║' && echo '║  Try: list_files, read_file, write_file           ║' && echo '╚══════════════════════════════════════════════════╝' && echo '' && claude"
+            end tell
+            '''
+            subprocess.Popen(["osascript", "-e", apple_script])
+        else:
+            print("⚠️  Claude Code not found. Install with: npm install -g @anthropic-ai/claude-code")
+            print("   Open a second terminal and run: claude")
+    else:
+        # Linux/Windows: just print instructions
+        print(f"Open a second terminal and run:")
+        print(f"  cd {project_root}")
+        print(f"  claude")
+        print(f"Claude Code will connect to your LetsWork MCP server automatically.")
+
+    # Launch TUI in current terminal
+    import src.server as server_module
+    from src.tui.app import LetsWorkApp
+
+    app = LetsWorkApp(
+        project_root=project_root,
+        lock_manager=server_module.lock_manager,
+        event_log=server_module.event_log,
+    )
+    app.run()
+
+
+def kill_session() -> None:
+    """No-op."""
+    pass

src/remote_client.py

@@ -0,0 +1,89 @@
+import requests
+import json
+import uuid
+
+
+class RemoteClient:
+    """Calls LetsWork MCP tools over HTTP. Guest TUI uses this instead of local file access."""
+
+    def __init__(self, mcp_url: str, token: str):
+        self.mcp_url = mcp_url.rstrip("/")
+        self.token = token
+        self.session_id = None
+
+    def _call_mcp(self, method: str, params: dict = None) -> dict:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": str(uuid.uuid4()),
+            "method": method,
+            "params": params or {}
+        }
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        }
+        if self.session_id:
+            headers["Mcp-Session-Id"] = self.session_id
+        try:
+            response = requests.post(self.mcp_url, json=payload, headers=headers, timeout=15)
+            if "Mcp-Session-Id" in response.headers:
+                self.session_id = response.headers["Mcp-Session-Id"]
+            content_type = response.headers.get("Content-Type", "")
+            if "text/event-stream" in content_type:
+                # Parse the last "data:" line as JSON
+                last_data = None
+                for line in response.text.splitlines():
+                    if line.startswith("data:"):
+                        last_data = line[len("data:"):].strip()
+                if last_data:
+                    return json.loads(last_data)
+                return {}
+            return response.json()
+        except Exception:
+            return {}
+
+    def initialize(self) -> bool:
+        try:
+            self._call_mcp("initialize", {
+                "protocolVersion": "2025-03-26",
+                "capabilities": {},
+                "clientInfo": {"name": "letswork-guest", "version": "1.0"}
+            })
+            self._call_mcp("notifications/initialized", {})
+            return True
+        except Exception:
+            return False
+
+    def call_tool(self, tool_name: str, arguments: dict = None) -> str:
+        try:
+            result = self._call_mcp("tools/call", {"name": tool_name, "arguments": arguments or {}})
+            try:
+                return result["result"]["content"][0]["text"]
+            except (KeyError, IndexError, TypeError):
+                return str(result)
+        except requests.RequestException:
+            return "Error: connection failed"
+
+    def list_files(self, path: str = ".") -> str:
+        return self.call_tool("list_files", {"path": path})
+
+    def read_file(self, path: str) -> str:
+        return self.call_tool("read_file", {"path": path})
+
+    def write_file(self, path: str, content: str, user_id: str) -> str:
+        return self.call_tool("write_file", {"path": path, "content": content, "user_id": user_id})
+
+    def lock_file(self, path: str, user_id: str) -> str:
+        return self.call_tool("lock_file", {"path": path, "user_id": user_id})
+
+    def unlock_file(self, path: str, user_id: str) -> str:
+        return self.call_tool("unlock_file", {"path": path, "user_id": user_id})
+
+    def send_message(self, user_id: str, message: str) -> str:
+        return self.call_tool("send_message", {"user_id": user_id, "message": message})
+
+    def get_events(self, since_index: int = 0) -> str:
+        return self.call_tool("get_events", {"since_index": since_index})
+
+    def get_status(self) -> str:
+        return self.call_tool("get_status", {})