webmux 0.14.0 → 0.16.0

package/README.md

@@ -72,9 +72,10 @@ webmux                          # opens on http://localhost:5111
 
 ## Configuration
 
-webmux uses a single config file in the project root:
+webmux uses a project config file in the project root, plus an optional local overlay:
 
 - **`.webmux.yaml`** — Worktree root, pane layout, service ports, profiles, linked repos, and Docker sandbox settings.
+- **`.webmux.local.yaml`** — Optional local-only overlay for additional `profiles` and `lifecycleHooks`. Profiles are additive, conflicting profile names are replaced by the local definition, and local lifecycle hook commands run after the project-level command for the same hook.
 
 <details>
 <summary><strong>.webmux.yaml example</strong></summary>

package/backend/dist/server.js

@@ -6905,7 +6905,7 @@ var require_public_api = __commonJS((exports) => {
 });
 
 // backend/src/server.ts
-import { join as join6, resolve as resolve5 } from "path";
+import { join as join6, resolve as resolve6 } from "path";
 import { networkInterfaces } from "os";
 
 // backend/src/lib/log.ts
@@ -7196,7 +7196,7 @@ async function loadControlToken() {
 
 // backend/src/adapters/config.ts
 import { readFileSync } from "fs";
-import { join } from "path";
+import { dirname as dirname2, join, resolve } from "path";
 
 // node_modules/.bun/yaml@2.8.2/node_modules/yaml/dist/index.js
 var composer = require_composer();
@@ -7275,6 +7275,23 @@ var DEFAULT_CONFIG = {
 function clonePanes(panes) {
   return panes.map((pane) => ({ ...pane }));
 }
+function cloneMounts(mounts) {
+  return mounts?.map((mount) => ({ ...mount }));
+}
+function cloneProfile(profile) {
+  return {
+    ...profile,
+    envPassthrough: [...profile.envPassthrough],
+    panes: clonePanes(profile.panes),
+    ...profile.mounts ? { mounts: cloneMounts(profile.mounts) } : {}
+  };
+}
+function cloneProfiles(profiles) {
+  return Object.fromEntries(Object.entries(profiles).map(([name, profile]) => [name, cloneProfile(profile)]));
+}
+function defaultProfiles() {
+  return { default: cloneProfile(DEFAULT_CONFIG.profiles.default) };
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -7347,16 +7364,16 @@ function parseProfile(raw, fallbackRuntime) {
     ...mounts ? { mounts } : {}
   };
 }
-function parseProfiles(raw) {
+function parseProfiles(raw, includeDefaultProfile) {
   if (!isRecord(raw))
-    return { default: { ...DEFAULT_CONFIG.profiles.default, panes: clonePanes(DEFAULT_CONFIG.profiles.default.panes) } };
+    return includeDefaultProfile ? defaultProfiles() : {};
   const profiles = Object.entries(raw).reduce((acc, [name, value]) => {
     const fallbackRuntime = name === "sandbox" ? "docker" : "host";
     acc[name] = parseProfile(value, fallbackRuntime);
     return acc;
   }, {});
   if (Object.keys(profiles).length === 0) {
-    return { default: { ...DEFAULT_CONFIG.profiles.default, panes: clonePanes(DEFAULT_CONFIG.profiles.default.panes) } };
+    return includeDefaultProfile ? defaultProfiles() : {};
   }
   return profiles;
 }
@@ -7428,6 +7445,69 @@ function getDefaultProfileName(config) {
 function readConfigFile(root) {
   return readFileSync(join(root, ".webmux.yaml"), "utf8");
 }
+function readLocalConfigFile(root) {
+  return readFileSync(join(root, ".webmux.local.yaml"), "utf8");
+}
+function parseConfigDocument(text) {
+  const parsed = $parse(text);
+  return isRecord(parsed) ? parsed : {};
+}
+function parseProjectConfig(parsed) {
+  return {
+    name: typeof parsed.name === "string" && parsed.name.trim() ? parsed.name.trim() : DEFAULT_CONFIG.name,
+    workspace: {
+      mainBranch: isRecord(parsed.workspace) && typeof parsed.workspace.mainBranch === "string" ? parsed.workspace.mainBranch : DEFAULT_CONFIG.workspace.mainBranch,
+      worktreeRoot: isRecord(parsed.workspace) && typeof parsed.workspace.worktreeRoot === "string" ? parsed.workspace.worktreeRoot : DEFAULT_CONFIG.workspace.worktreeRoot,
+      defaultAgent: isRecord(parsed.workspace) ? parseAgentKind(parsed.workspace.defaultAgent) : DEFAULT_CONFIG.workspace.defaultAgent
+    },
+    profiles: parseProfiles(parsed.profiles, true),
+    services: parseServices(parsed.services),
+    startupEnvs: parseStartupEnvs(parsed.startupEnvs),
+    integrations: {
+      github: {
+        linkedRepos: isRecord(parsed.integrations) && isRecord(parsed.integrations.github) ? parseLinkedRepos(parsed.integrations.github.linkedRepos) : isRecord(parsed.integrations) && Array.isArray(parsed.integrations.github) ? parseLinkedRepos(parsed.integrations.github) : []
+      },
+      linear: {
+        enabled: isRecord(parsed.integrations) && isRecord(parsed.integrations.linear) && typeof parsed.integrations.linear.enabled === "boolean" ? parsed.integrations.linear.enabled : DEFAULT_CONFIG.integrations.linear.enabled
+      }
+    },
+    lifecycleHooks: parseLifecycleHooks(parsed.lifecycleHooks),
+    autoName: parseAutoName(parsed.auto_name)
+  };
+}
+function defaultConfig() {
+  return parseProjectConfig({});
+}
+function loadLocalProjectConfigOverlay(root) {
+  try {
+    const text = readLocalConfigFile(root).trim();
+    if (!text) {
+      return { profiles: {}, lifecycleHooks: {} };
+    }
+    const parsed = parseConfigDocument(text);
+    return {
+      profiles: parseProfiles(parsed.profiles, false),
+      lifecycleHooks: parseLifecycleHooks(parsed.lifecycleHooks)
+    };
+  } catch {
+    return { profiles: {}, lifecycleHooks: {} };
+  }
+}
+function mergeHookCommand(projectCommand, localCommand) {
+  if (projectCommand && localCommand) {
+    return ["set -e", projectCommand, localCommand].join(`
+`);
+  }
+  return localCommand ?? projectCommand;
+}
+function mergeLifecycleHooks(projectHooks, localHooks) {
+  const postCreate = mergeHookCommand(projectHooks.postCreate, localHooks.postCreate);
+  const preRemove = mergeHookCommand(projectHooks.preRemove, localHooks.preRemove);
+  return {
+    ...postCreate ? { postCreate } : {},
+    ...preRemove ? { preRemove } : {}
+  };
+}
 function gitRoot(dir) {
   const result = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], { stdout: "pipe", stderr: "pipe", cwd: dir });
   if (result.exitCode !== 0)
@@ -7435,37 +7515,31 @@ function gitRoot(dir) {
   const root = new TextDecoder().decode(result.stdout).trim();
   return root || dir;
 }
-function loadConfig(dir) {
+function projectRoot(dir) {
+  const result = Bun.spawnSync(["git", "rev-parse", "--git-common-dir"], { stdout: "pipe", stderr: "pipe", cwd: dir });
+  if (result.exitCode !== 0)
+    return gitRoot(dir);
+  const commonDir = new TextDecoder().decode(result.stdout).trim();
+  return commonDir ? dirname2(resolve(dir, commonDir)) : gitRoot(dir);
+}
+function loadConfig(dir, options = {}) {
+  const root = options.resolvedRoot ? dir : projectRoot(dir);
+  let projectConfig;
   try {
-    const root = gitRoot(dir);
     const text = readConfigFile(root).trim();
-    if (!text)
-      return DEFAULT_CONFIG;
-    const parsed = $parse(text);
-    return {
-      name: typeof parsed.name === "string" && parsed.name.trim() ? parsed.name.trim() : DEFAULT_CONFIG.name,
-      workspace: {
-        mainBranch: isRecord(parsed.workspace) && typeof parsed.workspace.mainBranch === "string" ? parsed.workspace.mainBranch : DEFAULT_CONFIG.workspace.mainBranch,
-        worktreeRoot: isRecord(parsed.workspace) && typeof parsed.workspace.worktreeRoot === "string" ? parsed.workspace.worktreeRoot : DEFAULT_CONFIG.workspace.worktreeRoot,
-        defaultAgent: isRecord(parsed.workspace) ? parseAgentKind(parsed.workspace.defaultAgent) : DEFAULT_CONFIG.workspace.defaultAgent
-      },
-      profiles: parseProfiles(parsed.profiles),
-      services: parseServices(parsed.services),
-      startupEnvs: parseStartupEnvs(parsed.startupEnvs),
-      integrations: {
-        github: {
-          linkedRepos: isRecord(parsed.integrations) && isRecord(parsed.integrations.github) ? parseLinkedRepos(parsed.integrations.github.linkedRepos) : isRecord(parsed.integrations) && Array.isArray(parsed.integrations.github) ? parseLinkedRepos(parsed.integrations.github) : []
-        },
-        linear: {
-          enabled: isRecord(parsed.integrations) && isRecord(parsed.integrations.linear) && typeof parsed.integrations.linear.enabled === "boolean" ? parsed.integrations.linear.enabled : DEFAULT_CONFIG.integrations.linear.enabled
-        }
-      },
-      lifecycleHooks: parseLifecycleHooks(parsed.lifecycleHooks),
-      autoName: parseAutoName(parsed.auto_name)
-    };
+    projectConfig = text ? parseProjectConfig(parseConfigDocument(text)) : defaultConfig();
   } catch {
-    return DEFAULT_CONFIG;
+    projectConfig = defaultConfig();
   }
+  const localOverlay = loadLocalProjectConfigOverlay(root);
+  return {
+    ...projectConfig,
+    profiles: {
+      ...cloneProfiles(projectConfig.profiles),
+      ...cloneProfiles(localOverlay.profiles)
+    },
+    lifecycleHooks: mergeLifecycleHooks(projectConfig.lifecycleHooks, localOverlay.lifecycleHooks)
+  };
 }
 function expandTemplate(template, env) {
   return template.replace(/\$\{(\w+)\}/g, (_, key) => env[key] ?? "");
@@ -7612,11 +7686,11 @@ async function fetchAssignedIssues() {
 // backend/src/services/lifecycle-service.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { mkdir as mkdir4 } from "fs/promises";
-import { dirname as dirname3, resolve as resolve3 } from "path";
+import { dirname as dirname4, resolve as resolve4 } from "path";
 
 // backend/src/adapters/agent-runtime.ts
 import { chmod as chmod2, mkdir as mkdir3 } from "fs/promises";
-import { dirname as dirname2, join as join3 } from "path";
+import { dirname as dirname3, join as join3 } from "path";
 
 // backend/src/adapters/fs.ts
 import { mkdir as mkdir2 } from "fs/promises";
@@ -8024,7 +8098,7 @@ async function ensureAgentRuntimeArtifacts(input) {
     agentCtlPath: join3(storagePaths.webmuxDir, "webmux-agentctl"),
     claudeSettingsPath: join3(input.worktreePath, ".claude", "settings.local.json")
   };
-  await mkdir3(dirname2(artifacts.claudeSettingsPath), { recursive: true });
+  await mkdir3(dirname3(artifacts.claudeSettingsPath), { recursive: true });
   await Bun.write(artifacts.agentCtlPath, buildAgentCtlScript());
   await chmod2(artifacts.agentCtlPath, 493);
   const hookSettings = buildClaudeHookSettings(artifacts);
@@ -8038,7 +8112,7 @@ async function ensureAgentRuntimeArtifacts(input) {
 
 // backend/src/adapters/tmux.ts
 import { createHash } from "crypto";
-import { basename, resolve } from "path";
+import { basename, resolve as resolve2 } from "path";
 function runTmux(args) {
   const result = Bun.spawnSync(["tmux", ...args], {
     stdout: "pipe",
@@ -8057,13 +8131,16 @@ function assertTmuxOk(args, action) {
   }
   return result.stdout;
 }
+function isIgnorableKillWindowError(stderr) {
+  return stderr.includes("can't find window") || stderr.includes("can't find session") || stderr.includes("no server running") || stderr.includes("error connecting to") && stderr.includes("No such file or directory");
+}
 function sanitizeTmuxNameSegment(value, maxLength = 24) {
   const sanitized = value.toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/-{2,}/g, "-").replace(/^[.-]+|[.-]+$/g, "");
   const trimmed = sanitized.slice(0, maxLength);
   return trimmed || "x";
 }
-function buildProjectSessionName(projectRoot) {
-  const resolved = resolve(projectRoot);
+function buildProjectSessionName(projectRoot2) {
+  const resolved = resolve2(projectRoot2);
   const base = sanitizeTmuxNameSegment(basename(resolved), 18);
   const hash = createHash("sha1").update(resolved).digest("hex").slice(0, 8);
   return `wm-${base}-${hash}`;
@@ -8090,8 +8167,10 @@ class BunTmuxGateway {
   ensureSession(sessionName, cwd) {
     const check = runTmux(["has-session", "-t", sessionName]);
     if (check.exitCode !== 0) {
-      assertTmuxOk(["new-session", "-d", "-s", sessionName, "-c", cwd], `create tmux session ${sessionName}`);
+      assertTmuxOk(["new-session", "-d", "-s", sessionName, "-c", cwd, ";", "set-option", "-t", sessionName, "destroy-unattached", "off"], `create tmux session ${sessionName}`);
+      return;
     }
+    assertTmuxOk(["set-option", "-t", sessionName, "destroy-unattached", "off"], `set destroy-unattached off for ${sessionName}`);
   }
   hasWindow(sessionName, windowName) {
     const result = runTmux(["list-windows", "-t", sessionName, "-F", "#{window_name}"]);
@@ -8102,7 +8181,7 @@ class BunTmuxGateway {
   }
   killWindow(sessionName, windowName) {
     const result = runTmux(["kill-window", "-t", `${sessionName}:${windowName}`]);
-    if (result.exitCode !== 0 && !result.stderr.includes("can't find window")) {
+    if (result.exitCode !== 0 && !isIgnorableKillWindowError(result.stderr)) {
       throw new Error(`kill tmux window ${sessionName}:${windowName} failed: ${result.stderr}`);
     }
   }
@@ -8246,7 +8325,7 @@ function resolvePaneStartupCommand(template, commands) {
       return template.command;
   }
 }
-function planSessionLayout(projectRoot, branch, templates, ctx) {
+function planSessionLayout(projectRoot2, branch, templates, ctx) {
   if (templates.length === 0) {
     throw new Error("At least one pane template is required");
   }
@@ -8267,7 +8346,7 @@ function planSessionLayout(projectRoot, branch, templates, ctx) {
   });
   const focusPaneIndex = panes.find((pane) => pane.focus)?.index ?? 0;
   return {
-    sessionName: buildProjectSessionName(projectRoot),
+    sessionName: buildProjectSessionName(projectRoot2),
     windowName: buildWorktreeWindowName(branch),
     shellCommand: ctx.paneCommands.shell,
     panes,
@@ -8313,7 +8392,7 @@ import { randomUUID } from "crypto";
 
 // backend/src/adapters/git.ts
 import { rmSync } from "fs";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 function runGit(args, cwd) {
   const result = Bun.spawnSync(["git", ...args], {
     cwd,
@@ -8347,8 +8426,8 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function isRegisteredWorktree(entries, worktreePath) {
-  const resolvedPath = resolve2(worktreePath);
-  return entries.some((entry) => resolve2(entry.path) === resolvedPath);
+  const resolvedPath = resolve3(worktreePath);
+  return entries.some((entry) => resolve3(entry.path) === resolvedPath);
 }
 function removeDirectory(path) {
   rmSync(path, {
@@ -8371,11 +8450,11 @@ function currentCheckoutRef(cwd) {
 }
 function resolveWorktreeRoot(cwd) {
   const output = runGit(["rev-parse", "--show-toplevel"], cwd);
-  return resolve2(cwd, output);
+  return resolve3(cwd, output);
 }
 function resolveWorktreeGitDir(cwd) {
   const output = runGit(["rev-parse", "--git-dir"], cwd);
-  return resolve2(cwd, output);
+  return resolve3(cwd, output);
 }
 function parseGitWorktreePorcelain(output) {
   const entries = [];
@@ -8718,7 +8797,7 @@ class LifecycleService {
         agent,
         phase: "creating_worktree"
       });
-      await mkdir4(dirname3(worktreePath), { recursive: true });
+      await mkdir4(dirname4(worktreePath), { recursive: true });
       initialized = await createManagedWorktree({
         repoRoot: this.deps.projectRoot,
         worktreePath,
@@ -8953,17 +9032,17 @@ class LifecycleService {
     return allocateServicePorts(metas, this.deps.config.services);
   }
   resolveWorktreePath(branch) {
-    return resolve3(this.deps.projectRoot, this.deps.config.workspace.worktreeRoot, branch);
+    return resolve4(this.deps.projectRoot, this.deps.config.workspace.worktreeRoot, branch);
   }
   listLocalBranches() {
-    return this.deps.git.listLocalBranches(resolve3(this.deps.projectRoot));
+    return this.deps.git.listLocalBranches(resolve4(this.deps.projectRoot));
   }
   listCheckedOutBranches() {
-    return new Set(this.deps.git.listWorktrees(resolve3(this.deps.projectRoot)).filter((entry) => !entry.bare && entry.branch !== null).map((entry) => entry.branch));
+    return new Set(this.deps.git.listWorktrees(resolve4(this.deps.projectRoot)).filter((entry) => !entry.bare && entry.branch !== null).map((entry) => entry.branch));
   }
   listProjectWorktrees() {
-    const projectRoot = resolve3(this.deps.projectRoot);
-    return this.deps.git.listWorktrees(projectRoot).filter((entry) => !entry.bare && resolve3(entry.path) !== projectRoot);
+    const projectRoot2 = resolve4(this.deps.projectRoot);
+    return this.deps.git.listWorktrees(projectRoot2).filter((entry) => !entry.bare && resolve4(entry.path) !== projectRoot2);
   }
   async readManagedMetas() {
     const metas = await Promise.all(this.listProjectWorktrees().map(async (entry) => {
@@ -9984,7 +10063,7 @@ class BunPortProbe {
     this.hostnames = hostnames;
   }
   isListening(port) {
-    return new Promise((resolve4) => {
+    return new Promise((resolve5) => {
       let settled = false;
       let pending = this.hostnames.length;
       const settle = (result) => {
@@ -9993,20 +10072,20 @@ class BunPortProbe {
         if (result) {
           settled = true;
           clearTimeout(timer);
-          resolve4(true);
+          resolve5(true);
           return;
         }
         pending--;
         if (pending === 0) {
           settled = true;
           clearTimeout(timer);
-          resolve4(false);
+          resolve5(false);
         }
       };
       const timer = setTimeout(() => {
         if (!settled) {
           settled = true;
-          resolve4(false);
+          resolve5(false);
         }
       }, this.timeoutMs);
       for (const hostname of this.hostnames) {
@@ -10411,9 +10490,9 @@ class ProjectRuntime {
 }
 
 // backend/src/services/reconciliation-service.ts
-import { basename as basename2, resolve as resolve4 } from "path";
+import { basename as basename2, resolve as resolve5 } from "path";
 function makeUnmanagedWorktreeId(path) {
-  return `unmanaged:${resolve4(path)}`;
+  return `unmanaged:${resolve5(path)}`;
 }
 function isValidPort2(port) {
   return port !== null && Number.isInteger(port) && port >= 1 && port <= 65535;
@@ -10456,7 +10535,7 @@ class ReconciliationService {
     this.deps = deps;
   }
   async reconcile(repoRoot) {
-    const normalizedRepoRoot = resolve4(repoRoot);
+    const normalizedRepoRoot = resolve5(repoRoot);
     const worktrees = this.deps.git.listWorktrees(normalizedRepoRoot);
     const sessionName = buildProjectSessionName(normalizedRepoRoot);
     let windows = [];
@@ -10469,7 +10548,7 @@ class ReconciliationService {
     for (const entry of worktrees) {
       if (entry.bare)
         continue;
-      if (resolve4(entry.path) === normalizedRepoRoot)
+      if (resolve5(entry.path) === normalizedRepoRoot)
         continue;
       const gitDir = this.deps.git.resolveWorktreeGitDir(entry.path);
       const meta = await readWorktreeMeta(gitDir);
@@ -10548,8 +10627,8 @@ class WorktreeCreationTracker {
 // backend/src/runtime.ts
 function createWebmuxRuntime(options = {}) {
   const port = options.port ?? parseInt(Bun.env.PORT || "5111", 10);
-  const projectDir = gitRoot(options.projectDir ?? Bun.env.WEBMUX_PROJECT_DIR ?? process.cwd());
-  const config = loadConfig(projectDir);
+  const projectDir = projectRoot(options.projectDir ?? Bun.env.WEBMUX_PROJECT_DIR ?? process.cwd());
+  const config = loadConfig(projectDir, { resolvedRoot: true });
   const git = new BunGitGateway;
   const portProbe = new BunPortProbe;
   const tmux = new BunTmuxGateway;
@@ -10640,7 +10719,7 @@ function getFrontendConfig() {
     startupEnvs: config.startupEnvs,
     linkedRepos: config.integrations.github.linkedRepos.map((lr) => ({
       alias: lr.alias,
-      ...lr.dir ? { dir: resolve5(PROJECT_DIR, lr.dir) } : {}
+      ...lr.dir ? { dir: resolve6(PROJECT_DIR, lr.dir) } : {}
     }))
   };
 }
@@ -10749,9 +10828,9 @@ async function hasValidControlToken(req) {
 }
 async function getWorktreeGitDirs() {
   const gitDirs = new Map;
-  const projectRoot = resolve5(PROJECT_DIR);
-  for (const entry of git.listWorktrees(projectRoot)) {
-    if (entry.bare || resolve5(entry.path) === projectRoot || !entry.branch)
+  const projectRoot2 = resolve6(PROJECT_DIR);
+  for (const entry of git.listWorktrees(projectRoot2)) {
+    if (entry.bare || resolve6(entry.path) === projectRoot2 || !entry.branch)
       continue;
     gitDirs.set(entry.branch, git.resolveWorktreeGitDir(entry.path));
   }
@@ -11023,8 +11102,8 @@ Bun.serve({
       const url = new URL(req.url);
       const rawPath = url.pathname === "/" ? "index.html" : url.pathname;
       const filePath = join6(STATIC_DIR, rawPath);
-      const staticRoot = resolve5(STATIC_DIR);
-      if (!resolve5(filePath).startsWith(staticRoot + "/")) {
+      const staticRoot = resolve6(STATIC_DIR);
+      if (!resolve6(filePath).startsWith(staticRoot + "/")) {
         return new Response("Forbidden", { status: 403 });
       }
       const file = Bun.file(filePath);
@@ -11039,6 +11118,8 @@ Bun.serve({
     return new Response("Not Found", { status: 404 });
   },
   websocket: {
+    idleTimeout: 255,
+    sendPings: true,
     data: {},
     open(ws) {
       log.debug(`[ws] open branch=${ws.data.branch}`);
@@ -11109,8 +11190,8 @@ Bun.serve({
           break;
       }
     },
-    async close(ws) {
-      log.debug(`[ws] close branch=${ws.data.branch} attached=${ws.data.attached} worktreeId=${ws.data.worktreeId}`);
+    async close(ws, code, reason) {
+      log.debug(`[ws] close branch=${ws.data.branch} code=${code} reason=${reason} attached=${ws.data.attached} worktreeId=${ws.data.worktreeId}`);
       if (ws.data.worktreeId) {
         clearCallbacks(ws.data.worktreeId);
         await detach(ws.data.worktreeId);