wmdev 0.1.0 → 0.2.1

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 |

package/backend/src/config.ts

@@ -4,6 +4,8 @@ import { parse as parseYaml } from "yaml";
 export interface ServiceConfig {
   name: string;
   portEnv: string;
+  portStart?: number;
+  portStep?: number;
 }
 
 export interface ProfileConfig {

package/backend/src/env.ts

@@ -1,3 +1,5 @@
+import type { ServiceConfig } from "./config";
+
 /** Read key=value pairs from a worktree's .env.local file. */
 export async function readEnvLocal(wtDir: string): Promise<Record<string, string>> {
   try {
@@ -13,24 +15,81 @@ export async function readEnvLocal(wtDir: string): Promise<Record<string, string
   }
 }
 
-/** Upsert a key=value pair in a worktree's .env.local file. */
-export async function upsertEnvLocal(wtDir: string, key: string, value: string): Promise<void> {
+/** Batch-write multiple key=value pairs to a worktree's .env.local (upsert each key). */
+export async function writeEnvLocal(wtDir: string, entries: Record<string, string>): Promise<void> {
   const filePath = `${wtDir}/.env.local`;
   let lines: string[] = [];
   try {
     const content = (await Bun.file(filePath).text()).trim();
     if (content) lines = content.split("\n");
   } catch {
-    // File doesn't exist yet, start with empty lines
+    // File doesn't exist yet
   }
 
-  const pattern = new RegExp(`^${key}=`);
-  const idx = lines.findIndex((l) => pattern.test(l));
-  if (idx >= 0) {
-    lines[idx] = `${key}=${value}`;
-  } else {
-    lines.push(`${key}=${value}`);
+  for (const [key, value] of Object.entries(entries)) {
+    const pattern = new RegExp(`^${key}=`);
+    const idx = lines.findIndex((l) => pattern.test(l));
+    if (idx >= 0) {
+      lines[idx] = `${key}=${value}`;
+    } else {
+      lines.push(`${key}=${value}`);
+    }
   }
 
   await Bun.write(filePath, lines.join("\n") + "\n");
 }
+
+/** Read .env.local from all worktree paths, optionally excluding one directory. */
+export async function readAllWorktreeEnvs(
+  worktreePaths: string[],
+  excludeDir?: string,
+): Promise<Record<string, string>[]> {
+  const results: Record<string, string>[] = [];
+  for (const p of worktreePaths) {
+    if (excludeDir && p === excludeDir) continue;
+    results.push(await readEnvLocal(p));
+  }
+  return results;
+}
+
+/**
+ * Pure: compute port assignments for a new worktree.
+ * Uses the first allocatable service as a reference to reverse-compute
+ * occupied slot indices. Index 0 is reserved for main. Returns a map
+ * of portEnv → port value for all services that have portStart set.
+ */
+export function allocatePorts(
+  existingEnvs: Record<string, string>[],
+  services: ServiceConfig[],
+): Record<string, string> {
+  const allocatable = services.filter((s) => s.portStart != null);
+  if (allocatable.length === 0) return {};
+
+  // Use the first allocatable service to discover occupied slot indices
+  const ref = allocatable[0];
+  const refStart = ref.portStart!;
+  const refStep = ref.portStep ?? 1;
+
+  const occupied = new Set<number>();
+  for (const env of existingEnvs) {
+    const raw = env[ref.portEnv];
+    if (raw == null) continue;
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < refStart) continue;
+    const diff = port - refStart;
+    if (diff % refStep !== 0) continue;
+    occupied.add(diff / refStep);
+  }
+
+  // Find the first free slot starting from 1 (0 is reserved for main)
+  let slot = 1;
+  while (occupied.has(slot)) slot++;
+
+  const result: Record<string, string> = {};
+  for (const svc of allocatable) {
+    const start = svc.portStart!;
+    const step = svc.portStep ?? 1;
+    result[svc.portEnv] = String(start + slot * step);
+  }
+  return result;
+}

package/backend/src/pr.ts

@@ -1,4 +1,4 @@
-import { readEnvLocal, upsertEnvLocal } from "./env";
+import { readEnvLocal, writeEnvLocal } from "./env";
 import type { LinkedRepoConfig } from "./config";
 import { log } from "./lib/log";
 
@@ -250,7 +250,7 @@ async function refreshStalePrData(wtDir: string): Promise<void> {
     }),
   );
 
