@jacques-ai/server 0.0.7-alpha.1

package/dist/connection/terminal-key.js

@@ -0,0 +1,271 @@
+/**
+ * Terminal Key Utilities
+ *
+ * Unified parsing, building, and matching of terminal key identifiers.
+ * Terminal keys uniquely identify terminal sessions across different terminal emulators.
+ *
+ * @module connection/terminal-key
+ */
+import { TerminalKeyPrefix } from './constants.js';
+/**
+ * Parse a terminal key string into its components.
+ *
+ * Handles all key formats:
+ * - ITERM:w0t0p0:UUID or ITERM:UUID
+ * - TTY:/dev/ttys001
+ * - PID:12345
+ * - KITTY:42
+ * - WEZTERM:pane:0
+ * - DISCOVERED:TTY:ttys001:12345
+ * - AUTO:session-uuid
+ *
+ * @param key The terminal key string to parse
+ * @returns Parsed terminal key structure
+ */
+export function parseTerminalKey(key) {
+    if (!key) {
+        return {
+            prefix: TerminalKeyPrefix.UNKNOWN,
+            value: '',
+            isDiscovered: false,
+        };
+    }
+    // Check for DISCOVERED: wrapper
+    if (key.startsWith('DISCOVERED:')) {
+        const inner = key.substring(11); // Remove "DISCOVERED:"
+        const innerParsed = parseInnerKey(inner);
+        return {
+            prefix: TerminalKeyPrefix.DISCOVERED,
+            value: inner,
+            isDiscovered: true,
+            innerKey: innerParsed,
+            pid: innerParsed.pid,
+            uuid: innerParsed.uuid,
+            tty: innerParsed.tty,
+        };
+    }
+    return parseInnerKey(key);
+}
+/**
+ * Parse the inner portion of a terminal key (without DISCOVERED: wrapper)
+ */
+function parseInnerKey(key) {
+    const colonIndex = key.indexOf(':');
+    if (colonIndex === -1) {
+        return {
+            prefix: TerminalKeyPrefix.UNKNOWN,
+            value: key,
+            isDiscovered: false,
+        };
+    }
+    const prefix = key.substring(0, colonIndex).toUpperCase();
+    const value = key.substring(colonIndex + 1);
+    const result = {
+        prefix: (prefix in TerminalKeyPrefix ? prefix : TerminalKeyPrefix.UNKNOWN),
+        value,
+        isDiscovered: false,
+    };
+    // Extract type-specific fields
+    switch (result.prefix) {
+        case TerminalKeyPrefix.ITERM:
+            result.uuid = extractItermUuid(value);
+            break;
+        case TerminalKeyPrefix.TTY:
+            result.tty = value;
+            // Check for TTY:path:pid format (used in DISCOVERED:TTY:...)
+            const ttyParts = value.split(':');
+            if (ttyParts.length >= 2) {
+                const lastPart = ttyParts[ttyParts.length - 1];
+                const maybePid = parseInt(lastPart, 10);
+                if (!isNaN(maybePid) && maybePid > 0) {
+                    result.pid = maybePid;
+                    result.tty = ttyParts.slice(0, -1).join(':');
+                }
+            }
+            break;
+        case TerminalKeyPrefix.PID:
+            const pid = parseInt(value, 10);
+            if (!isNaN(pid) && pid > 0) {
+                result.pid = pid;
+            }
+            break;
+        case TerminalKeyPrefix.KITTY:
+        case TerminalKeyPrefix.WEZTERM:
+        case TerminalKeyPrefix.TERM:
+        case TerminalKeyPrefix.WT:
+        case TerminalKeyPrefix.AUTO:
+            // No special extraction needed
+            break;
+    }
+    return result;
+}
+/**
+ * Build a terminal key string from identity information.
+ *
+ * Priority order:
+ * 1. iTerm session ID
+ * 2. Kitty window ID
+ * 3. WezTerm pane ID
+ * 4. Windows Terminal session
+ * 5. TTY path
+ * 6. PID (fallback)
+ *
+ * @param info Terminal identity information
+ * @returns Terminal key string or null if no valid identity
+ */
+export function buildTerminalKey(info) {
+    if (info.itermSessionId) {
+        return `ITERM:${info.itermSessionId}`;
+    }
+    if (info.kittyWindowId) {
+        return `KITTY:${info.kittyWindowId}`;
+    }
+    if (info.weztermPaneId) {
+        return `WEZTERM:${info.weztermPaneId}`;
+    }
+    if (info.wtSession) {
+        return `WT:${info.wtSession}`;
+    }
+    if (info.termSessionId) {
+        return `TERM:${info.termSessionId}`;
+    }
+    if (info.tty) {
+        return `TTY:${info.tty}`;
+    }
+    if (info.pid && info.pid > 0) {
+        return `PID:${info.pid}`;
+    }
+    return null;
+}
+/**
+ * Extract PID from a terminal key if present.
+ *
+ * Handles formats:
+ * - PID:12345
+ * - DISCOVERED:PID:12345
+ * - DISCOVERED:TTY:ttys001:12345 (PID at end)
+ *
+ * @param key Terminal key string
+ * @returns PID number or null if not extractable
+ */
+export function extractPid(key) {
+    if (!key)
+        return null;
+    // Check for DISCOVERED:PID:xxx or PID:xxx
+    const pidMatch = key.match(/(?:DISCOVERED:)?PID:(\d+)/);
+    if (pidMatch) {
+        return parseInt(pidMatch[1], 10);
+    }
+    // Check for DISCOVERED:TTY:xxx:pid at the end
+    const ttyMatch = key.match(/DISCOVERED:TTY:[^:]+:(\d+)$/);
+    if (ttyMatch) {
+        return parseInt(ttyMatch[1], 10);
+    }
+    return null;
+}
+/**
+ * Extract the UUID from an iTerm session ID or terminal key.
+ *
+ * iTerm's ITERM_SESSION_ID format is "w0t0p0:UUID" where:
+ * - w0 = window index
+ * - t0 = tab index
+ * - p0 = pane index
+ * - UUID = unique session identifier
+ *
+ * AppleScript's `unique ID of session` returns just the UUID portion.
+ *
+ * @param value The iTerm session ID value (after ITERM: prefix) or full key
+ * @returns The UUID portion, or the input if no colon present
+ */
+export function extractItermUuid(value) {
+    if (!value)
+        return '';
+    // If this is a full ITERM: key, extract the value portion
+    let itermValue = value;
+    if (value.startsWith('ITERM:')) {
+        itermValue = value.substring(6);
+    }
+    // Find the colon separator between w0t0p0 and UUID
+    const colonIndex = itermValue.indexOf(':');
+    if (colonIndex === -1) {
+        // No colon means it's already just the UUID
+        return itermValue;
+    }
+    // Return everything after the colon (the UUID)
+    return itermValue.substring(colonIndex + 1);
+}
+/**
+ * Check if two terminal keys refer to the same terminal.
+ *
+ * Handles special cases:
+ * - iTerm keys match by UUID (ignoring w0t0p0 prefix differences)
+ * - DISCOVERED: wrapper is unwrapped for comparison
+ * - Exact string match as fallback
+ *
+ * @param keyA First terminal key
+ * @param keyB Second terminal key
+ * @returns True if keys match the same terminal
+ */
+export function matchTerminalKeys(keyA, keyB) {
+    if (!keyA || !keyB)
+        return false;
+    // Exact match
+    if (keyA === keyB)
+        return true;
+    const parsedA = parseTerminalKey(keyA);
+    const parsedB = parseTerminalKey(keyB);
+    // Get effective prefix (unwrap DISCOVERED)
+    const effectiveA = parsedA.isDiscovered && parsedA.innerKey ? parsedA.innerKey : parsedA;
+    const effectiveB = parsedB.isDiscovered && parsedB.innerKey ? parsedB.innerKey : parsedB;
+    // Different types don't match
+    if (effectiveA.prefix !== effectiveB.prefix)
+        return false;
+    // iTerm: match by UUID (handles w0t0p0:UUID vs UUID mismatch)
+    if (effectiveA.prefix === TerminalKeyPrefix.ITERM) {
+        const uuidA = effectiveA.uuid || extractItermUuid(effectiveA.value);
+        const uuidB = effectiveB.uuid || extractItermUuid(effectiveB.value);
+        return uuidA === uuidB && uuidA !== '';
+    }
+    // TTY: match by path (ignore PID suffix if present)
+    if (effectiveA.prefix === TerminalKeyPrefix.TTY) {
+        const ttyA = effectiveA.tty || effectiveA.value.split(':')[0];
+        const ttyB = effectiveB.tty || effectiveB.value.split(':')[0];
+        return ttyA === ttyB;
+    }
+    // PID: match by number
+    if (effectiveA.prefix === TerminalKeyPrefix.PID) {
+        return effectiveA.pid === effectiveB.pid && effectiveA.pid !== undefined;
+    }
+    // Default: exact value match
+    return effectiveA.value === effectiveB.value;
+}
+/**
+ * Get a human-readable description of a terminal key.
+ *
+ * @param key Terminal key string
+ * @returns Human-readable description
+ */
+export function describeTerminalKey(key) {
+    const parsed = parseTerminalKey(key);
+    if (parsed.prefix === TerminalKeyPrefix.UNKNOWN) {
+        return `Unknown terminal: ${key}`;
+    }
+    const prefix = parsed.isDiscovered ? `Discovered ${parsed.innerKey?.prefix || 'unknown'}` : parsed.prefix;
+    switch (parsed.innerKey?.prefix || parsed.prefix) {
+        case TerminalKeyPrefix.ITERM:
+            return `${prefix} (UUID: ${parsed.uuid?.substring(0, 8)}...)`;
+        case TerminalKeyPrefix.TTY:
+            return `${prefix} (${parsed.tty})`;
+        case TerminalKeyPrefix.PID:
+            return `${prefix} (PID: ${parsed.pid})`;
+        case TerminalKeyPrefix.KITTY:
+            return `${prefix} (Window: ${parsed.value})`;
+        case TerminalKeyPrefix.WEZTERM:
+            return `${prefix} (Pane: ${parsed.value})`;
+        case TerminalKeyPrefix.AUTO:
+            return `Auto-registered session`;
+        default:
+            return `${prefix}: ${parsed.value}`;
+    }
+}
+//# sourceMappingURL=terminal-key.js.map

