@ohzw/worktree-command-tui 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# worktree-command-tui
+
+`worktree-command-tui` is a terminal UI (TUI) tool for operating multiple Git worktrees from one repository.
+It helps you inspect, start, and stop per-worktree processes with quick keyboard-driven workflows.
+
+## Features
+
+- List and monitor worktrees for the current repository
+- Start/stop worktree-specific commands
+- Keep process handling centralized for each session
+- Persist namespace-aware runtime state
+- Support JSONC config (with comments and trailing commas)
+
+## Requirements
+
+- Node.js `>=20`
+- A Git repository in the target working directory
+
+## Installation
+
+```bash
+npm install -g @ohzw/worktree-command-tui
+```
+
+## Usage
+
+### 1) Initialize configuration
+
+Run this once in a repository root (or any subdirectory of the repository):
+
+```bash
+wctui init
+```
+
+This creates `.worktree-command-tui.jsonc` with a sensible default configuration.
+
+To regenerate an existing configuration:
+
+```bash
+wctui init --force
+```
+
+### 2) Start the TUI
+
+```bash
+wctui
+```
+
+`worktree-command-tui` is still available as a compatibility alias.
+
+If no configuration file is found, the CLI will prompt you to run `wctui init`.
+
+## Configuration
+
+The tool reads these files in this order:
+
+1. `.worktree-command-tui.jsonc`
+2. `.worktree-command-tui.json`
+
+A minimal example of the generated config:
+
+```jsonc
+{
+  // Session namespace used for logs/state
+  "namespace": "worktree-command-tui",
+  // Command executed in each selected worktree
+  "command": ["npm", "run", "start"],
+  // Port used for cleanup/monitoring
+  "port": 3000,
+  // Required files that must exist in a worktree
+  "requiredFiles": ["package.json"],
+  // Optional command substrings considered orphaned processes
+  "orphanMatchers": []
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run test          # Run test suite
+npm run typecheck     # Run TypeScript type-check
+npm run build         # Build distributable output to dist/
+```
+
+## License
+
+MIT

package/dist/app.d.ts

@@ -0,0 +1,21 @@
+import type { AppActions, AppModel } from './core/runtime.js';
+export interface ShellDimensions {
+    rootWidth: number;
+    rootHeight: number;
+    bodyWidth: number;
+    listWidth: number;
+    actionWidth: number;
+}
+export interface AppWindowSize {
+    columns: number;
+    rows: number;
+}
+export declare function getShellDimensions(columns: number, rows: number): ShellDimensions;
+export declare function shouldUseCompactLayout(columns: number, rows: number, worktreeCount?: number): boolean;
+export declare function shouldUseMinimalLayout(columns: number, rows: number): boolean;
+export declare function shouldStackPanes(columns: number, rows: number, worktreeCount?: number): boolean;
+export declare function App({ initialModel, actions, windowSizeOverride, }: {
+    initialModel: AppModel;
+    actions: AppActions;
+    windowSizeOverride?: AppWindowSize;
+}): import("react").JSX.Element;

package/dist/app.js

