dsh-winrm 0.3.1 → 0.4.1

package/src/engine.ts

@@ -6,12 +6,25 @@
  * per plugin apply.
  */
 
-import type { ClusterResult, ExecResult, ProcessInfo, RemoteDirEntry, ServiceInfo, TestResult, TransferProgress, WinHostSummary } from './protocol.ts'
+import type { ClusterResult, ExecResult, ProcessInfo, RemoteDirEntry, RemoteEditOutcome, RemoteTextEncoding, RemoteTextWindow, RemoteWriteOutcome, ServiceInfo, TestResult, TransferProgress, WinHostSummary } from './protocol.ts'
 import type { HostStore } from './store.ts'
-import { connOf, downloadChunks, downloadStream, runScript, testConnection, uploadBuffer, uploadStream } from './engine/client.ts'
+import { connOf, downloadChunks, downloadStream, remoteFileSize, runScript, testConnection, uploadBuffer, uploadStream } from './engine/client.ts'
 import { downloadSmb, smbReachable, smbUnavailable, uploadSmb, type TransferChannel } from './smb.ts'
 import { ConsoleSession } from './engine/console.ts'
-import { psKillProcess, psListDir, psListProcesses, psListServices, psServiceAction } from './powershell.ts'
+import { DIFF_BASIS_MAX_BYTES } from './diff.ts'
+import { psEditText, psKillProcess, psListDir, psListProcesses, psListServices, psReadTextBasis, psReadTextWindow, psServiceAction } from './powershell.ts'
+
+/** Longest single line the reader returns before cutting it (characters). */
+export const READ_MAX_LINE_LENGTH = 2_000
+
+/** Lines the reader returns when the caller does not choose a page size. */
+export const READ_DEFAULT_LIMIT = 2_000
+
+/** Most lines the reader will return in one call. */
+export const READ_MAX_LIMIT = 5_000
+
+/** Byte budget for one read window; keeps the envelope well under the transport limit. */
+export const READ_MAX_BYTES = 512 * 1_024
 
 /** JSON-safe parse of the envelope output into a typed value. */
 function parseJson<T>(text: string): T {
@@ -20,6 +33,42 @@ function parseJson<T>(text: string): T {
   return JSON.parse(trimmed) as T
 }
 
+/**
+ * Parse one JSON object out of an envelope's stdout.
+ *
+ * The file tools report their own failures inside the JSON (`{"error":…}`)
+ * with exit code 0, so an unparseable body means the fragment never ran;
+ * returning undefined lets the caller say so instead of throwing a
+ * `SyntaxError` with no context.
+ * @param text - envelope stdout.
+ * @returns the parsed object, or undefined when the body is empty or not JSON.
+ */
+function parseObject<T>(text: string): T | undefined {
+  const trimmed = text.trim()
+  if (trimmed === '' || trimmed === 'null') return undefined
+  if (!trimmed.startsWith('{')) return undefined
+  try {
+    return JSON.parse(trimmed) as T
+  } catch {
+    return undefined
+  }
+}
+
+/** Mark an over-long line the reader cut, so the model knows it is incomplete. */
+function annotateCutLine(text: string): string {
+  return text.length > READ_MAX_LINE_LENGTH
+    ? `${text.slice(0, READ_MAX_LINE_LENGTH)}… (line truncated to ${READ_MAX_LINE_LENGTH} chars)`
+    : text
+}
+
+/** Encode text for a remote write, applying the requested byte-order mark. */
+function encodeText(content: string, encoding: RemoteTextEncoding): Buffer {
+  const body = Buffer.from(content, 'utf8')
+  if (encoding === 'utf8bom') return Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), body])
+  if (encoding === 'utf16le') return Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(content, 'utf16le')])
+  return body
+}
+
 /** A tiny per-alias in-flight limiter so GUI bursts do not pile up sockets. */
 class AliasGate {
   private queues = new Map<string, Promise<void>>()
@@ -233,6 +282,167 @@ export class WinRmEngine {
     })
   }
 
