dsh-winrm 0.1.0

package/src/index.ts

@@ -0,0 +1,142 @@
+/**
+ * dsh-winrm — host half. Mounts the WinRM engine (per-call PowerShell
+ * execution with a UTF-8 envelope, streaming console, service/process
+ * management, base64-chunked file transfer, cluster), the /api/dsh-winrm
+ * route family plus the console WebSocket upgrade, the agent tools
+ * (winrm_list, winrm_exec, winrm_service, winrm_process, winrm_upload,
+ * winrm_download, winrm_cluster), and a system-prompt announcement. The
+ * browser half (./client) renders the host manager and operations panel.
+ * Everything rides official NPM SDK packages — no dsh source changes.
+ *
+ * Config is read live through `Volatile` references (`.get()`), so the
+ * Settings page can flip `enabled` / `announceToAgent` without remounting;
+ * `loader/volatile-update` re-runs the registration sync when they change.
+ */
+
+import type { Context, Volatile } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+// Type-only: the loader's Events merge (`loader/volatile-update`).
+import type {} from '@deepseek-ai/cordis-plugin-loader'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-tools'
+import { WinRmEngine } from './engine.ts'
+import { makeRoutes } from './routes.ts'
+import { HostStore } from './store.ts'
+import {
+  winrmClusterTool,
+  winrmDownloadTool,
+  winrmExecTool,
+  winrmListTool,
+  winrmProcessTool,
+  winrmServiceTool,
+  winrmUploadTool,
+} from './tools.ts'
+import { mountOnce } from './mount-once.ts'
+
+/** Stable cordis plugin name. */
+export const name = 'winrm'
+
+/** Services required before the WinRM surfaces can mount. */
+export const inject = ['webServer', 'tools', 'systemPrompt']
+
+/** Plugin config, validated by the same-named schemastery schema. Live fields are `Volatile`. */
+export interface Config {
+  /** When true (default), a system-prompt section announces the plugin to every agent. */
+  announceToAgent?: Volatile<boolean>
+  /** Master switch for the plugin (routes, tools, prompt section). */
+  enabled?: Volatile<boolean>
+}
+
+export const Config = z.object({
+  announceToAgent: z.boolean().default(true).volatile(),
+  enabled: z.boolean().default(true).volatile(),
+})
+
+/** Schema default, re-read for hand-built test contexts. */
+const DEFAULT_ANNOUNCE = true
+
+/** Schema default for the master switch. */
+const DEFAULT_ENABLED = true
+
+/** Order of the announcement section within the tool-guidance band. */
+const SECTION_ORDER = 151
+
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+export const WINRM_GUIDANCE = '本机已安装 dsh-winrm 插件（DSH 远程 Windows 运维，WinRM/PowerShell Remoting）：侧边栏「Windows」入口；仿照 dsh-ssh 插件开发。能力：主机配置存 ~/.dsh/dsh-winrm.json（GUI 配置后 agent 方可使用）；winrm_list 列出主机、winrm_exec 执行 PowerShell 命令（UTF-8 信封，中文不乱码）、winrm_service 服务管理（start/stop/restart/启动类型）、winrm_process 进程管理（list/kill）、winrm_upload/winrm_download 文件传输（base64 分块，无 SMB 依赖）、winrm_cluster 集群并发执行；Web 控制台走 WebSocket。认证：通过原生 Node.js WinRM 客户端（winrm-client）的 NTLM/Negotiate 与 Basic 实现，兼容本地账户与域账户；传输支持 http(5985)/https(5986)。前提：目标机需启用 WinRM（scripts/enable-winrm.ps1），本机无需 Python —— WinRM 走纯 Node 依赖。HTTP 仅建议受信内网使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出可能含敏感信息；传输/执行消耗真实远程资源，先确认再操作。用户提到「Windows 服务器 / WinRM / PowerShell 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。'
+
+/**
+ * Mount the WinRM engine, routes, tools, and announcement.
+ * @param ctx - host plugin context carrying webServer/tools/systemPrompt.
+ * @param config - resolved plugin config (volatile fields read via `.get()`).
+ */
+export const apply = mountOnce('dsh-winrm', applyImpl)
+
+function applyImpl(ctx: Context, config?: Config): void {
+  const resolve = (): { announceToAgent: boolean; enabled: boolean } => ({
+    announceToAgent: config?.announceToAgent?.get() ?? DEFAULT_ANNOUNCE,
+    enabled: config?.enabled?.get() ?? DEFAULT_ENABLED,
+  })
+
+  const store = new HostStore()
+  const engine = new WinRmEngine(store)
+
+  const { routes, upgrade } = makeRoutes({ store, engine })
+  const tools = [
+    winrmListTool(engine),
+    winrmExecTool(engine),
+    winrmServiceTool(engine),
+    winrmProcessTool(engine),
+    winrmUploadTool(engine),
+    winrmDownloadTool(engine),
+    winrmClusterTool(engine),
+  ]
+
+  let disposeSection: (() => void) | undefined
+  let disposeRoutes: (() => void) | undefined
+  let disposeTools: (() => void) | undefined
+
+  const registerRoutes = (): (() => void) => {
+    const disposers = routes.map(route => ctx.webServer.register(route))
+    const upgradeDisposer = ctx.webServer.registerUpgrade(upgrade)
+    return () => {
+      for (const dispose of disposers) dispose()
+      upgradeDisposer()
+    }
+  }
+  const registerTools = (): (() => void) => {
+    const disposers = tools.map(tool => ctx.tools.register(tool))
+    return () => { for (const dispose of disposers) dispose() }
+  }
+
+  const sync = (): void => {
+    disposeSection?.(); disposeSection = undefined
+    disposeRoutes?.(); disposeRoutes = undefined
+    disposeTools?.(); disposeTools = undefined
+    const value = resolve()
+    if (!value.enabled) return
+    if (value.announceToAgent) {
+      disposeSection = ctx.systemPrompt.section({
+        name: 'plugin:dsh-winrm',
+        order: SECTION_ORDER,
+        text: WINRM_GUIDANCE,
+      })
+    }
+    disposeRoutes = registerRoutes()
+    disposeTools = registerTools()
+  }
+
+  // Volatile config edits land on the running references, then notify the
+  // owning fiber here — re-sync the registrations against the new values.
+  ctx.on('loader/volatile-update', sync)
+
+  // Single teardown: dispose whatever the latest sync left registered.
+  ctx.effect(() => () => {
+    disposeSection?.()
+    disposeRoutes?.()
+    disposeTools?.()
+    engine.dispose()
+  }, 'dsh-winrm: teardown')
+
+  sync()
+}

