@ohzw/worktree-command-tui 0.1.4 → 0.1.5

package/README.md

@@ -3,6 +3,9 @@
 `worktree-command-tui` is a terminal UI for managing Git worktrees from inside a repository.
 It keeps one active runtime session per namespace, lets you switch worktrees with the keyboard, and keeps logs/process cleanup tied to the repo's shared Git state.
 
+<img width="1023" height="582" alt="image" src="https://github.com/user-attachments/assets/ef33c2aa-0af4-4701-b1ec-fa9289e8ee3a" />
+
+
 ## Features
 
 - Discover worktrees from the current repository even when launched from a subdirectory
@@ -121,8 +124,8 @@ Example config:
   // The selected worktree path is appended as the final argv entry.
   "editorCommand": ["code"],
 
-  // TCP port owned by the command, used when stopping stale/orphaned processes.
-  "port": 3000,
+  // TCP ports owned by the command, used when stopping stale/orphaned processes.
+  "ports": [3000],
 
   // Files that must exist in a worktree before the command can be started there.
   "requiredFiles": ["package.json"],
@@ -134,8 +137,9 @@ Example config:
 
 Notes:
 
-- `setupCommand` is optional and never runs automatically; `i` only appears when it is configured
+- `setupCommand` is optional and never runs automatically; `i` only appears when it is configured. It accepts one argv array or an array of argv arrays executed in order. The built-in `["copy-root-file", "source", "destination"]` copies from the repo root into the selected worktree.
 - `editorCommand` is optional; when set, the selected worktree path is appended to the argv and `e` becomes available
+- Use `ports` for every backend/frontend/dev-server port the command may bind; legacy single `port` configs still load
 - The generated default config auto-detects package manager hints from `packageManager` or common lockfiles and chooses a default script such as `dev`, `start`, or `serve`
 - Session records and logs are stored under the repository's Git common dir, so they are shared across worktrees in the same repo
 

package/dist/app.js

@@ -81,6 +81,23 @@ function syncActiveTags(rows, activePath) {
     });
     return changed ? nextRows : rows;
 }
+function rowMatchesFilter(row, normalizedQuery) {
+    if (normalizedQuery === '') {
+        return true;
+    }
+    const pullRequest = row.pullRequest?.kind === 'found' ? row.pullRequest : null;
+    return row.branch.toLowerCase().includes(normalizedQuery)
+        || row.path.toLowerCase().includes(normalizedQuery)
+        || row.shortPath.toLowerCase().includes(normalizedQuery)
+        || (pullRequest !== null && (`${pullRequest.number} ${pullRequest.title}`).toLowerCase().includes(normalizedQuery));
+}
+function filterRows(rows, query) {
+    const normalizedQuery = query.trim().toLowerCase();
+    if (normalizedQuery === '') {
+        return rows;
+    }
+    return rows.filter(row => rowMatchesFilter(row, normalizedQuery));
+}
 function shouldRefreshLogs(model) {
     return model.activePath !== null && (model.status.kind === 'running' || model.status.kind === 'error');
 }
@@ -106,7 +123,10 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
     const liveWindowSize = useWindowSize();
     const { columns, rows } = windowSizeOverride ?? liveWindowSize;
     const [model, setModel] = useState(initialModel);
-    const [selectedPath, setSelectedPath] = useState(initialModel.rows[0]?.path ?? null);
+    const [filterQuery, setFilterQuery] = useState('');
+    const [isFilterInputOpen, setIsFilterInputOpen] = useState(false);
+    const visibleRows = useMemo(() => filterRows(model.rows, filterQuery), [model.rows, filterQuery]);
+    const [selectedPath, setSelectedPath] = useState(visibleRows[0]?.path ?? null);
     const [selectionScrollOffset, setSelectionScrollOffset] = useState(0);
     const [worktreeScrollOffset, setWorktreeScrollOffset] = useState(0);
     const [logScrollOffset, setLogScrollOffset] = useState(0);
@@ -121,8 +141,8 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
     const lastStartRequestRef = useRef({ path: null, atMs: 0 });
     const alertTimeoutRef = useRef(null);
     useEffect(() => {
-        setSelectedPath(currentPath => getNextSelectedPath(model.rows, currentPath));
-    }, [model.rows]);
+        setSelectedPath(currentPath => getNextSelectedPath(visibleRows, currentPath));
+    }, [visibleRows]);
     useEffect(() => {
         setSelectionScrollOffset(0);
     }, [selectedPath]);
@@ -196,16 +216,16 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
             setPendingDelete(null);
         }
     }, [confirmationOpen, model.rows, pendingDelete]);
-    const selectedIndex = useMemo(() => getSelectedIndex(model.rows, selectedPath), [model.rows, selectedPath]);
-    const selected = model.rows[selectedIndex];
+    const selectedIndex = useMemo(() => getSelectedIndex(visibleRows, selectedPath), [visibleRows, selectedPath]);
+    const selected = visibleRows[selectedIndex];
     const { rootWidth, rootHeight, bodyWidth, listWidth, actionWidth } = getShellDimensions(columns, rows);
     const minimalLayout = shouldUseMinimalLayout(rootWidth, rootHeight);
-    const compactLayout = !minimalLayout && shouldUseCompactLayout(rootWidth, rootHeight, model.rows.length);
-    const stackedLayout = !minimalLayout && !compactLayout && shouldStackPanes(rootWidth, rootHeight, model.rows.length);
-    const compactDetailPane = !stackedLayout && rootHeight <= 30 && model.rows.length > 1;
-    const showLogPanel = !stackedLayout && rootHeight >= 34;
+    const compactLayout = !minimalLayout && shouldUseCompactLayout(rootWidth, rootHeight, visibleRows.length);
+    const stackedLayout = !minimalLayout && !compactLayout && shouldStackPanes(rootWidth, rootHeight, visibleRows.length);
+    const compactDetailPane = !stackedLayout && rootHeight <= 30 && visibleRows.length > 1;
+    const showLogPanel = rootHeight >= 34;
     const logPaneHeight = showLogPanel ? getLogPaneHeight(rootHeight) : 0;