+  // ------------------------------------------------------------------ text
+
+  /**
+   * Read a bounded, line-numbered window of a remote text file.
+   *
+   * One PowerShell round trip: the remote side decodes the file, counts every
+   * line, and returns only the requested window, so a large log costs one
+   * transfer of the window rather than of the file.
+   * @param alias - configured host.
+   * @param remotePath - path on the target.
+   * @param offset - 1-based first line to return.
+   * @param limit - maximum number of lines to return.
+   * @returns the window plus the file's total line count and encoding.
+   */
+  async readFile(alias: string, remotePath: string, offset: number, limit: number): Promise<RemoteTextWindow> {
+    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),
+        psReadTextWindow(remotePath, offset, limit, READ_MAX_LINE_LENGTH, READ_MAX_BYTES),
+        { timeoutMs: 120_000 },
+      )
+      const payload = parseObject<{
+        exists?: boolean
+        error?: string
+        size?: number
+        encoding?: string
+        totalLines?: number
+        lineCount?: number
+        truncated?: boolean
+        truncatedByBytes?: boolean
+        linesText?: string
+      }>(result.stdout)
+      if (payload === undefined) {
+        throw new Error(result.stderr.trim() || result.stdout.trim() || `failed to read '${remotePath}'`)
+      }
+      if (payload.error !== undefined) {
+        throw new Error(`${remotePath}: ${payload.error} (the reader decodes UTF-8 and UTF-16 with a BOM; a binary file has no line structure to show)`)
+      }
+      if (payload.exists !== true) throw new Error(`remote file not found: ${remotePath}`)
+      const totalLines = payload.totalLines ?? 0
+      const lineCount = payload.lineCount ?? 0
+      // `truncated` also covers the byte budget, in which case the offset may
+      // legitimately point past what this window reached.
+      if (payload.truncated !== true && offset > totalLines && totalLines > 0) {
+        throw new Error(`offset ${offset} is out of range for '${remotePath}' (${totalLines} lines)`)
+      }
+      const texts = lineCount === 0 ? [] : (payload.linesText ?? '').split('\n')
+      return {
+        path: remotePath,
+        offset,
+        lines: texts.map((text, index) => ({ number: offset + index, text: annotateCutLine(text) })),
+        totalLines,
+        encoding: payload.encoding ?? 'utf8',
+        // Counted before annotation so the card can say how many lines it cut
+        // without the client pattern-matching the annotation suffix.
+        truncatedLines: texts.filter(text => text.length > READ_MAX_LINE_LENGTH).length,
+        truncatedByBytes: payload.truncatedByBytes === true,
+      }
+    })
+  }
+
+  /**
+   * Write a whole remote text file, creating parent directories as needed.
+   *
+   * Reuses the transfer transport (single streamed stdin when available, the
+   * 48 KiB chunk path otherwise) so a large write does not pay one shell cycle
+   * per chunk.
+   * @param alias - configured host.
+   * @param remotePath - path on the target; overwritten when it exists.
+   * @param content - UTF-8 text to write.
+   * @param encoding - byte-order mark to emit (`utf8`, `utf8bom`, `utf16le`).
+   * @returns the operation kind, byte count, encoding written, and both texts
+   *   the diff card compares.
+   */
+  async writeFile(alias: string, remotePath: string, content: string, encoding: RemoteTextEncoding): Promise<RemoteWriteOutcome> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) throw new Error(`alias '${alias}' not found`)
+    const data = encodeText(content, encoding)
+    return this.gate.run(alias, async () => {
+      const conn = connOf(entry)
+      const previous = await remoteFileSize(conn, remotePath)
+      // The diff card compares the previous text with the new one, so the prior
+      // content is read before overwriting it. That costs one extra round trip,
+      // which is skipped for a create and for a file past the basis cap rather
+      // than trimmed to fit — a partial basis would make every line look edited.
+      let before: string | null = null
+      if (previous !== null && previous <= DIFF_BASIS_MAX_BYTES) {
+        const basis = await runScript(conn, psReadTextBasis(remotePath, DIFF_BASIS_MAX_BYTES), { timeoutMs: 60_000 })
+        const payload = parseObject<{ error?: string; tooLarge?: boolean; text?: string | null }>(basis.stdout)
+        if (payload !== undefined && payload.error === undefined && payload.tooLarge !== true && typeof payload.text === 'string') {
+          before = Buffer.from(payload.text, 'base64').toString('utf8')
+        }
+      }
+      let bytes = await uploadStream(conn, remotePath, data)
+      if (bytes === null) bytes = await uploadBuffer(conn, remotePath, data)
+      return {
+        path: remotePath,
+        operation: previous === null ? 'create' : 'update',
+        bytes,
+        encoding,
+        before,
+        after: content,
+      }
+    })
+  }
+
+  /**
+   * Replace `oldString` with `newString` inside a remote text file.
+   *
+   * The replacement is literal, never a pattern, and the file's existing
+   * encoding is preserved. Without `replaceAll` the edit is refused unless the
+   * needle is unique, so a stale needle cannot rewrite the wrong region.
+   * @param alias - configured host.
+   * @param remotePath - path on the target.
+   * @param oldString - exact text to find.
+   * @param newString - text to substitute.
+   * @param replaceAll - replace every occurrence instead of requiring one.
+   * @returns the replacement count, the file's new size, and both texts the
+   *   diff card compares.
+   */
+  async editFile(
+    alias: string,
+    remotePath: string,
+    oldString: string,
+    newString: string,
+    replaceAll: boolean,
+  ): Promise<RemoteEditOutcome> {
+    const entry = this.store.find(alias)
+    if (entry === undefined) throw new Error(`alias '${alias}' not found`)
+    if (oldString === '') throw new Error('oldString must be a non-empty string')
+    if (oldString === newString) throw new Error('oldString and newString are identical; nothing to change')
+    const oldB64 = Buffer.from(oldString, 'utf8').toString('base64')
+    const newB64 = Buffer.from(newString, 'utf8').toString('base64')
+    return this.gate.run(alias, async () => {
+      const result = await runScript(connOf(entry), psEditText(remotePath, oldB64, newB64, replaceAll, DIFF_BASIS_MAX_BYTES), { timeoutMs: 120_000 })
+      const payload = parseObject<{
+        error?: string
+        path?: string
+        encoding?: string
+        replacements?: number
+        size?: number
+        basis?: { before?: string; after?: string } | null
+      }>(result.stdout)
+      if (payload === undefined) {
+        throw new Error(result.stderr.trim() || result.stdout.trim() || `failed to edit '${remotePath}'`)
+      }
+      if (payload.error !== undefined) throw new Error(payload.error)
+      const basis = payload.basis ?? null
+      return {
+        path: payload.path ?? remotePath,
+        encoding: payload.encoding ?? 'utf8',
+        replacements: payload.replacements ?? 0,
+        size: payload.size ?? 0,
+        before: basis === null ? null : Buffer.from(basis.before ?? '', 'base64').toString('utf8'),
+        after: basis === null ? null : Buffer.from(basis.after ?? '', 'base64').toString('utf8'),
+      }
+    })
+  }
+
   // -------------------------------------------------------------- transfer
 
   /** Upload one local file to a remote path. Defaults to SMB with WinRM fallback. */