package/src/invariant.ts

@@ -0,0 +1,4 @@
+/** Invariant companion plugin (no assertions — nothing to check at runtime). */
+
+/** Provides no assertions: the winrm plugin owns no cross-package runtime invariants. */
+export function apply(): void {}

package/src/loopback.ts

@@ -0,0 +1,63 @@
+// Generated by scripts/sync-shared.mjs from shared/host/loopback.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Loopback trust fence shared by the host route families: socket address,
+ * Host header, and browser same-origin markers. Packages receive this file as
+ * a generated copy via scripts/sync-shared.mjs; edit the shared source and
+ * re-run the sync instead of editing a copy.
+ *
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
+ * markers (sec-fetch-site and Origin) for the request-level fence.
+ * @module dsh-web-ui-shared/host/loopback
+ */
+
+import type { IncomingMessage } from 'node:http'
+
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+export function isIPv4Loopback(v4: string): boolean {
+  const parts = v4.split('.')
+  return parts.length === 4
+    && parts[0] === '127'
+    && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+export function isLoopbackAddress(address: string | undefined): boolean {
+  if (address === undefined) return false
+  const normalized = address.toLowerCase()
+  if (normalized === '::1') return true
+  if (normalized.startsWith('::ffff:')) return isIPv4Loopback(normalized.slice('::ffff:'.length))
+  return isIPv4Loopback(normalized)
+}
+
+/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
+export function isLoopbackHostname(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  return isIPv4Loopback(hostname)
+}
+
+/**
+ * Request-level trust fence: a loopback socket address AND a loopback Host
+ * header, plus browser same-origin markers. The socket address is
+ * authoritative; X-Forwarded-For is never trusted.
+ */
+export function isLoopbackRequest(request: IncomingMessage): boolean {
+  if (!isLoopbackAddress(request.socket.remoteAddress)) return false
+  const host = request.headers.host
+  if (typeof host !== 'string') return false
+  let hostUrl: URL
+  try {
+    hostUrl = new URL('http://' + host)
+  } catch {
+    return false
+  }
+  if (!isLoopbackHostname(hostUrl.hostname)) return false
+  if (request.headers['sec-fetch-site'] === 'cross-site') return false
+  const origin = request.headers.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}

package/src/mount-once.ts

@@ -0,0 +1,48 @@
+// Generated by scripts/sync-shared.mjs from shared/host/mount-once.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Host single-instance guard shared by the plugin family. The family bundle
+ * (dsh-web-ui-all / dsh-skins) namespaces every child row id (web-ui-*), so
+ * the loader accepts a standalone install of the same package side by side;
+ * without this guard the second instance would still re-register the same
+ * webserver routes, tools, settings namespaces, and system-prompt sections
+ * and fail the boot. mountOnce makes the second host apply a no-op for the
+ * lifetime of the first instance (the browser half is already deduped by
+ * package name in the client module host).
+ *
+ * The registry rides a global symbol so two module instances of the same
+ * package (npm copy vs repository link) still share one verdict. cordis
+ * `ctx.effect` runs its callback immediately and treats the callback's
+ * return value as the fiber disposer, so the unmarker is returned, not run.
+ */
+
+const MOUNTED = Symbol.for('dsh-web-ui.mounted-plugins')
+
+interface MountRegistry {
+  [MOUNTED]?: Set<string>
+}
+
+function mountedSet(): Set<string> {
+  const registry = globalThis as MountRegistry
+  return (registry[MOUNTED] ??= new Set())
+}
+
+/**
+ * Wrap a cordis plugin apply so the package runs at most once per process.
+ * The first mount registers normally and unmarks when its fiber disposes;
+ * any later mount of the same package name is a no-op.
+ * @param packageName - npm package identity shared by every install source.
+ * @param fn - the original plugin apply.
+ * @returns an apply of the same shape.
+ */
+export function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T {
+  return ((...args: unknown[]) => {
+    const mounted = mountedSet()
+    if (mounted.has(packageName)) return
+    mounted.add(packageName)
+    const ctx = args[0] as { effect?: (effect: () => unknown) => unknown } | undefined
+    ctx?.effect?.(() => () => {
+      mounted.delete(packageName)
+    })
+    return fn(...args)
+  }) as T
+}

package/src/powershell.ts

@@ -0,0 +1,208 @@
+/**
+ * PowerShell snippet builders. Every payload rides the UTF-8 base64
+ * envelope: the WinRM host prints only ASCII (marker + base64 of UTF-8 text)
+ * so Chinese / any codepage output survives the transport losslessly. One-shot
+ * commands execute directly in the PowerShell session created by WinRM.
+ */
+
+/** Marker line prefix carrying the exit code: '__DSH_WINRM__<code>'. */
+export const ENVELOPE_MARKER = '__DSH_WINRM__'
+
+/** PS single-quoted literal (doubles embedded quotes). */
+export function sq(value: string): string {
+  return "'" + value.replace(/'/g, "''") + "'"
+}
+
+/** Base64 of a UTF-16LE PowerShell script, for -EncodedCommand. */
+export function encodeCommand(script: string): string {
+  return Buffer.from(script, 'utf16le').toString('base64')
+}
+
+/**
+ * The UTF-8 WinRM session script: runs `userScript` inside a script block,
+ * merges stderr, prints the exit-code marker and base64 of UTF-8 output.
+ */
+export function wrapEnvelope(userScript: string): string {
+  return [
+    "$ErrorActionPreference = 'Continue'",
+    "$__out = & { " + userScript + " } 2>&1 | Out-String -Width 4096",
+    "$__code = 0",
+    "if ($null -ne $LASTEXITCODE) { $__code = $LASTEXITCODE }",
+    "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
+    "'__DSH_WINRM__' + [string]$__code",
+    "[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes([string]$__out))",
+    '',
+  ].join('\r\n')
+}
+
+/** One-shot script body for the PowerShell session already created by WinRM. */
+export function winrmPowerShellScript(userScript: string): string {
+  return wrapEnvelope(userScript)
+}
+
+/** The full powershell.exe command line (ASCII-safe) for a script body. */
+export function powershellCommandLine(script: string): string {
+  return 'powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -EncodedCommand ' + encodeCommand(script)
+}
+
+/** One-shot non-interactive PowerShell command line (envelope-wrapped). */
+export function execCommandLine(userScript: string): string {
+  return powershellCommandLine(wrapEnvelope(userScript))
+}
+
+/** Interactive bootstrap for the streaming console (keeps the shell alive). */
+export function consoleCommandLine(): string {
+  const bootstrap = [
+    "$ErrorActionPreference = 'Continue'",
+    "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
+    "'__DSH_WINRM_CONSOLE_READY__'",
+    '',
+  ].join('\r\n')
+  // -NoExit keeps powershell.exe alive reading stdin (interactive mode).
+  return 'powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -EncodedCommand '
+    + encodeCommand(bootstrap) + ' -NoExit'
+}
+
+// ------------------------------------------------------------ snippets
+
+/** JSON: full service table (CIM). */
+export function psListServices(): string {
+  return [
+    '$__s = Get-CimInstance Win32_Service | Select-Object Name, DisplayName, State, StartMode, StartName | ForEach-Object {',
+    '  [PSCustomObject]@{ name=$_.Name; displayName=$_.DisplayName; status=[string]$_.State; startMode=[string]$_.StartMode; startName=[string]$_.StartName }',
+    '}',
+    'ConvertTo-Json -InputObject $__s -Compress -Depth 3',
+    '',
+  ].join('\r\n')
+}
+
+/** JSON: one service after an action. */
+export function psServiceAction(name: string, action: 'start' | 'stop' | 'restart' | 'set-auto' | 'set-manual' | 'set-disabled'): string {
+  const statements: string[] = []
+  if (action === 'start') statements.push('Start-Service -Name ' + sq(name) + ' -ErrorAction Stop')
+  if (action === 'stop') statements.push('Stop-Service -Name ' + sq(name) + ' -Force -ErrorAction Stop')
+  if (action === 'restart') statements.push('Restart-Service -Name ' + sq(name) + ' -Force -ErrorAction Stop')
+  if (action === 'set-auto') statements.push('Set-Service -Name ' + sq(name) + ' -StartupType Automatic -ErrorAction Stop')
+  if (action === 'set-manual') statements.push('Set-Service -Name ' + sq(name) + ' -StartupType Manual -ErrorAction Stop')
+  if (action === 'set-disabled') statements.push('Set-Service -Name ' + sq(name) + ' -StartupType Disabled -ErrorAction Stop')
+  statements.push('$__s = Get-CimInstance Win32_Service -Filter ' + sq('Name=' + name.replace(/'/g, "''")) + ' | Select-Object Name, DisplayName, State, StartMode, StartName')
+  statements.push('ConvertTo-Json -InputObject $__s -Compress -Depth 3')
+  return statements.join('\r\n')
+}
+
+/** JSON: process table. */
+export function psListProcesses(): string {
+  return [
+    '$__p = Get-Process | Sort-Object Id | Select-Object Id, ProcessName, CPU, WS, StartTime, Path | ForEach-Object {',
+    '  [PSCustomObject]@{ id=$_.Id; name=$_.ProcessName; cpu=if($null -eq $_.CPU){$null}else{[math]::Round([double]$_.CPU,1)}; memMB=[math]::Round($_.WS/1MB,1); startTime=if($_.StartTime){$_.StartTime.ToString(\'yyyy-MM-dd HH:mm:ss\')}else{$null}; path=[string]$_.Path }',
+    '}',
+    'ConvertTo-Json -InputObject $__p -Compress -Depth 3',
+    '',
+  ].join('\r\n')
+}
+
+/** Kill one process by id. */
+export function psKillProcess(id: number): string {
+  return 'Stop-Process -Id ' + String(id) + ' -Force -ErrorAction Stop; "killed " + ' + String(id)
+}
+
+/** JSON: directory listing. */
+export function psListDir(dir: string): string {
+  return [
+    '$__d = ' + sq(dir),
+    '$__items = Get-ChildItem -LiteralPath $__d -Force -ErrorAction Stop | Select-Object Name, PSIsContainer, Length, LastWriteTime | ForEach-Object {',
+    '  [PSCustomObject]@{ name=[string]$_.Name; type=if($_.PSIsContainer){\'dir\'}elseif(-not $_.PSIsContainer -and $_.Length -ge 0){\'file\'}else{\'other\'}; size=if($_.PSIsContainer){0}else{[long]$_.Length}; mtimeMs=[long](([DateTimeOffset]$_.LastWriteTime).ToUnixTimeMilliseconds()) }',
+    '}',
+    'ConvertTo-Json -InputObject $__items -Compress -Depth 3',
+    '',
+  ].join('\r\n')
+}
+
+/** Plain: remote file size in bytes (0 when missing). */
+export function psFileSize(p: string): string {
+  return [
+    '$__f = Get-Item -LiteralPath ' + sq(p) + ' -ErrorAction SilentlyContinue',
+    'if ($null -eq $__f) { "0" } elseif ($__f.PSIsContainer) { "0" } else { [string]$__f.Length }',
+    '',
+  ].join('\r\n')
+}
+
+/** Plain: base64 of up to `count` bytes at `offset` (download chunk). */
+export function psReadChunk(p: string, offset: number, count: number): string {
+  return [
+    '$__p = ' + sq(p),
+    '$__fs = [System.IO.File]::OpenRead($__p)',
+    'try {',
+    '  $__fs.Position = [long]' + String(offset),
+    '  $__buf = New-Object byte[] ' + String(count),
+    '  $__n = $__fs.Read($__buf, 0, $__buf.Length)',
+    '  [System.Convert]::ToBase64String($__buf, 0, $__n)',
+    '} finally { $__fs.Dispose() }',
+    '',
+  ].join('\r\n')
+}
+
+/**
+ * Plain: append `b64` bytes to `p` (Create on first chunk, Append after),
+ * prints the number of bytes written.
+ */
+export function psWriteChunk(p: string, b64: string, append: boolean): string {
+  return [
+    '$__p = ' + sq(p),
+    '$__d = [System.IO.Path]::GetDirectoryName($__p)',
+    'if (-not [string]::IsNullOrEmpty($__d)) { [System.IO.Directory]::CreateDirectory($__d) | Out-Null }',
+    '$__b = [System.Convert]::FromBase64String(' + sq(b64) + ')',
+    '$__mode = ' + (append ? '[System.IO.FileMode]::Append' : '[System.IO.FileMode]::Create'),
+    '$__fs = New-Object System.IO.FileStream($__p, $__mode, [System.IO.FileAccess]::Write, [System.IO.FileShare]::Read)',
+    'try { $__fs.Write($__b, 0, $__b.Length) } finally { $__fs.Dispose() }',
+    '[string]$__b.Length',
+    '',
+  ].join('\r\n')
+}
+
+/**
+ * Parse the envelope output: { exitCode, text } or null when absent.
+ *
+ * The base64 body is optional and the separating newline may be missing: a
+ * command that printed nothing emits the marker alone (an empty string has
+ * no base64 body), and a transport that trims each response drops the
+ * trailing newline. The exit code is signed because `$LASTEXITCODE` can be
+ * negative.
+ */
+export function parseEnvelope(output: string): { exitCode: number; text: string } | null {
+  const match = /^__DSH_WINRM__(-?\d+)(?:\r?\n([\s\S]*))?$/.exec(output)
+  if (match === null) return null
+  const exitCode = Number.parseInt(match[1], 10)
+  const payload = (match[2] ?? '').trim()
+  try {
+    const text = Buffer.from(payload, 'base64').toString('utf8')
+    return { exitCode, text }
+  } catch {
+    return { exitCode, text: payload }
+  }
+}
+
+/** The `#< CLIXML` stream header PowerShell writes once before its serialized records. */
+const CLIXML_HEADER = /^#< CLIXML\r?$/gm
+
+/** One serialized record block (`<Objs …>…</Objs>`) holding host progress/verbose records. */
+const CLIXML_RECORDS = /<Objs\b[^>]*>[\s\S]*?<\/Objs>\r?\n?/g
+
+/**
+ * Remove PowerShell's CLIXML host records from the WinRS stderr stream.
+ *
+ * PowerShell marks its stderr stream with a `#< CLIXML` header line and
+ * serializes the remote host's own progress/verbose records into `<Objs>`
+ * blocks. Both are removed here. Anything else on the stream is genuine
+ * process-level stderr and is preserved verbatim — text written between the
+ * header and a record block (for example `[Console]::Error`) is real output,
+ * not part of the CLIXML payload.
+ *
+ * The script's own error output is already merged into stdout by the
+ * envelope, so this only removes transport-level noise.
+ * @param stderr - raw stderr text captured from the WinRS stream.
+ * @returns the stderr text without CLIXML host records.
+ */
+export function stripClixml(stderr: string): string {
+  return stderr.replace(CLIXML_HEADER, '').replace(CLIXML_RECORDS, '').trim()
+}

package/src/protocol.ts

@@ -0,0 +1,178 @@
+/**
+ * Wire contract between the host half (routes.ts) and the browser half
+ * (client/api.ts). Pure types only — imported by both halves, bundled into
+ * each, no runtime identity to share.
+ */
+
+/** WinRM transport flavors. */
+export type WinTransport = 'http' | 'https'
+
+/** One stored host entry (the ~/.dsh/dsh-winrm.json store shape). */
+export interface WinHostEntry {
+  /** Stable, user-chosen identifier used by every operation. */
+  alias: string
+  /** Hostname or IP of the target Windows machine. */
+  host: string
+  /** WinRM port (5985 HTTP, 5986 HTTPS). */
+  port: number
+  /** Login user. The transport auto-selects NTLM/Negotiate or Basic for local and domain accounts. */
+  user: string
+  /** Authentication (WinRM password; transport handles NTLM/Negotiate/Basic in-process). */
+  auth: {
+    kind: 'password'
+    password?: string
+  }
+  /** http (5985) or https (5986). */
+  transport: WinTransport
+  /** Whether self-signed HTTPS certificates are accepted. */
+  rejectUnauthorized?: boolean
+  /** Free-form note. */
+  description?: string
+  /** Deployment environment label (development / production / ...). */
+  environment?: string
+  /** Free-form tags. */
+  tags: string[]
+  /** Physical location note. */
+  location?: string
+  createdAt: number
+  updatedAt: number
+}
+
+/** Public (secret-free) projection of an entry, safe for the browser/agent. */
+export interface WinHostSummary {
+  alias: string
+  host: string
+  port: number
+  user: string
+  auth: 'password'
+  transport: WinTransport
+  rejectUnauthorized?: boolean
+  description?: string
+  environment?: string
+  tags: string[]
+  location?: string
+  createdAt: number
+  updatedAt: number
+}
+
+/** Result of one PowerShell command execution. */
+export interface ExecResult {
+  success: boolean
+  /** Remote exit code, or null when the channel died without one. */
+  exitCode: number | null
+  timedOut: boolean
+  stdout: string
+  stderr: string
+  /** Wall-clock duration of the round trip in ms. */
+  durationMs: number
+  /** Connection error message when the command never ran. */
+  error?: string
+}
+
+/** One Windows service entry. */
+export interface ServiceInfo {
+  name: string
+  displayName: string
+  status: string
+  startMode: string
+  startName?: string
+}
+
+/** One Windows process entry. */
+export interface ProcessInfo {
+  id: number
+  name: string
+  cpu?: number
+  memMB?: number
+  startTime?: string
+  path?: string
+}
+
+/** One directory listing entry (remote file browser). */
+export interface RemoteDirEntry {
+  name: string
+  type: 'dir' | 'file' | 'other'
+  size: number
+  mtimeMs: number
+}
+
+/** One server entry in a cluster run. */
+export interface ClusterResult {
+  alias: string
+  ok: boolean
+  exitCode?: number | null
+  timedOut?: boolean
+  stdout?: string
+  stderr?: string
+  durationMs?: number
+  error?: string
+}
+
+/** Transfer progress frame (upload/download). */
+export interface TransferProgress {
+  phase: 'connecting' | 'transferring' | 'done' | 'error'
+  file: string
+  transferred: number
+  total: number
+  percent: number
+  speedBps?: number
+  error?: string
+}
+
+/** Test-connection outcome. */
+export interface TestResult {
+  ok: boolean
+  latencyMs?: number
+  error?: string
+}
+
+/** Host edit payload (create/update); 'alias' comes from the URL for updates. */
+export interface WinHostPayload {
+  alias?: string
+  host: string
+  port?: number
+  user: string
+  /** Authentication. Required on create; on update an omitted auth keeps the stored password. */
+  auth?: WinHostEntry['auth']
+  transport?: WinTransport
+  rejectUnauthorized?: boolean
+  description?: string
+  environment?: string
+  tags?: string[]
+  location?: string
+}
+
+/** JSON error body used by every route. */
+export interface ApiErrorBody {
+  error: string
+}
+
+/** WebSocket console protocol frames (host -> client and client -> host). */
+export type ConsoleServerFrame =
+  | { type: 'ready'; alias: string }
+  | { type: 'output'; data: string }
+  | { type: 'exit'; code: number | null; error?: string }
+
+export type ConsoleClientFrame =
+  | { type: 'input'; data: string }
+
+/** Route paths the client calls (shared literals). */
+export const WINRM_API_BASE = '/api/dsh-winrm' as const
+
+export const WINRM_API = {
+  hosts: WINRM_API_BASE + '/hosts',
+  test: WINRM_API_BASE + '/test',
+  exec: WINRM_API_BASE + '/exec',
+  cluster: WINRM_API_BASE + '/cluster',
+  services: WINRM_API_BASE + '/services',
+  processes: WINRM_API_BASE + '/processes',
+  ls: WINRM_API_BASE + '/ls',
+  upload: WINRM_API_BASE + '/upload',
+  download: WINRM_API_BASE + '/download',
+  console: WINRM_API_BASE + '/console',
+} as const
+
+/** NDJSON transfer stream line shapes (upload). */
+export type TransferStreamLine =
+  | { type: 'progress'; progress: TransferProgress }
+  | { type: 'result'; ok: boolean; transferredBytes?: number; error?: string }