-    const stackedPaneHeight = Math.max(3, Math.floor((rootHeight - STACKED_LAYOUT_FRAME_ROWS) / 2));
+    const stackedPaneHeight = Math.max(3, Math.floor((rootHeight - STACKED_LAYOUT_FRAME_ROWS - logPaneHeight) / 2));
     const paneHeight = stackedLayout
         ? stackedPaneHeight
         : Math.max(3, rootHeight - STACKED_LAYOUT_FRAME_ROWS - logPaneHeight);
@@ -217,11 +237,15 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
     const maxLogScrollOffset = Math.max(0, logLineCount - logViewportHeight);
     const logScrollPageSize = Math.max(1, Math.floor((logViewportHeight || rootHeight) / 2));
     function moveSelection(nextIndex) {
-        const clampedIndex = clampSelectionIndex(nextIndex, model.rows.length);
+        const clampedIndex = clampSelectionIndex(nextIndex, visibleRows.length);
         if (clampedIndex === null) {
             return;
         }
-        setSelectedPath(model.rows[clampedIndex].path);
+        setSelectedPath(visibleRows[clampedIndex].path);
+    }
+    function clearFilter() {
+        setFilterQuery('');
+        setIsFilterInputOpen(false);
     }
     function clearTransientAlert() {
         if (alertTimeoutRef.current !== null) {
@@ -262,6 +286,29 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
         last.atMs = nowMs;
         return true;
     }
+    function startSelectedWorktree() {
+        if (userActionInFlightRef.current) {
+            return;
+        }
+        const decision = decideEnterInteraction(selected, model.activePath);
+        if (decision.kind === 'ignore') {
+            return;
+        }
+        if (decision.kind === 'set-status') {
+            if (decision.suppressesBackgroundRefreshes) {
+                invalidateStaleLogRefreshes();
+            }
+            setModel(current => ({ ...current, status: decision.status }));
+            clearTransientAlert();
+            return;
+        }
+        if (!shouldAcceptStartRequest(decision.path)) {
+            return;
+        }
+        setModel(current => ({ ...current, status: decision.status }));
+        clearTransientAlert();
+        void apply(() => actions.start(decision.path));
+    }
     useInput((input, key) => {
         if (isHelpOverlayOpen) {
             if (key.escape || input === '\u001B' || input === 'q' || input === '?') {
@@ -318,6 +365,44 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
             }
             return;
         }
+        if (isFilterInputOpen) {
+            if (key.escape || input === '\u001B') {
+                clearFilter();
+                return;
+            }
+            if (key.upArrow) {
+                moveSelection(selectedIndex - 1);
+                return;
+            }
+            if (key.downArrow) {
+                moveSelection(selectedIndex + 1);
+                return;
+            }
+            if (key.pageDown) {
+                setSelectionScrollOffset(current => current + selectionScrollPageSize);
+                return;
+            }
+            if (key.pageUp) {
+                setSelectionScrollOffset(current => Math.max(0, current - selectionScrollPageSize));
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setFilterQuery(current => current.slice(0, -1));
+                return;
+            }
+            if (key.return) {
+                startSelectedWorktree();
+                return;
+            }
+            if (input && !key.ctrl && !key.meta) {
+                setFilterQuery(current => current + input);
+            }
+            return;
+        }
+        if (input === '/') {
+            setIsFilterInputOpen(true);
+            return;
+        }
         if (key.escape || input === 'q') {
             exit();
             return;
@@ -335,7 +420,7 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
             return;
         }
         if (input === 'G') {
-            moveSelection(model.rows.length - 1);
+            moveSelection(visibleRows.length - 1);
             return;
         }
         if (input === '?') {
@@ -362,28 +447,8 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
             setSelectionScrollOffset(current => Math.max(0, current - selectionScrollPageSize));
             return;
         }
-        if (userActionInFlightRef.current) {
-            return;
-        }
         if (key.return) {
-            const decision = decideEnterInteraction(selected, model.activePath);
-            if (decision.kind === 'ignore') {
-                return;
-            }
-            if (decision.kind === 'set-status') {
-                if (decision.suppressesBackgroundRefreshes) {
-                    invalidateStaleLogRefreshes();
-                }
-                setModel(current => ({ ...current, status: decision.status }));
-                clearTransientAlert();
-                return;
-            }
-            if (!shouldAcceptStartRequest(decision.path)) {
-                return;
-            }
-            setModel(current => ({ ...current, status: decision.status }));
-            clearTransientAlert();
-            void apply(() => actions.start(decision.path));
+            startSelectedWorktree();
             return;
         }
         if (input === 's') {
@@ -462,7 +527,7 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
                         if (listPaneViewportHeight === undefined) {
                             return 0;
                         }
-                        const max = Math.max(0, model.rows.length - listPaneViewportHeight);
+                        const max = Math.max(0, visibleRows.length - listPaneViewportHeight);
                         return Math.max(0, Math.min(max, current + event.delta * mouseWheelLineStep));
                     });
                 };
@@ -519,14 +584,14 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
                 stdout.write(DISABLE_MOUSE_TRACKING);
             }
         };