package/dist/connection/terminal-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-key.js","sourceRoot":"","sources":["../../src/connection/terminal-key.ts"],"names":[],"mappings":"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"}

package/dist/connection/terminal-key.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Terminal Key Utilities Tests
+ */
+export {};
+//# sourceMappingURL=terminal-key.test.d.ts.map

package/dist/connection/terminal-key.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-key.test.d.ts","sourceRoot":"","sources":["../../src/connection/terminal-key.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/connection/terminal-key.test.js

@@ -0,0 +1,221 @@
+/**
+ * Terminal Key Utilities Tests
+ */
+import { parseTerminalKey, buildTerminalKey, extractPid, extractItermUuid, matchTerminalKeys, describeTerminalKey, } from './terminal-key.js';
+import { TerminalKeyPrefix } from './constants.js';
+describe('terminal-key', () => {
+    describe('parseTerminalKey', () => {
+        it('should parse ITERM key with w0t0p0:UUID format', () => {
+            const result = parseTerminalKey('ITERM:w0t0p0:8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512');
+            expect(result.prefix).toBe(TerminalKeyPrefix.ITERM);
+            expect(result.value).toBe('w0t0p0:8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512');
+            expect(result.uuid).toBe('8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512');
+            expect(result.isDiscovered).toBe(false);
+        });
+        it('should parse ITERM key with UUID only', () => {
+            const result = parseTerminalKey('ITERM:8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512');
+            expect(result.prefix).toBe(TerminalKeyPrefix.ITERM);
+            expect(result.uuid).toBe('8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512');
+        });
+        it('should parse TTY key', () => {
+            const result = parseTerminalKey('TTY:/dev/ttys001');
+            expect(result.prefix).toBe(TerminalKeyPrefix.TTY);
+            expect(result.tty).toBe('/dev/ttys001');
+        });
+        it('should parse PID key', () => {
+            const result = parseTerminalKey('PID:12345');
+            expect(result.prefix).toBe(TerminalKeyPrefix.PID);
+            expect(result.pid).toBe(12345);
+        });
+        it('should parse KITTY key', () => {
+            const result = parseTerminalKey('KITTY:42');
+            expect(result.prefix).toBe(TerminalKeyPrefix.KITTY);
+            expect(result.value).toBe('42');
+        });
+        it('should parse WEZTERM key', () => {
+            const result = parseTerminalKey('WEZTERM:pane:0');
+            expect(result.prefix).toBe(TerminalKeyPrefix.WEZTERM);
+            expect(result.value).toBe('pane:0');
+        });
+        it('should parse AUTO key', () => {
+            const result = parseTerminalKey('AUTO:abc-123-def');
+            expect(result.prefix).toBe(TerminalKeyPrefix.AUTO);
+            expect(result.value).toBe('abc-123-def');
+        });
+        it('should parse DISCOVERED:TTY key with PID', () => {
+            const result = parseTerminalKey('DISCOVERED:TTY:ttys001:12345');
+            expect(result.prefix).toBe(TerminalKeyPrefix.DISCOVERED);
+            expect(result.isDiscovered).toBe(true);
+            expect(result.innerKey?.prefix).toBe(TerminalKeyPrefix.TTY);
+            expect(result.pid).toBe(12345);
+            expect(result.tty).toBe('ttys001');
+        });
+        it('should parse DISCOVERED:PID key', () => {
+            const result = parseTerminalKey('DISCOVERED:PID:54321');
+            expect(result.prefix).toBe(TerminalKeyPrefix.DISCOVERED);
+            expect(result.isDiscovered).toBe(true);
+            expect(result.innerKey?.prefix).toBe(TerminalKeyPrefix.PID);
+            expect(result.pid).toBe(54321);
+        });
+        it('should parse DISCOVERED:iTerm2 key', () => {
+            const result = parseTerminalKey('DISCOVERED:iTerm2:ABC123-DEF456');
+            expect(result.prefix).toBe(TerminalKeyPrefix.DISCOVERED);
+            expect(result.isDiscovered).toBe(true);
+        });
+        it('should handle empty string', () => {
+            const result = parseTerminalKey('');
+            expect(result.prefix).toBe(TerminalKeyPrefix.UNKNOWN);
+            expect(result.value).toBe('');
+        });
+        it('should handle key without colon', () => {
+            const result = parseTerminalKey('invalid-key');
+            expect(result.prefix).toBe(TerminalKeyPrefix.UNKNOWN);
+            expect(result.value).toBe('invalid-key');
+        });
+    });
+    describe('buildTerminalKey', () => {
+        it('should build ITERM key', () => {
+            const key = buildTerminalKey({ itermSessionId: 'w0t0p0:UUID-123' });
+            expect(key).toBe('ITERM:w0t0p0:UUID-123');
+        });
+        it('should build TTY key', () => {
+            const key = buildTerminalKey({ tty: '/dev/ttys001' });
+            expect(key).toBe('TTY:/dev/ttys001');
+        });
+        it('should build PID key', () => {
+            const key = buildTerminalKey({ pid: 12345 });
+            expect(key).toBe('PID:12345');
+        });
+        it('should build KITTY key', () => {
+            const key = buildTerminalKey({ kittyWindowId: '42' });
+            expect(key).toBe('KITTY:42');
+        });
+        it('should build WEZTERM key', () => {
+            const key = buildTerminalKey({ weztermPaneId: 'pane:0' });
+            expect(key).toBe('WEZTERM:pane:0');
+        });
+        it('should prioritize iTerm over TTY', () => {
+            const key = buildTerminalKey({ itermSessionId: 'UUID', tty: '/dev/ttys001' });
+            expect(key).toBe('ITERM:UUID');
+        });
+        it('should prioritize TTY over PID', () => {
+            const key = buildTerminalKey({ tty: '/dev/ttys001', pid: 12345 });
+            expect(key).toBe('TTY:/dev/ttys001');
+        });
+        it('should return null for empty identity', () => {
+            const key = buildTerminalKey({});
+            expect(key).toBeNull();
+        });
+        it('should return null for zero PID', () => {
+            const key = buildTerminalKey({ pid: 0 });
+            expect(key).toBeNull();
+        });
+    });
+    describe('extractPid', () => {
+        it('should extract PID from PID:xxx format', () => {
+            expect(extractPid('PID:12345')).toBe(12345);
+        });
+        it('should extract PID from DISCOVERED:PID:xxx format', () => {
+            expect(extractPid('DISCOVERED:PID:54321')).toBe(54321);
+        });
+        it('should extract PID from DISCOVERED:TTY:xxx:pid format', () => {
+            expect(extractPid('DISCOVERED:TTY:ttys001:68231')).toBe(68231);
+        });
+        it('should return null for TTY without PID', () => {
+            expect(extractPid('TTY:/dev/ttys001')).toBeNull();
+        });
+        it('should return null for ITERM key', () => {
+            expect(extractPid('ITERM:w0t0p0:UUID')).toBeNull();
+        });
+        it('should return null for empty string', () => {
+            expect(extractPid('')).toBeNull();
+        });
+        it('should return null for null-ish input', () => {
+            expect(extractPid(null)).toBeNull();
+        });
+    });
+    describe('extractItermUuid', () => {
+        it('should extract UUID from w0t0p0:UUID format', () => {
+            expect(extractItermUuid('w0t0p0:8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512'))
+                .toBe('8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512');
+        });
+        it('should extract UUID from w1t2p0:UUID format', () => {
+            expect(extractItermUuid('w1t2p0:ABCDEF12-3456-7890-ABCD-EF1234567890'))
+                .toBe('ABCDEF12-3456-7890-ABCD-EF1234567890');
+        });
+        it('should return value as-is if no colon present', () => {
+            expect(extractItermUuid('8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512'))
+                .toBe('8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512');
+        });
+        it('should handle full ITERM: key', () => {
+            expect(extractItermUuid('ITERM:w0t0p0:UUID-123'))
+                .toBe('UUID-123');
+        });
+        it('should return empty string for empty input', () => {
+            expect(extractItermUuid('')).toBe('');
+        });
+    });
+    describe('matchTerminalKeys', () => {
+        it('should match identical keys', () => {
+            expect(matchTerminalKeys('ITERM:w0t0p0:UUID', 'ITERM:w0t0p0:UUID')).toBe(true);
+        });
+        it('should match iTerm keys with same UUID but different w/t/p prefix', () => {
+            expect(matchTerminalKeys('ITERM:w0t0p0:8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512', 'ITERM:w1t2p0:8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512')).toBe(true);
+        });
+        it('should match iTerm key with and without w/t/p prefix', () => {
+            expect(matchTerminalKeys('ITERM:w0t0p0:UUID-123', 'ITERM:UUID-123')).toBe(true);
+        });
+        it('should not match iTerm keys with different UUIDs', () => {
+            expect(matchTerminalKeys('ITERM:UUID-A', 'ITERM:UUID-B')).toBe(false);
+        });
+        it('should match TTY keys', () => {
+            expect(matchTerminalKeys('TTY:/dev/ttys001', 'TTY:/dev/ttys001')).toBe(true);
+        });
+        it('should not match different TTY keys', () => {
+            expect(matchTerminalKeys('TTY:/dev/ttys001', 'TTY:/dev/ttys002')).toBe(false);
+        });
+        it('should match PID keys', () => {
+            expect(matchTerminalKeys('PID:12345', 'PID:12345')).toBe(true);
+        });
+        it('should not match different types', () => {
+            expect(matchTerminalKeys('ITERM:UUID', 'TTY:/dev/ttys001')).toBe(false);
+        });
+        it('should match DISCOVERED key with unwrapped key', () => {
+            expect(matchTerminalKeys('DISCOVERED:TTY:ttys001:12345', 'TTY:ttys001')).toBe(true);
+        });
+        it('should return false for empty keys', () => {
+            expect(matchTerminalKeys('', 'ITERM:UUID')).toBe(false);
+            expect(matchTerminalKeys('ITERM:UUID', '')).toBe(false);
+        });
+    });
+    describe('describeTerminalKey', () => {
+        it('should describe ITERM key', () => {
+            const desc = describeTerminalKey('ITERM:w0t0p0:8A7D83CA-3FA0-4D00-B34E-08C4FFA1E512');
+            expect(desc).toContain('ITERM');
+            expect(desc).toContain('8A7D83CA');
+        });
+        it('should describe TTY key', () => {
+            const desc = describeTerminalKey('TTY:/dev/ttys001');
+            expect(desc).toContain('TTY');
+            expect(desc).toContain('/dev/ttys001');
+        });
+        it('should describe PID key', () => {
+            const desc = describeTerminalKey('PID:12345');
+            expect(desc).toContain('PID');
+            expect(desc).toContain('12345');
+        });
+        it('should describe DISCOVERED key', () => {
+            const desc = describeTerminalKey('DISCOVERED:TTY:ttys001:12345');
+            expect(desc).toContain('Discovered');
+        });
+        it('should describe AUTO key', () => {
+            const desc = describeTerminalKey('AUTO:session-123');
+            expect(desc).toContain('Auto-registered');
+        });
+        it('should describe unknown key', () => {
+            const desc = describeTerminalKey('invalid');
+            expect(desc).toContain('Unknown');
+        });
+    });
+});
+//# sourceMappingURL=terminal-key.test.js.map