-  await upsertEnvLocal(wtDir, "PR_DATA", JSON.stringify(updated));
+  await writeEnvLocal(wtDir, { PR_DATA: JSON.stringify(updated) });
 }
 
 /** Sync PR status to .env.local for all worktrees that have open PRs. */
@@ -287,7 +287,7 @@ export async function syncPrStatus(
     if (!wtDir || seen.has(wtDir)) continue;
     seen.add(wtDir);
 
-    await upsertEnvLocal(wtDir, "PR_DATA", JSON.stringify(entries));
+    await writeEnvLocal(wtDir, { PR_DATA: JSON.stringify(entries) });
   }
 
   if (seen.size > 0) {

package/backend/src/workmux.ts

@@ -1,5 +1,5 @@
 import { $ } from "bun";
-import { readEnvLocal } from "./env";
+import { readEnvLocal, writeEnvLocal, readAllWorktreeEnvs, allocatePorts } from "./env";
 import { expandTemplate, type ProfileConfig, type SandboxProfileConfig, type ServiceConfig } from "./config";
 import { launchContainer, removeContainer } from "./docker";
 import { log } from "./lib/log";
@@ -166,17 +166,6 @@ export function parseWorktreePorcelain(output: string): Map<string, string> {
   return paths;
 }
 
-/** Find the on-disk path for a worktree branch via `git worktree list`. */
-function findWorktreeDir(branch: string): string | null {
-  const result = Bun.spawnSync(["git", "worktree", "list", "--porcelain"], { stdout: "pipe", stderr: "pipe" });
-  if (result.exitCode !== 0) {
-    log.warn(`[workmux] git worktree list failed (exit ${result.exitCode})`);
-    return null;
-  }
-  const output = new TextDecoder().decode(result.stdout);
-  return parseWorktreePorcelain(output).get(branch) ?? null;
-}
-
 function ensureTmux(): void {
   const check = Bun.spawnSync(["tmux", "list-sessions"], { stdout: "pipe", stderr: "pipe" });
   if (check.exitCode !== 0) {
@@ -302,20 +291,22 @@ export async function addWorktree(
 
   const windowTarget = `wm-${branch}`;
 
-  // Read worktree dir from git (tmux pane may not have cd'd yet with -C)
-  const wtDir = findWorktreeDir(branch);
-  const env = wtDir ? await readEnvLocal(wtDir) : {};
-  log.debug(`[workmux:add] branch=${branch} dir=${wtDir ?? "(not found)"} env=${JSON.stringify(env)}`);
+  // Parse worktree list once — used for both dir lookup and port allocation
+  const porcelainResult = Bun.spawnSync(["git", "worktree", "list", "--porcelain"], { stdout: "pipe", stderr: "pipe" });
+  const worktreeMap = parseWorktreePorcelain(new TextDecoder().decode(porcelainResult.stdout));
+  const wtDir = worktreeMap.get(branch) ?? null;
 
-  // Append profile to .env.local (worktree-env creates it, we just add to it)
+  // Allocate ports + write PROFILE/AGENT to .env.local
   if (wtDir) {
-    const envPath = `${wtDir}/.env.local`;
-    const existing = await Bun.file(envPath).text().catch(() => "");
-    if (!existing.includes("PROFILE=")) {
-      await Bun.write(envPath, existing.trimEnd() + `\nPROFILE=${profile}\nAGENT=${agent}\n`);
-    }
+    const allPaths = [...worktreeMap.values()];
+    const existingEnvs = await readAllWorktreeEnvs(allPaths, wtDir);
+    const portAssignments = opts?.services ? allocatePorts(existingEnvs, opts.services) : {};
+    await writeEnvLocal(wtDir, { ...portAssignments, PROFILE: profile, AGENT: agent });
   }
 
+  const env = wtDir ? await readEnvLocal(wtDir) : {};
+  log.debug(`[workmux:add] branch=${branch} dir=${wtDir ?? "(not found)"} env=${JSON.stringify(env)}`);
+
   // For profiles with a system prompt, kill extra panes and send commands
   if (hasSystemPrompt && profileConfig) {
     // Kill extra panes (highest index first to avoid shifting)