@@ -326,6 +536,7 @@ export class WinRmEngine {
       const report = (transferred: number, total: number): void => {
         onProgress?.({ phase: 'transferring', file: remotePath, transferred, total, percent: total > 0 ? Math.round((transferred / total) * 1000) / 10 : 0 })
       }
+      let delivered = 0
       try {
         const conn = connOf(entry)
         const streamed = await downloadStream(conn, remotePath, put, report)
@@ -341,6 +552,12 @@ export class WinRmEngine {
             },
             report,
           )
+          delivered = bytes
+        } else {
+          // `bytes` counts every positional write, and a retry re-sends the
+          // ranges from their start — so it would report more than the file
+          // holds. The successful attempt's own total is the file size.
+          delivered = streamed
         }
         await queue
         // A zero-byte remote file produces no writes, so the sink is still
@@ -360,8 +577,8 @@ export class WinRmEngine {
         // already truncated that file to nothing.
         if (!completed && sink !== null) await rm(localPath, { force: true }).catch(() => undefined)
       }
-      onProgress?.({ phase: 'done', file: remotePath, transferred: bytes, total: bytes, percent: 100 })
-      return { bytes, channel: 'winrm' }
+      onProgress?.({ phase: 'done', file: remotePath, transferred: delivered, total: delivered, percent: 100 })
+      return { bytes: delivered, channel: 'winrm' }
     })
   }
 

