@jacques-ai/server 0.0.7-alpha.1

package/dist/terminal-activator.js

@@ -0,0 +1,264 @@
+/**
+ * Terminal Activator
+ *
+ * Activates (brings to foreground with keyboard focus) a terminal window
+ * identified by its terminal_key. Supports iTerm2, Kitty, WezTerm,
+ * Terminal.app, and PID-based fallback.
+ */
+import { exec as execCb } from 'child_process';
+import { promisify } from 'util';
+import { runAppleScript, extractItermUuid } from './connection/index.js';
+const execAsync = promisify(execCb);
+/**
+ * Activate a terminal window by its terminal_key.
+ *
+ * Terminal key formats:
+ * - ITERM:<w0t0p0:UUID>  (ITERM_SESSION_ID = "w0t0p0:UUID")
+ * - KITTY:<window-id>
+ * - WEZTERM:<pane-id>
+ * - TERM:<session-id>    (from statusline.sh using TERM_SESSION_ID)
+ * - TTY:<tty-path>
+ * - PID:<process-id>
+ * - AUTO:* or UNKNOWN:* (unsupported)
+ * - DISCOVERED:<type>:<value>[:extra] (from process scanner, unwrapped to inner type)
+ */
+export async function activateTerminal(terminalKey) {
+    const colonIndex = terminalKey.indexOf(':');
+    if (colonIndex === -1) {
+        return { success: false, method: 'unsupported', error: `Invalid terminal key format: ${terminalKey}` };
+    }
+    const prefix = terminalKey.substring(0, colonIndex);
+    const value = terminalKey.substring(colonIndex + 1);
+    switch (prefix) {
+        case 'DISCOVERED':
+            // DISCOVERED keys have format: DISCOVERED:<type>:<value>[:pid]
+            // Extract the inner key and try to activate it
+            return activateDiscoveredTerminal(value);
+        case 'ITERM':
+            return activateITerm(value);
+        case 'KITTY':
+            return activateKitty(value);
+        case 'WEZTERM':
+            return activateWezTerm(value);
+        case 'TERM':
+            // TERM_SESSION_ID from Terminal.app - no reliable activation API
+            return { success: false, method: 'unsupported', error: 'TERM_SESSION_ID does not support remote activation' };
+        case 'TTY':
+            return activateByTTY(value);
+        case 'PID':
+            return activateByPid(value);
+        case 'AUTO':
+        case 'UNKNOWN':
+            return { success: false, method: 'unsupported', error: 'Terminal does not support remote activation' };
+        default:
+            return { success: false, method: 'unsupported', error: `Unknown terminal key prefix: ${prefix}` };
+    }
+}
+/**
+ * Activate a terminal from a DISCOVERED key.
+ *
+ * Discovered key formats (after DISCOVERED: prefix is stripped):
+ * - iTerm2:w0t0p0:<uuid>  → use ITERM activation with uuid
+ * - TTY:<tty-path>:<pid>  → use TTY activation with tty-path
+ * - PID:<pid>             → use PID activation
+ */
+async function activateDiscoveredTerminal(innerKey) {
+    const colonIndex = innerKey.indexOf(':');
+    if (colonIndex === -1) {
+        return { success: false, method: 'unsupported', error: `Invalid discovered key format: ${innerKey}` };
+    }
+    const innerType = innerKey.substring(0, colonIndex);
+    const innerValue = innerKey.substring(colonIndex + 1);
+    switch (innerType) {
+        case 'iTerm2': {
+            // iTerm2 discovered keys have format: iTerm2:w0t0p0:<uuid>
+            // The UUID is after the second colon
+            const secondColon = innerValue.indexOf(':');
+            if (secondColon === -1) {
+                // Just a single value, use it directly
+                return activateITerm(innerValue);
+            }
+            // Extract UUID (everything after w0t0p0:)
+            const uuid = innerValue.substring(secondColon + 1);
+            return activateITerm(uuid);
+        }
+        case 'TTY': {
+            // TTY discovered keys have format: TTY:<tty-path>:<pid>
+            // We need just the tty-path for activation
+            const lastColon = innerValue.lastIndexOf(':');
+            if (lastColon === -1) {
+                // No PID suffix, use value as-is
+                return activateByTTY(innerValue);
+            }
+            // Check if the last segment is a PID (all digits)
+            const possiblePid = innerValue.substring(lastColon + 1);
+            if (/^\d+$/.test(possiblePid)) {
+                // Last part is a PID, strip it
+                const ttyPath = innerValue.substring(0, lastColon);
+                return activateByTTY(ttyPath);
+            }
+            // Not a PID suffix, use full value
+            return activateByTTY(innerValue);
+        }
+        case 'PID':
+            return activateByPid(innerValue);
+        default:
+            // Unknown inner type, try using it as-is by reconstructing the key
+            return activateTerminal(`${innerType}:${innerValue}`);
+    }
+}
+// extractItermUuid is re-exported from connection module for backwards compatibility
+export { extractItermUuid } from './connection/index.js';
+/**
+ * Activate an iTerm2 tab by session UUID using AppleScript.
+ * Iterates all windows/tabs/sessions to find the matching UUID,
+ * selects the tab, and activates the window.
+ *
+ * ITERM_SESSION_ID env var is "w0t0p0:UUID" format.
+ * AppleScript's `unique ID of session` returns just the UUID.
+ */
+async function activateITerm(itermSessionId) {
+    const uuid = extractItermUuid(itermSessionId);
+    const script = `
+    tell application "iTerm2"
+      repeat with w in windows
+        repeat with t in tabs of w
+          repeat with s in sessions of t
+            if unique ID of s is "${uuid}" then
+              select t
+              set index of w to 1
+              activate
+              return "ok"
+            end if
+          end repeat
+        end repeat
+      end repeat
+      return "not_found"
+    end tell
+  `;
+    try {
+        const result = await runAppleScript(script);
+        if (result === 'ok') {
+            return { success: true, method: 'iterm' };
+        }
+        return { success: false, method: 'iterm', error: `Session not found: ${uuid}` };
+    }
+    catch (err) {
+        return { success: false, method: 'iterm', error: formatError(err) };
+    }
+}
+/**
+ * Activate a Kitty window by ID.
+ * Requires `allow_remote_control yes` in kitty.conf.
+ */
+async function activateKitty(windowId) {
+    try {
+        await execAsync(`kitten @ focus-window --match id:${windowId}`);
+        return { success: true, method: 'kitty' };
+    }
+    catch (err) {
+        return { success: false, method: 'kitty', error: formatError(err) };
+    }
+}
+/**
+ * Activate a WezTerm pane by pane ID.
+ */
+async function activateWezTerm(paneId) {
+    try {
+        await execAsync(`wezterm cli activate-pane --pane-id ${paneId}`);
+        return { success: true, method: 'wezterm' };
+    }
+    catch (err) {
+        return { success: false, method: 'wezterm', error: formatError(err) };
+    }
+}
+/**
+ * Activate a terminal by TTY path, trying all known terminal apps.
+ * Tries iTerm2 first (most common for discovered sessions), then Terminal.app.
+ */
+async function activateByTTY(ttyPath) {
+    const normalizedPath = ttyPath.startsWith('/dev/') ? ttyPath : `/dev/${ttyPath}`;
+    // Try iTerm2 first
+    try {
+        const itermScript = `
+      tell application "iTerm2"
+        repeat with w in windows
+          repeat with t in tabs of w
+            repeat with s in sessions of t
+              if tty of s contains "${normalizedPath}" then
+                select t
+                set index of w to 1
+                activate
+                return "ok"
+              end if
+            end repeat
+          end repeat
+        end repeat
+        return "not_found"
+      end tell
+    `;
+        const result = await runAppleScript(itermScript);
+        if (result === 'ok') {
+            return { success: true, method: 'iterm' };
+        }
+    }
+    catch {
+        // iTerm2 not running or errored, fall through to Terminal.app
+    }
+    // Try Terminal.app
+    return activateTerminalApp(normalizedPath);
+}
+/**
+ * Activate a Terminal.app tab by matching its TTY path.
+ * Uses AppleScript to iterate windows/tabs and match the tty.
+ */
+async function activateTerminalApp(ttyPath) {
+    // Normalize TTY path - ps returns "ttys012" but Terminal.app expects "/dev/ttys012"
+    const normalizedPath = ttyPath.startsWith('/dev/') ? ttyPath : `/dev/${ttyPath}`;
+    const script = `
+    tell application "Terminal"
+      repeat with w in windows
+        repeat with t in tabs of w
+          if tty of t is "${normalizedPath}" then
+            set selected tab of w to t
+            set index of w to 1
+            activate
+            return "ok"
+          end if
+        end repeat
+      end repeat
+      return "not_found"
+    end tell
+  `;
+    try {
+        const result = await runAppleScript(script);
+        if (result === 'ok') {
+            return { success: true, method: 'terminal_app' };
+        }
+        return { success: false, method: 'terminal_app', error: `TTY not found: ${normalizedPath}` };
+    }
+    catch (err) {
+        return { success: false, method: 'terminal_app', error: formatError(err) };
+    }
+}
+/**
+ * Activate a terminal by its process ID using System Events.
+ * This is app-level only (cannot select specific tabs).
+ */
+async function activateByPid(pid) {
+    const script = `tell application "System Events" to set frontmost of first process whose unix id is ${pid} to true`;
+    try {
+        await runAppleScript(script);
+        return { success: true, method: 'pid' };
+    }
+    catch (err) {
+        return { success: false, method: 'pid', error: formatError(err) };
+    }
+}
+function formatError(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+//# sourceMappingURL=terminal-activator.js.map

package/dist/terminal-activator.js.map

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

package/dist/terminal-activator.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Terminal Activator Tests
+ *
+ * Tests prefix parsing and unsupported terminal handling.
+ * The actual exec calls (osascript, kitten, wezterm) are platform-specific
+ * and tested via manual verification.
+ */
+export {};
+//# sourceMappingURL=terminal-activator.test.d.ts.map

package/dist/terminal-activator.test.d.ts.map

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

package/dist/terminal-activator.test.js

@@ -0,0 +1,95 @@
+/**
+ * Terminal Activator Tests
+ *
+ * Tests prefix parsing and unsupported terminal handling.
+ * The actual exec calls (osascript, kitten, wezterm) are platform-specific
+ * and tested via manual verification.
+ */
+import { activateTerminal, extractItermUuid } from './terminal-activator.js';
+describe('activateTerminal', () => {
+    describe('prefix parsing', () => {
+        it('should return unsupported for invalid key format (no colon)', async () => {
+            const result = await activateTerminal('invalid-key');
+            expect(result.success).toBe(false);
+            expect(result.method).toBe('unsupported');
+            expect(result.error).toContain('Invalid terminal key format');
+        });
+        it('should return unsupported for empty string', async () => {
+            const result = await activateTerminal('');
+            expect(result.success).toBe(false);
+            expect(result.method).toBe('unsupported');
+            expect(result.error).toContain('Invalid terminal key format');
+        });
+        it('should return unsupported for AUTO prefix', async () => {
+            const result = await activateTerminal('AUTO:12345');
+            expect(result.success).toBe(false);
+            expect(result.method).toBe('unsupported');
+            expect(result.error).toContain('does not support remote activation');
+        });
+        it('should return unsupported for UNKNOWN prefix', async () => {
+            const result = await activateTerminal('UNKNOWN:something');
+            expect(result.success).toBe(false);
+            expect(result.method).toBe('unsupported');
+            expect(result.error).toContain('does not support remote activation');
+        });
+        it('should return unsupported for unrecognized prefix', async () => {
+            const result = await activateTerminal('VSCODE:1234');
+            expect(result.success).toBe(false);
+            expect(result.method).toBe('unsupported');
+            expect(result.error).toContain('Unknown terminal key prefix');
+        });
+        it('should return unsupported for ALACRITTY prefix', async () => {
+            const result = await activateTerminal('ALACRITTY:window1');
+            expect(result.success).toBe(false);
+            expect(result.method).toBe('unsupported');
+            expect(result.error).toContain('Unknown terminal key prefix');
+        });
+        it('should return unsupported for TERM prefix', async () => {
+            const result = await activateTerminal('TERM:123.456');
+            expect(result.success).toBe(false);
+            expect(result.method).toBe('unsupported');
+            expect(result.error).toContain('does not support remote activation');
+        });
+    });
+    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');
+        });
+    });
+    // Integration-style tests that actually call exec.
+    // These will fail in CI but verify correct method dispatch.
+    // Use short timeout since these may hang on some platforms.
+    describe('method dispatch', () => {
+        it('should dispatch to iterm for ITERM prefix', async () => {
+            const result = await activateTerminal('ITERM:12345678-1234-1234-1234-123456789abc');
+            expect(result.method).toBe('iterm');
+        }, 3000);
+        it('should dispatch to kitty for KITTY prefix', async () => {
+            const result = await activateTerminal('KITTY:42');
+            expect(result.method).toBe('kitty');
+        }, 3000);
+        it('should dispatch to wezterm for WEZTERM prefix', async () => {
+            const result = await activateTerminal('WEZTERM:7');
+            expect(result.method).toBe('wezterm');
+        }, 3000);
+        it('should dispatch to iterm or terminal_app for TTY prefix', async () => {
+            const result = await activateTerminal('TTY:/dev/ttys003');
+            // activateByTTY tries iTerm2 first, then Terminal.app
+            expect(['iterm', 'terminal_app']).toContain(result.method);
+        }, 10000);
+        it('should dispatch to pid for PID prefix', async () => {
+            const result = await activateTerminal('PID:99999');
+            expect(result.method).toBe('pid');
+        }, 3000);
+    });
+});
+//# sourceMappingURL=terminal-activator.test.js.map