@@ -0,0 +1,139 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Box, Text, useApp, useInput, useWindowSize } from 'ink';
+import { ActionPanel } from './components/ActionPanel.js';
+import { ContextBar } from './components/ContextBar.js';
+import { Header } from './components/Header.js';
+import { WorktreeList } from './components/WorktreeList.js';
+function getNextSelectedPath(rows, currentPath) {
+    if (rows.length === 0) {
+        return null;
+    }
+    if (currentPath && rows.some(row => row.path === currentPath)) {
+        return currentPath;
+    }
+    return rows[0].path;
+}
+export function getShellDimensions(columns, rows) {
+    const rootWidth = Math.max(columns, 1);
+    const rootHeight = Math.max(rows, 1);
+    const bodyWidth = Math.max(rootWidth - 4, 1);
+    const maxListWidth = Math.max(1, bodyWidth - 21);
+    const desiredListWidth = Math.max(1, Math.floor((bodyWidth - 1) * 0.34));
+    const listWidth = Math.min(42, desiredListWidth, maxListWidth);
+    const actionWidth = Math.max(1, bodyWidth - listWidth - 1);
+    return { rootWidth, rootHeight, bodyWidth, listWidth, actionWidth };
+}
+export function shouldUseCompactLayout(columns, rows, worktreeCount = 0) {
+    const contentAwareRowFloor = Math.max(20, worktreeCount + 12);
+    return columns < 72 || rows <= contentAwareRowFloor || (columns < 96 && rows < 24);
+}
+export function shouldUseMinimalLayout(columns, rows) {
+    return columns < 20 || rows < 6;
+}
+export function shouldStackPanes(columns, rows, worktreeCount = 0) {
+    const minimumRows = Math.max(26, worktreeCount + 18);
+    return columns < 96 && rows >= minimumRows;
+}
+export function App({ initialModel, actions, windowSizeOverride, }) {
+    const { exit } = useApp();
+    const liveWindowSize = useWindowSize();
+    const { columns, rows } = windowSizeOverride ?? liveWindowSize;
+    const [model, setModel] = useState(initialModel);
+    const [selectedPath, setSelectedPath] = useState(initialModel.rows[0]?.path ?? null);
+    const inFlightRef = useRef(false);
+    useEffect(() => {
+        setSelectedPath(currentPath => getNextSelectedPath(model.rows, currentPath));
+    }, [model.rows]);
+    const selectedIndex = useMemo(() => {
+        if (selectedPath === null) {
+            return 0;
+        }
+        const foundIndex = model.rows.findIndex(row => row.path === selectedPath);
+        return foundIndex >= 0 ? foundIndex : 0;
+    }, [model.rows, selectedPath]);
+    const selected = model.rows[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 <= 26;
+    function moveSelection(nextIndex) {
+        if (model.rows.length === 0) {
+            return;
+        }
+        setSelectedPath(model.rows[Math.min(Math.max(nextIndex, 0), model.rows.length - 1)].path);
+    }
+    async function apply(action) {
+        inFlightRef.current = true;
+        try {
+            const next = await action();
+            setModel(next);
+        }
+        catch (error) {
+            setModel(current => ({
+                ...current,
+                status: {
+                    kind: 'error',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            }));
+        }
+        finally {
+            inFlightRef.current = false;
+        }
+    }
+    useInput((input, key) => {
+        if (key.escape || input === 'q') {
+            exit();
+            return;
+        }
+        if (key.upArrow || input === 'k') {
+            moveSelection(selectedIndex - 1);
+            return;
+        }
+        if (key.downArrow || input === 'j') {
+            moveSelection(selectedIndex + 1);
+            return;
+        }
+        if (input === 'g') {
+            moveSelection(0);
+            return;
+        }
+        if (input === 'G') {
+            moveSelection(model.rows.length - 1);
+            return;
+        }
+        if (inFlightRef.current) {
+            return;
+        }
+        if (key.return && selected) {
+            if (selected.invalidReason) {
+                setModel(current => ({ ...current, status: { kind: 'error', message: selected.invalidReason } }));
+                return;
+            }
+            if (selected.path === model.activePath) {
+                setModel(current => ({ ...current, status: { kind: 'idle', message: 'already active' } }));
+                return;
+            }
+            setModel(current => ({ ...current, status: { kind: 'starting', message: `Starting ${selected.branch}...` } }));
+            void apply(() => actions.start(selected.path));
+            return;
+        }
+        if (input === 's') {
+            setModel(current => ({ ...current, status: { kind: 'stopping', message: 'Stopping active session...' } }));
+            void apply(() => actions.stop());
+            return;
+        }
+        if (input === 'r') {
+            void apply(() => actions.refresh());
+        }
+    });
+    if (minimalLayout) {
+        return (_jsxs(Box, { width: rootWidth, flexDirection: "column", children: [_jsxs(Text, { bold: true, color: "green", wrap: "truncate-end", children: ["A:", model.activeBranch ?? '-'] }), rootHeight >= 2 ? _jsxs(Text, { wrap: "truncate-end", children: ["S:", selected?.branch ?? '-'] }) : null, rootHeight >= 3 ? _jsxs(Text, { wrap: "truncate-end", children: ["T:", model.status.kind] }) : null, rootHeight >= 4 ? _jsx(Text, { dimColor: true, wrap: "truncate-end", children: "\u2191\u2193jk\u21B5q" }) : null] }));
+    }
+    if (compactLayout) {
+        return (_jsxs(Box, { width: rootWidth, borderStyle: "round", borderColor: "yellow", flexDirection: "column", paddingX: 1, children: [_jsxs(Text, { bold: true, color: "green", wrap: "truncate-end", children: ["Active: ", model.activeBranch ?? '-'] }), _jsxs(Text, { wrap: "truncate-end", children: ["Selected: ", selected?.branch ?? '-'] }), _jsxs(Text, { wrap: "truncate-end", children: ["Status: ", model.status.kind, " \u2014 ", model.status.message] }), _jsx(Text, { dimColor: true, wrap: "truncate-end", children: "Keys: \u2191\u2193/jk g/G \u21B5 s r q \u00B7 Resize terminal for split view" })] }));
+    }
+    return (_jsxs(Box, { width: rootWidth, height: stackedLayout ? undefined : rootHeight, borderStyle: "round", borderColor: "gray", flexDirection: "column", paddingX: 1, 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, stacked: stackedLayout }), _jsx(ActionPanel, { selectedRow: selected, activePath: model.activePath, stacked: stackedLayout, width: stackedLayout ? bodyWidth : actionWidth, compactDetails: compactDetailPane })] }), _jsx(ContextBar, { status: model.status })] }));
+}

