aiwcli 0.15.5 → 0.17.0

package/dist/lib/multiplexer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Unified multiplexer abstraction.
+ * Backends implement the Multiplexer interface: resolveStrategy() for context-aware
+ * decision making, split()/createSession() for pane management.
+ * Factory: detectMultiplexer() → Multiplexer | null
+ */
+export type LaunchStrategy = 'split' | 'create-session' | 'inline' | 'unavailable';
+export interface StrategyContext {
+    calledFromRepl: boolean;
+    platform: NodeJS.Platform;
+    disableMux: boolean;
+}
+export interface ResolvedStrategy {
+    strategy: LaunchStrategy;
+    reason: string;
+}
+export type SplitDirection = 'auto' | 'horizontal' | 'vertical';
+export interface SplitOptions {
+    toolName: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    mode: 'exec' | 'repl';
+    split: SplitDirection;
+    promptPath?: string | undefined;
+    sentinelPath: string;
+    holdPane: boolean;
+    retryOnQuickExit: boolean;
+}
+export interface LaunchResult {
+    launched: boolean;
+    backend: string;
+    handle?: string | undefined;
+    sentinelPath?: string | undefined;
+    exitCode?: number | undefined;
+    reason?: string | undefined;
+}
+export interface CreateSessionOptions {
+    sessionName: string;
+    toolPath: string;
+    toolArgs: string[];
+    cwd: string;
+    promptText?: string | undefined;
+    reattach: boolean;
+    enableMouse?: boolean | undefined;
+}
+export interface Multiplexer {
+    readonly backend: string;
+    resolveStrategy(ctx: StrategyContext): ResolvedStrategy;
+    split(options: SplitOptions): Promise<LaunchResult>;
+    createSession(options: CreateSessionOptions): Promise<LaunchResult>;
+    kill(handle: string): Promise<void>;
+}
+/**
+ * Resolve the priority order of multiplexer backends for a given platform.
+ * Pure function — no I/O, no PATH checks. Used by detectMultiplexer().
+ */
+export declare function resolveMultiplexerPriority(platform: NodeJS.Platform, env?: Record<string, string | undefined>): string[];
+/**
+ * Detect the best available multiplexer for the current platform.
+ * Windows → WeztermMultiplexer (if inside WezTerm) → PsmuxMultiplexer (fallback)
+ * Unix → TmuxMultiplexer (if tmux binary on PATH)
+ * Returns null if no multiplexer is available.
+ */
+export declare function detectMultiplexer(platform?: NodeJS.Platform): Promise<Multiplexer | null>;

package/dist/lib/multiplexer.js

@@ -0,0 +1,38 @@
+/**
+ * Unified multiplexer abstraction.
+ * Backends implement the Multiplexer interface: resolveStrategy() for context-aware
+ * decision making, split()/createSession() for pane management.
+ * Factory: detectMultiplexer() → Multiplexer | null
+ */
+/**
+ * Resolve the priority order of multiplexer backends for a given platform.
+ * Pure function — no I/O, no PATH checks. Used by detectMultiplexer().
+ */
+export function resolveMultiplexerPriority(platform, env = {}) {
+    if (platform === 'win32') {
+        // Prefer WezTerm if we detect a WezTerm environment
+        if (env.WEZTERM_PANE || env.TERM_PROGRAM === 'WezTerm') {
+            return ['wezterm', 'psmux'];
+        }
+        return ['psmux'];
+    }
+    return ['tmux'];
+}
+/**
+ * Detect the best available multiplexer for the current platform.
+ * Windows → WeztermMultiplexer (if inside WezTerm) → PsmuxMultiplexer (fallback)
+ * Unix → TmuxMultiplexer (if tmux binary on PATH)
+ * Returns null if no multiplexer is available.
+ */
+export async function detectMultiplexer(platform = process.platform) {
+    if (platform === 'win32') {
+        const { WeztermMultiplexer } = await import('./multiplexers/wezterm.js');
+        const wezterm = WeztermMultiplexer.create();
+        if (wezterm)
+            return wezterm;
+        const { PsmuxMultiplexer } = await import('./multiplexers/psmux.js');
+        return PsmuxMultiplexer.create();
+    }
+    const { TmuxMultiplexer } = await import('./multiplexers/tmux.js');
+    return TmuxMultiplexer.create();
+}