package/dist/terminal-activator.test.js.map

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

package/dist/terminal-launcher.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Terminal Launcher
+ *
+ * Launches a new terminal window in a given directory and runs `claude` in it.
+ * Supports iTerm2, Terminal.app, Kitty, WezTerm, Windows Terminal, PowerShell,
+ * and GNOME Terminal. Auto-detects the best available terminal per platform.
+ *
+ * Once claude starts, the existing hook infrastructure (SessionStart) handles
+ * auto-registration — the new session appears in Jacques automatically.
+ */
+export type LaunchMethod = 'iterm' | 'terminal_app' | 'kitty' | 'wezterm' | 'gnome_terminal' | 'windows_terminal' | 'powershell' | 'unsupported';
+export interface LaunchResult {
+    success: boolean;
+    method: LaunchMethod;
+    error?: string;
+    /** PID of the spawned terminal process (if detectable) */
+    pid?: number;
+}
+export interface LaunchOptions {
+    /** Working directory to run claude in */
+    cwd: string;
+    /** Preferred terminal emulator (overrides auto-detection) */
+    preferredTerminal?: string;
+    /** Target display bounds for window positioning (used for display-targeted launching) */
+    targetBounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Launch with --dangerously-skip-permissions flag */
+    dangerouslySkipPermissions?: boolean;
+}
+/**
+ * Launch a new terminal session running `claude` in the given directory.
+ *
+ * Terminal detection priority:
+ * - macOS: iTerm2 → Kitty → WezTerm → Terminal.app
+ * - Windows: Windows Terminal → PowerShell
+ * - Linux: Kitty → WezTerm → GNOME Terminal
+ */
+export declare function launchTerminalSession(options: LaunchOptions): Promise<LaunchResult>;
+/**
+ * Detect the best available terminal emulator for the current platform.
+ */
+export declare function detectAvailableTerminal(): Promise<LaunchMethod>;
+/**
+ * Check if a command is available on the system PATH.
+ */
+export declare function isCommandOnPath(cmd: string): Promise<boolean>;
+//# sourceMappingURL=terminal-launcher.d.ts.map

package/dist/terminal-launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-launcher.d.ts","sourceRoot":"","sources":["../src/terminal-launcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,cAAc,GACd,OAAO,GACP,SAAS,GACT,gBAAgB,GAChB,kBAAkB,GAClB,YAAY,GACZ,aAAa,CAAC;AAElB,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yFAAyF;IACzF,YAAY,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,sDAAsD;IACtD,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAyBzF;AAED;;GAEG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,YAAY,CAAC,CAmBrE;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnE"}