webmux 0.20.0 → 0.21.0

package/backend/dist/server.js

@@ -8886,7 +8886,7 @@ function listRemoteGitBranches(cwd) {
   } catch {}
   const output = runGit(["for-each-ref", "--format=%(refname:short)", "refs/remotes/origin"], cwd);
   return output.split(`
-`).map((line) => line.trim()).filter((line) => line.length > 0).map((line) => line.replace(/^origin\//, "")).filter((name) => name !== "HEAD");
+`).map((line) => line.trim()).filter((line) => line.length > 0).map((line) => line.replace(/^origin\//, "")).filter((name) => name !== "HEAD" && name !== "origin");
 }
 function readGitWorktreeStatus(cwd) {
   const dirtyOutput = runGit(["status", "--porcelain"], cwd);
@@ -8948,7 +8948,11 @@ class BunGitGateway {
       if (opts.baseBranch)
         args.push(opts.baseBranch);
     } else {
-      args.push(opts.worktreePath, opts.branch);
+      if (opts.startPoint) {
+        args.push("-b", opts.branch, opts.worktreePath, opts.startPoint);
+      } else {
+        args.push(opts.worktreePath, opts.branch);
+      }
     }
     runGit(args, opts.repoRoot);
   }
@@ -9114,7 +9118,8 @@ async function createManagedWorktree(opts, deps = {}) {
       worktreePath: opts.worktreePath,
       branch: opts.branch,
       mode: opts.mode,
-      baseBranch: opts.baseBranch
+      baseBranch: opts.baseBranch,
+      startPoint: opts.startPoint
     });
     worktreeCreated = true;
     const gitDir = git.resolveWorktreeGitDir(opts.worktreePath);
@@ -9207,7 +9212,7 @@ class LifecycleService {
       throw new LifecycleError("Base branch must differ from branch name", 400);
     }
     const baseBranch = mode === "new" ? requestedBaseBranch || this.deps.config.workspace.mainBranch : undefined;
-    this.ensureBranchAvailable(branch, mode);
+    const branchAvailability = this.resolveBranchAvailability(branch, mode);
     const { profileName, profile } = this.resolveProfile(input.profile);
     const agent = this.resolveAgent(input.agent);
     const worktreePath = this.resolveWorktreePath(branch);
@@ -9218,7 +9223,7 @@ class LifecycleService {
       profile: profileName,
       agent
     };
-    const deleteBranchOnRollback = mode === "new";
+    const deleteBranchOnRollback = mode === "new" || branchAvailability.deleteBranchOnRollback;
     let initialized = null;
     try {
       await this.reportCreateProgress({
@@ -9232,6 +9237,7 @@ class LifecycleService {
         branch,
         mode,
         ...baseBranch ? { baseBranch } : {},
+        ...branchAvailability.startPoint ? { startPoint: branchAvailability.startPoint } : {},
         profile: profileName,
         agent,
         runtime: profile.runtime,
@@ -9377,9 +9383,9 @@ class LifecycleService {
       throw this.wrapOperationError(error);
     }
   }
-  listAvailableBranches() {
+  listAvailableBranches(options = {}) {
     const localBranches = this.listLocalBranches().filter((branch) => isValidBranchName(branch));
-    const remoteBranches = this.listRemoteBranches().filter((branch) => isValidBranchName(branch));
+    const remoteBranches = options.includeRemote ? this.listRemoteBranches().filter((branch) => isValidBranchName(branch)) : [];
     const checkedOutBranches = this.listCheckedOutBranches();
     const allBranches = [...new Set([...localBranches, ...remoteBranches])];
     return allBranches.filter((branch) => !checkedOutBranches.has(branch)).sort((left, right) => left.localeCompare(right)).map((name) => ({ name }));
@@ -9404,20 +9410,28 @@ class LifecycleService {
     }
     return await this.deps.autoName.generateBranchName(this.deps.config.autoName, prompt);
   }
-  ensureBranchAvailable(branch, mode) {
+  resolveBranchAvailability(branch, mode) {
     const localBranches = new Set(this.listLocalBranches());
     if (mode === "new") {
       if (localBranches.has(branch)) {
         throw new LifecycleError(`Branch already exists: ${branch}`, 409);
       }
-      return;
+      return { deleteBranchOnRollback: false };
     }
-    if (!localBranches.has(branch)) {
-      throw new LifecycleError(`Branch not found: ${branch}`, 404);
+    if (localBranches.has(branch)) {
+      if (this.listCheckedOutBranches().has(branch)) {
+        throw new LifecycleError(`Branch already has a worktree: ${branch}`, 409);
+      }
+      return { deleteBranchOnRollback: false };
     }
-    if (this.listCheckedOutBranches().has(branch)) {
-      throw new LifecycleError(`Branch already has a worktree: ${branch}`, 409);
+    const remoteBranches = new Set(this.listRemoteBranches());
+    if (!remoteBranches.has(branch)) {
+      throw new LifecycleError(`Branch not found: ${branch}`, 404);
     }
+    return {
+      startPoint: `origin/${branch}`,
+      deleteBranchOnRollback: true
+    };
   }
   resolveProfile(profileName) {
     const name = profileName ?? getDefaultProfileName(this.deps.config);
@@ -11696,9 +11710,10 @@ async function apiRuntimeEvent(req) {
     ...notification ? { notification } : {}
   });
 }
-async function apiListBranches() {
+async function apiListBranches(req) {
+  const includeRemote = new URL(req.url).searchParams.get("includeRemote") === "true";
   return jsonResponse({
-    branches: lifecycleService.listAvailableBranches()
+    branches: lifecycleService.listAvailableBranches({ includeRemote })
   });
 }
 async function apiListBaseBranches() {
@@ -11984,7 +11999,7 @@ Bun.serve({
       GET: () => jsonResponse(getFrontendConfig())
     },
     "/api/branches": {
-      GET: () => catching("GET /api/branches", () => apiListBranches())
+      GET: (req) => catching("GET /api/branches", () => apiListBranches(req))
     },
     "/api/base-branches": {
       GET: () => catching("GET /api/base-branches", () => apiListBaseBranches())

package/bin/webmux.js

@@ -175,7 +175,7 @@ function listRemoteGitBranches(cwd) {
   } catch {}
   const output = runGit(["for-each-ref", "--format=%(refname:short)", "refs/remotes/origin"], cwd);
   return output.split(`
-`).map((line) => line.trim()).filter((line) => line.length > 0).map((line) => line.replace(/^origin\//, "")).filter((name) => name !== "HEAD");
+`).map((line) => line.trim()).filter((line) => line.length > 0).map((line) => line.replace(/^origin\//, "")).filter((name) => name !== "HEAD" && name !== "origin");
 }
 function readGitWorktreeStatus(cwd) {
   const dirtyOutput = runGit(["status", "--porcelain"], cwd);
@@ -237,7 +237,11 @@ class BunGitGateway {
       if (opts.baseBranch)
         args.push(opts.baseBranch);
     } else {
-      args.push(opts.worktreePath, opts.branch);
+      if (opts.startPoint) {
+        args.push("-b", opts.branch, opts.worktreePath, opts.startPoint);
+      } else {
+        args.push(opts.worktreePath, opts.branch);
+      }
     }
     runGit(args, opts.repoRoot);
   }
@@ -1529,7 +1533,9 @@ function buildInitPromptSpec(context) {
     "Do not modify any other file.",
     "Do not ask the user questions. Infer the config from the repository contents.",
     "Be efficient: inspect only the files needed to determine the project name, main branch, service layout, dev commands, and ports.",
-    "The YAML must be valid and minimal.",
+    "The active, uncommented YAML must be valid and minimal.",
+    "Do not remove other starter sections or their explanatory comments just because they are unused.",
+    "Keep optional examples and comments in place so the user can uncomment and use them later.",
     `Set workspace.defaultAgent to ${context.defaultAgent}.`,
     "Use this config shape:",
     "name: infer from the repository",
@@ -1544,6 +1550,7 @@ function buildInitPromptSpec(context) {
     "Include integrations.github.linkedRepos as an empty list, integrations.linear.enabled as true, and startupEnvs as an empty object.",
     "Only include optional sections like auto_name, lifecycleHooks, sandbox/docker config, mounts, or systemPrompt if the repository gives clear evidence they are needed.",
     "Prefer editing the existing keys over replacing the file with a completely different shape.",
+    "Preserve the existing template structure and comments unless a specific change requires updating them.",
     "Before finishing, verify that `.webmux.yaml` exists and contains the final YAML."
   ].join(`
 `);
@@ -1875,44 +1882,179 @@ function buildStarterTemplate(input) {
   const defaultAgent = input.defaultAgent ?? "claude";
   const packageManager = input.packageManager ?? "npm";
   const devCommand = buildRunScriptCommand(packageManager, "dev");
-  return `# Project display name in the dashboard
+  return `# Starter config for webmux.
+# Keep the active keys below as a minimal working setup, then uncomment
+# the examples to enable more services, profiles, integrations, or hooks.
+
+# Project display name shown in the dashboard and browser title.
 name: ${input.projectName}
 
 workspace:
+  # Git branch new worktrees start from.
   mainBranch: ${input.mainBranch}
+  # Relative or absolute directory where managed worktrees are created.
   worktreeRoot: ../worktrees
+  # Agent new worktrees use by default.
   defaultAgent: ${defaultAgent}
-
-# Each service defines a port env var that webmux injects into pane and agent
-# process environments when creating a worktree. Ports are auto-assigned:
-# base + (slot x step).
+  # Example background pull settings for keeping the main branch fresh.
+  # autoPull:
+  #   # Turn automatic pulls on or off.
+  #   enabled: false
+  #   # Seconds between pull attempts.
+  #   intervalSeconds: 300
+
+# Services define the ports webmux allocates and tracks per worktree.
 services:
-  - name: app
-    portEnv: PORT
-    portStart: 3000
-    portStep: 10
-
+  # Example app service with a predictable per-worktree port.
+  # - name: app
+  #   # Env var name injected into panes and hooks.
+  #   portEnv: PORT
+  #   # Starting port for the first worktree slot.
+  #   portStart: 3000
+  #   # Port increment between worktree slots.
+  #   portStep: 10
+  #   # Link shown in the dashboard when the service is running.
+  #   urlTemplate: http://localhost:\${PORT}
+
+# Profiles define runtime, permissions, and tmux pane layout.
 profiles:
   default:
+    # Run panes directly on the host machine.
     runtime: host
-    yolo: false
-    envPassthrough: []
+    # Forward selected host env vars into the agent process.
+    envPassthrough:
+      # - ANTHROPIC_API_KEY
+      # - OPENAI_API_KEY
+    # Extra system instructions for the agent in this profile.
+    # systemPrompt: >
+    #   You are working in \${WEBMUX_WORKTREE_PATH}
+    # Skip agent permission prompts in this profile.
+    # yolo: true
+    # Panes define the tmux layout created for each worktree session.
     panes:
+      # Main AI coding pane.
       - id: agent
+        # Pane type: agent, command, or shell.
         kind: agent
+        # Focus this pane when the session opens.
         focus: true
-      - id: app
-        kind: command
-        split: right
-        command: PORT=$PORT ${devCommand}
-
+        # Place this pane to the right of the existing layout.
+        # split: right
+        # Percent of the available space this pane should take.
+        # sizePct: 50
+        # Start this pane in the repo root or managed worktree.
+        # cwd: worktree
+      # Example dev server pane.
+      # - id: app
+      #   # Pane type: agent, command, or shell.
+      #   kind: command
+      #   # Place this pane to the right of the existing layout.
+      #   split: right
+      #   # Percent of the available space this pane should take.
+      #   sizePct: 50
+      #   # Start this pane in the repo root or managed worktree.
+      #   cwd: worktree
+      #   # Change into a subdirectory before running the command.
+      #   workingDir: frontend
+      #   # Command run when the pane starts. webmux injects $PORT.
+      #   command: PORT=$PORT ${devCommand}
+      # Example shell pane for manual commands.
+      # - id: shell
+      #   # Pane type: agent, command, or shell.
+      #   kind: shell
+      #   # Place this pane below the existing layout.
+      #   split: bottom
+      #   # Percent of the available space this pane should take.
+      #   sizePct: 30
+      #   # Start this pane in the repo root or managed worktree.
+      #   cwd: repo
+
+  # Example sandbox profile that runs panes inside Docker.
+  # sandbox:
+  #   # Run panes inside a container instead of on the host.
+  #   runtime: docker
+  #   # Docker image used for the sandbox container.
+  #   image: ghcr.io/your-org/your-image:latest
+  #   # Forward selected host env vars into the container.
+  #   envPassthrough:
+  #     - ANTHROPIC_API_KEY
+  #     - OPENAI_API_KEY
+  #   # Extra system instructions for the agent in this profile.
+  #   systemPrompt: >
+  #     Extra instructions for the sandbox profile.
+  #   # Skip agent permission prompts in this profile.
+  #   yolo: true
+  #   # Extra host paths to mount into the container.
+  #   mounts:
+  #     # Host path mounted into the sandbox.
+  #     - hostPath: ~/.codex
+  #       # Path inside the container.
+  #       guestPath: /root/.codex
+  #       # Allow writes through this mount.
+  #       writable: true
+  #   # Panes define the tmux layout created for sandbox sessions.
+  #   panes:
+  #     # Main AI coding pane.
+  #     - id: agent
+  #       # Pane type: agent, command, or shell.
+  #       kind: agent
+  #       # Focus this pane when the session opens.
+  #       focus: true
+  #     # Example shell pane for manual commands.
+  #     - id: shell
+  #       # Pane type: agent, command, or shell.
+  #       kind: shell
+  #       # Place this pane to the right of the existing layout.
+  #       split: right
+  #       # Start this pane in the repo root or managed worktree.
+  #       cwd: repo
+
+# Integrations connect webmux to external systems.
 integrations:
   github:
-    linkedRepos: []
+    # Additional local repos webmux should consider alongside the main repo.
+    linkedRepos:
+      # GitHub slug for a related repo.
+      # - repo: your-org/your-repo
+      #   # Short label shown in the UI.
+      #   alias: repo
+      #   # Relative or absolute path to that local checkout.
+      #   dir: ../your-repo
+    # Remove managed worktrees automatically when their PR merges.
+    # autoRemoveOnMerge: true
   linear:
+    # Enable Linear issue lookup and linking in the UI.
     enabled: true
-
-startupEnvs: {}
+    # Auto-create worktrees for assigned issues.
+    # autoCreateWorktrees: true
+    # Show a create-ticket action in the dashboard.
+    # createTicketOption: true
+    # Restrict issue sync to a specific Linear team id.
+    # teamId: team-123
+
+# startupEnvs become runtime env vars for panes, agents, and hooks.
+startupEnvs:
+  # Example feature flag available in every worktree session.
+  # FEATURE_FLAG: true
+  # Example service URL built from allocated ports.
+  # API_BASE_URL: http://localhost:\${PORT}
+
+# lifecycleHooks run custom shell commands during worktree lifecycle events.
+# lifecycleHooks:
+#   # Runs after env setup and before panes start.
+#   postCreate: bun install
+#   # Runs before the worktree directory is removed.
+#   preRemove: tmux kill-session -t "$WEBMUX_WORKTREE_ID" || true
+
+# auto_name lets webmux generate a branch name when one is not provided.
+# auto_name:
+#   # Provider used for automatic branch naming.
+#   provider: ${defaultAgent}
+#   # Model used for automatic branch naming.
+#   model: ${defaultAgent === "codex" ? "gpt-5.1-codex" : "claude-3-5-haiku-latest"}
+#   # Prompt that tells the model how to name branches.
+#   system_prompt: >
+#     Generate a short kebab-case git branch name.
 `;
 }
 var FAST_CLAUDE_MODEL = "haiku", FAST_CLAUDE_EFFORT = "low", FAST_CODEX_MODEL = "gpt-5.1-codex", FAST_CODEX_REASONING = "low";
@@ -11182,7 +11324,8 @@ async function createManagedWorktree(opts, deps2 = {}) {
       worktreePath: opts.worktreePath,
       branch: opts.branch,
       mode: opts.mode,
-      baseBranch: opts.baseBranch
+      baseBranch: opts.baseBranch,
+      startPoint: opts.startPoint
     });
     worktreeCreated = true;
     const gitDir = git.resolveWorktreeGitDir(opts.worktreePath);
@@ -11275,7 +11418,7 @@ class LifecycleService {
       throw new LifecycleError("Base branch must differ from branch name", 400);
     }
     const baseBranch = mode === "new" ? requestedBaseBranch || this.deps.config.workspace.mainBranch : undefined;
-    this.ensureBranchAvailable(branch, mode);
+    const branchAvailability = this.resolveBranchAvailability(branch, mode);
     const { profileName, profile } = this.resolveProfile(input.profile);
     const agent = this.resolveAgent(input.agent);
     const worktreePath = this.resolveWorktreePath(branch);
@@ -11286,7 +11429,7 @@ class LifecycleService {
       profile: profileName,
       agent
     };
-    const deleteBranchOnRollback = mode === "new";
+    const deleteBranchOnRollback = mode === "new" || branchAvailability.deleteBranchOnRollback;
     let initialized = null;
     try {
       await this.reportCreateProgress({
@@ -11300,6 +11443,7 @@ class LifecycleService {
         branch,
         mode,
         ...baseBranch ? { baseBranch } : {},
+        ...branchAvailability.startPoint ? { startPoint: branchAvailability.startPoint } : {},
         profile: profileName,
         agent,
         runtime: profile.runtime,
@@ -11445,9 +11589,9 @@ class LifecycleService {
       throw this.wrapOperationError(error);
     }
   }
-  listAvailableBranches() {
+  listAvailableBranches(options = {}) {
     const localBranches = this.listLocalBranches().filter((branch) => isValidBranchName(branch));
-    const remoteBranches = this.listRemoteBranches().filter((branch) => isValidBranchName(branch));
+    const remoteBranches = options.includeRemote ? this.listRemoteBranches().filter((branch) => isValidBranchName(branch)) : [];
     const checkedOutBranches = this.listCheckedOutBranches();
     const allBranches = [...new Set([...localBranches, ...remoteBranches])];
     return allBranches.filter((branch) => !checkedOutBranches.has(branch)).sort((left, right) => left.localeCompare(right)).map((name) => ({ name }));
@@ -11472,20 +11616,28 @@ class LifecycleService {
     }
     return await this.deps.autoName.generateBranchName(this.deps.config.autoName, prompt);
   }
-  ensureBranchAvailable(branch, mode) {
+  resolveBranchAvailability(branch, mode) {
     const localBranches = new Set(this.listLocalBranches());
     if (mode === "new") {
       if (localBranches.has(branch)) {
         throw new LifecycleError(`Branch already exists: ${branch}`, 409);
       }
-      return;
+      return { deleteBranchOnRollback: false };
     }
-    if (!localBranches.has(branch)) {
-      throw new LifecycleError(`Branch not found: ${branch}`, 404);
+    if (localBranches.has(branch)) {
+      if (this.listCheckedOutBranches().has(branch)) {
+        throw new LifecycleError(`Branch already has a worktree: ${branch}`, 409);
+      }
+      return { deleteBranchOnRollback: false };
     }
-    if (this.listCheckedOutBranches().has(branch)) {
-      throw new LifecycleError(`Branch already has a worktree: ${branch}`, 409);
+    const remoteBranches = new Set(this.listRemoteBranches());
+    if (!remoteBranches.has(branch)) {
+      throw new LifecycleError(`Branch not found: ${branch}`, 404);
     }
+    return {
+      startPoint: `origin/${branch}`,
+      deleteBranchOnRollback: true
+    };
   }
   resolveProfile(profileName) {
     const name = profileName ?? getDefaultProfileName(this.deps.config);
@@ -12764,7 +12916,7 @@ import { fileURLToPath } from "url";
 // package.json
 var package_default = {
   name: "webmux",
-  version: "0.20.0",
+  version: "0.21.0",
   description: "Web dashboard for workmux \u2014 browser UI with embedded terminals, PR monitoring, and CI integration",
   type: "module",
   repository: {