package/dist/lib/multiplexers/psmux.d.ts

@@ -0,0 +1,55 @@
+/**
+ * PsmuxMultiplexer — unified psmux (Windows ConPTY) backend.
+ * Composes with PowerShellAdapter for command building.
+ * Owns: version checking, session readiness polling, bootstrap defaults.
+ */
+import type { CreateSessionOptions, LaunchResult, Multiplexer, ResolvedStrategy, SplitOptions, StrategyContext } from '../multiplexer.js';
+import type { ShellAdapter } from '../shell-adapters/shell-adapter.js';
+/** @internal */
+export interface PsmuxVersion {
+    major: number;
+    minor: number;
+    patch: number;
+}
+/** @internal */
+export declare function meetsMinVersion(v: PsmuxVersion): boolean;
+/** @internal */
+export declare function parseVersionString(stdout: string): null | PsmuxVersion;
+type PsmuxSplitFlag = '-h' | '-v';
+/** @internal — translate unified SplitDirection to psmux flag. */
+export declare function toPsmuxSplitFlag(direction: 'horizontal' | 'vertical'): PsmuxSplitFlag;
+/** @internal */
+export declare function buildCreateSessionArgs(params: {
+    cwd: string;
+    encodedCommand: string;
+    sessionName: string;
+}): string[];
+/** @internal */
+export declare function buildSplitWindowArgs(params: {
+    cwd?: string;
+    encodedCommand: string;
+    splitFlag: '-h' | '-v';
+    splitTarget?: string | undefined;
+}): string[];
+/** @internal */
+export declare function buildAttachArgs(sessionName: string): string[];
+export declare class PsmuxMultiplexer implements Multiplexer {
+    readonly backend: "psmux";
+    private readonly psmuxPath;
+    private readonly shell;
+    private constructor();
+    static create(): Promise<null | PsmuxMultiplexer>;
+    resolveStrategy(ctx: StrategyContext): ResolvedStrategy;
+    createSession(options: CreateSessionOptions): Promise<LaunchResult>;
+    kill(handle: string): Promise<void>;
+    split(options: SplitOptions): Promise<LaunchResult>;
+    private applyBootstrapDefaults;
+    private hasSession;
+    private resolveAutoSplit;
+    private waitForSessionReady;
+}
+/** @internal */
+export declare function buildPsmuxBootstrapCommands(enableMouse?: boolean): string[][];
+/** @internal */
+export declare function buildPsmuxShellCommand(shell: ShellAdapter, opts: CreateSessionOptions, promptFilePath?: string): string;
+export {};

package/dist/lib/multiplexers/psmux.js

