wmdev 0.1.0 → 0.2.2

package/README.md

@@ -2,6 +2,8 @@
 
 Web dashboard for [workmux](https://github.com/raine/workmux). Provides a browser UI with embedded terminals, PR status monitoring, and CI integration on top of workmux's worktree + tmux orchestration.
 
+https://github.com/user-attachments/assets/fa13366d-e758-4221-94bf-13a5738bf7e7
+
 ## What is workmux?
 
 [workmux](https://github.com/raine/workmux) is a CLI tool that orchestrates git worktrees and tmux. It pairs each worktree with a tmux window, provisions files (copy/symlink), runs lifecycle hooks, and has first-class AI agent support. A single `workmux add` creates the worktree, opens a tmux window with configured panes, and starts your agent. `workmux merge` merges the branch, deletes the worktree, closes the window, and cleans up branches.
@@ -19,6 +21,7 @@ wmdev is a web UI that wraps workmux. It delegates core worktree lifecycle opera
 | Open/focus a worktree's tmux window | **workmux** (`workmux open`) |
 | List worktrees and agent status | **workmux** (`workmux list`, `workmux status`) |
 | File provisioning and lifecycle hooks | **workmux** (`.workmux.yaml` `files` and `post_create`) |
+| Port allocation for worktree services | **wmdev** (when `portStart` is set in `.wmdev.yaml`) or **workmux** (via `post_create` hook) |
 | Browser terminal (xterm.js ↔ tmux) | **wmdev** |
 | Service health monitoring (port polling) | **wmdev** |
 | PR status tracking and badges | **wmdev** (polls `gh pr list`) |
@@ -61,9 +64,13 @@ wmdev uses two config files in the project root:
 ```yaml
 # Services to monitor — each maps a display name to a port env var.
 # The dashboard polls these ports and shows health status badges.
+# When portStart is set, wmdev auto-allocates ports for new worktrees
+# and writes them to .env.local (no post_create hook needed).
 services:
   - name: string             # Display name (e.g. "BE", "FE")
     portEnv: string          # Env var holding the port (e.g. "BACKEND_PORT")
+    portStart: number        # (optional) Base port for slot 0 (e.g. 5111)
+    portStep: number         # (optional) Increment per worktree slot (default: 1)
 
 # Profiles define the environment when creating a worktree via the dashboard.
 profiles:
@@ -108,8 +115,12 @@ linkedRepos: []
 services:
   - name: BE
     portEnv: DASHBOARD_PORT
+    portStart: 5111
+    portStep: 10
   - name: FE
     portEnv: FRONTEND_PORT
+    portStart: 5112
+    portStep: 10
 
 profiles:
   default:
@@ -140,6 +151,8 @@ linkedRepos:
 |-----------|------|----------|-------------|
 | `services[].name` | string | yes | Display name shown in the dashboard |
 | `services[].portEnv` | string | yes | Env var containing the service port (read from each worktree's `.env.local`) |
+| `services[].portStart` | number | no | Base port for slot 0. When set, wmdev auto-allocates ports for new worktrees |
+| `services[].portStep` | number | no | Port increment per worktree slot (default: `1`). Slot 0 is reserved for main |
 | `profiles.default.name` | string | yes | Identifier for the default profile |
 | `profiles.default.systemPrompt` | string | no | System prompt for the agent; `${VAR}` placeholders expanded at runtime |
 | `profiles.default.envPassthrough` | string[] | no | Env vars passed through to the agent process |
@@ -159,20 +172,9 @@ If your `.workmux.yaml` has `auto_name.model` configured, the create-worktree di
 
 ## Architecture
 
-```
-Browser (localhost:5111)
-    │
-    ├── REST API (/api/*)  ──┐
-    └── WebSocket (/ws/*)  ──┤
-                             │
-                    Backend (Bun HTTP server)
-                             │
-              ┌──────────────┼──────────────┐
-              │              │              │
-          workmux CLI    tmux sessions   Docker
-          (worktree       (terminal      (sandbox
-           lifecycle)      access)        containers)
-```
+<p align="center">
+  <img src="docs/architecture.svg" alt="Architecture diagram" />
+</p>
 
 **Backend** — Bun/TypeScript HTTP + WebSocket server (`backend/src/server.ts`):
 
@@ -183,9 +185,9 @@ Browser (localhost:5111)
 
 ### Terminal streaming
 
-```
-Browser (xterm.js)  ←— WebSocket —→  Backend  ←— stdin/stdout pipes —→  script (PTY)  ←— tmux attach —→  tmux grouped session
-```
+<p align="center">
+  <img src="docs/terminal-streaming.svg" alt="Terminal streaming diagram" />
+</p>
 
 When a worktree is selected, the frontend opens a WebSocket to `/ws/<worktree>`. The backend spawns a PTY via `script` and attaches to a **grouped tmux session** — a separate view into the same windows. This allows the dashboard and a real terminal to view the same worktree simultaneously.