package/dist/connection/terminal-key.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-key.test.js","sourceRoot":"","sources":["../../src/connection/terminal-key.test.ts"],"names":[],"mappings":"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"}

package/dist/connection/worktree.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Worktree Management
+ *
+ * Creates, lists, inspects, and removes git worktrees for the project.
+ * Extends git-info.ts (read-only detection) with write operations.
+ *
+ * @module connection/worktree
+ */
+export interface CreateWorktreeOptions {
+    /** Canonical git repo root (main worktree root) */
+    repoRoot: string;
+    /** Name for the new worktree (used as directory suffix and branch name) */
+    name: string;
+    /** Base branch to create from (defaults to HEAD) */
+    baseBranch?: string;
+}
+export interface CreateWorktreeResult {
+    success: boolean;
+    /** Absolute path to the new worktree directory */
+    worktreePath?: string;
+    /** Branch name created for the worktree */
+    branch?: string;
+    error?: string;
+}
+export interface WorktreeEntry {
+    /** Worktree name (basename of directory) */
+    name: string;
+    /** Absolute path to worktree directory */
+    path: string;
+    /** Branch checked out in this worktree */
+    branch: string | null;
+    /** Whether this is the main worktree */
+    isMain: boolean;
+}
+export interface WorktreeStatus {
+    /** Whether the worktree has uncommitted changes (staged or unstaged) */
+    hasUncommittedChanges: boolean;
+    /** Whether the worktree branch has been merged into the default branch */
+    isMergedToMain: boolean;
+}
+export interface WorktreeWithStatus extends WorktreeEntry {
+    status: WorktreeStatus;
+}
+export interface RemoveWorktreeOptions {
+    /** Canonical git repo root (main worktree root) */
+    repoRoot: string;
+    /** Absolute path of the worktree to remove */
+    worktreePath: string;
+    /** Force removal even with uncommitted changes */
+    force?: boolean;
+    /** Also delete the branch after removing the worktree */
+    deleteBranch?: boolean;
+}
+export interface RemoveWorktreeResult {
+    success: boolean;
+    error?: string;
+    /** Whether the branch was also deleted */
+    branchDeleted?: boolean;
+}
+export declare function validateWorktreeName(name: string): string | null;
+/**
+ * Compute the worktree path: sibling to repo root with name suffix.
+ * e.g. /path/to/project → /path/to/project-<name>
+ */
+export declare function computeWorktreePath(repoRoot: string, name: string): string;
+/**
+ * Create a new git worktree as a sibling directory.
+ *
+ * Runs `git worktree add -b <name> <path>` which creates both
+ * the worktree directory and a new branch.
+ */
+export declare function createWorktree(options: CreateWorktreeOptions): Promise<CreateWorktreeResult>;
+/**
+ * List all worktrees for a repository.
+ * Prunes stale entries first, then wraps `git worktree list --porcelain`.
+ */
+export declare function listWorktrees(repoRoot: string): Promise<WorktreeEntry[]>;
+/**
+ * Parse `git worktree list --porcelain` output into structured entries.
+ *
+ * Format:
+ *   worktree /path/to/main
+ *   HEAD abc123
+ *   branch refs/heads/main
+ *   (blank line)
+ *   worktree /path/to/other
+ *   HEAD def456
+ *   branch refs/heads/feature
+ *   (blank line)
+ */
+export declare function parsePorcelainOutput(output: string, repoRoot: string): WorktreeEntry[];
+/**
+ * Detect the default branch for a repository (main or master).
+ * Tries `git symbolic-ref refs/remotes/origin/HEAD`, falls back to checking
+ * if 'main' or 'master' branch exists locally.
+ */
+export declare function detectDefaultBranch(repoRoot: string): Promise<string>;
+/**
+ * Check status of a single worktree: uncommitted changes and merge status.
+ */
+export declare function checkWorktreeStatus(worktreePath: string, branch: string | null, defaultBranch: string, repoRoot: string): Promise<WorktreeStatus>;
+/**
+ * List all worktrees with their status (uncommitted changes, merge status).
+ * Returns all worktrees including main.
+ */
+export declare function listWorktreesWithStatus(repoRoot: string): Promise<WorktreeWithStatus[]>;
+/**
+ * Remove a git worktree and optionally delete its branch.
+ *
+ * Runs `git worktree remove <path>` with optional --force flag.
+ * If deleteBranch is true, also runs `git branch -d <branch>`.
+ */
+export declare function removeWorktree(options: RemoveWorktreeOptions): Promise<RemoveWorktreeResult>;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/connection/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/connection/worktree.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wCAAwC;IACxC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,qBAAqB,EAAE,OAAO,CAAC;IAC/B,0EAA0E;IAC1E,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAMD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKhE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1E;AAID;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA8ClG;AAID;;;GAGG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAkB9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CAoCtF;AAID;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB3E;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,CAAC,CA2DzB;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA2B7F;AAID;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAgElG"}