-    }, [stdin, stdout, listWidth, stackedLayout, listPaneViewportHeight, mouseWheelLineStep, model.rows.length, showLogPanel, logPaneTop, logPaneBottom, maxLogScrollOffset, worktreePaneRight, selectionPaneLeft, bodyPaneTop, bodyPaneBottom, stackedWorktreePaneTop, stackedWorktreePaneBottom, stackedSelectionPaneTop, stackedSelectionPaneBottom, isLogOverlayOpen, isHelpOverlayOpen]);
+    }, [stdin, stdout, listWidth, stackedLayout, listPaneViewportHeight, mouseWheelLineStep, visibleRows.length, showLogPanel, logPaneTop, logPaneBottom, maxLogScrollOffset, worktreePaneRight, selectionPaneLeft, bodyPaneTop, bodyPaneBottom, stackedWorktreePaneTop, stackedWorktreePaneBottom, stackedSelectionPaneTop, stackedSelectionPaneBottom, isLogOverlayOpen, isHelpOverlayOpen]);
     useEffect(() => {
         if (listPaneViewportHeight === undefined) {
             setWorktreeScrollOffset(0);
             return;
         }
         setWorktreeScrollOffset(current => {
-            const max = Math.max(0, model.rows.length - listPaneViewportHeight);
+            const max = Math.max(0, visibleRows.length - listPaneViewportHeight);
             if (selectedIndex < current) {
                 return Math.max(0, selectedIndex);
             }
@@ -535,7 +600,7 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
             }
             return Math.min(current, max);
         });
-    }, [selectedIndex, listPaneViewportHeight, model.rows.length]);
+    }, [selectedIndex, listPaneViewportHeight, visibleRows.length]);
     useEffect(() => {
         if (!showLogPanel && !isLogOverlayOpen) {
             setLogScrollOffset(0);
@@ -557,14 +622,14 @@ export function App({ initialModel, actions, windowSizeOverride, }) {
     if (minimalLayout) {
         return (_jsxs(Box, { width: rootWidth, height: rootHeight, flexDirection: "column", children: [_jsxs(Text, { bold: true, color: "green", wrap: "truncate-end", children: ["A:", safeActiveBranch] }), rootHeight >= 2 ? _jsxs(Text, { wrap: "truncate-end", children: ["S:", safeSelectedBranch] }) : null, rootHeight >= 3 ? _jsx(Text, { wrap: "truncate-end", children: confirmationOpen ? `D:${safeVisibleStatusMessage}` : `T:${model.status.kind}` }) : null, rootHeight >= 4 ? (confirmationOpen
                     ? _jsx(Text, { dimColor: true, wrap: "truncate-end", children: "d/y confirm \u00B7 Esc/n/q cancel" })
-                    : _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["\u2191\u2193jk\u21B5", model.setupAvailable ? 'i' : '', model.editorAvailable ? 'e' : '', "odLq"] })) : null] }));
+                    : _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["\u2191\u2193jk/\u21B5", model.setupAvailable ? 'i' : '', model.editorAvailable ? 'e' : '', "odLq"] })) : null] }));
     }
     if (compactLayout) {
         return (_jsxs(Box, { width: rootWidth, height: rootHeight, flexDirection: "column", children: [_jsxs(Text, { bold: true, color: "green", wrap: "truncate-end", children: ["Active: ", safeActiveBranch] }), _jsxs(Text, { wrap: "truncate-end", children: ["Selected: ", safeSelectedBranch] }), safeCompletedAlert
                     ? _jsxs(Text, { color: "green", wrap: "truncate-end", children: ["\u2714 ", safeCompletedAlert] })
                     : model.status.kind === 'setting-up' || model.status.kind === 'starting' || model.status.kind === 'stopping' ? (_jsx(Spinner, { label: `Status: ${model.status.kind} — ${safeModelStatusMessage}` })) : (_jsxs(Text, { wrap: "truncate-end", children: ["Status: ", visibleStatus.kind, " \u2014 ", safeVisibleStatusMessage] })), _jsx(Text, { dimColor: true, wrap: "truncate-end", children: confirmationOpen
                         ? 'Keys: d/y confirm | Esc/n/q cancel'
-                        : `Keys: ↑↓/jk g/G ↵${model.setupAvailable ? ' i' : ''}${model.editorAvailable ? ' e' : ''} o d L s r q · Resize terminal for split view` })] }));
+                        : `Keys: ↑↓/jk g/G / Filter ↵${model.setupAvailable ? ' i' : ''}${model.editorAvailable ? ' e' : ''} o d L s r q · Resize terminal for split view` })] }));
     }
-    return (_jsxs(Box, { width: rootWidth, height: rootHeight, flexDirection: "column", children: [_jsx(Header, { repoName: model.repoName, namespace: model.namespace, activeBranch: model.activeBranch }), _jsxs(Box, { flexDirection: stackedLayout ? 'column' : 'row', flexGrow: stackedLayout ? 0 : 1, flexShrink: 1, children: [_jsx(WorktreeList, { rows: model.rows, selectedIndex: selectedIndex, width: stackedLayout ? bodyWidth : listWidth, height: paneHeight, stacked: stackedLayout, scrollOffset: worktreeScrollOffset }), _jsx(ActionPanel, { selectedRow: selected, activePath: model.activePath, setupAvailable: model.setupAvailable, stacked: stackedLayout, width: stackedLayout ? bodyWidth : actionWidth, height: paneHeight, compactDetails: compactDetailPane, scrollOffset: selectionScrollOffset })] }), showLogPanel ? _jsx(LogPanel, { logs: model.logs, width: bodyWidth, height: logPaneHeight, scrollOffset: logScrollOffset }) : null, _jsx(ContextBar, { status: visibleStatus, setupAvailable: model.setupAvailable, editorAvailable: model.editorAvailable, confirmationOpen: confirmationOpen }), safeCompletedAlert ? (_jsx(Box, { position: "absolute", top: 1, right: 2, children: _jsx(Alert, { variant: "success", children: safeCompletedAlert }) })) : null] }));
+    return (_jsxs(Box, { width: rootWidth, height: rootHeight, flexDirection: "column", children: [_jsx(Header, { repoName: model.repoName, namespace: model.namespace, activeBranch: model.activeBranch }), _jsxs(Box, { flexDirection: stackedLayout ? 'column' : 'row', flexGrow: stackedLayout ? 0 : 1, flexShrink: 1, children: [_jsx(WorktreeList, { rows: visibleRows, selectedIndex: selectedIndex, width: stackedLayout ? bodyWidth : listWidth, height: paneHeight, stacked: stackedLayout, scrollOffset: worktreeScrollOffset, filterQuery: filterQuery, isFilterInputOpen: isFilterInputOpen, totalRowCount: model.rows.length }), _jsx(ActionPanel, { selectedRow: selected, activePath: model.activePath, setupAvailable: model.setupAvailable, stacked: stackedLayout, width: stackedLayout ? bodyWidth : actionWidth, height: paneHeight, compactDetails: compactDetailPane, scrollOffset: selectionScrollOffset })] }), showLogPanel ? _jsx(LogPanel, { logs: model.logs, width: bodyWidth, height: logPaneHeight, scrollOffset: logScrollOffset }) : null, _jsx(ContextBar, { status: visibleStatus, setupAvailable: model.setupAvailable, editorAvailable: model.editorAvailable, confirmationOpen: confirmationOpen }), safeCompletedAlert ? (_jsx(Box, { position: "absolute", top: 1, right: 2, children: _jsx(Alert, { variant: "success", children: safeCompletedAlert }) })) : null] }));
 }