@@ -0,0 +1,324 @@
+/**
+ * PsmuxMultiplexer — unified psmux (Windows ConPTY) backend.
+ * Composes with PowerShellAdapter for command building.
+ * Owns: version checking, session readiness polling, bootstrap defaults.
+ */
+import { existsSync, readdirSync, writeFileSync } from 'node:fs';
+import * as os from 'node:os';
+import path from 'node:path';
+import { sanitizedProcessEnv } from '../env-sanitizer.js';
+import { PANE_HOLD_MESSAGE, buildBootstrapPrompt, getLastLine, spawnAttached, splitFlagFromDimensions } from '../mux-utils.js';
+import { execFileAsync, findExecutable } from '../runtime/subprocess-utils.js';
+import { PowerShellAdapter } from '../shell-adapters/powershell-adapter.js';
+const MIN_VERSION = { major: 0, minor: 4, patch: 0 };
+const ATTACH_RETRY_DELAY_MS = 200;
+const SESSION_READY_BACKOFF_MS = [50, 100, 150, 250];
+const PSMUX_TERMINAL_OVERRIDES = ',*:Ss@:Se@:Cs@:Cr@';
+/** @internal */
+export function meetsMinVersion(v) {
+    if (v.major > MIN_VERSION.major)
+        return true;
+    if (v.major < MIN_VERSION.major)
+        return false;
+    if (v.minor > MIN_VERSION.minor)
+        return true;
+    if (v.minor < MIN_VERSION.minor)
+        return false;
+    return v.patch >= MIN_VERSION.patch;
+}
+/** @internal */
+export function parseVersionString(stdout) {
+    const match = stdout.trim().match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+/** @internal — translate unified SplitDirection to psmux flag. */
+export function toPsmuxSplitFlag(direction) {
+    return direction === 'horizontal' ? '-h' : '-v';
+}
+/** @internal */
+export function buildCreateSessionArgs(params) {
+    return ['new-session', '-d', '-c', params.cwd, '-s', params.sessionName, params.encodedCommand];
+}
+/** @internal */
+export function buildSplitWindowArgs(params) {
+    const args = ['split-window', params.splitFlag, '-P', '-F', '#{pane_id}'];
+    if (params.cwd) {
+        args.push('-c', params.cwd);
+    }
+    if (params.splitTarget?.trim()) {
+        args.push('-t', params.splitTarget.trim());
+    }
+    args.push(params.encodedCommand);
+    return args;
+}
+/** @internal */
+export function buildAttachArgs(sessionName) {
+    return ['attach', '-t', sessionName];
+}
+export class PsmuxMultiplexer {
+    backend = 'psmux';
+    psmuxPath;
+    shell;
+    constructor(psmuxPath) {
+        this.psmuxPath = psmuxPath;
+        this.shell = new PowerShellAdapter();
+    }
+    static async create() {
+        if (process.platform !== 'win32')
+            return null;
+        const psmuxPath = findExecutable('psmux') ?? findPsmuxInWinget();
+        if (!psmuxPath)
+            return null;
+        const result = await execFileAsync(psmuxPath, ['-V'], { timeout: 3000 });
+        if (result.exitCode !== 0)
+            return null;
+        const version = parseVersionString(result.stdout);
+        if (!version)
+            return null;
+        if (!meetsMinVersion(version))
+            return null;
+        return new PsmuxMultiplexer(psmuxPath);
+    }
+    resolveStrategy(ctx) {
+        if (ctx.disableMux) {
+            return { strategy: 'inline', reason: 'Multiplexer disabled via --no-tmux' };
+        }
+        if (Boolean(process.env.PSMUX_PANE)) {
+            return { strategy: 'split', reason: 'Inside psmux session' };
+        }
+        return { strategy: 'create-session', reason: 'Outside psmux — will create new session' };
+    }
+    async createSession(options) {
+        const { sessionName, reattach, enableMouse = true, cwd } = options;
+        let promptFilePath;
+        if (options.promptText) {
+            promptFilePath = path.join(os.tmpdir(), `aiwcli-prompt-${Date.now()}-${process.pid}.txt`);
+            writeFileSync(promptFilePath, options.promptText, { encoding: 'utf8', mode: 0o600 });
+        }
+        const shellCommand = buildPsmuxShellCommand(this.shell, options, promptFilePath);
+        // Inject PSMUX_PANE=1 for inside-session detection + nesting cleanup
+        const nestingCleanup = this.shell.buildNestingCleanup();
+        const commandWithEnv = `$env:PSMUX_PANE='1'; ${nestingCleanup} ${shellCommand}`;
+        const psmuxArgs = buildCreateSessionArgs({
+            sessionName,
+            cwd,
+            encodedCommand: this.shell.encodeForExecution(commandWithEnv),
+        });
+        const shouldCreate = !reattach || !(await this.hasSession(sessionName));
+        if (shouldCreate) {
+            const detachedCreate = await execFileAsync(this.psmuxPath, psmuxArgs, { timeout: 5000 });
+            if (detachedCreate.exitCode !== 0) {
+                const stderr = detachedCreate.stderr.trim();
+                return {
+                    launched: false,
+                    exitCode: detachedCreate.exitCode ?? 1,
+                    backend: this.backend,
+                    reason: stderr ? `psmux new-session failed: ${stderr}` : 'psmux new-session failed',
+                };
+            }
+        }
+        const ready = await this.waitForSessionReady(sessionName);
+        if (!ready) {
+            return {
+                launched: false,
+                exitCode: 1,
+                backend: this.backend,
+                reason: `psmux session '${sessionName}' not ready for attach`,
+            };
+        }
+        await this.applyBootstrapDefaults(enableMouse);
+        const attachArgs = buildAttachArgs(sessionName);
+        const env = sanitizedProcessEnv();
+        const firstAttach = await spawnAttached(this.psmuxPath, attachArgs, env, this.backend);
+        if (firstAttach.launched || (firstAttach.exitCode !== undefined && firstAttach.exitCode !== 1))
+            return firstAttach;
+        await waitMs(ATTACH_RETRY_DELAY_MS);
+        const secondAttach = await spawnAttached(this.psmuxPath, attachArgs, env, this.backend);
+        if (secondAttach.launched || (secondAttach.exitCode !== undefined && secondAttach.exitCode !== 1))
+            return secondAttach;
+        return {
+            ...secondAttach,
+            reason: 'psmux attach failed after retry (auth/session readiness race)',
+            launched: false,
+        };
+    }
+    async kill(handle) {
+        if (!handle)
+            return;
+        await execFileAsync(this.psmuxPath, ['kill-pane', '-t', handle], { timeout: 3000 });
+    }
+    async split(options) {
+        const { toolName, args, env, cwd, mode, sentinelPath } = options;
+        const nativePath = findExecutable(toolName);
+        if (!nativePath) {
+            return { launched: false, backend: this.backend, reason: `${toolName} not found on PATH` };
+        }
+        try {
+            const baseCommand = this.shell.buildToolCommand({
+                toolPath: nativePath,
+                args,
+                env,
+                mode,
+                ...(options.promptPath ? { promptPath: options.promptPath } : {}),
+            });
+            const holdMessage = PANE_HOLD_MESSAGE;
+            const wrappedCommand = this.shell.wrapSentinel({
+                command: baseCommand,
+                sentinelPath,
+                autoClose: false,
+                holdPane: false,
+                holdMessage,
+            });
+            const effectiveCommand = this.shell.encodeForExecution(wrappedCommand);
+            // Resolve split direction
+            const splitDirection = options.split;
+            let splitFlag;
+            if (splitDirection === 'auto') {
+                splitFlag = await this.resolveAutoSplit();
+            }
+            else {
+                splitFlag = toPsmuxSplitFlag(splitDirection);
+            }
+            await this.applyBootstrapDefaults();
+            const psmuxArgs = buildSplitWindowArgs({
+                splitFlag,
+                encodedCommand: effectiveCommand,
+                cwd,
+            });
+            const split = await execFileAsync(this.psmuxPath, psmuxArgs, { timeout: 5000 });
+            if (split.exitCode !== 0) {
+                return {
+                    launched: false,
+                    backend: this.backend,
+                    reason: 'psmux split-window failed',
+                };
+            }
+            const handle = getLastLine(split.stdout) || undefined;
+            return {
+                launched: true,
+                backend: this.backend,
+                handle,
+                sentinelPath,
+            };
+        }
+        catch (error) {
+            return {
+                launched: false,
+                backend: this.backend,
+                reason: `pane launch failed: ${String(error)}`,
+            };
+        }
+    }
+    async applyBootstrapDefaults(enableMouse = true) {
+        await runBootstrapCommands(this.psmuxPath, buildPsmuxBootstrapCommands(enableMouse));
+    }
+    async hasSession(sessionName) {
+        try {
+            const result = await execFileAsync(this.psmuxPath, ['has-session', '-t', sessionName], { timeout: 3000 });
+            return result.exitCode === 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    async resolveAutoSplit() {
+        try {
+            const size = await execFileAsync(this.psmuxPath, ['display-message', '-p', '#{pane_width} #{pane_height}'], { timeout: 3000 });
+            if (size.exitCode !== 0)
+                return '-h';
+            const parts = size.stdout.trim().split(/\s+/);
+            if (parts.length < 2)
+                return '-h';
+            const width = Number.parseInt(parts[0] ?? '', 10);
+            const height = Number.parseInt(parts[1] ?? '', 10);
+            if (!Number.isFinite(width) || !Number.isFinite(height))
+                return '-h';
+            return splitFlagFromDimensions(width, height);
+        }
+        catch {
+            return '-h';
+        }
+    }
+    async waitForSessionReady(sessionName) {
+        if (await this.hasSession(sessionName))
+            return true;
+        const poll = async (index) => {
+            const backoffMs = SESSION_READY_BACKOFF_MS[index];
+            if (backoffMs === undefined)
+                return false;
+            await waitMs(backoffMs);
+            if (await this.hasSession(sessionName))
+                return true;
+            return poll(index + 1);
+        };
+        return poll(0);
+    }
+}
+function findPsmuxInWinget() {
+    const localAppData = process.env.LOCALAPPDATA;
+    if (!localAppData)
+        return null;
+    const packagesDir = path.join(localAppData, 'Microsoft', 'WinGet', 'Packages');
+    if (!existsSync(packagesDir))
+        return null;
+    try {
+        const entries = readdirSync(packagesDir);
+        const psmuxDir = entries.find((e) => e.startsWith('marlocarlo.psmux'));
+        if (!psmuxDir)
+            return null;
+        const candidate = path.join(packagesDir, psmuxDir, 'psmux.exe');
+        return existsSync(candidate) ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** @internal */
+export function buildPsmuxBootstrapCommands(enableMouse = true) {
+    const commands = [];
+    if (enableMouse) {
+        commands.push(['set-option', '-g', 'mouse', 'on']);
+    }
+    commands.push(['set-option', '-g', 'history-limit', '50000'], ['set-option', '-g', 'cursor-blink', 'off'], ['set-option', '-g', 'cursor-style', 'block'], ['set-option', '-g', 'status-interval', '0'], ['set-option', '-g', 'terminal-overrides', PSMUX_TERMINAL_OVERRIDES]);
+    return commands;
+}
+/** @internal */
+export function buildPsmuxShellCommand(shell, opts, promptFilePath) {
+    const { toolPath, toolArgs } = opts;
+    const cmdParts = [];
+    cmdParts.push(`& ${shell.quote(toolPath)}`);
+    for (const arg of toolArgs) {
+        cmdParts.push(shell.quote(arg));
+    }
+    if (promptFilePath) {
+        const formatted = process.platform === 'win32'
+            ? promptFilePath.replaceAll('\\', '/')
+            : promptFilePath;
+        const bootstrap = buildBootstrapPrompt(formatted);
+        cmdParts.push(shell.quote(bootstrap));
+    }
+    return cmdParts.join(' ');
+}
+async function runBootstrapCommands(psmuxPath, commands, index = 0) {
+    const command = commands[index];
+    if (!command)
+        return;
+    try {
+        await execFileAsync(psmuxPath, command, { timeout: 3000 });
+    }
+    catch {
+        // Best effort only.
+    }
+    await runBootstrapCommands(psmuxPath, commands, index + 1);
+}
+function waitMs(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/lib/multiplexers/tmux.d.ts

@@ -0,0 +1,36 @@
+/**
+ * TmuxMultiplexer — unified tmux backend.
+ * Composes with BashAdapter for command building.
+ * Owns: split direction resolution, tmux session config, Windows bootstrap.
+ */
+import type { CreateSessionOptions, LaunchResult, Multiplexer, ResolvedStrategy, SplitOptions, StrategyContext } from '../multiplexer.js';
+import { type TmuxSplitFlag } from '../tmux-pane-placement.js';
+/** @internal — translate unified SplitDirection to tmux flag. */
+export declare function toTmuxSplitFlag(direction: 'horizontal' | 'vertical'): TmuxSplitFlag;
+/** @internal */
+export declare function withWindowsTmuxBootstrap(command: string, platform?: NodeJS.Platform): string;
+/** @internal */
+export declare function buildTmuxSplitWindowArgs(params: {
+    command: string;
+    cwd?: string | undefined;
+    splitFlag: '-h' | '-v';
+    splitTarget?: string | undefined;
+}): string[];
+/** @internal */
+export declare function buildTmuxCreateSessionArgs(params: {
+    cwd: string;
+    reattach?: boolean | undefined;
+    sessionName: string;
+    shellCommand: string;
+}): string[];
+export declare class TmuxMultiplexer implements Multiplexer {
+    readonly backend: "tmux";
+    private readonly tmuxPath;
+    private readonly shell;
+    private constructor();
+    static create(): null | TmuxMultiplexer;
+    resolveStrategy(ctx: StrategyContext): ResolvedStrategy;
+    createSession(options: CreateSessionOptions): Promise<LaunchResult>;
+    kill(handle: string): Promise<void>;
+    split(options: SplitOptions): Promise<LaunchResult>;
+}