@tiphareth/dsh-hardssh 0.1.2-alpha

package/src/remote/remote-process.ts

@@ -0,0 +1,203 @@
+/**
+ * One asynchronously-started SSH command projected onto the subprocess seam.
+ * Ported from UynajGI/dsh-ssh (MIT) — the raw ssh2 channel is replaced by the
+ * engine's streaming ExecSession.
+ */
+
+import { PassThrough } from 'node:stream'
+import type { SshEngine, ExecSession } from '../ssh/engine.ts'
+import type {
+  SubprocessCollect,
+  SubprocessHandle,
+  SubprocessOutcome,
+  SubprocessOutputMode,
+  SubprocessSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import type { WorkspaceState } from '../protocol.ts'
+import { quoteShellArg, readScrubbedRemoteEnvironment, serializeEnvironment } from './environment.ts'
+import { SshOutputCollector } from './output.ts'
+
+function isCollect(mode: SubprocessOutputMode): mode is SubprocessCollect {
+  return mode !== 'pipe' && mode !== 'inherit'
+}
+
+/** Resolve the remote working directory for one spawn spec. */
+function resolveRemoteCwd(state: WorkspaceState, cwd: string | undefined): string {
+  const root = state.remoteRoot
+  if (root === undefined) throw new Error('subprocess-ssh: remote workspace root is not set')
+  if (cwd !== undefined && cwd.startsWith('/')) return cwd
+  return root
+}
+
+/** Build the remote command text: cd, env -i scrub, exec the argv. */
+async function buildCommand(engine: SshEngine, alias: string, state: WorkspaceState, spec: SubprocessSpawnSpec): Promise<string> {
+  const environment = serializeEnvironment(await readScrubbedRemoteEnvironment(engine, alias), spec.env)
+  const argv = spec.argv.map(quoteShellArg).join(' ')
+  return `cd -- ${quoteShellArg(resolveRemoteCwd(state, spec.cwd))} && exec env -i -- ${environment} ${argv}`
+}
+
+/** SSH-backed subprocess handle. The channel does not expose a remote pid, so `pid` is `-1`. */
+export class SshSubprocessHandle implements SubprocessHandle {
+  readonly stdin: PassThrough | undefined
+  readonly stdout: PassThrough | undefined
+  readonly stderr: PassThrough | undefined
+  readonly collected: SubprocessHandle['collected']
+  readonly done: Promise<SubprocessOutcome>
+
+  private readonly terminationController = new AbortController()
+  private readonly stdoutCollector: SshOutputCollector | undefined
+  private readonly stderrCollector: SshOutputCollector | undefined
+  private session: ExecSession | undefined
+  private graceTimer: NodeJS.Timeout | undefined
+  private settled = false
+
+  constructor(
+    private readonly engine: SshEngine,
+    private readonly getState: () => WorkspaceState,
+    private readonly spec: SubprocessSpawnSpec,
+    private readonly spillDir: string,
+  ) {
+    const outMode = spec.stdio.stdout
+    const errMode = spec.stdio.stderr
+    this.stdout = outMode === 'pipe' ? new PassThrough() : undefined
+    this.stderr = errMode === 'pipe' ? new PassThrough() : undefined
+    this.stdoutCollector = isCollect(outMode)
+      ? new SshOutputCollector(outMode.maxBytes, outMode.spill?.maxBytes, 'stdout', spillDir)
+      : undefined
+    this.stderrCollector = isCollect(errMode)
+      ? new SshOutputCollector(errMode.maxBytes, errMode.spill?.maxBytes, 'stderr', spillDir)
+      : undefined
+    this.collected = {
+      ...(this.stdoutCollector !== undefined ? { stdout: this.stdoutCollector } : {}),
+      ...(this.stderrCollector !== undefined ? { stderr: this.stderrCollector } : {}),
+    }
+    this.stdin = spec.stdio.stdin === 'pipe' ? new PassThrough() : undefined
+
+    spec.signal?.addEventListener('abort', this.onAbort, { once: true })
+    this.done = this.run()
+    void this.done.catch(() => {})
+    if (spec.signal?.aborted === true) this.terminate()
+  }
+
+  /** Remote process id; `-1` because the SSH channel does not expose one. */
+  get pid(): number {
+    return -1
+  }
+
+  /** @inheritdoc */
+  terminate(): void {
+    if (this.settled || this.terminationController.signal.aborted) return
+    this.terminationController.abort(new Error('subprocess-ssh: command terminated'))
+    const session = this.session
+    if (session !== undefined) this.signalTerm(session)
+  }
+
+  /** @inheritdoc */
+  waitForExit(signal?: AbortSignal): Promise<boolean> {
+    if (this.settled) return Promise.resolve(true)
+    if (signal?.aborted === true) return Promise.resolve(false)
+    if (signal === undefined) {
+      return this.done.then(() => true, () => true)
+    }
+    return new Promise<boolean>((resolve) => {
+      const onAbort = (): void => { cleanup(); resolve(false) }
+      const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      void this.done.then(() => { cleanup(); resolve(true) }, () => { cleanup(); resolve(true) })
+    })
+  }
+
+  private readonly onAbort = (): void => { this.terminate() }
+
+  private signalTerm(session: ExecSession): void {
+    try {
+      session.signal('TERM')
+    } catch {
+      // The channel closed before the signal could be delivered; close is authoritative.
+    }
+    this.graceTimer = setTimeout(() => {
+      try {
+        session.signal('KILL')
+      } catch {
+        // Escalation after a graceful close is a no-op.
+      }
+    }, this.spec.graceMs)
+  }
+
+  private settle(): void {
+    if (this.settled) return
+    this.settled = true
+    if (this.graceTimer !== undefined) clearTimeout(this.graceTimer)
+    this.graceTimer = undefined
+    this.stdoutCollector?.seal()
+    this.stderrCollector?.seal()
+    this.spec.signal?.removeEventListener('abort', this.onAbort)
+  }
+
+  private async run(): Promise<SubprocessOutcome> {
+    let session: ExecSession
+    try {
+      const state = this.getState()
+      if (state.mode !== 'remote' || state.alias === undefined) {
+        throw new Error('subprocess-ssh: not in remote mode — switch the GUI to SSH mode first')
+      }
+      const command = await buildCommand(this.engine, state.alias, state, this.spec)
+      session = await this.engine.openExec(state.alias, command)
+    } catch (error) {
+      this.settle()
+      throw error
+    }
+    this.session = session
+    if (this.terminationController.signal.aborted) this.signalTerm(session)
+
+    this.wireStdout(session)
+    this.wireStderr(session)
+    if (this.stdin !== undefined) {
+      this.stdin.pipe({
+        write: (chunk: Buffer, encoding: BufferEncoding, callback?: (error?: Error | null) => void) => {
+          try {
+            session.send(chunk.toString(encoding ?? 'utf8'))
+            callback?.()
+          } catch (error) {
+            callback?.(error instanceof Error ? error : new Error(String(error)))
+          }
+        },
+        end: (callback?: () => void) => {
+          session.end()
+          callback?.()
+        },
+      } as unknown as NodeJS.WritableStream)
+    } else if (typeof this.spec.stdio.stdin === 'object') {
+      session.end(this.spec.stdio.stdin.data)
+    }
+
+    return await new Promise<SubprocessOutcome>((resolve, reject) => {
+      session.onExit = (code: number | null, error?: string) => {
+        this.settle()
+        if (error !== undefined) {
+          reject(new Error(`subprocess-ssh: ${error}`))
+        } else {
+          resolve({ exitCode: code, signal: null })
+        }
+      }
+    })
+  }
+
+  private wireStdout(session: ExecSession): void {
+    const mode = this.spec.stdio.stdout
+    session.onData = (data: Buffer) => {
+      if (mode === 'pipe') this.stdout?.write(data)
+      else if (mode === 'inherit') process.stdout.write(data)
+      else this.stdoutCollector?.push(data)
+    }
+  }
+
+  private wireStderr(session: ExecSession): void {
+    const mode = this.spec.stdio.stderr
+    session.onErrData = (data: Buffer) => {
+      if (mode === 'pipe') this.stderr?.write(data)
+      else if (mode === 'inherit') process.stderr.write(data)
+      else this.stderrCollector?.push(data)
+    }
+  }
+}

package/src/remote/remote-subprocess.ts

@@ -0,0 +1,159 @@
+/**
+ * Remote subprocess provider for the `ctx.subprocess` capability seam: each
+ * spawn opens a streaming exec channel (or a PTY for terminals) on the
+ * current SSH-mode host through the dsh-ssh engine; output spill files stay
+ * on the local host. Ported from UynajGI/dsh-ssh (MIT).
+ *
+ * @module dsh-hardssh/remote-subprocess
+ */
+
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, posix } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import type { SshEngine } from '../ssh/engine.ts'
+import { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess'
+import type {
+  SubprocessHandle,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import type { WorkspaceState } from '../protocol.ts'
+import { quoteShellArg } from './environment.ts'
+import { SshSubprocessHandle } from './remote-process.ts'
+import { SshTerminalHandle, spawnSshTerminal } from './remote-terminal.ts'
+
+/**
+ * Enforce the seam's documented grace bound (positive, finite, one Node timer).
+ */
+function requireRepresentableGrace(graceMs: number): void {
+  if (!Number.isFinite(graceMs) || graceMs <= 0 || graceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
+}
+
+/** SSH command manager registered as `ctx.subprocess` (remote mode). */
+export class SshSubprocessRuntime extends SubprocessRuntime {
+  private readonly live = new Set<SshSubprocessHandle>()
+  private readonly terminals = new Set<SshTerminalHandle>()
+  private readonly spillDir = mkdtempSync(join(tmpdir(), 'dsh-subprocess-ssh-'))
+  private disposing = false
+
+  constructor(
+    ctx: Context,
+    private readonly engine: SshEngine,
+    private readonly getState: () => WorkspaceState,
+  ) {
+    super(ctx)
+    ctx.effect(() => async () => {
+      this.disposing = true
+      const handles = [...this.live]
+      const terminals = [...this.terminals]
+      const pending: Promise<unknown>[] = []
+      for (const handle of handles) {
+        handle.terminate()
+        pending.push(handle.waitForExit().then(() => { this.live.delete(handle) }))
+      }
+      for (const terminal of terminals) {
+        pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
+      }
+      const outcomes = await Promise.allSettled(pending)
+      const failures = outcomes.flatMap<unknown>(outcome => outcome.status === 'rejected' ? [outcome.reason as unknown] : [])
+      if (failures.length === 1) throw failures[0]
+      if (failures.length > 1) throw new AggregateError(failures, 'subprocess-ssh: teardown failed')
+    }, 'ssh subprocess teardown')
+  }
+
+  /** @inheritdoc */
+  async resolveExecutable(
+    command: string,
+    env?: Readonly<Record<string, string>>,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    if (command.length === 0) throw new Error('subprocess-ssh: executable name must be non-empty')
+    signal?.throwIfAborted()
+    const state = this.getState()
+    if (state.mode !== 'remote' || state.alias === undefined) {
+      throw new Error('subprocess-ssh: not in remote mode — switch the GUI to SSH mode first')
+    }
+    if (posix.isAbsolute(command)) {
+      const result = await this.engine.exec(
+        state.alias,
+        `test -f ${quoteShellArg(command)} -a -x ${quoteShellArg(command)}`,
+        10_000,
+      )
+      signal?.throwIfAborted()
+      if (!result.success || result.exitCode !== 0) {
+        throw new Error(`subprocess-ssh: command ${JSON.stringify(command)} is not an executable file`)
+      }
+      return command
+    }
+    if (command.includes('/')) {
+      throw new Error(
+        `subprocess-ssh: command ${JSON.stringify(command)} is a relative path; use an absolute path or a bare PATH name`,
+      )
+    }
+    const path = env?.PATH
+    const prefix = path === undefined ? '' : `PATH=${quoteShellArg(path)} `
+    const result = await this.engine.exec(state.alias, `${prefix}command -v -- ${quoteShellArg(command)}`, 10_000)
+    signal?.throwIfAborted()
+    const executable = result.stdout.trim()
+    if (!result.success || result.exitCode !== 0
+      || executable.length === 0
+      || executable.includes('\n')
+      || (!posix.isAbsolute(executable) && !executable.includes('/'))) {
+      throw new Error(`subprocess-ssh: executable ${JSON.stringify(command)} did not resolve to one absolute path`)
+    }
+    const root = state.remoteRoot
+    if (root === undefined) throw new Error('subprocess-ssh: remote workspace root is not set')
+    return posix.isAbsolute(executable) ? executable : posix.resolve(root, executable)
+  }
+
+  /** @inheritdoc */
+  spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
+    if (this.disposing) throw new Error('subprocess-ssh: service is disposing')
+    const program = spec.argv[0]
+    if (program === undefined || program.length === 0) {
+      throw new Error('invalid argv: expected a non-empty program name at argv[0]')
+    }
+    requireRepresentableGrace(spec.graceMs)
+    if (spec.signal?.aborted === true) {
+      throw new Error(`aborted before spawn: ${String(spec.signal.reason)}`)
+    }
+    const handle = new SshSubprocessHandle(this.engine, this.getState, spec, this.spillDir)
+    this.live.add(handle)
+    const release = async (): Promise<void> => {
+      await handle.waitForExit()
+      this.live.delete(handle)
+    }
+    void handle.done.then(release, release).catch(() => {})
+    return handle
+  }
+
+  /** @inheritdoc */
+  async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    if (this.disposing) throw new Error('subprocess-ssh: service is disposing')
+    const program = spec.argv[0]
+    if (program === undefined || program.length === 0) {
+      throw new Error('subprocess-ssh: terminal argv must contain a program')
+    }
+    requireRepresentableGrace(spec.graceMs)
+    spec.signal?.throwIfAborted()
+    const terminal = await spawnSshTerminal(this.engine, this.getState, spec)
+    if (this.disposing) {
+      await terminal.terminate()
+      throw new Error('subprocess-ssh: service disposed during terminal setup')
+    }
+    this.terminals.add(terminal)
+    const release = async (): Promise<void> => {
+      await terminal.terminate()
+      this.terminals.delete(terminal)
+    }
+    void terminal.done.then(release, release).catch(() => {})
+    return terminal
+  }
+}
+
+export default SshSubprocessRuntime

package/src/remote/remote-terminal.ts

@@ -0,0 +1,141 @@
+/**
+ * SSH PTY allocation and process-session ownership for the subprocess seam.
+ * Ported from UynajGI/dsh-ssh (MIT) — the raw ssh2 shell channel is replaced
+ * by the engine's openShell session.
+ */
+
+import { PassThrough } from 'node:stream'
+import type { SshEngine } from '../ssh/engine.ts'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSignal,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import type { WorkspaceState } from '../protocol.ts'
+import { quoteShellArg, readScrubbedRemoteEnvironment, serializeEnvironment } from './environment.ts'
+
+/** Resolve after one duration. */
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/** One SSH PTY and its remote login shell, projected onto the subprocess terminal seam. */
+export class SshTerminalHandle implements SubprocessTerminalHandle {
+  readonly pid = -1
+  readonly output = new PassThrough()
+  readonly done: Promise<SubprocessOutcome>
+
+  private exitResolve!: (outcome: SubprocessOutcome) => void
+  topLevelExited = false
+  private cleanup: Promise<void> | undefined
+
+  constructor(
+    private readonly closeChannel: () => void,
+    private readonly sendChannel: (data: string) => void,
+    private readonly signalChannel: (name: string) => void,
+    private readonly graceMs: number,
+  ) {
+    this.done = new Promise<SubprocessOutcome>((resolve) => { this.exitResolve = resolve })
+  }
+
+  /** Settle the exit promise (called by the runtime when the channel closes). */
+  resolveExit(outcome: SubprocessOutcome): void {
+    this.exitResolve(outcome)
+  }
+
+  /** @inheritdoc */
+  write(data: string): Promise<void> {
+    if (this.topLevelExited) return Promise.reject(new Error('terminal process has exited'))
+    return new Promise<void>((resolve, reject) => {
+      try {
+        this.sendChannel(data)
+        resolve()
+      } catch (error) {
+        reject(error instanceof Error ? error : new Error(String(error)))
+      }
+    })
+  }
+
+  /** The SSH channel does not expose a foreground process group. */
+  inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+    return Promise.resolve(undefined)
+  }
+
+  /** @inheritdoc */
+  signalForeground(_signal: SubprocessTerminalSignal): Promise<number> {
+    return Promise.reject(new Error('subprocess-ssh: cannot resolve the foreground process group over an SSH channel'))
+  }
+
+  /** @inheritdoc */
+  terminate(): Promise<void> {
+    if (this.cleanup !== undefined) return this.cleanup
+    const cleanup = this.closeOnce()
+    this.cleanup = cleanup
+    void cleanup.catch(() => { this.cleanup = undefined })
+    return cleanup
+  }
+
+  private signal(name: string): void {
+    try {
+      this.signalChannel(name)
+    } catch {
+      // The channel closed before the signal could be delivered.
+    }
+  }
+
+  private async closeOnce(): Promise<void> {
+    this.signal('TERM')
+    await Promise.race([this.done.then(() => undefined, () => undefined), delay(this.graceMs)])
+    if (!this.topLevelExited) this.signal('KILL')
+    await Promise.race([this.done.then(() => undefined, () => undefined), delay(this.graceMs)])
+    if (!this.topLevelExited) {
+      this.closeChannel()
+      throw new Error('subprocess-ssh: terminal cleanup failed; channel still open')
+    }
+  }
+}
+
+/**
+ * Allocate an SSH PTY, replace its login shell with the requested argv, and
+ * return the live terminal handle.
+ */
+export async function spawnSshTerminal(
+  engine: SshEngine,
+  getState: () => WorkspaceState,
+  spec: SubprocessTerminalSpawnSpec,
+): Promise<SshTerminalHandle> {
+  spec.signal?.throwIfAborted()
+  const program = spec.argv[0]
+  if (program === undefined || program.length === 0) {
+    throw new Error('subprocess-ssh: terminal argv must contain a program')
+  }
+  const state = getState()
+  if (state.mode !== 'remote' || state.alias === undefined) {
+    throw new Error('subprocess-ssh: not in remote mode — switch the GUI to SSH mode first')
+  }
+  const environment = serializeEnvironment(await readScrubbedRemoteEnvironment(engine, state.alias), spec.env)
+  const session = await engine.openShell(state.alias, { cols: spec.cols, rows: spec.rows })
+  const root = state.remoteRoot
+  if (root === undefined) throw new Error('subprocess-ssh: remote workspace root is not set')
+  const cwd = spec.cwd !== undefined && spec.cwd.startsWith('/') ? spec.cwd : root
+  const handle = new SshTerminalHandle(
+    () => session.close(),
+    (data) => session.send(data),
+    (name) => session.signal(name),
+    spec.graceMs,
+  )
+  session.onData = (data: Buffer) => {
+    if (!handle.output.destroyed) handle.output.write(data)
+  }
+  session.onExit = (code: number | null, error?: string) => {
+    handle.topLevelExited = true
+    handle.output.end()
+    handle.resolveExit({ exitCode: error !== undefined ? null : code, signal: null })
+  }
+  const argv = spec.argv.map(quoteShellArg).join(' ')
+  await handle.write(`cd ${quoteShellArg(cwd)} && exec env -i -- ${environment} ${argv}\r`)
+  spec.signal?.throwIfAborted()
+  return handle
+}