package/dist/components/ContextBar.js

@@ -30,6 +30,7 @@ function buildKeyHints(setupAvailable, editorAvailable, confirmationOpen) {
         { binding: '↑↓/jk', label: 'Move' },
         { binding: 'Enter', label: 'Switch' },
     ];
+    hints.push({ binding: '/', label: 'Filter' });
     if (setupAvailable) {
         hints.push({ binding: 'i', label: 'Setup' });
     }

package/dist/components/HelpWindow.js

@@ -9,6 +9,8 @@ function buildHelpLines(setupAvailable, editorAvailable) {
         { section: 'Logs', binding: 'L', description: 'full-screen logs' },
         { section: 'Logs', binding: '[/]', description: 'scroll log' },
         { section: 'Actions', binding: 'Enter', description: 'start/switch/restart worktree' },
+        { section: 'Filter', binding: '/', description: 'filter by branch, path, or pull request' },
+        { section: 'Filter', binding: 'Esc', description: 'clear filter' },
     ];
     if (setupAvailable) {
         lines.push({ section: 'Actions', binding: 'i', description: 'setup selected worktree' });

package/dist/components/WorktreeList.d.ts

@@ -1,9 +1,12 @@
 import type { AppRow } from '../core/runtime.js';
-export declare function WorktreeList({ rows, selectedIndex, width, height, stacked, scrollOffset, }: {
+export declare function WorktreeList({ rows, selectedIndex, width, height, stacked, scrollOffset, filterQuery, isFilterInputOpen, totalRowCount, }: {
     rows: AppRow[];
     selectedIndex: number;
     width?: number;
     height?: number;
     stacked: boolean;
     scrollOffset?: number;
+    filterQuery?: string;
+    isFilterInputOpen?: boolean;
+    totalRowCount?: number;
 }): import("react").JSX.Element;

package/dist/components/WorktreeList.js

@@ -33,7 +33,7 @@ function truncateLabel(value, width) {
     }
     return `${value.slice(0, Math.max(width - 1, 0))}…`;
 }
-export function WorktreeList({ rows, selectedIndex, width, height, stacked, scrollOffset = 0, }) {
+export function WorktreeList({ rows, selectedIndex, width, height, stacked, scrollOffset = 0, filterQuery = '', isFilterInputOpen = false, totalRowCount = rows.length, }) {
     const branchWidth = Math.max(MIN_BRANCH_WIDTH, (width ?? 34) - 7);
     const viewport = sliceListViewport(rows, height === undefined ? rows.length : height - 3, scrollOffset);
     const contentViewportHeight = viewport.viewportHeight;
@@ -41,7 +41,12 @@ export function WorktreeList({ rows, selectedIndex, width, height, stacked, scro
     const visibleRows = viewport.visibleItems;
     const showScrollbar = height !== undefined && rows.length > contentViewportHeight;
     const scrollbarThumbRows = showScrollbar ? getScrollbarThumbRows(rows.length, contentViewportHeight, effectiveScrollOffset) : new Set();
-    return (_jsxs(Box, { width: width, height: height, flexGrow: stacked ? 0 : 1, marginRight: stacked ? 0 : 1, borderStyle: "round", borderColor: "cyan", flexDirection: "column", paddingX: 1, overflowY: "hidden", children: [_jsx(Text, { bold: true, color: "cyan", children: "Worktrees" }), visibleRows.map((row, index) => {
+    const hasFilter = filterQuery.trim() !== '';
+    const filterText = sanitizeInlineText(filterQuery);
+    const title = hasFilter || isFilterInputOpen
+        ? `Worktrees /${filterText}${isFilterInputOpen ? '█' : ''} (${rows.length}/${totalRowCount})`
+        : 'Worktrees';
+    return (_jsxs(Box, { width: width, height: height, flexGrow: stacked ? 0 : 1, marginRight: stacked ? 0 : 1, borderStyle: "round", borderColor: "cyan", flexDirection: "column", paddingX: 1, overflowY: "hidden", children: [_jsx(Text, { bold: true, color: "cyan", wrap: "truncate-end", children: title }), rows.length === 0 ? (_jsx(Text, { dimColor: true, wrap: "truncate-end", children: "No worktrees match filter." })) : null, visibleRows.map((row, index) => {
                 const isSelected = index + effectiveScrollOffset === selectedIndex;
                 const projection = projectWorktreeListRow(row, isSelected);
                 const tagSuffix = projection.isMain ? ' [root]' : '';

package/dist/core/command-runner.d.ts

@@ -4,8 +4,9 @@ interface CommandLogOptions {
     logsDir: string;
     logFileBase: string;
     errorLabel?: string;
+    workspaceRoot?: string;
 }
-export declare function runCommandToLog({ command, cwd, logsDir, logFileBase, errorLabel, }: CommandLogOptions): Promise<{
+export declare function runCommandToLog({ command, cwd, logsDir, logFileBase, errorLabel, workspaceRoot, }: CommandLogOptions): Promise<{
     logPath: string;
 }>;
 export declare function startDetachedCommand({ command, cwd, logsDir, logFileBase, }: {

package/dist/core/command-runner.js

@@ -1,6 +1,55 @@
-import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { appendFileSync, closeSync, copyFileSync, mkdirSync, openSync, realpathSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
+function writeLogLine(logPath, text) {
+    appendFileSync(logPath, text, 'utf8');
+}
+function isContainedPath(root, target, allowEqual) {
+    const relativePath = path.relative(root, target);
+    return (allowEqual && relativePath === '') || (relativePath !== '' && !relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+function resolveSourcePath(root, inputPath) {
+    const realRoot = realpathSync(root);
+    const source = path.resolve(realRoot, inputPath);
+    if (!isContainedPath(realRoot, source, false)) {
+        throw new Error(`source must stay under ${realRoot}`);
+    }
+    const realSource = realpathSync(source);
+    if (!isContainedPath(realRoot, realSource, false)) {
+        throw new Error(`source must stay under ${realRoot}`);
+    }
+    return realSource;
+}
+function resolveDestinationPath(root, inputPath) {
+    const realRoot = realpathSync(root);
+    const destination = path.resolve(realRoot, inputPath);
+    const basename = path.basename(destination);
+    if (basename === '' || basename === '.' || basename === '..') {
+        throw new Error(`destination must stay under ${realRoot}`);
+    }
+    mkdirSync(path.dirname(destination), { recursive: true });
+    const realParent = realpathSync(path.dirname(destination));
+    if (!isContainedPath(realRoot, realParent, true)) {
+        throw new Error(`destination must stay under ${realRoot}`);
+    }
+    return path.join(realParent, basename);
+}
+function runBuiltInCommand(input) {
+    if (input.command[0] !== 'copy-root-file') {
+        return false;
+    }
+    if (input.command.length !== 3) {
+        throw new Error(`${input.errorLabel} requires arguments: source and destination path`);
+    }
+    if (input.workspaceRoot === undefined) {
+        throw new Error(`${input.errorLabel} copy-root-file requires workspaceRoot`);
+    }
+    const source = resolveSourcePath(input.workspaceRoot, input.command[1] ?? '');
+    const destination = resolveDestinationPath(input.cwd, input.command[2] ?? '');
+    copyFileSync(source, destination);
+    writeLogLine(input.logPath, `copied ${source} -> ${destination}\n`);
+    return true;
+}
 function getLogEnvironment() {
     return {
         ...process.env,
@@ -8,7 +57,7 @@ function getLogEnvironment() {
         CLICOLOR_FORCE: process.env.CLICOLOR_FORCE ?? '1',
     };
 }
-export function runCommandToLog({ command, cwd, logsDir, logFileBase, errorLabel = 'setup command', }) {
+export function runCommandToLog({ command, cwd, logsDir, logFileBase, errorLabel = 'setup command', workspaceRoot, }) {
     mkdirSync(logsDir, { recursive: true });
     const logPath = path.join(logsDir, `${logFileBase}.log`);
     const fd = openSync(logPath, 'a');
@@ -22,6 +71,20 @@ export function runCommandToLog({ command, cwd, logsDir, logFileBase, errorLabel
         closeSync(fd);
         return true;
     };
+    try {
+        if (runBuiltInCommand({ command, cwd, logPath, workspaceRoot, errorLabel })) {
+            if (finalize()) {
+                resolve({ logPath });
+            }
+            return promise;
+        }
+    }
+    catch (error) {
+        if (finalize()) {
+            reject(new Error(`${errorLabel}: ${error instanceof Error ? error.message : String(error)}; see ${logPath}`));
+        }
+        return promise;
+    }
     const child = spawn(command[0], command.slice(1), {
         cwd,
         env: getLogEnvironment(),

package/dist/core/config-lifecycle.d.ts

@@ -17,9 +17,9 @@ export declare function isSafeNamespace(value: unknown): value is string;
 export declare function toSafeNamespace(value: string): string;
 export declare function validateToolConfig(raw: unknown): ToolConfig;
 export declare function createDefaultToolConfig(options: DefaultToolConfigOptions): ToolConfig;
+export declare function renderConfigJsonc(config: ToolConfig): string;
 export declare function loadToolConfig({ repoRoot }: {
     repoRoot: string;
 }): Promise<ToolConfig>;
-export declare function renderConfigJsonc(config: ToolConfig): string;
 export declare function findExistingConfigPath(workspaceRoot: string, fileExists: (filePath: string) => Promise<boolean>): Promise<string | null>;
 export declare function writeToolConfigForRepo({ workspaceRoot, force, config }: ConfigInitOptions, fileExists: (filePath: string) => Promise<boolean>): Promise<ConfigInitResult>;

package/dist/core/config-lifecycle.js

@@ -37,6 +37,28 @@ function readOrphanMatchers(value) {
     }
     return matchers;
 }
+function isNonEmptyStringArray(value) {
+    return Array.isArray(value) && value.length > 0 && value.every(part => isNonEmptyString(part));
+}
+function readOptionalSetupCommands(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error('setupCommand must be a non-empty string array or an array of non-empty string arrays when set');
+    }
+    const looksLikeSingleCommand = value.every(part => isNonEmptyString(part));
+    if (looksLikeSingleCommand) {
+        return [value];
+    }
+    if (!value.every(part => Array.isArray(part))) {
+        throw new Error('setupCommand must be a non-empty string array or an array of non-empty string arrays when set');
+    }
+    if (!value.every(part => isNonEmptyStringArray(part))) {
+        throw new Error('setupCommand must be a non-empty string array or an array of non-empty string arrays when set');
+    }
+    return value;
+}
 function readRequiredCommand(value, fieldName) {
     if (!Array.isArray(value) || value.length === 0 || value.some(part => !isNonEmptyString(part))) {
         throw new Error(`${fieldName} must be a non-empty string array`);
@@ -52,24 +74,51 @@ function readOptionalCommand(value, fieldName) {
     }
     return value;
 }
-function readPort(value) {
+function readPort(value, fieldName) {
     if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 65535) {
-        throw new Error('port must be an integer between 1 and 65535');
+        throw new Error(`${fieldName} must be an integer between 1 and 65535`);
+    }
+    return value;
+}
+function readPorts(value) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value) || value.length === 0 || value.some(port => typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535)) {
+        throw new Error('ports must be a non-empty array of integers between 1 and 65535');
     }
     return value;
 }
+function uniquePorts(ports) {
+    return [...new Set(ports)];
+}
+function mergeConfiguredPorts(legacyPort, configuredPorts) {
+    const merged = configuredPorts.length > 0 ? configuredPorts : legacyPort === undefined ? [] : [legacyPort];
+    const resolved = uniquePorts(merged);
+    if (resolved.length === 0) {
+        throw new Error('port or ports must be configured');
+    }
+    return resolved;
+}
+function readPortList(port, ports) {
+    const legacyPort = port === undefined ? undefined : readPort(port, 'port');
+    const configuredPorts = readPorts(ports);
+    return mergeConfiguredPorts(legacyPort, configuredPorts);
+}
 export function validateToolConfig(raw) {
     const config = (raw ?? {});
     const command = readRequiredCommand(config.command, 'command');
     if (!isSafeNamespace(config.namespace)) {
         throw new Error(`namespace must match ${SAFE_NAMESPACE_DESCRIPTION}`);
     }
+    const ports = readPortList(config.port, config.ports);
     return {
         namespace: config.namespace,
         command,
-        setupCommand: readOptionalCommand(config.setupCommand, 'setupCommand'),
+        setupCommand: readOptionalSetupCommands(config.setupCommand),
         editorCommand: readOptionalCommand(config.editorCommand, 'editorCommand'),
-        port: readPort(config.port),
+        port: ports[0] ?? 0,
+        ports,
         requiredFiles: readStringList(config.requiredFiles, 'requiredFiles'),
         orphanMatchers: readOrphanMatchers(config.orphanMatchers),
     };
@@ -78,38 +127,20 @@ export function createDefaultToolConfig(options) {
     return validateToolConfig({
         namespace: toSafeNamespace(options.namespaceSeed),
         command: [options.packageManager, 'run', options.script],
-        setupCommand: [options.packageManager, 'install'],
+        setupCommand: [[options.packageManager, 'install']],
         editorCommand: ['code'],
-        port: 3000,
+        ports: [3000],
         requiredFiles: ['package.json'],
         orphanMatchers: [],
     });
 }
-async function readConfigFile(configPath) {
-    if ((await stat(configPath)).size > MAX_CONFIG_BYTES) {
-        throw new Error('config file is too large');
-    }
-    return readFile(configPath, 'utf8');
-}
-async function readFirstConfig(repoRoot) {
-    let firstError;
-    for (const fileName of CONFIG_FILE_NAMES) {
-        try {
-            return await readConfigFile(path.join(repoRoot, fileName));
-        }
-        catch (error) {
-            firstError ??= error;
-        }
-    }
-    throw firstError;
-}
-export async function loadToolConfig({ repoRoot }) {
-    return validateToolConfig(parseJsonc(await readFirstConfig(repoRoot)));
-}
 export function renderConfigJsonc(config) {
     const setupCommandSection = config.setupCommand === undefined ? '' : `
-  // Optional command run manually with the setup key in the selected worktree.
+  // Optional command(s) run manually with the setup key in the selected worktree.
   // Review before running in untrusted worktrees; package installs may run lifecycle scripts.
+  // When this is an array of arrays, each entry is executed in order.
+  // Built-in helper: ["copy-root-file", ".env", ".env"]
+  // copies .env from the repository root to the selected worktree.
   "setupCommand": ${JSON.stringify(config.setupCommand)},
 `;
     const editorCommandSection = config.editorCommand === undefined ? '' : `
@@ -126,8 +157,9 @@ export function renderConfigJsonc(config) {
   // Treat this config as trusted code. argv form avoids shell metacharacter expansion.
   "command": ${JSON.stringify(config.command)},
 ${setupCommandSection}${editorCommandSection}
-  // TCP port owned by the command, used when stopping stale/orphaned processes.
-  "port": ${JSON.stringify(config.port)},
+  // TCP ports owned by the command, used when stopping stale/orphaned processes.
+  // Include all ports your command may bind.
+  "ports": ${JSON.stringify(config.ports)},
 
   // Files that must exist in a worktree before the command can be started there.
   "requiredFiles": ${JSON.stringify(config.requiredFiles)},
@@ -139,6 +171,27 @@ ${setupCommandSection}${editorCommandSection}
 }
 `;
 }
+async function readConfigFile(configPath) {
+    if ((await stat(configPath)).size > MAX_CONFIG_BYTES) {
+        throw new Error('config file is too large');
+    }
+    return readFile(configPath, 'utf8');
+}
+async function readFirstConfig(repoRoot) {
+    let firstError;
+    for (const fileName of CONFIG_FILE_NAMES) {
+        try {
+            return await readConfigFile(path.join(repoRoot, fileName));
+        }
+        catch (error) {
+            firstError ??= error;
+        }
+    }
+    throw firstError;
+}
+export async function loadToolConfig({ repoRoot }) {
+    return validateToolConfig(parseJsonc(await readFirstConfig(repoRoot)));
+}
 export async function findExistingConfigPath(workspaceRoot, fileExists) {
     for (const fileName of CONFIG_FILE_NAMES) {
         const configPath = path.join(workspaceRoot, fileName);

package/dist/core/config.d.ts

@@ -4,9 +4,10 @@ export declare const CONFIG_FILE_NAMES: readonly [".worktree-command-tui.jsonc",
 export interface ToolConfig {
     namespace: string;
     command: string[];
-    setupCommand?: string[];
+    setupCommand?: string[][];
     editorCommand?: string[];
     port: number;
+    ports: number[];
     requiredFiles: string[];
     orphanMatchers: string[];
 }

package/dist/core/process-control.d.ts

@@ -6,6 +6,6 @@ export interface CleanupDeps {
 }
 export declare function stopSessionWithFallback(input: {
     pgid: number;
-    port: number;
+    ports: number[];
     orphanMatchers: string[];
 }, deps: CleanupDeps): Promise<boolean>;

package/dist/core/process-control.js

@@ -6,7 +6,9 @@ export async function stopSessionWithFallback(input, deps) {
     if (!(await deps.isSessionAlive(input.pgid))) {
         return true;
     }
-    await deps.killPortOwner(input.port, input.pgid);
+    for (const port of input.ports) {
+        await deps.killPortOwner(port, input.pgid);
+    }
     for (const matcher of input.orphanMatchers) {
         await deps.killOrphans(matcher, input.pgid);
     }

package/dist/core/runtime-state.d.ts

@@ -17,6 +17,7 @@ export interface RuntimeStateAdapter {
         cwd: string;
         logsDir: string;
         logFileBase: string;
+        workspaceRoot: string | undefined;
     }) => Promise<{
         logPath: string;
     }>;
@@ -37,6 +38,7 @@ export interface RuntimeStateAdapter {
 export interface RuntimeStateOptions {
     config: ToolConfig;
     paths: SessionPaths;
+    workspaceRoot?: string;
     adapter: RuntimeStateAdapter;
 }
-export declare function createRuntimeStateActions({ config, paths, adapter }: RuntimeStateOptions): AppActions;
+export declare function createRuntimeStateActions({ config, paths, workspaceRoot, adapter }: RuntimeStateOptions): AppActions;

package/dist/core/runtime-state.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 function toLogFileBase(branch) {
     return branch.replace(/[\\/]/g, '-');
 }
-export function createRuntimeStateActions({ config, paths, adapter }) {
+export function createRuntimeStateActions({ config, paths, workspaceRoot, adapter }) {
     const refreshLogs = async () => {
         const active = await adapter.readActive();
         return {
@@ -40,8 +40,8 @@ export function createRuntimeStateActions({ config, paths, adapter }) {
         };
     };
     const setup = async (worktreePath) => {
-        const setupCommand = config.setupCommand;
-        if (setupCommand === undefined) {
+        const setupCommands = config.setupCommand;
+        if (setupCommands === undefined) {
             const model = await adapter.refresh();
             return {
                 ...model,
@@ -51,21 +51,34 @@ export function createRuntimeStateActions({ config, paths, adapter }) {
         const branch = await adapter.readWorktreeBranch(worktreePath);
         const logFileBase = `${toLogFileBase(branch)}.setup`;
         const setupLogPath = path.join(paths.logsDir, `${logFileBase}.log`);
-        try {
-            await adapter.runSetup({
-                command: setupCommand,
-                cwd: worktreePath,
-                logsDir: paths.logsDir,
-                logFileBase,
-            });
-        }
-        catch (error) {
-            const model = await adapter.refresh();
-            return {
-                ...model,
-                status: { kind: 'error', message: error instanceof Error ? error.message : String(error) },
-                logs: await adapter.readLogs(setupLogPath),
-            };
+        for (let index = 0; index < setupCommands.length; index += 1) {
+            const setupCommand = setupCommands[index];
+            if (setupCommand === undefined) {
+                const model = await adapter.refresh();
+                return {
+                    ...model,
+                    status: { kind: 'error', message: `setup command ${index + 1} is not configured` },
+                    logs: await adapter.readLogs(setupLogPath),
+                };
+            }
+            try {
+                await adapter.runSetup({
+                    command: setupCommand,
+                    cwd: worktreePath,
+                    logsDir: paths.logsDir,
+                    logFileBase,
+                    workspaceRoot,
+                });
+            }
+            catch (error) {
+                const model = await adapter.refresh();
+                const commandLabel = setupCommands.length > 1 ? `setup command ${index + 1}/${setupCommands.length} ` : '';
+                return {
+                    ...model,
+                    status: { kind: 'error', message: `${commandLabel}${error instanceof Error ? error.message : String(error)}`.trim() },
+                    logs: await adapter.readLogs(setupLogPath),
+                };
+            }
         }
         const model = await adapter.refresh();
         return {
@@ -99,6 +112,7 @@ export function createRuntimeStateActions({ config, paths, adapter }) {
             pid: started.pid,
             pgid: started.pgid,
             port: config.port,
+            ports: config.ports,
             logPath: started.logPath,
             startedAt: adapter.nowIso(),
         });

package/dist/core/runtime.js

@@ -70,8 +70,8 @@ async function buildRows(mainWorktreePath, workspaceRoot, activePath, requiredFi
     }));
     return rows;
 }
-async function stopRecordedSession(pgid, port, orphanMatchers) {
-    const stopped = await stopSessionWithFallback({ pgid, port, orphanMatchers }, {
+async function stopRecordedSession(pgid, ports, orphanMatchers) {
+    const stopped = await stopSessionWithFallback({ pgid, ports, orphanMatchers }, {
         killProcessGroup,
         killPortOwner,
         killOrphans,
@@ -81,6 +81,9 @@ async function stopRecordedSession(pgid, port, orphanMatchers) {
         throw new Error(`Failed to stop existing session pgid=${pgid}`);
     }
 }
+function sessionCleanupPorts(active, configuredPorts) {
+    return [...new Set([...(active.ports ?? [active.port]), ...configuredPorts])];
+}
 async function launchDetachedCommand(command, cwd) {
     const { promise, resolve, reject } = Promise.withResolvers();
     let settled = false;
@@ -141,6 +144,7 @@ export async function buildActions(cwd) {
     return createRuntimeStateActions({
         config,
         paths,
+        workspaceRoot,
         adapter: {
             refresh: async () => buildInitialModel(cwd),
             readActive: async () => readSessionRecord(paths, { isSessionAlive: isProcessGroupAlive }),
@@ -153,9 +157,9 @@ export async function buildActions(cwd) {
                 return selected.branch;
             },
             getInvalidReason: async (worktreePath) => getInvalidReason(worktreePath, config.requiredFiles),
-            runSetup: runCommandToLog,
+            runSetup: async (input) => runCommandToLog({ ...input, workspaceRoot }),
             startCommand: startDetachedCommand,
-            stopSession: async (active) => stopRecordedSession(active.pgid, active.port, config.orphanMatchers),
+            stopSession: async (active) => stopRecordedSession(active.pgid, sessionCleanupPorts(active, config.ports), config.orphanMatchers),
             clearSession: async () => clearSessionRecord(paths),
             writeSession: async (record) => writeSessionRecord(paths, record),
             openEditor: async (worktreePath) => {
@@ -179,7 +183,7 @@ export async function buildActions(cwd) {
                     return { kind: 'idle', message: `no pull request found for ${selected.branch}` };
                 }
                 if (pullRequest.kind === 'unavailable') {
-                    return { kind: 'error', message: `pull request metadata is unavailable for ${selected.branch}` };
+                    return { kind: 'idle', message: `pull request metadata unavailable for ${selected.branch}` };
                 }
                 await launchDetachedCommand(getBrowserOpenCommand(pullRequest.url), worktreePath);
                 return { kind: 'idle', message: `opened pull request #${pullRequest.number} for ${selected.branch}` };
@@ -194,7 +198,7 @@ export async function buildActions(cwd) {
                 }
                 const active = await readSessionRecord(paths, { isSessionAlive: isProcessGroupAlive });
                 if (active?.worktreePath === worktreePath) {
-                    await stopRecordedSession(active.pgid, active.port, config.orphanMatchers);
+                    await stopRecordedSession(active.pgid, sessionCleanupPorts(active, config.ports), config.orphanMatchers);
                     await clearSessionRecord(paths);
                 }
                 await execFileAsync('git', ['worktree', 'remove', worktreePath], { cwd: workspaceRoot });

package/dist/core/session-store.d.ts

@@ -5,6 +5,7 @@ export interface SessionRecord {
     pid: number;
     pgid: number;
     port: number;
+    ports?: number[];
     logPath: string;
     startedAt: string;
 }

package/dist/core/session-store.js

@@ -1,26 +1,41 @@
 import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-const MAX_SESSION_BYTES = 16 * 1024;
 function isSafeProcessId(value) {
     return typeof value === 'number' && Number.isInteger(value) && value > 1;
 }
-function isValidPort(value) {
+function isSafePort(value) {
     return typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= 65535;
 }
-function isSessionRecord(value) {
+function normalizeSessionRecordPorts(port, ports) {
+    if (ports !== undefined && ports.length > 0) {
+        return ports;
+    }
+    if (port !== undefined) {
+        return [port];
+    }
+    return [];
+}
+function parseSessionRecord(value) {
     if (typeof value !== 'object' || value === null) {
-        return false;
+        return null;
     }
     const record = value;
-    return (typeof record.namespace === 'string' &&
-        typeof record.worktreePath === 'string' &&
-        typeof record.branch === 'string' &&
-        isSafeProcessId(record.pid) &&
-        isSafeProcessId(record.pgid) &&
-        isValidPort(record.port) &&
-        typeof record.logPath === 'string' &&
-        typeof record.startedAt === 'string');
+    const parsedPorts = normalizeSessionRecordPorts(record.port, Array.isArray(record.ports) ? record.ports : undefined);
+    if (typeof record.namespace !== 'string' ||
+        typeof record.worktreePath !== 'string' ||
+        typeof record.branch !== 'string' ||
+        !isSafeProcessId(record.pgid) ||
+        !isSafeProcessId(record.pid) ||
+        !isSafePort(record.port) ||
+        !parsedPorts.every(isSafePort) ||
+        parsedPorts.length === 0 ||
+        typeof record.logPath !== 'string' ||
+        typeof record.startedAt !== 'string') {
+        return null;
+    }
+    return { ...record, ports: parsedPorts };
 }
+const MAX_SESSION_BYTES = 16 * 1024;
 export function getSessionPaths(gitCommonDir, namespace) {
     const baseDir = path.join(gitCommonDir, 'worktree-command-tui');
     return {
@@ -42,8 +57,8 @@ export async function readSessionRecord(paths, { isSessionAlive }) {
         if (source === null) {
             return null;
         }
-        const parsed = JSON.parse(source);
-        if (!isSessionRecord(parsed)) {
+        const parsed = parseSessionRecord(JSON.parse(source));
+        if (parsed === null) {
             await rm(paths.sessionFile, { force: true });
             return null;
         }
@@ -59,7 +74,10 @@ export async function readSessionRecord(paths, { isSessionAlive }) {
 }
 export async function writeSessionRecord(paths, record) {
     await mkdir(paths.baseDir, { recursive: true });
-    await writeFile(paths.sessionFile, JSON.stringify(record, null, 2));
+    await writeFile(paths.sessionFile, JSON.stringify({
+        ...record,
+        ports: record.ports ?? [record.port],
+    }, null, 2));
 }
 export async function clearSessionRecord(paths) {
     await rm(paths.sessionFile, { force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ohzw/worktree-command-tui",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "A TUI for managing git worktrees",
   "private": false,
   "type": "module",