dsh-remote-workspaces 0.2.0 → 0.3.0

package/src/shell-sessions.js

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto'
+
+/**
+ * In-process registry of interactive UI shell sessions (local + remote).
+ *
+ * Every `openLocal` allocates an INDEPENDENT PTY process through the harness's
+ * `ctx.subprocess.spawnTerminal` seam; every `openRemote` opens an INDEPENDENT
+ * ssh2 shell channel through `SshClient.openShell`. Sessions never share a
+ * process/connection, cwd, stdin/stdout, or buffer (the §3.1 isolation model).
+ * Lifecycle is process-local (matches ctx.terminals semantics): no persistence,
+ * no cross-process recovery.
+ *
+ * A session keeps TWO buffers over the same stream:
+ *   - `unread` — drained by `read` (incremental polling);
+ *   - `history` — the full (capped) output, returned on ATTACH so a re-mounted
+ *     tab replays its scrollback instead of coming back blank.
+ *
+ * Attach: an `open*` carrying a stable `key` REUSES a still-live session under
+ * that key instead of spawning a new one — this is what keeps a Shell tab's
+ * terminal alive across the client unmounting it on a DSH-session switch.
+ */
+
+const MAX_UNREAD = 256 * 1024
+const MAX_HISTORY = 512 * 1024
+
+export function createShellSessions({ getSubprocess, openRemote: openRemoteChannel, sweepMs = 10 * 60 * 1000 }) {
+  const sessions = new Map()
+
+  // Reap sessions no client has read from or written to within `sweepMs`: a
+  // shell whose tab was lost to a refresh (or an archived session) has nobody
+  // left to close it. An on-screen tab polls continuously, so only abandoned
+  // shells — or ones hidden longer than the threshold — are collected.
+  function sweep(now = Date.now()) {
+    for (const [id, session] of [...sessions]) {
+      if (!session.ended && now - session.lastActivityAt > sweepMs) {
+        sessions.delete(id)
+        void session.handle.terminate()
+      }
+    }
+  }
+  const sweepTimer = setInterval(sweep, 60 * 1000)
+  if (typeof sweepTimer.unref === 'function') sweepTimer.unref()
+
+  function liveSession(key) {
+    if (typeof key !== 'string' || key === '') return undefined
+    const existing = sessions.get(key)
+    return existing !== undefined && !existing.ended ? existing : undefined
+  }
+
+  function pushCapped(bag, cap, buf) {
+    bag.chunks.push(buf)
+    bag.bytes += buf.length
+    while (bag.bytes > cap && bag.chunks.length > 1) {
+      bag.bytes -= bag.chunks.shift().length
+    }
+  }
+
+  function register(handle, meta, key) {
+    const id = typeof key === 'string' && key !== '' ? key : randomUUID()
+    const session = {
+      id,
+      handle,
+      meta,
+      unread: { chunks: [], bytes: 0 },
+      history: { chunks: [], bytes: 0 },
+      ended: false,
+      lastActivityAt: Date.now(),
+    }
+    handle.output.on('data', (chunk) => {
+      const buf = Buffer.from(chunk)
+      pushCapped(session.unread, MAX_UNREAD, buf)
+      pushCapped(session.history, MAX_HISTORY, buf)
+    })
+    handle.output.on('end', () => { session.ended = true })
+    handle.output.on('close', () => { session.ended = true })
+    sessions.set(id, session)
+    return session
+  }
+
+  function historyText(session) {
+    return Buffer.concat(session.history.chunks).toString('utf8')
+  }
+
+  async function openLocal(opts = {}) {
+    const key = typeof opts.key === 'string' && opts.key !== '' ? opts.key : undefined
+    const existing = liveSession(key)
+    if (existing !== undefined) {
+      const history = historyText(existing)
+      // The attach hands the client the full scrollback, so the unread tail is
+      // now covered — start incremental reads fresh to avoid double replay.
+      existing.unread.chunks.length = 0
+      existing.unread.bytes = 0
+      return { id: existing.id, pid: existing.handle.pid, kind: 'local', attached: true, history }
+    }
+    const subprocess = getSubprocess()
+    if (subprocess === undefined || typeof subprocess.spawnTerminal !== 'function') {
+      throw new Error('subprocess service unavailable (no spawnTerminal)')
+    }
+    const win = process.platform === 'win32'
+    const argv = win ? ['powershell.exe', '-NoLogo'] : ['bash', '-i']
+    const cwd = typeof opts.cwd === 'string' && opts.cwd !== '' ? opts.cwd : process.cwd()
+    const rows = Number.isInteger(opts.rows) && opts.rows > 0 ? opts.rows : 24
+    const cols = Number.isInteger(opts.cols) && opts.cols > 0 ? opts.cols : 80
+    const handle = await subprocess.spawnTerminal({ argv, cwd, rows, cols, graceMs: 3000 })
+    const session = register(handle, { kind: 'local', label: win ? 'PowerShell' : 'bash' }, key)
+    return { id: session.id, pid: handle.pid, kind: 'local', attached: false }
+  }
+
+  async function openRemote(machine, opts = {}) {
+    const key = typeof opts.key === 'string' && opts.key !== '' ? opts.key : undefined
+    const existing = liveSession(key)
+    if (existing !== undefined) {
+      const history = historyText(existing)
+      existing.unread.chunks.length = 0
+      existing.unread.bytes = 0
+      return { id: existing.id, pid: null, kind: 'remote', attached: true, history }
+    }
+    if (typeof openRemoteChannel !== 'function') throw new Error('remote shell unavailable (no openShell)')
+    const rows = Number.isInteger(opts.rows) && opts.rows > 0 ? opts.rows : 24
+    const cols = Number.isInteger(opts.cols) && opts.cols > 0 ? opts.cols : 80
+    const cwd = typeof opts.cwd === 'string' && opts.cwd !== '' ? opts.cwd : undefined
+    const handle = await openRemoteChannel(machine ?? {}, { rows, cols, ...(cwd ? { cwd } : {}) })
+    const session = register(handle, {
+      kind: 'remote',
+      label: (machine && (machine.alias || machine.host)) || 'remote',
+    }, key)
+    return { id: session.id, pid: null, kind: 'remote', attached: false }
+  }
+
+  function requireSession(id) {
+    const session = sessions.get(id)
+    if (session === undefined) throw new Error(`shell session not found: ${id}`)
+    return session
+  }
+
+  async function write(id, data) {
+    const session = requireSession(id)
+    session.lastActivityAt = Date.now()
+    if (!session.ended && typeof data === 'string' && data !== '') await session.handle.write(data)
+  }
+
+  function read(id) {
+    const session = requireSession(id)
+    session.lastActivityAt = Date.now()
+    const text = Buffer.concat(session.unread.chunks).toString('utf8')
+    session.unread.chunks.length = 0
+    session.unread.bytes = 0
+    return { text, eof: session.ended }
+  }
+
+  async function resize(id, rows, cols) {
+    const session = requireSession(id)
+    if (session.ended) return { resized: false }
+    if (typeof session.handle.resize === 'function') {
+      session.handle.resize(rows, cols)
+      return { resized: true }
+    }
+    return { resized: false }
+  }
+
+  async function close(id) {
+    const session = sessions.get(id)
+    if (session === undefined) return { closed: false }
+    sessions.delete(id)
+    await session.handle.terminate()
+    return { closed: true }
+  }
+
+  function list() {
+    return [...sessions.values()].map((session) => ({
+      id: session.id,
+      pid: session.handle.pid ?? null,
+      kind: session.meta.kind,
+      label: session.meta.label,
+      ended: session.ended,
+    }))
+  }
+
+  return { openLocal, openRemote, write, read, resize, close, list, sweep }
+}

