dsh-ssh-workbench 0.0.0-stage → 1.7.0

package/lib/core/store.js

@@ -0,0 +1,83 @@
+/**
+ * Server inventory: JSON document under the harness home.
+ * Pure data logic; no DSH imports so it stays unit testable without the host
+ * runtime.
+ */
+import { randomUUID } from 'node:crypto'
+import { serversPath, writePrivateFile, readTextFile } from './paths.js'
+
+const PLATFORMS = new Set(['posix', 'windows'])
+
+function defaultShellFor(platform) {
+  return platform === 'windows' ? 'powershell' : 'bash'
+}
+
+function asString(value, fallback = '') {
+  return typeof value === 'string' ? value.trim() : fallback
+}
+
+function asStringArray(value) {
+  if (!Array.isArray(value)) return []
+  return value.map((item) => asString(item)).filter(Boolean)
+}
+
+/**
+ * Validate and canonicalise one stored server record. Throws on records the
+ * plugin could never execute, so a corrupt inventory fails loud at the
+ * boundary instead of deep inside an SSH call.
+ */
+export function normalizeServer(raw, { idFactory = () => `srv_${randomUUID()}` } = {}) {
+  if (!raw || typeof raw !== 'object') throw new Error('server record must be an object')
+  const name = asString(raw.name)
+  const host = asString(raw.host)
+  if (!name) throw new Error('server.name is required')
+  if (!host) throw new Error(`server "${name}" needs a host`)
+  const port = Number.isInteger(raw.port) && raw.port > 0 && raw.port < 65536 ? raw.port : 22
+  const username = asString(raw.username, 'root') || 'root'
+  const platform = PLATFORMS.has(raw.platform) ? raw.platform : 'posix'
+  const authRef = normalizeAuthRef(raw.authRef, name)
+  return {
+    id: asString(raw.id, idFactory()) || idFactory(),
+    name,
+    host,
+    port,
+    username,
+    platform,
+    defaultShell: asString(raw.defaultShell, defaultShellFor(platform)) || defaultShellFor(platform),
+    tags: asStringArray(raw.tags),
+    description: asString(raw.description),
+    enabled: raw.enabled !== false,
+    facts: raw.facts && typeof raw.facts === 'object' ? { ...raw.facts } : {},
+    authRef,
+  }
+}
+
+function normalizeAuthRef(raw, serverName) {
+  if (!raw || typeof raw !== 'object') throw new Error(`server "${serverName}" needs authRef`)
+  if (raw.type === 'sshKey') {
+    const keyPath = asString(raw.path)
+    if (!keyPath) throw new Error(`server "${serverName}" sshKey authRef needs a path`)
+    return { type: 'sshKey', path: keyPath }
+  }
+  if (raw.type === 'password') return { type: 'password' }
+  throw new Error(`server "${serverName}" has unsupported authRef type`)
+}
+
+export function loadServers(file = serversPath()) {
+  const text = readTextFile(file)
+  if (!text.trim()) return []
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    throw new Error(`servers.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if (!Array.isArray(parsed)) throw new Error('servers.json must be an array')
+  return parsed.map((record) => normalizeServer(record))
+}
+
+export function saveServers(servers, file = serversPath()) {
+  const normalized = servers.map((record) => normalizeServer(record))
+  writePrivateFile(file, `${JSON.stringify(normalized, null, 2)}\n`)
+  return normalized
+}

package/lib/core/terminals.js

@@ -0,0 +1,299 @@
+/**
+ * Interactive terminal sessions for the workbench.
+ *
+ * Remote sessions run on the existing ssh2 broker shell channel; local ones use
+ * the Host subprocess service's PTY (`spawnTerminal`). The browser renders them
+ * with xterm and polls `read`, so the transport needs no new socket protocol
+ * and stays on the plugin's authenticated routes.
+ *
+ * Sessions are process-local, buffered (bounded) and reclaimed after a period
+ * of inactivity or when their server/plugin goes away. Closing a session ends
+ * the remote channel or the local PTY; nothing survives a Host restart.
+ */
+import { randomUUID } from 'node:crypto'
+import { StringDecoder } from 'node:string_decoder'
+
+const MAX_BUFFER_CHARS = 512 * 1024
+const MAX_SESSIONS = 12
+const MAX_WAIT_MS = 20000
+const DEFAULT_IDLE_MS = 30 * 60 * 1000
+
+function clampDimension(value, fallback, max) {
+  const number = Number(value)
+  if (!Number.isFinite(number) || number < 1) return fallback
+  return Math.min(Math.max(Math.floor(number), 1), max)
+}
+
+function describe(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export function createTerminalHub({ runtime, getSubprocess, getLocalCwd, log = () => {} } = {}) {
+  /** @type {Map<string, object>} */
+  const sessions = new Map()
+  // Slots reserved by opens that are still waiting for their transport. The
+  // cap must be checked atomically: `open()` awaits the transport, so counting
+  // only inserted sessions lets concurrent calls all pass the same check.
+  let pendingOpens = 0
+  let disposed = false
+
+  function notify(session) {
+    for (const wake of [...session.waiters]) {
+      session.waiters.delete(wake)
+      try { wake() } catch { /* a waiter must never break the session */ }
+    }
+  }
+
+  function append(session, text) {
+    if (!text) return
+    session.text += text
+    if (session.text.length > MAX_BUFFER_CHARS) {
+      let drop = session.text.length - MAX_BUFFER_CHARS
+      // Never cut a UTF-16 surrogate pair in half: a slice starting on the low
+      // half would leave an orphan surrogate that the client renders as U+FFFD.
+      const first = session.text.charCodeAt(drop)
+      if (first >= 0xdc00 && first <= 0xdfff) drop += 1
+      session.text = session.text.slice(drop)
+      session.base += drop
+    }
+    notify(session)
+  }
+
+  function finish(session, exitCode, signal) {
+    if (session.exited) return
+    append(session, session.decoder.end())
+    session.exited = true
+    session.exitCode = Number.isInteger(exitCode) ? exitCode : null
+    session.signal = typeof signal === 'string' ? signal : null
+    notify(session)
+  }
+
+  function snapshot(session, cursor) {
+    let offset = Number.isInteger(cursor) && cursor >= 0 ? cursor : 0
+    let reset = false
+    if (offset < session.base) {
+      reset = true
+      offset = session.base
+    }
+    return {
+      session: session.id,
+      cursor: session.base + session.text.length,
+      data: session.text.slice(offset - session.base),
+      reset,
+      exited: session.exited,
+      exitCode: session.exitCode,
+      signal: session.signal,
+      title: session.title,
+      kind: session.kind,
+    }
+  }
+
+  function publicSession(session) {
+    return {
+      session: session.id,
+      kind: session.kind,
+      title: session.title,
+      server: session.server?.name ?? null,
+      cols: session.cols,
+      rows: session.rows,
+      cwd: session.cwd,
+    }
+  }
+
+  function closeSession(session, reason) {
+    if (!session || session.closed) return
+    session.closed = true
+    sessions.delete(session.id)
+    // Mark the session exited *before* waking readers so a suspended
+    // `/terminal/read` long-poll returns `exited:true` immediately instead of
+    // holding the request until its wait timeout (or reporting the stale
+    // "not found" of a removed session).
+    session.exited = true
+    session.exitCode = null
+    session.signal = null
+    notify(session)
+    session.waiters.clear()
+    const handle = session.handle
+    session.handle = null
+    if (handle) {
+      try {
+        if (typeof handle.close === 'function') handle.close()
+        else if (typeof handle.terminate === 'function') handle.terminate()
+      } catch (error) {
+        log(`terminal close failed (${reason ?? 'close'})`, { error: describe(error) })
+      }
+    }
+  }
+
+  async function open({ kind, server, cols, rows, cwd } = {}) {
+    if (disposed) throw new Error('terminal hub is disposed')
+    // Reserve the slot synchronously, before the first await, so two concurrent
+    // opens cannot both pass the cap check and overshoot MAX_SESSIONS.
+    if (sessions.size + pendingOpens >= MAX_SESSIONS) {
+      throw new Error(`too many terminals (${MAX_SESSIONS}); close one first`)
+    }
+    pendingOpens += 1
+    const session = {
+      id: `term_${randomUUID()}`,
+      kind: kind === 'remote' ? 'remote' : 'local',
+      title: kind === 'remote' ? (server?.name ?? 'remote') : 'local',
+      server: server ?? null,
+      cwd: typeof cwd === 'string' ? cwd : undefined,
+      cols: clampDimension(cols, 80, 500),
+      rows: clampDimension(rows, 24, 300),
+      text: '',
+      base: 0,
+      waiters: new Set(),
+      exited: false,
+      exitCode: null,
+      signal: null,
+      closed: false,
+      decoder: new StringDecoder('utf8'),
+      handle: null,
+      lastUsed: Date.now(),
+    }
+    try {
+      if (session.kind === 'remote') {
+        if (!server) throw new Error('remote terminal needs a managed resource')
+        const handle = await runtime.shell(server, { cols: session.cols, rows: session.rows })
+        session.handle = handle
+        session.title = server.name
+        handle.onData((data) => {
+          const buffer = Buffer.isBuffer(data) ? data : Buffer.from(String(data))
+          append(session, session.decoder.write(buffer))
+        })
+        handle.onClose(() => finish(session, null, null))
+        handle.onError((error) => {
+          append(session, `\r\n[remote shell error: ${describe(error)}]\r\n`)
+          finish(session, null, null)
+        })
+      } else {
+        const subprocess = getSubprocess?.()
+        if (!subprocess || typeof subprocess.spawnTerminal !== 'function') {
+          throw new Error('local terminals are unavailable on this host')
+        }
+        const environment = await subprocess.terminalEnvironment?.()
+        // The Host PTY provider names its platform (`windows` on win32) and the
+        // preferred shell (ComSpec on Windows, $SHELL/login shell on POSIX).
+        // `-i` is a POSIX login-shell flag: cmd.exe/pwsh reject it, so only
+        // POSIX shells get it.
+        const localPlatform = environment?.platform === 'windows' || (environment?.platform === undefined && process.platform === 'win32')
+          ? 'windows'
+          : 'posix'
+        const shell = environment?.defaultShell || (localPlatform === 'windows' ? (process.env.ComSpec || 'cmd.exe') : '/bin/sh')
+        const argv = localPlatform === 'windows' ? [shell] : [shell, '-i']
+        const handle = await subprocess.spawnTerminal({
+          argv,
+          cwd: typeof cwd === 'string' && cwd ? cwd : getLocalCwd?.(),
+          cols: session.cols,
+          rows: session.rows,
+          terminalType: 'xterm-256color',
+          graceMs: 1000,
+        })
+        session.handle = {
+          write: (data) => handle.write(data),
+          resize: (nextCols, nextRows) => handle.resize(nextCols, nextRows),
+          close: () => handle.terminate(),
+        }
+        handle.output.on('data', (data) => {
+          const buffer = Buffer.isBuffer(data) ? data : Buffer.from(String(data))
+          append(session, session.decoder.write(buffer))
+        })
+        handle.done.then(
+          (outcome) => finish(session, outcome?.exitCode, outcome?.signal),
+          (error) => {
+            append(session, `\r\n[local terminal error: ${describe(error)}]\r\n`)
+            finish(session, null, null)
+          },
+        )
+      }
+      // The hub may have been disposed while the transport was connecting: do
+      // not leak a session (or a PTY) into a torn-down hub.
+      if (disposed) throw new Error('terminal hub is disposed')
+    } catch (error) {
+      closeSession(session, 'open failed')
+      throw error
+    } finally {
+      pendingOpens -= 1
+    }
+    sessions.set(session.id, session)
+    session.lastUsed = Date.now()
+    return publicSession(session)
+  }
+
+  function input(id, data) {
+    const session = sessions.get(id)
+    if (!session || session.exited || !session.handle) return false
+    session.lastUsed = Date.now()
+    session.handle.write(String(data ?? ''))
+    return true
+  }
+
+  function resize(id, cols, rows) {
+    const session = sessions.get(id)
+    if (!session || session.exited || !session.handle) return false
+    session.lastUsed = Date.now()
+    session.cols = clampDimension(cols, session.cols, 500)
+    session.rows = clampDimension(rows, session.rows, 300)
+    try {
+      session.handle.resize(session.cols, session.rows)
+    } catch (error) {
+      log('terminal resize failed', { error: describe(error) })
+    }
+    return true
+  }
+
+  async function read(id, { cursor = 0, waitMs = 0 } = {}) {
+    const session = sessions.get(id)
+    if (!session) throw new Error('terminal session not found')
+    session.lastUsed = Date.now()
+    const initial = snapshot(session, cursor)
+    const wait = Math.min(Math.max(Number(waitMs) || 0, 0), MAX_WAIT_MS)
+    if (initial.data || initial.exited || wait === 0) return initial
+    await new Promise((resolve) => {
+      const wake = () => {
+        clearTimeout(timer)
+        session.waiters.delete(wake)
+        resolve()
+      }
+      const timer = setTimeout(wake, wait)
+      timer.unref?.()
+      session.waiters.add(wake)
+    })
+    return snapshot(session, cursor)
+  }
+
+  function close(id) {
+    const session = sessions.get(id)
+    if (!session) return false
+    closeSession(session, 'requested')
+    return true
+  }
+
+  function closeForServer(serverId) {
+    let closed = 0
+    for (const session of [...sessions.values()]) {
+      if (session.server?.id !== serverId) continue
+      closeSession(session, 'server changed')
+      closed += 1
+    }
+    return closed
+  }
+
+  function dispose() {
+    disposed = true
+    for (const session of [...sessions.values()]) closeSession(session, 'plugin unloaded')
+    if (cleanup) clearInterval(cleanup)
+  }
+
+  const cleanup = setInterval(() => {
+    const cutoff = Date.now() - DEFAULT_IDLE_MS
+    for (const session of [...sessions.values()]) {
+      if (session.waiters.size > 0) continue
+      if (session.lastUsed < cutoff) closeSession(session, 'idle')
+    }
+  }, 60 * 1000)
+  cleanup.unref?.()
+
+  return { open, read, input, resize, close, closeForServer, dispose, count: () => sessions.size }
+}

package/lib/core/win32-adapter.js

@@ -0,0 +1,141 @@
+/**
+ * Windows (PowerShell) shell adapter.
+ *
+ * Windows targets expose an SSH server (Microsoft OpenSSH Server) whose login
+ * shell is either `cmd.exe` or PowerShell. A command is therefore not sent as
+ * a raw string: it is wrapped into a small PowerShell script, encoded as
+ * UTF-16LE base64 and executed with `-EncodedCommand`, which removes every
+ * quoting/escaping failure mode and works no matter which default shell sshd
+ * picked.
+ *
+ * The wrapper also forces UTF-8 console output (Windows defaults to an OEM
+ * code page or UTF-16, which would arrive at ssh2 as mojibake) and propagates
+ * the real exit code (`-EncodedCommand` alone exits 0 for a failed cmdlet).
+ */
+import { BG_ERR_MARKER, BG_LOG_MARKER, BG_PID_MARKER } from './background.js'
+import { normalizeDialect } from './dialect.js'
+import { resolveTimeoutMs } from './posix-shell.js'
+
+const POWERSHELL_UTF8 = [
+  "$ErrorActionPreference = 'Continue'",
+  '$__sdhUtf8 = New-Object System.Text.UTF8Encoding $false',
+  '[Console]::OutputEncoding = $__sdhUtf8',
+  '$OutputEncoding = $__sdhUtf8',
+].join('; ')
+
+/**
+ * Deterministic exit status for a PowerShell script:
+ * - a failed statement without a native exit code → 1;
+ * - a failed/native command with an exit code → that code;
+ * - everything else → 0.
+ */
+const EXIT_SUFFIX = [
+  'if (-not $?) { if ($LASTEXITCODE -ne $null -and $LASTEXITCODE -ne 0) { exit [int]$LASTEXITCODE }; exit 1 }',
+  'if ($LASTEXITCODE -ne $null) { exit [int]$LASTEXITCODE }',
+  'exit 0',
+].join('; ')
+
+/** PowerShell single-quoted literal. */
+export function quotePowerShell(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}
+
+/**
+ * Classify one model-supplied workdir.
+ * @returns {{ kind: 'none'|'home'|'absolute'|'relative', path?: string, label: string } | { error: string }}
+ */
+export function normalizeWindowsWorkdir(workdir) {
+  const raw = typeof workdir === 'string' ? workdir.trim() : ''
+  if (!raw) return { kind: 'none', label: '~' }
+  if (raw.includes('\n') || raw.includes('\r')) return { error: 'workdir must not contain newlines' }
+  if (raw === '~') return { kind: 'home', label: '~' }
+  if (raw.startsWith('~/') || raw.startsWith('~\\')) {
+    const rest = raw.slice(2)
+    if (!rest) return { kind: 'home', label: '~' }
+    return { kind: 'relative', path: rest, label: `~/${rest.replace(/\\/g, '/')}` }
+  }
+  // Drive path, UNC path, or a root-relative POSIX-style path (Windows treats
+  // `/foo` as the current drive root).
+  if (/^[A-Za-z]:[\\/]/.test(raw) || raw.startsWith('\\\\') || raw.startsWith('/')) {
+    return { kind: 'absolute', path: raw, label: raw }
+  }
+  return { kind: 'relative', path: raw, label: `~/${raw.replace(/\\/g, '/')}` }
+}
+
+function locationScript(dir) {
+  if (dir.kind === 'none') return ''
+  const literal =
+    dir.kind === 'home'
+      ? '$HOME'
+      : dir.kind === 'relative'
+        ? `(Join-Path $HOME ${quotePowerShell(dir.path)})`
+        : quotePowerShell(dir.path)
+  return `try { Set-Location -LiteralPath ${literal} -ErrorAction Stop } catch { Write-Error ('cannot change directory: ' + $_.Exception.Message); exit 2 }`
+}
+
+/** The PowerShell executable to invoke on the target. */
+function powershellExe(server) {
+  const shell = String(server?.defaultShell ?? '')
+  return /pwsh/i.test(shell) ? 'pwsh.exe' : 'powershell.exe'
+}
+
+/** Wrap a PowerShell script into one SSH command line. */
+export function buildPowerShellInvocation(script, server) {
+  const encoded = Buffer.from(String(script), 'utf16le').toString('base64')
+  return `${powershellExe(server)} -NoProfile -NonInteractive -EncodedCommand ${encoded}`
+}
+
+export const win32Adapter = {
+  id: 'win32',
+  platform: 'windows',
+  toolName: 'remote_pwsh',
+  label: 'Windows/PowerShell',
+  // No POSIX `timeout` utility on Windows: the deadline is client-side only.
+  remoteTimeout: false,
+  supportsDialect: (dialect) => normalizeDialect(dialect) === 'windows',
+  unsupportedMessage: (server) =>
+    `target "${server?.name ?? 'unknown'}" is a POSIX server; remote_pwsh runs PowerShell on Windows targets — use remote_bash for POSIX targets`,
+  buildCommand(command, workdir, server) {
+    const dir = normalizeWindowsWorkdir(workdir)
+    if (dir.error !== undefined) return dir
+    const script = [POWERSHELL_UTF8, locationScript(dir), String(command ?? ''), EXIT_SUFFIX]
+      .filter((part) => typeof part === 'string' && part.length > 0)
+      .join('\n')
+    return { command: buildPowerShellInvocation(script, server), cwd: dir.label }
+  },
+  /**
+   * Start a detached PowerShell script and report its pid plus log files.
+   *
+   * The inner script (the same one a foreground call would run) is launched by
+   * `Start-Process`, which detaches it from the SSH channel; stdout/stderr are
+   * redirected into files the model can read with `Get-Content -Wait`.
+   */
+  buildBackgroundCommand(command, workdir, server) {
+    const dir = normalizeWindowsWorkdir(workdir)
+    if (dir.error !== undefined) return dir
+    const inner = [POWERSHELL_UTF8, locationScript(dir), String(command ?? ''), EXIT_SUFFIX]
+      .filter((part) => typeof part === 'string' && part.length > 0)
+      .join('\n')
+    const innerEncoded = Buffer.from(inner, 'utf16le').toString('base64')
+    const exe = quotePowerShell(powershellExe(server))
+    const outer = [
+      '$__sdhLog = Join-Path $env:TEMP ("dsh-ssh-workbench-bg-" + [Guid]::NewGuid().ToString("N") + ".log")',
+      '$__sdhErr = "$__sdhLog.err"',
+      `$__sdhExe = ${exe}`,
+      `$__sdhArgs = @('-NoProfile','-NonInteractive','-EncodedCommand','${innerEncoded}')`,
+      '$__sdhProc = Start-Process -FilePath $__sdhExe -ArgumentList $__sdhArgs -RedirectStandardOutput $__sdhLog -RedirectStandardError $__sdhErr -WindowStyle Hidden -PassThru',
+      `Write-Output "${BG_PID_MARKER}$($__sdhProc.Id)"`,
+      `Write-Output "${BG_LOG_MARKER}$__sdhLog"`,
+      `Write-Output "${BG_ERR_MARKER}$__sdhErr"`,
+    ].join('\n')
+    return { command: buildPowerShellInvocation(outer, server), cwd: dir.label }
+  },
+  // The scripts already carry their own exit code handling; there is no
+  // remote deadline utility to wrap around them.
+  wrapTimeout: (command) => String(command ?? ''),
+  resolveTimeoutMs,
+  timeoutNotice: () =>
+    '[remote] client-side timeout only: this Windows target has no POSIX `timeout` wrapper, so the PowerShell process may still be running.',
+  cancelNotice: () =>
+    '[remote] cancelled: the SSH channel was closed, but the PowerShell process may still be running.',
+}