diff --git a/packages/plugin/src/remote-terminal-provider.ts b/packages/plugin/src/remote-terminal-provider.ts new file mode 100644 index 0000000..7edd23c --- /dev/null +++ b/packages/plugin/src/remote-terminal-provider.ts @@ -0,0 +1,161 @@ +import { spawn } from 'node:child_process' +import { access } from 'node:fs/promises' +import { constants } from 'node:fs' +import { userInfo } from 'node:os' +import { delimiter, isAbsolute, join } from 'node:path' +import { PassThrough } from 'node:stream' +import { RpcError } from './safe-error.js' + +export interface TerminalShell { path: string; args: string[]; name: string } +export interface TerminalActivity { state: 'idle' | 'busy' | 'unknown'; revision: number } +export interface RemoteTerminalSpec { + argv: readonly string[] + cwd: string + cols: number + rows: number + terminalType: string + env: Record + signal: AbortSignal +} +export interface RemoteTerminalProcess { + output: AsyncIterable + write(data: string): void | Promise + resize(cols: number, rows: number): void | Promise + terminate(): void | Promise + completed: Promise<{ exitCode: number | null }> + inspectActivity?(): Promise +} +/** Injectable process seam; shell discovery stays in the same execution environment. */ +export type RemoteTerminalSpawner = ((spec: RemoteTerminalSpec) => Promise) & { + shells?(signal: AbortSignal): Promise +} +export interface HostSubprocessLike { + spawnTerminal(spec: Record): Promise + terminalEnvironment?(signal?: AbortSignal): Promise<{ platform: 'posix' | 'windows'; defaultShell?: string }> + resolveExecutable?(file: string, env?: Record, signal?: AbortSignal): Promise +} +interface HostTerminalHandleLike { + output: PassThrough + write(data: string): void | Promise + resize(cols: number, rows: number): void | Promise + terminate(): void | Promise + done: Promise<{ exitCode?: number | null } | undefined> + inspectActivity?(): Promise +} + +/** Match official shell profiles: ordinary shells are explicitly interactive. */ +function profile(path: string): TerminalShell { + const name = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\')) + 1) + const kind = name.toLowerCase().replace(/\.exe$/u, '') + return { path, name, args: kind === 'cmd' ? [] : ['pwsh', 'powershell'].includes(kind) ? ['-NoLogo'] : ['-i'] } +} + +async function localExecutable(file: string, _env?: Record, signal?: AbortSignal): Promise { + signal?.throwIfAborted() + const extensions = process.platform === 'win32' && !/\.[^\\/]+$/.test(file) + ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';') : [''] + const paths = isAbsolute(file) ? [file] : (process.env.PATH ?? '').split(delimiter).filter(Boolean).map(dir => join(dir, file)) + for (const path of paths) for (const extension of extensions) { + try { await access(path + extension, process.platform === 'win32' ? constants.F_OK : constants.X_OK); signal?.throwIfAborted(); return path + extension } + catch (error) { if (signal?.aborted) throw error } + } + throw new RpcError('TERMINAL_SHELL_UNAVAILABLE', 'The terminal shell is unavailable.') +} + +export async function discoverTerminalShells(provider?: HostSubprocessLike, signal = new AbortController().signal): Promise { + signal.throwIfAborted() + if (provider?.terminalEnvironment && !provider.resolveExecutable) throw new RpcError('TERMINAL_SHELL_UNAVAILABLE', 'The terminal provider cannot verify its shells.') + // Older providers lack discovery. Only that compatibility path uses Host-local facts. + const environment = provider?.terminalEnvironment === undefined + ? { platform: process.platform === 'win32' ? 'windows' as const : 'posix' as const, + defaultShell: process.platform === 'win32' ? process.env.ComSpec : process.env.SHELL || userInfo().shell || undefined } + : await provider.terminalEnvironment(signal) + const resolve = provider?.resolveExecutable?.bind(provider) ?? localExecutable + const preferred = profile(environment.defaultShell || (environment.platform === 'windows' ? 'cmd.exe' : '/bin/sh')) + preferred.path = await resolve(preferred.path, undefined, signal) + // Legacy providers do not distinguish missing candidates from transport + // failures. Verify their default, without guessing which errors to swallow. + if (provider && !provider.terminalEnvironment) return [preferred] + const candidates = ['zsh', 'bash', 'fish', 'pwsh', 'powershell', 'cmd'] + const found = await Promise.all(candidates.map(async file => { + try { return { ...profile(file), path: await resolve(file, undefined, signal) } } + catch (error) { + if (error instanceof RpcError && error.code === 'TERMINAL_SHELL_UNAVAILABLE' + || error instanceof Error && error.name === 'SubprocessExecutableNotFoundError') return undefined + throw error + } + })) + signal.throwIfAborted() + const shells = new Map() + for (const shell of [preferred, ...found]) if (shell) { + const kind = shell.name.toLowerCase().replace(/\.exe$/u, '') + if (!shells.has(kind)) shells.set(kind, shell) + } + return [...shells.values()] +} + +/** Compatibility fallback only: pipes cannot provide PTY resize or job control. */ +export function pipeTerminalSpawner(): RemoteTerminalSpawner { + return Object.assign(async (spec: RemoteTerminalSpec): Promise => { + spec.signal.throwIfAborted() + const child = spawn(spec.argv[0]!, spec.argv.slice(1), { + cwd: spec.cwd, stdio: 'pipe', windowsHide: true, + env: { ...process.env, ...spec.env, TERM: spec.terminalType }, + }) + const output = new PassThrough() + output.setEncoding('utf8') + child.stdout.pipe(output, { end: false }) + child.stderr.pipe(output, { end: false }) + const completed = new Promise<{ exitCode: number | null }>((resolve, reject) => { + child.once('error', error => { output.destroy(); reject(error) }) + child.once('close', exitCode => { output.end(); resolve({ exitCode }) }) + }) + void completed.catch(() => undefined) + const abort = () => { child.kill() } + spec.signal.addEventListener('abort', abort, { once: true }) + try { + await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject) }) + spec.signal.throwIfAborted() + } catch (error) { child.kill(); throw error } + finally { spec.signal.removeEventListener('abort', abort) } + return { + output: output as unknown as AsyncIterable, + write: data => { child.stdin.write(data) }, resize: () => undefined, + terminate: async () => { + child.kill() + const timer = setTimeout(() => { child.kill('SIGKILL') }, 1000) + timer.unref() + try { await completed } finally { clearTimeout(timer) } + }, + completed, + } + }, { shells: (signal: AbortSignal) => discoverTerminalShells(undefined, signal) }) +} + +/** Reuse official PTY, shell activity integration and process-range termination. */ +export function subprocessTerminalSpawner(subprocess: HostSubprocessLike): RemoteTerminalSpawner { + return Object.assign(async (spec: RemoteTerminalSpec): Promise => { + spec.signal.throwIfAborted() + const allocation = new AbortController() + const abort = () => allocation.abort(spec.signal.reason) + spec.signal.addEventListener('abort', abort, { once: true }) + let handle: HostTerminalHandleLike + try { + handle = await subprocess.spawnTerminal({ ...spec, signal: allocation.signal, argv: [...spec.argv], shellActivity: true, graceMs: 1000 }) as HostTerminalHandleLike + } finally { + // A completed allocation belongs to the Host, not the request timeout or + // the physical connection, including on older subprocess providers. + spec.signal.removeEventListener('abort', abort) + } + handle.output.setEncoding?.('utf8') + const completed = handle.done.then(outcome => ({ exitCode: typeof outcome?.exitCode === 'number' ? outcome.exitCode : null })) + void completed.catch(() => { handle.output.destroy() }) + return { + output: handle.output as unknown as AsyncIterable, + write: data => handle.write(data), resize: (cols, rows) => handle.resize(cols, rows), + terminate: () => handle.terminate(), + completed, + ...(handle.inspectActivity === undefined ? {} : { inspectActivity: () => handle.inspectActivity!() }), + } + }, { shells: (signal: AbortSignal) => discoverTerminalShells(subprocess, signal) }) +}