package/src/transport.js

@@ -29,6 +29,22 @@ export function psQuote(value) {
   return `'${String(value).replace(/'/g, "''")}'`
 }
 
+/**
+ * First-input `cd` command that lands an interactive shell channel in `cwd`,
+ * dialect-aware: POSIX single-quotes, PowerShell (cd = Set-Location) single-
+ * quotes a forward-slash win path, and cmd.exe — where single quotes are
+ * literal — uses double quotes + backslashes with `/d` to switch drive too.
+ */
+export function shellCdCommand(profile, cwd) {
+  const p = profile ?? { family: 'unknown' }
+  if (p.family === 'windows') {
+    const winPath = toWinPath(cwd)
+    if (p.shell === 'cmd') return `cd /d "${winPath.replace(/\//g, '\\')}"\r`
+    return `cd ${psQuote(winPath)}\r`
+  }
+  return `cd ${shellQuote(cwd)}\r`
+}
+
 /**
  * Strip PowerShell progress records from a stderr capture. When a nested
  * powershell is launched by a Windows OpenSSH exec channel (e.g. the cmd
@@ -113,9 +129,15 @@ export function profileCacheKey({ host, user, port }) {
 
 /**
  * Detect a target's OS family and default exec shell without parsing
- * localized output: `uname -s` proves a POSIX shell; `cmd /c ver` proves
- * Windows (it runs from cmd, PowerShell and Git Bash defaults alike); a
+ * localized output: `uname -s` proves a POSIX shell; the bare `ver` builtin
+ * proves a cmd-default Windows host; a quoted nested `cmd /c "ver"` proves
+ * Windows under a PowerShell default (PowerShell itself has no `ver`); a
  * `$PSVersionTable` expression then tells cmd from PowerShell as the default.
+ *
+ * Quoting matters on real cmd-default Windows hosts: OpenSSH wraps the exec
+ * payload for cmd.exe in a way that mangles inner unquoted spaces — `cmd /c
+ * ver` arrives as `ver"` and fails, while a bare single token (`ver`) and a
+ * quoted inner command (`cmd /c "ver"`) both pass (verified on a real host).
  */
 export async function probeRemoteProfile(client) {
   const uname = await client.run('uname -s')
@@ -123,16 +145,30 @@ export async function probeRemoteProfile(client) {
     const os = (uname.stdout ?? '').trim().toLowerCase()
     return { family: 'posix', os: os.startsWith('darwin') ? 'darwin' : 'linux', shell: 'posix' }
   }
-  const ver = await client.run('cmd /c ver')
-  if (ver.ok && /windows/i.test(ver.stdout ?? '')) {
+  const ver = await client.run('ver')
+  if (ver.ok) return { family: 'windows', os: 'windows', shell: 'cmd' }
+  const nested = await client.run('cmd /c "ver"')
+  if (nested.ok && /windows/i.test(nested.stdout ?? '')) {
     const ps = await client.run('$PSVersionTable.PSVersion.ToString()')
     return ps.ok
       ? { family: 'windows', os: 'windows', shell: 'powershell' }
       : { family: 'windows', os: 'windows', shell: 'cmd' }
   }
+  const ps = await client.run('$PSVersionTable.PSVersion.ToString()')
+  if (ps.ok) return { family: 'windows', os: 'windows', shell: 'powershell' }
   return { family: 'unknown', os: 'unknown', shell: 'unknown' }
 }
 
+/**
+ * Error text used whenever a command cannot run because the remote profile
+ * probe failed (family 'unknown'). Explicit instead of guessing a dialect:
+ * sending a POSIX `cd 'x' || exit 1` script to a Windows/cmd host produces the
+ * misleading "文件名、目录名或卷标语法不正确" (Win32 123) failure, and the
+ * other way around is equally wrong — so callers refuse loudly.
+ */
+export const PROBE_UNKNOWN_MSG =
+  'cannot determine the remote shell type (exec probe failed); command not executed. Check the host side: the account home/profile directory must exist, the OpenSSH DefaultShell must be valid, and the exec channel itself must be usable.'
+
 /** Encode a PowerShell script for quote-safe transport through cmd.exe.
  *
  * `powershell -EncodedCommand` would be ideal (no quoting at all), but a
@@ -162,7 +198,15 @@ export function psCommandEnvelope(script) {
  * text (no CLIXML records).
  */
 export function buildExecScript(profile, command, cwd) {
-  if (profile === undefined || profile.family !== 'windows') {
+  if (profile === undefined) {
+    return cwd ? `cd ${shellQuote(cwd)} || exit 1\n${command}` : command
+  }
+  if (profile.family === 'unknown') {
+    // Never guess: a POSIX script against a Windows/cmd host dies on the first
+    // line with Win32 123-style errors and never reaches the command.
+    throw new Error(PROBE_UNKNOWN_MSG)
+  }
+  if (profile.family !== 'windows') {
     return cwd ? `cd ${shellQuote(cwd)} || exit 1\n${command}` : command
   }
   const script = [
@@ -362,6 +406,9 @@ export class SshClient {
    */
   async execShell(command, { cwd, timeoutMs = 60000, stdoutMaxBytes = 64000, stderrMaxBytes = 64000, stdin, signal } = {}) {
     const profile = await this.profile()
+    if (profile.family === 'unknown') {
+      return { ok: false, error: PROBE_UNKNOWN_MSG }
+    }
     const script = buildExecScript(profile, command, cwd)
     return await new Promise((resolve) => {
       const conn = new Client()
@@ -466,6 +513,63 @@ export class SshClient {
     })
   }
 
+  /**
+   * Open an INTERACTIVE shell channel with a PTY — the remote half of the UI
+   * Shell tool. ssh2 `conn.shell` + a pty is the same mechanism on POSIX and
+   * Windows OpenSSH (ConPTY) remotes; the target's DefaultShell decides whether
+   * the session is a login shell, cmd, or PowerShell, and its OS decides the
+   * line endings. The channel merges stderr into stdout (one data stream) and
+   * the bytes are passed through RAW — a PTY already emits terminal-ready CRLF
+   * that xterm renders directly, so the exec-channel CRLF folding must NOT be
+   * applied here.
+   *
+   * When `cwd` is given, the shell is chdir'd there as its first input (a
+   * dialect-aware `cd`, probed once per target). The shell still starts at the
+   * remote account's home; the `cd` is emitted into the PTY so the prompt and
+   * every later command land in the requested directory.
+   *
+   * Resolves a handle compatible with the local PTY one:
+   *   { output, write, terminate, resize, pid } where `output` is the ssh2
+   *   stream (an EventEmitter emitting 'data' and 'close'), `resize` maps to
+   *   `setWindow` (REACHABLE here, unlike the local seam — the S0 finding), and
+   *   `terminate` closes the channel then ends the connection.
+   */
+  openShell({ rows = 24, cols = 80, term = 'xterm-256color', env, cwd } = {}) {
+    const chdirPromise = cwd !== undefined && cwd !== null && cwd !== ''
+      ? this.profile().then((profile) => shellCdCommand(profile, cwd)).catch(() => '')
+      : Promise.resolve('')
+    return chdirPromise.then((chdir) => new Promise((resolve, reject) => {
+      const conn = new Client()
+      let settled = false
+      const fail = (error) => {
+        if (settled) return
+        settled = true
+        try { conn.end() } catch {}
+        reject(error instanceof Error ? error : new Error(String(error)))
+      }
+      const timer = setTimeout(() => fail(new Error('SSH shell 连接超时')), this.readyTimeoutMs)
+      conn.on('ready', () => {
+        conn.shell({ term, rows, cols, ...(env ? { env } : {}) }, (err, stream) => {
+          if (err) { clearTimeout(timer); fail(err); return }
+          clearTimeout(timer)
+          settled = true
+          let closed = false
+          stream.on('close', () => { closed = true })
+          if (chdir !== '') stream.write(chdir)
+          resolve({
+            output: stream,
+            pid: null,
+            write(data) { if (!closed) { try { stream.write(data) } catch {} } },
+            terminate() { try { stream.close() } catch {} try { conn.end() } catch {} },
+            resize(r, c) { if (!closed) { try { stream.setWindow(r, c) } catch {} } },
+          })
+        })
+      })
+      conn.on('error', (connError) => { clearTimeout(timer); fail(connError) })
+      try { conn.connect(this.connectConfig()) } catch (connectError) { clearTimeout(timer); fail(connectError) }
+    }))
+  }
+
   /**
    * Open a LONG-LIVED exec channel for streaming (used by background/start
    * jobs on Windows remotes, where no nohup-style detach exists and closing
@@ -480,6 +584,15 @@ export class SshClient {
    */
   async execStream(command, { cwd, signal, stdoutMaxBytes = 16 * 1024 * 1024, stderrMaxBytes = 16 * 1024 * 1024 } = {}) {
     const profile = await this.profile()
+    if (profile.family === 'unknown') {
+      // Same explicit refusal as execShell: no dialect to build the script in.
+      return {
+        readOut: () => ({ delta: '', lossy: false }),
+        readErr: () => ({ delta: '', lossy: false }),
+        exit: Promise.resolve({ error: PROBE_UNKNOWN_MSG }),
+        terminate() {},
+      }
+    }
     const windows = profile.family === 'windows'
     const ssh = this
     // The marker runs FIRST inside the same remote shell that owns the exec
@@ -604,14 +717,18 @@ export class SshClient {
 
   /**
    * Cached remote execution profile ({ family, os, shell }); probed once per
-   * target and reused for the process lifetime.
+   * target and reused for the process lifetime. FAILED probes (family
+   * 'unknown') are never cached, so the next call re-probes: a transient
+   * failure or a host-side fix is picked up without restarting the process.
    */
   async profile() {
     const key = profileCacheKey(this)
     let profile = REMOTE_PROFILE_CACHE.get(key)
     if (profile === undefined) {
       profile = await probeRemoteProfile(this)
-      REMOTE_PROFILE_CACHE.set(key, profile)
+      if (profile.family === 'posix' || profile.family === 'windows') {
+        REMOTE_PROFILE_CACHE.set(key, profile)
+      }
     }
     return profile
   }