package/dist/components/ActionPanel.d.ts

@@ -0,0 +1,10 @@
+import type { AppRow } from '../core/runtime.js';
+export declare function getPullRequestColor(selectedRow: AppRow): 'green' | 'yellow' | 'red' | undefined;
+export declare function getActionColor(selectedRow: AppRow): 'yellow' | 'red' | undefined;
+export declare function ActionPanel({ selectedRow, activePath, stacked, width, compactDetails, }: {
+    selectedRow: AppRow | undefined;
+    activePath: string | null;
+    stacked: boolean;
+    width?: number;
+    compactDetails?: boolean;
+}): import("react").JSX.Element;

package/dist/components/ActionPanel.js

@@ -0,0 +1,129 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+function formatTags(tags) {
+    return tags.length === 0 ? '-' : tags.join(' · ');
+}
+function sanitizeInlineText(value) {
+    return value
+        .replace(/[\r\n\t\u2028\u2029]+/g, ' ')
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, '')
+        .replace(/\p{Cf}/gu, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function formatUpstream(selectedRow) {
+    if (selectedRow.upstreamUnavailable) {
+        return 'unavailable';
+    }
+    if (!selectedRow.upstream) {
+        return '-';
+    }
+    return `${sanitizeInlineText(selectedRow.upstream.branch)} (↑${selectedRow.upstream.ahead} ↓${selectedRow.upstream.behind})`;
+}
+function formatWorkingTree(selectedRow) {
+    if (!selectedRow.workingTree) {
+        return 'unavailable';
+    }
+    const { staged, unstaged, untracked, conflicts } = selectedRow.workingTree;
+    if (staged === 0 && unstaged === 0 && untracked === 0 && conflicts === 0) {
+        return 'clean';
+    }
+    const parts = [];
+    if (staged > 0) {
+        parts.push(`index ${staged}`);
+    }
+    if (unstaged > 0) {
+        parts.push(`worktree ${unstaged}`);
+    }
+    if (untracked > 0) {
+        parts.push(`untracked ${untracked}`);
+    }
+    if (conflicts > 0) {
+        parts.push(`conflicts ${conflicts}`);
+    }
+    return `dirty (${parts.join(' · ')})`;
+}
+function formatPullRequest(selectedRow) {
+    if (!selectedRow.pullRequest || selectedRow.pullRequest.kind === 'none') {
+        return 'none';
+    }
+    if (selectedRow.pullRequest.kind === 'unavailable') {
+        return 'unavailable';
+    }
+    const draft = selectedRow.pullRequest.isDraft ? 'draft/' : '';
+    return `#${selectedRow.pullRequest.number} ${draft}${selectedRow.pullRequest.state.toLowerCase()} → ${sanitizeInlineText(selectedRow.pullRequest.baseBranch)}`;
+}
+function getPullRequestLabel(selectedRow) {
+    if (selectedRow.pullRequest?.kind === 'found' && selectedRow.pullRequest.state !== 'OPEN') {
+        return 'Last PR';
+    }
+    return 'PR';
+}
+function getPullRequestTitleLabel(selectedRow) {
+    if (selectedRow.pullRequest?.kind === 'found' && selectedRow.pullRequest.state !== 'OPEN') {
+        return 'Last PR Title';
+    }
+    return 'PR Title';
+}
+export function getPullRequestColor(selectedRow) {
+    if (!selectedRow.pullRequest || selectedRow.pullRequest.kind === 'none') {
+        return undefined;
+    }
+    if (selectedRow.pullRequest.kind === 'unavailable') {
+        return 'red';
+    }
+    if (selectedRow.pullRequest.state !== 'OPEN') {
+        return undefined;
+    }
+    return selectedRow.pullRequest.isDraft ? 'yellow' : 'green';
+}
+function getActionMessage(selectedRow, activePath) {
+    if (selectedRow.invalidReason) {
+        return 'Cannot start this worktree.';
+    }
+    if (selectedRow.path === activePath) {
+        return 'Already active. Press s to stop the current session.';
+    }
+    return 'Press Enter to start here and switch the active session.';
+}
+export function getActionColor(selectedRow) {
+    if (selectedRow.invalidReason) {
+        return 'red';
+    }
+    if ((selectedRow.workingTree?.conflicts ?? 0) > 0) {
+        return 'red';
+    }
+    if ((selectedRow.workingTree?.staged ?? 0) > 0
+        || (selectedRow.workingTree?.unstaged ?? 0) > 0
+        || (selectedRow.workingTree?.untracked ?? 0) > 0) {
+        return 'yellow';
+    }
+    return undefined;
+}
+function getNotes(selectedRow) {
+    if (selectedRow.invalidReason) {
+        return selectedRow.invalidReason;
+    }
+    if (selectedRow.tags.includes('external')) {
+        return 'External worktree managed outside the main checkout path.';
+    }
+    if (selectedRow.tags.includes('active')) {
+        return 'This worktree currently owns the running command session.';
+    }
+    return 'Ready to launch with the configured command in this worktree.';
+}
+function SectionHeader({ label }) {
+    return (_jsxs(Text, { bold: true, color: "cyan", children: ["[", label, "]"] }));
+}
+export function ActionPanel({ selectedRow, activePath, stacked, width, compactDetails, }) {
+    if (!selectedRow) {
+        return (_jsxs(Box, { width: width, flexGrow: stacked ? 0 : 1, flexShrink: 1, borderStyle: "round", borderColor: "magenta", flexDirection: "column", paddingX: 1, children: [_jsx(Text, { bold: true, color: "magenta", children: "Selection / Action" }), _jsx(Text, { dimColor: true, children: "No worktrees found." })] }));
+    }
+    const actionMessage = getActionMessage(selectedRow, activePath);
+    const showFullPath = !compactDetails && selectedRow.shortPath !== selectedRow.path;
+    const showTags = !compactDetails;
+    const pullRequestTitle = selectedRow.pullRequest?.kind === 'found' && !compactDetails
+        ? sanitizeInlineText(selectedRow.pullRequest.title)
+        : null;
+    return (_jsxs(Box, { width: width, flexGrow: stacked ? 0 : 1, flexShrink: 1, borderStyle: "round", borderColor: "magenta", flexDirection: "column", paddingX: 1, children: [_jsx(Text, { bold: true, color: "magenta", children: "Selection / Action" }), _jsx(SectionHeader, { label: "Identity" }), _jsxs(Text, { bold: true, color: selectedRow.tags.includes('active') ? 'green' : undefined, wrap: "truncate-end", children: ["Branch: ", sanitizeInlineText(selectedRow.branch)] }), _jsxs(Text, { wrap: "truncate-end", children: ["Path: ", sanitizeInlineText(selectedRow.shortPath)] }), showFullPath ? _jsxs(Text, { wrap: "truncate-end", children: ["Full Path: ", sanitizeInlineText(selectedRow.path)] }) : undefined, _jsxs(Text, { wrap: "truncate-end", children: ["HEAD: ", selectedRow.headSha || '-'] }), showTags ? _jsxs(Text, { wrap: "truncate-end", children: ["Tags: ", formatTags(selectedRow.tags)] }) : undefined, _jsx(SectionHeader, { label: "Git / PR" }), _jsxs(Text, { wrap: "truncate-end", children: ["Upstream: ", formatUpstream(selectedRow)] }), _jsxs(Text, { wrap: "truncate-end", children: ["Status: ", formatWorkingTree(selectedRow)] }), _jsxs(Text, { color: getPullRequestColor(selectedRow), dimColor: selectedRow.pullRequest?.kind === 'found' && selectedRow.pullRequest.state !== 'OPEN', wrap: "truncate-end", children: [getPullRequestLabel(selectedRow), ": ", formatPullRequest(selectedRow)] }), pullRequestTitle ? _jsxs(Text, { dimColor: selectedRow.pullRequest?.kind === 'found' && selectedRow.pullRequest.state !== 'OPEN', wrap: "truncate-end", children: [getPullRequestTitleLabel(selectedRow), ": ", pullRequestTitle] }) : undefined, _jsx(SectionHeader, { label: "Action" }), _jsx(Text, { color: getActionColor(selectedRow), wrap: "truncate-end", children: actionMessage }), _jsx(SectionHeader, { label: "Notes" }), _jsx(Text, { dimColor: true, wrap: "truncate-end", children: getNotes(selectedRow) })] }));
+}

package/dist/components/ContextBar.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+import type { AppStatus } from '../core/runtime.js';
+export declare function ContextBar({ status }: {
+    status: AppStatus;
+}): React.JSX.Element;

package/dist/components/ContextBar.js

@@ -0,0 +1,12 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+const COLOR_BY_KIND = {
+    idle: 'blue',
+    starting: 'yellow',
+    running: 'green',
+    stopping: 'yellow',
+    error: 'red',
+};
+export function ContextBar({ status }) {
+    return (_jsxs(Box, { borderStyle: "round", borderColor: COLOR_BY_KIND[status.kind], flexDirection: "column", paddingX: 1, children: [_jsxs(Text, { color: COLOR_BY_KIND[status.kind], wrap: "truncate-end", children: ["Status: ", status.kind, " \u2014 ", status.message] }), _jsx(Text, { dimColor: true, wrap: "truncate-end", children: "Keys: \u2191\u2193/jk move  g/G first/last  Enter start/switch  s stop  r refresh  q quit" })] }));
+}

package/dist/components/Header.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+export declare function Header({ repoName, namespace, activeBranch, }: {
+    repoName: string;
+    namespace: string;
+    activeBranch: string | null;
+}): React.JSX.Element;

package/dist/components/Header.js

@@ -0,0 +1,5 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+export function Header({ repoName, namespace, activeBranch, }) {
+    return (_jsxs(Box, { borderStyle: "round", borderColor: "blue", flexDirection: "column", paddingX: 1, children: [_jsxs(Text, { bold: true, color: "blue", wrap: "truncate-end", children: ["Worktree Command TUI \u00B7 Repo: ", repoName] }), _jsxs(Text, { color: "green", wrap: "truncate-end", children: ["Active: ", activeBranch ?? '-'] }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["Namespace: ", namespace] })] }));
+}