package/src/index.ts

@@ -3,8 +3,9 @@
  * execution with a UTF-8 envelope, streaming console, service/process
  * management, streamed 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
+ * (winrm_list, winrm_exec, winrm_service, winrm_process, winrm_read,
+ * winrm_write, winrm_edit, 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.
  *
@@ -27,11 +28,14 @@ import { HostStore } from './store.ts'
 import {
   winrmClusterTool,
   winrmDownloadTool,
+  winrmEditTool,
   winrmExecTool,
   winrmListTool,
   winrmProcessTool,
+  winrmReadTool,
   winrmServiceTool,
   winrmUploadTool,
+  winrmWriteTool,
 } from './tools.ts'
 import { mountOnce } from './mount-once.ts'
 
@@ -64,7 +68,7 @@ const DEFAULT_ENABLED = true
 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 文件传输（SMB 管理共享可达时优先，否则走 WinRM 流式传输，无 SMB 依赖，大文件经 SHA256 校验）、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 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。'
+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_read/winrm_write/winrm_edit 远程文本文件读写（按行分页、编码感知、精确串替换，作用于远端主机而非本机，本机文件仍用 read/write/edit）、winrm_upload/winrm_download 文件传输（channel=auto 时若目标 445 可达走 SMB 管理共享，否则走 WinRM 流式传输；channel=smb 在 445 关闭时直接报错、需改用 winrm；大文件可下载，流式通道按字节持续推进、仅在字节断流时才判超时、完成后经 SHA256 校验）、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.
@@ -88,6 +92,9 @@ function applyImpl(ctx: Context, config?: Config): void {
     winrmExecTool(engine),
     winrmServiceTool(engine),
     winrmProcessTool(engine),
+    winrmReadTool(engine),
+    winrmWriteTool(engine),
+    winrmEditTool(engine),
     winrmUploadTool(engine),
     winrmDownloadTool(engine),
     winrmClusterTool(engine),

package/src/powershell.ts

@@ -343,6 +343,259 @@ export function psWriteChunk(p: string, b64: string, append: boolean): string {
   ].join('\r\n')
 }
 
+/**
+ * JSON: one bounded, line-numbered window of a remote TEXT file.
+ *
+ * Decodes UTF-8 (with or without BOM), UTF-16LE and UTF-16BE by BOM, and
+ * rejects invalid UTF-8 instead of returning mojibake — a binary file fails
+ * loudly rather than as unreadable text. Lines are numbered from 1 over the
+ * whole file, `offset` selects the first returned line, and the window stops
+ * early once the joined text would exceed `maxBytes` (reported as
+ * `truncated`, so the caller knows more lines remain). A line longer than
+ * `maxLineLength` is cut to `maxLineLength + 1` code units here; the Node half
+ * appends the truncation note.
+ *
+ * A missing path or a directory emits `{"exists":false}`; anything the reader
+ * rejects emits `{"error":…}`. Both keep the exit code at 0 so the caller
+ * always receives parseable JSON rather than a PowerShell error record.
+ * @param p - remote path.
+ * @param offset - 1-based first line to return.
+ * @param limit - maximum number of lines to return.
+ * @param maxLineLength - maximum characters kept per line.
+ * @param maxBytes - maximum UTF-8 bytes of joined line text.
+ * @returns the PowerShell fragment.
+ */
+export function psReadTextWindow(
+  p: string,
+  offset: number,
+  limit: number,
+  maxLineLength: number,
+  maxBytes: number,
+): string {
+  return [
+    '$__p = ' + sq(p),
+    '$__err = $null',
+    '$__json = $null',
+    'try {',
+    '  $__i = Get-Item -LiteralPath $__p -ErrorAction SilentlyContinue',
+    '  if ($null -eq $__i -or $__i.PSIsContainer) {',
+    '    $__json = [pscustomobject]@{ exists = $false } | ConvertTo-Json -Compress',
+    '  } else {',
+    '    $__fs = [System.IO.File]::OpenRead($__p)',
+    '    try {',
+    '      $__b0 = New-Object byte[] 3',
+    '      $__n0 = $__fs.Read($__b0, 0, 3)',
+    '      $__fs.Position = 0',
+    "      $__enc = 'utf8'",
+    '      $__coding = New-Object System.Text.UTF8Encoding($false, $true)',
+    '      if ($__n0 -ge 2 -and $__b0[0] -eq 255 -and $__b0[1] -eq 254) {',
+    "        $__enc = 'utf16le'",
+    '        $__coding = [System.Text.Encoding]::Unicode',
+    '      } elseif ($__n0 -ge 2 -and $__b0[0] -eq 254 -and $__b0[1] -eq 255) {',
+    "        $__enc = 'utf16be'",
+    '        $__coding = [System.Text.Encoding]::BigEndianUnicode',
+    '      } elseif ($__n0 -ge 3 -and $__b0[0] -eq 239 -and $__b0[1] -eq 187 -and $__b0[2] -eq 191) {',
+    "        $__enc = 'utf8bom'",
+    '      }',
+    '      $__r = New-Object System.IO.StreamReader($__fs, $__coding, $true)',
+    '      try {',
+    '        $__total = 0',
+    '        $__sel = New-Object System.Collections.ArrayList',
+    '        $__used = 0',
+    '        $__cut = $false',
+    '        $__bytes = $false',
+    '        while ($null -ne ($__line = $__r.ReadLine())) {',
+    '          $__total++',
+    '          if ($__cut) { continue }',
+    '          if ($__total -lt ' + String(offset) + ') { continue }',
+    '          if ($__sel.Count -ge ' + String(limit) + ') { $__cut = $true; continue }',
+    '          $__t = $__line',
+    '          if ($__t.Length -gt ' + String(maxLineLength + 1) + ') { $__t = $__t.Substring(0, ' + String(maxLineLength + 1) + ') }',
+    '          $__b = [System.Text.Encoding]::UTF8.GetByteCount($__t)',
+    '          if ($__sel.Count -gt 0) { $__b++ }',
+    '          if ($__used + $__b -gt ' + String(maxBytes) + ') { $__cut = $true; $__bytes = $true; continue }',
+    '          $__used += $__b',
+    '          [void]$__sel.Add($__t)',
+    '        }',
+    '      } finally { $__r.Dispose() }',
+    '    } finally { $__fs.Dispose() }',
+    '    $__json = [pscustomobject]@{',
+    '      exists = $true',
+    '      size = [long]$__i.Length',
+    '      encoding = $__enc',
+    '      totalLines = $__total',
+    '      lineCount = $__sel.Count',
+    '      truncated = $__cut',
+    '      truncatedByBytes = $__bytes',
+    '      linesText = (($__sel | ForEach-Object { [string]$_ }) -join "`n")',
+    '    } | ConvertTo-Json -Compress -Depth 3',
+    '  }',
+    '} catch { $__err = $_.Exception.GetBaseException().Message }',
+    'if ($null -ne $__err) { [pscustomobject]@{ error = $__err } | ConvertTo-Json -Compress }',
+    'else { $__json }',
+    '',
+  ].join('\r\n')
+}
+
+/**
+ * JSON: replace `oldB64` with `newB64` (both UTF-8, base64-carried) in a remote
+ * text file, preserving its encoding and writing through the same file.
+ *
+ * The search is ordinal and never pattern-based, so a replacement cannot be
+ * reinterpreted as a regular expression. Without `replaceAll` the edit is
+ * refused unless the needle appears exactly once, which is what keeps a stale
+ * or too-short needle from rewriting the wrong region. The file is read whole,
+ * so this is meant for source files and configuration, not for multi-hundred-
+ * megabyte logs.
+ *
+ * Failures (missing file, absent needle, ambiguous needle, undecodable bytes)
+ * are reported as `{"error":…}` with exit code 0 so the caller always receives
+ * parseable JSON.
+ * @param p - remote path.
+ * @param oldB64 - base64 of the UTF-8 text to find.
+ * @param newB64 - base64 of the UTF-8 text to substitute.
+ * @param replaceAll - replace every occurrence instead of requiring exactly one.
+ * @param basisMaxBytes - include the before/after text when the original file is
+ *   at most this large; `0` omits the basis entirely.
+ * @returns the PowerShell fragment.
+ */
+export function psEditText(p: string, oldB64: string, newB64: string, replaceAll: boolean, basisMaxBytes = 0): string {
+  // Only the selected mode is emitted. The two bodies fail differently, and
+  // shipping the unused one would leave a message in the script that can never
+  // fire — which reads like a live rule to anyone auditing the wire.
+  const branch = replaceAll
+    ? [
+        '  $__count = [int](($__text.Length - $__text.Replace($__old, [string]::Empty).Length) / $__old.Length)',
+        "  if ($__count -eq 0) { throw ('oldString was not found in ' + $__p) }",
+        '  $__out = $__text.Replace($__old, $__new)',
+      ]
+    : [
+        '  $__at = $__text.IndexOf($__old, [System.StringComparison]::Ordinal)',
+        "  if ($__at -lt 0) { throw ('oldString was not found in ' + $__p) }",
+        '  if ($__text.IndexOf($__old, $__at + 1, [System.StringComparison]::Ordinal) -ge 0) {',
+        "    throw ('oldString appears more than once in ' + $__p + '; pass replaceAll=true or include more surrounding context')",
+        '  }',
+        '  $__out = $__text.Substring(0, $__at) + $__new + $__text.Substring($__at + $__old.Length)',
+        '  $__count = 1',
+      ]
+  // A zero cap means the caller does not want a diff basis; emit a literal
+  // `if ($false)` rather than a comparison that would still read a large file.
+  const basisGuard = basisMaxBytes > 0 ? `[long]$__i.Length -le ${basisMaxBytes}` : '$false'
+  return [
+    '$__p = ' + sq(p),
+    '$__err = $null',
+    '$__json = $null',
+    'try {',
+    '  $__i = Get-Item -LiteralPath $__p -ErrorAction SilentlyContinue',
+    "  if ($null -eq $__i -or $__i.PSIsContainer) { throw ('remote file not found: ' + $__p) }",
+    '  $__old = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String(' + sq(oldB64) + '))',
+    '  $__new = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String(' + sq(newB64) + '))',
+    '  if ($__old.Length -eq 0) { throw ' + sq('oldString must be a non-empty string') + ' }',
+    '  $__fs = [System.IO.File]::OpenRead($__p)',
+    '  try {',
+    '    $__b0 = New-Object byte[] 3',
+    '    $__n0 = $__fs.Read($__b0, 0, 3)',
+    '    $__fs.Position = 0',
+    "    $__enc = 'utf8'",
+    '    $__coding = New-Object System.Text.UTF8Encoding($false, $true)',
+    '    if ($__n0 -ge 2 -and $__b0[0] -eq 255 -and $__b0[1] -eq 254) {',
+    "      $__enc = 'utf16le'",
+    '      $__coding = [System.Text.Encoding]::Unicode',
+    '    } elseif ($__n0 -ge 2 -and $__b0[0] -eq 254 -and $__b0[1] -eq 255) {',
+    "      $__enc = 'utf16be'",
+    '      $__coding = [System.Text.Encoding]::BigEndianUnicode',
+    '    } elseif ($__n0 -ge 3 -and $__b0[0] -eq 239 -and $__b0[1] -eq 187 -and $__b0[2] -eq 191) {',
+    "      $__enc = 'utf8bom'",
+    '    }',
+    '    $__r = New-Object System.IO.StreamReader($__fs, $__coding, $true)',
+    '    try { $__text = $__r.ReadToEnd() } finally { $__r.Dispose() }',
+    '  } finally { $__fs.Dispose() }',
+    ...branch,
+    '  if ($__enc -eq "utf8bom") { [System.IO.File]::WriteAllText($__p, $__out, (New-Object System.Text.UTF8Encoding($true))) }',
+    '  elseif ($__enc -eq "utf16le") { [System.IO.File]::WriteAllText($__p, $__out, [System.Text.Encoding]::Unicode) }',
+    '  elseif ($__enc -eq "utf16be") { [System.IO.File]::WriteAllText($__p, $__out, [System.Text.Encoding]::BigEndianUnicode) }',
+    '  else { [System.IO.File]::WriteAllText($__p, $__out, (New-Object System.Text.UTF8Encoding($false))) }',
+    '  $__basis = $null',
+    '  if (' + basisGuard + ') {',
+    '    $__basis = [pscustomobject]@{',
+    '      before = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($__text))',
+    '      after = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($__out))',
+    '    }',
+    '  }',
+    '  $__json = [pscustomobject]@{',
+    '    path = $__p',
+    '    encoding = $__enc',
+    '    replacements = $__count',
+    '    size = [long](Get-Item -LiteralPath $__p).Length',
+    '    basis = $__basis',
+    '  } | ConvertTo-Json -Compress -Depth 3',
+    '} catch { $__err = $_.Exception.GetBaseException().Message }',
+    'if ($null -ne $__err) { [pscustomobject]@{ error = $__err } | ConvertTo-Json -Compress }',
+    'else { $__json }',
+    '',
+  ].join('\r\n')
+}
+
+/**
+ * JSON: the whole remote text file as base64, or a refusal when it is missing
+ * or larger than `maxBytes`.
+ *
+ * The write tool needs the previous text to project a diff card, and the line
+ * window reader cannot serve that: it numbers lines and caps each one, so a
+ * long line would silently truncate inside the diff basis. The BOM detection
+ * repeats {@link psEditText}'s on purpose — both must decode identically, and a
+ * shared emitter would hide that requirement behind a helper neither could be
+ * reviewed against.
+ *
+ * Failures are reported as `{"error":…}` with exit code 0, so the caller always
+ * receives parseable JSON.
+ * @param p - remote path.
+ * @param maxBytes - largest file whose text is returned.
+ * @returns the PowerShell fragment.
+ */
+export function psReadTextBasis(p: string, maxBytes: number): string {
+  return [
+    '$__p = ' + sq(p),
+    '$__err = $null',
+    '$__json = $null',
+    'try {',
+    '  $__i = Get-Item -LiteralPath $__p -ErrorAction SilentlyContinue',
+    "  if ($null -eq $__i -or $__i.PSIsContainer) { throw ('remote file not found: ' + $__p) }",
+    `  if ([long]$__i.Length -gt ${maxBytes}) {`,
+    '    $__json = [pscustomobject]@{ tooLarge = $true; encoding = $null; text = $null } | ConvertTo-Json -Compress',
+    '  } else {',
+    '    $__fs = [System.IO.File]::OpenRead($__p)',
+    '    try {',
+    '      $__b0 = New-Object byte[] 3',
+    '      $__n0 = $__fs.Read($__b0, 0, 3)',
+    '      $__fs.Position = 0',
+    "      $__enc = 'utf8'",
+    '      $__coding = New-Object System.Text.UTF8Encoding($false, $true)',
+    '      if ($__n0 -ge 2 -and $__b0[0] -eq 255 -and $__b0[1] -eq 254) {',
+    "        $__enc = 'utf16le'",
+    '        $__coding = [System.Text.Encoding]::Unicode',
+    '      } elseif ($__n0 -ge 2 -and $__b0[0] -eq 254 -and $__b0[1] -eq 255) {',
+    "        $__enc = 'utf16be'",
+    '        $__coding = [System.Text.Encoding]::BigEndianUnicode',
+    '      } elseif ($__n0 -ge 3 -and $__b0[0] -eq 239 -and $__b0[1] -eq 187 -and $__b0[2] -eq 191) {',
+    "        $__enc = 'utf8bom'",
+    '      }',
+    '      $__r = New-Object System.IO.StreamReader($__fs, $__coding, $true)',
+    '      try { $__text = $__r.ReadToEnd() } finally { $__r.Dispose() }',
+    '    } finally { $__fs.Dispose() }',
+    '    $__json = [pscustomobject]@{',
+    '      tooLarge = $false',
+    '      encoding = $__enc',
+    '      text = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($__text))',
+    '    } | ConvertTo-Json -Compress -Depth 3',
+    '  }',
+    '} catch { $__err = $_.Exception.GetBaseException().Message }',
+    'if ($null -ne $__err) { [pscustomobject]@{ error = $__err } | ConvertTo-Json -Compress }',
+    'else { $__json }',
+    '',
+  ].join('\r\n')
+}
+
 /** Magic stamped into the frame header that precedes every stream chunk. */
 export const STREAM_FRAME_MAGIC = 'DSHZ'
 

package/src/protocol.ts

@@ -96,6 +96,65 @@ export interface RemoteDirEntry {
   mtimeMs: number
 }
 
+/** One numbered line of a remote text file. */
+export interface RemoteTextLine {
+  /** 1-based line number within the remote file. */
+  number: number
+  /** Line text without its terminator; over-long lines are cut and annotated. */
+  text: string
+}
+
+/** Result of reading a bounded window of a remote text file. */
+export interface RemoteTextWindow {
+  path: string
+  /** 1-based line number of the first returned line. */
+  offset: number
+  lines: RemoteTextLine[]
+  /** Lines in the whole file, so the caller can page. */
+  totalLines: number
+  /** Detected encoding: `utf8`, `utf8bom`, `utf16le` or `utf16be`. */
+  encoding: string
+  /** True when the window stopped at the byte budget instead of at `limit`. */
+  truncatedByBytes: boolean
+  /** Lines whose text was cut at the per-line cap and annotated in `lines`. */
+  truncatedLines: number
+}
+
+/** Text encodings the writer can emit. */
+export type RemoteTextEncoding = 'utf8' | 'utf8bom' | 'utf16le'
+
+/** Result of writing a remote text file. */
+export interface RemoteWriteOutcome {
+  path: string
+  /** `create` when the path was absent, `update` when it was overwritten. */
+  operation: 'create' | 'update'
+  bytes: number
+  encoding: RemoteTextEncoding
+  /**
+   * Previous file text, or `null` for a create and for a file too large to
+   * serve as a diff basis. Only the presentation layer reads it.
+   */
+  before: string | null
+  /** Text after the write, on the same basis as {@link RemoteWriteOutcome.before}. */
+  after: string
+}
+
+/** Result of an in-place remote text edit. */
+export interface RemoteEditOutcome {
+  path: string
+  /** Encoding the file already had, preserved across the edit. */
+  encoding: string
+  replacements: number
+  size: number
+  /**
+   * File text before the edit, or `null` when the file was too large to serve
+   * as a diff basis. Only the presentation layer reads it.
+   */
+  before: string | null
+  /** Text after the edit, on the same basis as {@link RemoteEditOutcome.before}. */
+  after: string | null
+}
+
 /** One server entry in a cluster run. */
 export interface ClusterResult {
   alias: string

package/src/smb.ts

@@ -134,7 +134,10 @@ export async function smbReachable(host: string): Promise<boolean> {
 
 /** Error thrown when SMB was requested or probed and the target is not listening. */
 export function smbUnavailable(host: string): Error {
-  return new Error('SMB is not reachable on ' + host + ':445 (the admin share needs TCP 445 open and the Server service running)')
+  return new Error(
+    'SMB is not reachable on ' + host + ':445 (the admin share needs TCP 445 open and the Server service running); '
+    + 'retry with channel "winrm" to transfer over WinRM instead',
+  )
 }
 
 /**