dsh-winrm 0.1.0

package/src/engine/client.ts

@@ -0,0 +1,291 @@
+/**
+ * WinRM transport bridge.
+ *
+ * Runs each PowerShell payload over a native Node.js WinRM client
+ * (winrm-client) — no Python/pywinrm subprocess. The script rides the
+ * UTF-8 base64 envelope (marker + base64 of UTF-8 output) so Chinese and
+ * any codepage output survives the WinRM transport losslessly; the envelope
+ * is base64-encoded with `-EncodedCommand`, keeping the command line a
+ * single ASCII-safe line that WinRS/cmd.exe cannot mangle.
+ *
+ * Auth is chosen per attempt (HTTPS: Basic first, then NTLM; HTTP: NTLM
+ * first, then Basic) with fallback, so a host that only enables one scheme
+ * still connects. Credentials are passed to the library in-process — they
+ * never appear in a child-process argument list.
+ */
+
+import { Command, Shell } from 'winrm-client'
+import type { WinHostEntry } from '../protocol.ts'
+import { parseEnvelope, powershellCommandLine, psFileSize, psReadChunk, psWriteChunk, stripClixml, winrmPowerShellScript } from '../powershell.ts'
+
+/** Connection parameters for one target (transport-agnostic projection of a host entry). */
+export interface WinRMParams {
+  host: string
+  port: number
+  path: string
+  username: string
+  password: string
+  useHttps?: boolean
+  rejectUnauthorized?: boolean
+}
+
+/** winrm-client auth schemes (mirrors its `AuthMethod`). */
+type WinrmAuth = 'basic' | 'ntlm'
+
+/** Extra wall-clock budget so connection setup does not eat the command's timeout window. */
+const SETUP_GRACE_MS = 5_000
+
+/** Upper bound on the best-effort shell-delete round trip after a timed-out call. */
+const DELETE_TIMEOUT_MS = 10_000
+
+/** Sentinel: the command exceeded its deadline (distinct from auth/transport errors). */
+class WinrmTimedOut extends Error {
+  constructor() {
+    super('WinRM request timed out')
+    this.name = 'WinrmTimedOut'
+  }
+}
+
+/** Small cancellable delay used to bound the shell-delete cleanup. */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => { setTimeout(resolve, ms) })
+}
+
+/**
+ * Race a promise against a deadline; the loser's later settlement is
+ * ignored (Promise.race attaches a handler to both), so a hung WinRM call
+ * cannot surface as an unhandled rejection.
+ * @param promise - the operation to bound.
+ * @param ms - milliseconds before rejecting with {@link WinrmTimedOut}.
+ * @returns the operation result, or rejects with WinrmTimedOut on deadline.
+ */
+async function raceDeadline<T>(promise: Promise<T>, ms: number): Promise<T> {
+  let timer: NodeJS.Timeout | undefined
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => { reject(new WinrmTimedOut()) }, ms)
+  })
+  try {
+    return await Promise.race([promise, timeout])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
+/** Build winrm-client's base params for one auth scheme. */
+function baseParams(conn: WinRMParams, authMethod: WinrmAuth) {
+  return {
+    host: conn.host,
+    port: conn.port,
+    path: conn.path,
+    username: conn.username,
+    password: conn.password,
+    authMethod,
+    useHttps: conn.useHttps ?? false,
+    rejectUnauthorized: conn.rejectUnauthorized ?? true,
+  }
+}
+
+/**
+ * One shell lifecycle: create → run the encoded script → receive until the
+ * command completes → delete. Bounded by an overall deadline; on timeout the
+ * delete is fired without blocking the caller.
+ * @param conn - connection parameters.
+ * @param envelope - the wrapped UTF-8 envelope script (already prepared).
+ * @param timeoutMs - command execution budget measured from just after Execute.
+ * @param authMethod - the auth scheme for this attempt.
+ * @returns stdout/stderr captured from the WinRS streams.
+ * @throws WinrmTimedOut when the deadline passes; other errors are auth/transport failures.
+ */
+async function attemptOnce(
+  conn: WinRMParams,
+  envelope: string,
+  timeoutMs: number,
+  authMethod: WinrmAuth,
+): Promise<{ stdout: string; stderr: string }> {
+  const base = baseParams(conn, authMethod)
+  const hardDeadline = Date.now() + timeoutMs + SETUP_GRACE_MS
+  const state = { shellId: undefined as string | undefined, timedOut: false, settled: false }
+
+  const inner = (async (): Promise<{ stdout: string; stderr: string }> => {
+    const shellId = await Shell.doCreateShell(base)
+    state.shellId = shellId
+    // The deadline can fire while the shell is still being created, in which
+    // case this attempt has already settled and its `finally` ran without a
+    // shell id: abandon the request and remove the shell here so a slow
+    // handshake cannot leak it or run the command after the timeout.
+    if (state.settled) {
+      void Shell.doDeleteShell({ ...base, shellId }).catch(() => undefined)
+      throw new WinrmTimedOut()
+    }
+    const command = powershellCommandLine(envelope)
+    const commandId = await Command.doExecuteCommand({ ...base, shellId, command })
+    const receive = { ...base, shellId, commandId }
+    const commandDeadline = Date.now() + timeoutMs
+    let stdout = ''
+    let stderr = ''
+    for (;;) {
+      if (state.settled || Date.now() >= commandDeadline) throw new WinrmTimedOut()
+      const chunk = await Command.doReceiveOutputNonBlocking(receive)
+      stdout += chunk.output
+      stderr += chunk.stderr
+      if (chunk.isComplete) return { stdout, stderr }
+    }
+  })()
+
+  try {
+    return await raceDeadline(inner, hardDeadline - Date.now())
+  } catch (error) {
+    if (error instanceof WinrmTimedOut || Date.now() >= hardDeadline) {
+      state.timedOut = true
+      throw error instanceof WinrmTimedOut ? error : new WinrmTimedOut()
+    }
+    throw error
+  } finally {
+    state.settled = true
+    const shellId = state.shellId
+    if (shellId !== undefined) {
+      const deletion = Shell.doDeleteShell({ ...base, shellId }).catch(() => undefined)
+      if (state.timedOut) void deletion
+      else await Promise.race([deletion, sleep(DELETE_TIMEOUT_MS)])
+    }
+  }
+}
+
+/**
+ * Run one envelope over WinRM, trying each auth scheme in order until one
+ * succeeds. A timeout aborts immediately (retrying auth would waste the
+ * remaining budget on a reachable-but-slow host).
+ * @param conn - connection parameters.
+ * @param envelope - the wrapped UTF-8 envelope script.
+ * @param timeoutMs - command execution budget.
+ * @returns captured stdout/stderr.
+ * @throws WinrmTimedOut on deadline; the last auth/transport error when every scheme fails.
+ */
+async function runWinrm(
+  conn: WinRMParams,
+  envelope: string,
+  timeoutMs: number,
+): Promise<{ stdout: string; stderr: string }> {
+  const candidates: WinrmAuth[] = conn.useHttps ? ['basic', 'ntlm'] : ['ntlm', 'basic']
+  let lastError: unknown
+  for (const authMethod of candidates) {
+    try {
+      return await attemptOnce(conn, envelope, timeoutMs, authMethod)
+    } catch (error) {
+      if (error instanceof WinrmTimedOut) throw error
+      lastError = error
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error('all WinRM authentication methods failed')
+}
+
+export async function runScript(
+  conn: WinRMParams,
+  script: string,
+  options: { timeoutMs?: number; onChunk?: (chunk: { output: string; stderr: string }) => void } = {},
+): Promise<{ stdout: string; stderr: string; exitCode: number | null; timedOut: boolean; durationMs: number }> {
+  const started = Date.now()
+  const timeoutMs = options.timeoutMs ?? 60_000
+  const envelope = winrmPowerShellScript(script)
+
+  let outcome: { stdout: string; stderr: string }
+  try {
+    outcome = await runWinrm(conn, envelope, timeoutMs)
+  } catch (error) {
+    if (error instanceof WinrmTimedOut) {
+      return { stdout: '', stderr: '', exitCode: null, timedOut: true, durationMs: Date.now() - started }
+    }
+    throw error
+  }
+
+  const raw = outcome.stdout
+  const parsed = parseEnvelope(raw)
+  // The envelope is the wrapper's completion signal, and it always prints —
+  // even for output that is empty. Its absence therefore means the script
+  // never ran to completion (a parse error, or an aborted shell), which is a
+  // failure; the raw stream is still returned as evidence.
+  const exitCode = parsed !== null ? parsed.exitCode : 1
+  // A script that reached the envelope leaves only the host's CLIXML records
+  // on stderr; an aborted one keeps its stderr untouched for diagnosis.
+  const stderr = parsed !== null ? stripClixml(outcome.stderr) : outcome.stderr
+  options.onChunk?.({ output: raw, stderr })
+  return {
+    stdout: parsed !== null ? parsed.text : raw,
+    stderr,
+    exitCode,
+    timedOut: false,
+    durationMs: Date.now() - started,
+  }
+}
+
+export function connOf(entry: WinHostEntry): WinRMParams {
+  return {
+    host: entry.host,
+    port: entry.port,
+    path: '/wsman',
+    username: entry.user,
+    password: entry.auth.password ?? '',
+    useHttps: entry.transport === 'https',
+    rejectUnauthorized: entry.rejectUnauthorized ?? true,
+  }
+}
+
+export async function testConnection(conn: WinRMParams): Promise<{ ok: boolean; latencyMs: number; error?: string }> {
+  const started = Date.now()
+  try {
+    const result = await runScript(conn, 'Write-Output ok', { timeoutMs: 30_000 })
+    return { ok: result.exitCode === 0 && result.stdout.trim() !== '', latencyMs: Date.now() - started }
+  } catch (error) {
+    return { ok: false, latencyMs: Date.now() - started, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+export const TRANSFER_CHUNK = 48 * 1024
+
+export async function remoteFileSize(conn: WinRMParams, remotePath: string, timeoutMs = 60_000): Promise<number> {
+  const result = await runScript(conn, psFileSize(remotePath), { timeoutMs })
+  const value = Number.parseInt(result.stdout.trim(), 10)
+  return Number.isFinite(value) ? value : 0
+}
+
+export async function downloadChunks(
+  conn: WinRMParams,
+  remotePath: string,
+  onChunk: (b64: string, bytes: number) => void,
+  onProgress?: (transferred: number, total: number) => void,
+  timeoutMs = 60_000,
+): Promise<number> {
+  const total = await remoteFileSize(conn, remotePath, timeoutMs)
+  if (total === 0) return 0
+  let offset = 0
+  for (;;) {
+    const result = await runScript(conn, psReadChunk(remotePath, offset, TRANSFER_CHUNK), { timeoutMs })
+    const b64 = result.stdout.trim()
+    const bytes = Buffer.from(b64, 'base64').length
+    if (bytes === 0) break
+    onChunk(b64, bytes)
+    offset += bytes
+    onProgress?.(offset, total)
+    if (offset >= total || bytes < TRANSFER_CHUNK) break
+  }
+  return offset
+}
+
+export async function uploadBuffer(
+  conn: WinRMParams,
+  remotePath: string,
+  data: Buffer,
+  onProgress?: (transferred: number, total: number) => void,
+  timeoutMs = 60_000,
+): Promise<number> {
+  let written = 0
+  let first = true
+  for (let offset = 0; offset < data.length; offset += TRANSFER_CHUNK) {
+    const chunk = data.subarray(offset, Math.min(offset + TRANSFER_CHUNK, data.length))
+    await runScript(conn, psWriteChunk(remotePath, chunk.toString('base64'), !first), { timeoutMs })
+    written += chunk.length
+    first = false
+    onProgress?.(written, data.length)
+  }
+  return written
+}

package/src/engine/console.ts

@@ -0,0 +1,62 @@
+/**
+ * WebSocket PowerShell console backed by winrm-client one-shot commands.
+ *
+ * The native Node WinRM client executes each submitted command through the
+ * same UTF-8 envelope as winrm_exec; the WebSocket remains open while
+ * commands are serialized. This is intentionally a command console rather
+ * than a persistent remote process, so every line is authenticated and
+ * isolated.
+ */
+
+import type { WinRMParams } from './client.ts'
+import { runScript } from './client.ts'
+
+export class ConsoleSession {
+  private conn: WinRMParams
+  private running = false
+  private exited = false
+  private queue: Promise<void> = Promise.resolve()
+  onData: ((data: string) => void) | undefined
+  onExit: ((code: number | null, error?: string) => void) | undefined
+
+  constructor(conn: WinRMParams) {
+    this.conn = conn
+  }
+
+  async start(): Promise<void> {
+    this.running = true
+  }
+
+  send(data: string): void {
+    const command = data.replace(/\r?\n/g, '').trim()
+    if (!this.running || command === '') return
+    if (command.toLowerCase() === 'exit') {
+      this.close()
+      return
+    }
+    this.queue = this.queue.then(async () => {
+      if (!this.running) return
+      try {
+        const result = await runScript(this.conn, command, { timeoutMs: 120_000 })
+        if (result.stdout !== '') this.onData?.(result.stdout + (result.stdout.endsWith('\n') ? '' : '\n'))
+        if (result.stderr !== '') this.onData?.(result.stderr + (result.stderr.endsWith('\n') ? '' : '\n'))
+        if (result.timedOut) this.onData?.('[timed out]\n')
+      } catch (error) {
+        this.onData?.('[error] ' + (error instanceof Error ? error.message : String(error)) + '\n')
+      }
+    })
+  }
+
+  close(): void {
+    if (!this.running) return
+    this.running = false
+    this.exited = true
+  }
+
+  private finish(code: number | null, error?: string): void {
+    if (this.exited) return
+    this.exited = true
+    this.running = false
+    this.onExit?.(code, error)
+  }
+}

package/src/engine.ts

@@ -0,0 +1,331 @@
+/**
+ * The WinRM engine facade: host lookup, PowerShell exec (UTF-8 envelope),
+ * service & process management, directory listing, base64-chunked file
+ * transfer, cluster execution and the streaming console. The heavy lifting
+ * lives in engine/ (client, console); this class composes them behind one
+ * WinRmEngine instance per plugin apply.
+ */
+
+import type { ClusterResult, ExecResult, ProcessInfo, RemoteDirEntry, ServiceInfo, TestResult, TransferProgress, WinHostSummary } from './protocol.ts'
+import type { HostStore } from './store.ts'
+import { connOf, downloadChunks, runScript, testConnection, uploadBuffer } from './engine/client.ts'
+import { downloadSmb, uploadSmb, type TransferChannel } from './smb.ts'
+import { ConsoleSession } from './engine/console.ts'
+import { psKillProcess, psListDir, psListProcesses, psListServices, psServiceAction } from './powershell.ts'
+
+/** JSON-safe parse of the envelope output into a typed value. */
+function parseJson<T>(text: string): T {
+  const trimmed = text.trim()
+  if (trimmed === '' || trimmed === 'null') return [] as unknown as T
+  return JSON.parse(trimmed) as T
+}
+
+/** A tiny per-alias in-flight limiter so GUI bursts do not pile up sockets. */
+class AliasGate {
+  private queues = new Map<string, Promise<void>>()
+
+  async run<T>(alias: string, fn: () => Promise<T>): Promise<T> {
+    const prev = this.queues.get(alias) ?? Promise.resolve()
+    const next = prev.then(() => fn(), () => fn())
+    // Keep the chain alive even when fn rejects (the caller observes the rejection).
+    this.queues.set(alias, next.then(() => undefined, () => undefined))
+    try {
+      return await next
+    } finally {
+      if (this.queues.get(alias) === next.then(() => undefined, () => undefined)) {
+        // (The identity check above is intentionally approximate; the queue
+        // entry is replaced per run, so stale entries are naturally dropped.)
+      }
+      void prev
+    }
+  }
+}
+
+/** The engine. One instance per plugin apply; dispose() clears nothing pooled (WinRM is per-call HTTP). */
+export class WinRmEngine {
+  readonly store: HostStore
+  private gate = new AliasGate()
+
+  constructor(store: HostStore) {
+    this.store = store
+  }
+
+  // ---------------------------------------------------------------- config
+
+  /** Secret-free host list (filtered by the optional query). */
+  list(query?: string): WinHostSummary[] {
+    const needle = query?.trim().toLowerCase()
+    return this.store.list()
+      .filter(entry => needle === undefined || needle === ''
+        || entry.alias.toLowerCase().includes(needle)
+        || (entry.description ?? '').toLowerCase().includes(needle)
+        || entry.host.toLowerCase().includes(needle)
+        || entry.tags.some(tag => tag.toLowerCase().includes(needle)))
+      .map(entry => this.store.summarize(entry))
+  }
+
+  /** One host summary by alias. */
+  find(alias: string): WinHostSummary | undefined {
+    const entry = this.store.find(alias)
+    return entry === undefined ? undefined : this.store.summarize(entry)
+  }
+
+  // ------------------------------------------------------------------ exec
+
+  /** Run one PowerShell command on `alias`. */
+  async exec(alias: string, command: string, timeoutMs?: number): Promise<ExecResult> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) {
+      return { success: false, exitCode: null, timedOut: false, stdout: '', stderr: '', durationMs: 0, error: `alias '${alias}' not found` }
+    }
+    return this.gate.run(alias, async () => {
+      try {
+        const result = await runScript(connOf(entry), command, { timeoutMs: timeoutMs ?? 60_000 })
+        return {
+          success: result.exitCode === 0,
+          exitCode: result.exitCode,
+          timedOut: result.timedOut,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          durationMs: result.durationMs,
+        }
+      } catch (error) {
+        return { success: false, exitCode: null, timedOut: false, stdout: '', stderr: '', durationMs: 0, error: error instanceof Error ? error.message : String(error) }
+      }
+    })
+  }
+
+  // --------------------------------------------------------------- cluster
+
+  /** Run one command against many hosts concurrently. */
+  async cluster(options: {
+    command: string
+    aliases?: string[]
+    environment?: string
+    tags?: string[]
+    timeoutMs?: number
+    maxWorkers?: number
+  }): Promise<ClusterResult[]> {
+    const hosts = this.store.list()
+    let matched = hosts
+    if (options.aliases !== undefined && options.aliases.length > 0) {
+      const set = new Set(options.aliases)
+      matched = matched.filter(entry => set.has(entry.alias))
+    }
+    if (options.environment !== undefined && options.environment !== '') {
+      matched = matched.filter(entry => entry.environment === options.environment)
+    }
+    if (options.tags !== undefined && options.tags.length > 0) {
+      matched = matched.filter(entry => options.tags!.every(tag => entry.tags.includes(tag)))
+    }
+    const maxWorkers = Math.max(1, Math.min(options.maxWorkers ?? 8, 32))
+    const results: ClusterResult[] = []
+    let cursor = 0
+    const worker = async (): Promise<void> => {
+      for (;;) {
+        const index = cursor++
+        const entry = matched[index]
+        if (entry === undefined) return
+        const started = Date.now()
+        const outcome = await this.exec(entry.alias, options.command, options.timeoutMs)
+        results.push({
+          alias: entry.alias,
+          ok: outcome.success,
+          exitCode: outcome.exitCode,
+          timedOut: outcome.timedOut,
+          stdout: outcome.stdout,
+          stderr: outcome.stderr,
+          durationMs: outcome.durationMs,
+          ...(outcome.error !== undefined ? { error: outcome.error } : {}),
+        })
+        void started
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(maxWorkers, matched.length) }, () => worker()))
+    return results
+  }
+
+  // -------------------------------------------------------------- services
+
+  /** Full service table. */
+  async listServices(alias: string): Promise<ServiceInfo[]> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) throw new Error(`alias '${alias}' not found`)
+    return this.gate.run(alias, async () => {
+      const result = await runScript(connOf(entry), psListServices(), { timeoutMs: 60_000 })
+      if (result.exitCode !== 0) throw new Error(result.stdout || 'failed to list services')
+      const items = parseJson<Array<{ name?: string; displayName?: string; status?: string; startMode?: string; startName?: string }>>(result.stdout)
+      return items.map(item => ({
+        name: item.name ?? '',
+        displayName: item.displayName ?? '',
+        status: item.status ?? '',
+        startMode: item.startMode ?? '',
+        startName: item.startName ?? '',
+      }))
+    })
+  }
+
+  /** One service action, returning the refreshed service row. */
+  async serviceAction(alias: string, name: string, action: 'start' | 'stop' | 'restart' | 'set-auto' | 'set-manual' | 'set-disabled'): Promise<ServiceInfo> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) throw new Error(`alias '${alias}' not found`)
+    return this.gate.run(alias, async () => {
+      const result = await runScript(connOf(entry), psServiceAction(name, action), { timeoutMs: 60_000 })
+      if (result.exitCode !== 0) throw new Error(result.stdout || `service action '${action}' failed`)
+      const item = parseJson<Array<{ name?: string; displayName?: string; status?: string; startMode?: string; startName?: string }>>(result.stdout)[0] ?? {}
+      return {
+        name: item.name ?? name,
+        displayName: item.displayName ?? '',
+        status: item.status ?? '',
+        startMode: item.startMode ?? '',
+        startName: item.startName ?? '',
+      }
+    })
+  }
+
+  // ------------------------------------------------------------- processes
+
+  /** Full process table. */
+  async listProcesses(alias: string): Promise<ProcessInfo[]> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) throw new Error(`alias '${alias}' not found`)
+    return this.gate.run(alias, async () => {
+      const result = await runScript(connOf(entry), psListProcesses(), { timeoutMs: 60_000 })
+      if (result.exitCode !== 0) throw new Error(result.stdout || 'failed to list processes')
+      const items = parseJson<Array<{ id?: number; name?: string; cpu?: number | null; memMB?: number; startTime?: string | null; path?: string | null }>>(result.stdout)
+      return items.map(item => ({
+        id: item.id ?? 0,
+        name: item.name ?? '',
+        ...(item.cpu !== undefined && item.cpu !== null ? { cpu: item.cpu } : {}),
+        ...(item.memMB !== undefined && item.memMB !== null ? { memMB: item.memMB } : {}),
+        ...(item.startTime !== undefined && item.startTime !== null ? { startTime: item.startTime } : {}),
+        ...(item.path !== undefined && item.path !== null ? { path: item.path } : {}),
+      }))
+    })
+  }
+
+  /** Kill one process by id. */
+  async killProcess(alias: string, id: number): Promise<void> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) throw new Error(`alias '${alias}' not found`)
+    return this.gate.run(alias, async () => {
+      const result = await runScript(connOf(entry), psKillProcess(id), { timeoutMs: 30_000 })
+      if (result.exitCode !== 0) throw new Error(result.stdout || 'failed to kill process')
+    })
+  }
+
+  // -------------------------------------------------------------------- ls
+
+  /** List a remote directory. */
+  async ls(alias: string, dir: string): Promise<RemoteDirEntry[]> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) throw new Error(`alias '${alias}' not found`)
+    return this.gate.run(alias, async () => {
+      const result = await runScript(connOf(entry), psListDir(dir), { timeoutMs: 60_000 })
+      if (result.exitCode !== 0) throw new Error(result.stdout || `failed to list '${dir}'`)
+      const items = parseJson<Array<{ name?: string; type?: string; size?: number; mtimeMs?: number }>>(result.stdout)
+      return items.map(item => ({
+        name: item.name ?? '',
+        type: (item.type === 'dir' || item.type === 'file' ? item.type : 'other') as RemoteDirEntry['type'],
+        size: item.size ?? 0,
+        mtimeMs: item.mtimeMs ?? 0,
+      }))
+    })
+  }
+
+  // -------------------------------------------------------------- transfer
+
+  /** Upload one local file to a remote path. Defaults to SMB with WinRM fallback. */
+  async upload(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, channel: TransferChannel = 'auto'): Promise<{ bytes: number; channel?: TransferChannel }> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) throw new Error(`alias '${alias}' not found`)
+    const { readFileSync } = await import('node:fs')
+    const data = readFileSync(localPath)
+    return this.gate.run(alias, async () => {
+      onProgress?.({ phase: 'connecting', file: remotePath, transferred: 0, total: data.length, percent: 0 })
+      if (channel !== 'winrm') {
+        try {
+          const outcome = await uploadSmb(entry, localPath, remotePath)
+          onProgress?.({ phase: 'done', file: remotePath, transferred: outcome.bytes, total: outcome.bytes, percent: 100 })
+          return { bytes: outcome.bytes, channel: outcome.channel }
+        } catch (error) {
+          if (channel === 'smb') throw error
+          onProgress?.({ phase: 'connecting', file: remotePath, transferred: 0, total: data.length, percent: 0 })
+        }
+      }
+      const bytes = await uploadBuffer(connOf(entry), remotePath, data, (transferred, total) => {
+        onProgress?.({ phase: 'transferring', file: remotePath, transferred, total, percent: total > 0 ? Math.round((transferred / total) * 1000) / 10 : 0 })
+      })
+      onProgress?.({ phase: 'done', file: remotePath, transferred: bytes, total: bytes, percent: 100 })
+      return { bytes, channel: 'winrm' }
+    })
+  }
+
+  /** Download one remote file to a local path. Defaults to SMB with WinRM fallback. */
+  async download(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, channel: TransferChannel = 'auto'): Promise<{ bytes: number; channel?: TransferChannel }> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) throw new Error(`alias '${alias}' not found`)
+    return this.gate.run(alias, async () => {
+      onProgress?.({ phase: 'connecting', file: remotePath, transferred: 0, total: 0, percent: 0 })
+      if (channel !== 'winrm') {
+        try {
+          const outcome = await downloadSmb(entry, remotePath, localPath)
+          onProgress?.({ phase: 'done', file: remotePath, transferred: outcome.bytes, total: outcome.bytes, percent: 100 })
+          return { bytes: outcome.bytes, channel: outcome.channel }
+        } catch (error) {
+          if (channel === 'smb') throw error
+          onProgress?.({ phase: 'connecting', file: remotePath, transferred: 0, total: 0, percent: 0 })
+        }
+      }
+      const { createWriteStream } = await import('node:fs')
+      const sink = createWriteStream(localPath, { mode: 0o600 })
+      let bytes = 0
+      await new Promise<void>((resolve, reject) => {
+        sink.on('error', reject)
+        void downloadChunks(
+          connOf(entry),
+          remotePath,
+          (b64) => {
+            const buffer = Buffer.from(b64, 'base64')
+            bytes += buffer.length
+            sink.write(buffer)
+          },
+          (transferred, total) => onProgress?.({ phase: 'transferring', file: remotePath, transferred, total, percent: total > 0 ? Math.round((transferred / total) * 1000) / 10 : 0 }),
+        ).then(
+          () => sink.end(resolve),
+          (error) => { sink.destroy(); reject(error) },
+        )
+      })
+      onProgress?.({ phase: 'done', file: remotePath, transferred: bytes, total: bytes, percent: 100 })
+      return { bytes, channel: 'winrm' }
+    })
+  }
+
+  // --------------------------------------------------------------- console
+
+  /** Open a streaming PowerShell console session (standalone connection). */
+  async openConsole(alias: string): Promise<ConsoleSession> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) throw new Error(`alias '${alias}' not found`)
+    const session = new ConsoleSession(connOf(entry))
+    await session.start()
+    return session
+  }
+
+  // ------------------------------------------------------------------ misc
+
+  /** Probe connectivity. */
+  async test(alias: string): Promise<TestResult> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) return { ok: false, error: `alias '${alias}' not found` }
+    return this.gate.run(alias, async () => {
+      const result = await testConnection(connOf(entry))
+      return result
+    })
+  }
+
+  /** No pooled resources to close (WinRM is per-call HTTP). */
+  dispose(): void {
+    // Nothing to tear down: every operation owns its shell lifecycle.
+  }
+}