package/dist/components/WorktreeList.d.ts

@@ -0,0 +1,7 @@
+import type { AppRow } from '../core/runtime.js';
+export declare function WorktreeList({ rows, selectedIndex, width, stacked, }: {
+    rows: AppRow[];
+    selectedIndex: number;
+    width?: number;
+    stacked: boolean;
+}): import("react").JSX.Element;

package/dist/components/WorktreeList.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+const MIN_BRANCH_WIDTH = 24;
+function sanitizeInlineText(value) {
+    return value
+        .replace(/[\r\n\t\u2028\u2029]+/g, ' ')
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, '')
+        .replace(/\p{Cf}/gu, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function getIndicator(row) {
+    if (row.tags.includes('active')) {
+        return '*';
+    }
+    if (row.tags.includes('invalid')) {
+        return '!';
+    }
+    if (row.tags.includes('external')) {
+        return '^';
+    }
+    if (row.tags.includes('main')) {
+        return '#';
+    }
+    return '-';
+}
+function getRowColor(row, isSelected) {
+    if (row.tags.includes('active')) {
+        return 'green';
+    }
+    if (isSelected) {
+        return 'cyan';
+    }
+    if (row.tags.includes('invalid')) {
+        return 'red';
+    }
+    if (row.tags.includes('external')) {
+        return 'yellow';
+    }
+    if (row.tags.includes('main')) {
+        return 'blue';
+    }
+    return undefined;
+}
+function truncateLabel(value, width) {
+    if (value.length <= width) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(width - 1, 0))}…`;
+}
+export function WorktreeList({ rows, selectedIndex, width, stacked, }) {
+    const branchWidth = Math.max(MIN_BRANCH_WIDTH, (width ?? 34) - 7);
+    return (_jsxs(Box, { width: width, flexGrow: stacked ? 0 : 1, marginRight: stacked ? 0 : 1, borderStyle: "round", borderColor: "cyan", flexDirection: "column", paddingX: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "Worktrees" }), rows.map((row, index) => {
+                const isSelected = index === selectedIndex;
+                const line = `${isSelected ? '>' : ' '} ${getIndicator(row)} ${truncateLabel(sanitizeInlineText(row.branch), branchWidth)}`;
+                return (_jsx(Text, { color: getRowColor(row, isSelected), dimColor: !isSelected && getRowColor(row, isSelected) === undefined, wrap: "truncate-end", children: line }, row.path));
+            })] }));
+}

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

@@ -0,0 +1,10 @@
+export declare function startDetachedCommand({ command, cwd, logsDir, logFileBase, }: {
+    command: string[];
+    cwd: string;
+    logsDir: string;
+    logFileBase: string;
+}): Promise<{
+    pid: number;
+    pgid: number;
+    logPath: string;
+}>;

package/dist/core/command-runner.js

@@ -0,0 +1,38 @@
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+export function startDetachedCommand({ command, cwd, logsDir, logFileBase, }) {
+    mkdirSync(logsDir, { recursive: true });
+    const logPath = path.join(logsDir, `${logFileBase}.log`);
+    const fd = openSync(logPath, 'a');
+    const { promise, resolve, reject } = Promise.withResolvers();
+    let settled = false;
+    const child = spawn(command[0], command.slice(1), {
+        cwd,
+        detached: true,
+        stdio: ['ignore', fd, fd],
+    });
+    const finalize = () => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        closeSync(fd);
+    };
+    child.once('error', error => {
+        finalize();
+        reject(error);
+    });
+    child.once('spawn', () => {
+        const pid = child.pid;
+        if (pid === undefined) {
+            finalize();
+            reject(new Error('spawn succeeded without pid'));
+            return;
+        }
+        child.unref();
+        finalize();
+        resolve({ pid, pgid: pid, logPath });
+    });
+    return promise;
+}

package/dist/core/config.d.ts

@@ -0,0 +1,14 @@
+export declare const CONFIG_FILE_NAME = ".worktree-command-tui.jsonc";
+export declare const LEGACY_CONFIG_FILE_NAME = ".worktree-command-tui.json";
+export declare const CONFIG_FILE_NAMES: readonly [".worktree-command-tui.jsonc", ".worktree-command-tui.json"];
+export interface ToolConfig {
+    namespace: string;
+    command: string[];
+    port: number;
+    requiredFiles: string[];
+    orphanMatchers: string[];
+}
+export declare function parseJsonc(source: string): unknown;
+export declare function loadToolConfig({ repoRoot }: {
+    repoRoot: string;
+}): Promise<ToolConfig>;