dsh-winrm 0.3.1 → 0.4.0

package/lib/index.js

@@ -322,6 +322,243 @@ function psWriteChunk(p, b64, append) {
 		""
 	].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.
+*/
+function psReadTextWindow(p, offset, limit, maxLineLength, maxBytes) {
+	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.
+*/
+function psEditText(p, oldB64, newB64, replaceAll, basisMaxBytes = 0) {
+	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"
+	];
+	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.
+*/
+function psReadTextBasis(p, maxBytes) {
+	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. */
 const STREAM_FRAME_MAGIC = "DSHZ";
 /** Remote-side buffer used while draining stdin (or inflating a frame) into the file. */
@@ -1663,14 +1900,125 @@ var ConsoleSession = class {
 		this.onExit?.(code, error);
 	}
 };
+/**
+* Largest file whose text may serve as a diff basis. Above this the card shows
+* the path and operation without hunks: fetching and projecting a bigger basis
+* would cost another transfer and a large metadata payload for a summary the
+* user reads at a glance.
+*/
+const DIFF_BASIS_MAX_BYTES = 256 * 1024;
+/** Split text into lines, treating every terminator as a separator. */
+function toLines(text) {
+	return text === "" ? [] : text.split(/\r?\n/);
+}
+/**
+* Compute the hunks between two texts.
+* @param path - remote path stamped on every hunk.
+* @param before - file text before the change.
+* @param after - file text after the change.
+* @returns one hunk per contiguous change in file order; empty when equal.
+*/
+function computeHunkDiffs(path, before, after) {
+	if (before === after) return [];
+	const oldLines = toLines(before);
+	const newLines = toLines(after);
+	let head = 0;
+	while (head < oldLines.length && head < newLines.length && oldLines[head] === newLines[head]) head += 1;
+	let tail = 0;
+	while (tail < oldLines.length - head && tail < newLines.length - head && oldLines[oldLines.length - 1 - tail] === newLines[newLines.length - 1 - tail]) tail += 1;
+	const oldMid = oldLines.slice(head, oldLines.length - tail);
+	const newMid = newLines.slice(head, newLines.length - tail);
+	/** Build one hunk around the changed range `[from, to)` in the middle. */
+	const emit = (from, to) => {
+		const start = Math.max(0, from - 3);
+		const stop = Math.min(oldMid.length, to + 3);
+		return {
+			path,
+			oldText: oldLines.slice(head + start, head + stop).join("\n"),
+			newText: newLines.slice(head + start, head + stop).join("\n")
+		};
+	};
+	if (oldMid.length !== newMid.length) return [{
+		path,
+		oldText: oldLines.slice(Math.max(0, head - 3), oldLines.length - Math.max(0, tail - 3)).join("\n"),
+		newText: newLines.slice(Math.max(0, head - 3), newLines.length - Math.max(0, tail - 3)).join("\n")
+	}];
+	const diffs = [];
+	let index = 0;
+	while (index < oldMid.length) {
+		if (oldMid[index] === newMid[index]) {
+			index += 1;
+			continue;
+		}
+		const from = index;
+		while (index < oldMid.length && oldMid[index] !== newMid[index]) index += 1;
+		diffs.push(emit(from, index));
+	}
+	return diffs;
+}
+/**
+* Compute hunks and drop them when the serialized payload would exceed the cap.
+* @param path - remote path stamped on every hunk.
+* @param before - prior text.
+* @param after - text after the change.
+* @returns the kept hunks; empty when nothing changed or the payload is too big.
+*/
+function boundedHunkDiffs(path, before, after) {
+	const diffs = computeHunkDiffs(path, before, after);
+	if (diffs.length === 0) return diffs;
+	return JSON.stringify(diffs).length > 524288 ? [] : diffs;
+}
 //#endregion
 //#region src/engine.ts
+/** Longest single line the reader returns before cutting it (characters). */
+const READ_MAX_LINE_LENGTH = 2e3;
+/** Lines the reader returns when the caller does not choose a page size. */
+const READ_DEFAULT_LIMIT = 2e3;
+/** Most lines the reader will return in one call. */
+const READ_MAX_LIMIT = 5e3;
+/** Byte budget for one read window; keeps the envelope well under the transport limit. */
+const READ_MAX_BYTES = 512 * 1024;
 /** JSON-safe parse of the envelope output into a typed value. */
 function parseJson(text) {
 	const trimmed = text.trim();
 	if (trimmed === "" || trimmed === "null") return [];
 	return JSON.parse(trimmed);
 }
+/**
+* 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(text) {
+	const trimmed = text.trim();
+	if (trimmed === "" || trimmed === "null") return void 0;
+	if (!trimmed.startsWith("{")) return void 0;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return;
+	}
+}
+/** Mark an over-long line the reader cut, so the model knows it is incomplete. */
+function annotateCutLine(text) {
+	return text.length > 2e3 ? `${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, encoding) {
+	const body = Buffer.from(content, "utf8");
+	if (encoding === "utf8bom") return Buffer.concat([Buffer.from([
+		239,
+		187,
+		191
+	]), body]);
+	if (encoding === "utf16le") return Buffer.concat([Buffer.from([255, 254]), Buffer.from(content, "utf16le")]);
+	return body;
+}
 /** A tiny per-alias in-flight limiter so GUI bursts do not pile up sockets. */
 var AliasGate = class {
 	queues = /* @__PURE__ */ new Map();
@@ -1844,6 +2192,119 @@ var WinRmEngine = class {
 			}));
 		});
 	}
+	/**
+	* 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, remotePath, offset, limit) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) 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: 12e4 });
+			const payload = parseObject(result.stdout);
+			if (payload === void 0) throw new Error(result.stderr.trim() || result.stdout.trim() || `failed to read '${remotePath}'`);
+			if (payload.error !== void 0) 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;
+			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",
+				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, remotePath, content, encoding) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) 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);
+			let before = null;
+			if (previous !== null && previous <= 262144) {
+				const payload = parseObject((await runScript(conn, psReadTextBasis(remotePath, DIFF_BASIS_MAX_BYTES), { timeoutMs: 6e4 })).stdout);
+				if (payload !== void 0 && payload.error === void 0 && 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, remotePath, oldString, newString, replaceAll) {
+		const entry = this.store.find(alias);
+		if (entry === void 0) 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: 12e4 });
+			const payload = parseObject(result.stdout);
+			if (payload === void 0) throw new Error(result.stderr.trim() || result.stdout.trim() || `failed to edit '${remotePath}'`);
+			if (payload.error !== void 0) 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")
+			};
+		});
+	}
 	/** Upload one local file to a remote path. Defaults to SMB with WinRM fallback. */
 	async upload(alias, localPath, remotePath, onProgress, channel = "auto") {
 		const entry = this.store.find(alias);
@@ -3373,6 +3834,368 @@ function winrmClusterTool(engine) {
 		}
 	});
 }
+/** Render a read window in the numbered envelope the local read tool uses. */
+function renderWindow(window) {
+	const lines = window.lines ?? [];
+	const offset = window.offset ?? 1;
+	const total = window.totalLines ?? 0;
+	const last = offset + lines.length - 1;
+	const body = lines.map((line) => `${line.number}: ${line.text}`).join("\n");
+	const encoding = window.encoding !== void 0 && window.encoding !== "utf8" ? `, encoding ${window.encoding}` : "";
+	let footer;
+	if (lines.length === 0) footer = total === 0 ? `(End of file - total 0 lines${encoding})` : `(No lines at offset ${offset}; the file has ${total} lines${encoding}.)`;
+	else if (window.truncatedByBytes === true) footer = `(Showing lines ${offset}-${last} of ${total}${encoding}. The window stopped at the byte budget — continue with offset=${last + 1}.)`;
+	else if (last < total) footer = `(Showing lines ${offset}-${last} of ${total}${encoding}. Continue with offset=${last + 1}.)`;
+	else footer = `(End of file - total ${total} lines${encoding})`;
+	const content = body === "" ? footer : `${body}\n\n${footer}`;
+	return [
+		`<path>${window.path ?? ""}</path>`,
+		"<type>file</type>",
+		"<content>",
+		content,
+		"</content>"
+	].join("\n");
+}
+/** The remote read tool: a line-numbered window of a text file on the target. */
+function winrmReadTool(engine) {
+	return defineTool({
+		name: "winrm_read",
+		description: "Read a text file ON A REMOTE Windows host and return its content line-numbered. The path is on the Windows host, not this machine — use `read` for local files. Decodes UTF-8 (with or without BOM) and UTF-16 with a BOM, and refuses binary files instead of returning mojibake. Page through large files with offset and limit. Triggers: read file on Windows server, inspect remote config/log/script.",
+		parameters: {
+			alias: {
+				type: "string",
+				required: true,
+				description: "Host alias from winrm_list."
+			},
+			remotePath: {
+				type: "string",
+				required: true,
+				description: "Path on the remote host, e.g. C:\\temp\\app.log."
+			},
+			offset: {
+				type: "integer",
+				description: "1-based first line to return. Defaults to 1."
+			},
+			limit: {
+				type: "integer",
+				description: `Maximum lines to return (default ${READ_DEFAULT_LIMIT}, max ${READ_MAX_LIMIT}).`
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					path: { type: "string" },
+					offset: { type: "integer" },
+					lines: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								number: {
+									type: "integer",
+									required: true
+								},
+								text: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					},
+					totalLines: { type: "integer" },
+					encoding: { type: "string" },
+					truncatedByBytes: { type: "boolean" },
+					truncatedLines: { type: "integer" },
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => text(value.ok ? renderWindow(value) : `read failed: ${value.error ?? "unknown error"}`),
+			presentationMeta: (args, value) => value.ok ? {
+				card: "winrm-read",
+				path: value.path ?? args.remotePath,
+				offset: value.offset ?? 1,
+				lines: value.lines ?? [],
+				totalLines: value.totalLines ?? 0,
+				encoding: value.encoding ?? "utf8",
+				truncatedByBytes: value.truncatedByBytes === true,
+				truncatedLines: value.truncatedLines ?? 0,
+				error: ""
+			} : {
+				card: "winrm-read",
+				path: args.remotePath,
+				offset: 0,
+				lines: [],
+				totalLines: 0,
+				encoding: "",
+				truncatedByBytes: false,
+				truncatedLines: 0,
+				error: value.error ?? "unknown error"
+			}
+		},
+		async execute(args) {
+			const offset = Math.max(1, Math.trunc(args.offset ?? 1));
+			const limit = Math.min(READ_MAX_LIMIT, Math.max(1, Math.trunc(args.limit ?? 2e3)));
+			try {
+				return {
+					ok: true,
+					...await engine.readFile(args.alias, args.remotePath, offset, limit)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		}
+	});
+}
+/** The remote write tool: replace a whole text file on the target. */
+function winrmWriteTool(engine) {
+	return defineTool({
+		name: "winrm_write",
+		description: "Write a text file ON A REMOTE Windows host, creating parent directories and overwriting any existing file. The path is on the Windows host, not this machine — use `write` for local files, and prefer winrm_edit when only part of an existing file changes. Line endings are sent verbatim, so include \\r\\n for a Windows-native file. The encoding is whatever `encoding` asks for — rewriting an existing utf16le or utf8bom file without setting it converts the file to plain UTF-8; `winrm_read` names a non-UTF-8 file in its footer when you need to match one. Triggers: write file on Windows server, create remote script/config, overwrite remote file.",
+		parameters: {
+			alias: {
+				type: "string",
+				required: true,
+				description: "Host alias from winrm_list."
+			},
+			remotePath: {
+				type: "string",
+				required: true,
+				description: "Destination path on the remote host, e.g. C:\\temp\\script.ps1 (parent dirs are created)."
+			},
+			content: {
+				type: "string",
+				required: true,
+				description: "Full file content."
+			},
+			encoding: {
+				type: "string",
+				enum: [
+					"utf8",
+					"utf8bom",
+					"utf16le"
+				],
+				description: "Byte-order mark to emit: utf8 (default, no BOM), utf8bom, or utf16le (PowerShell 5.1 reads a BOM-less script as ANSI, so non-ASCII script text needs a BOM). Does not preserve the existing file's encoding — pass it explicitly when overwriting a UTF-16 or BOM-carrying file."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					path: { type: "string" },
+					operation: {
+						type: "string",
+						enum: ["create", "update"]
+					},
+					bytes: { type: "integer" },
+					encoding: {
+						type: "string",
+						enum: [
+							"utf8",
+							"utf8bom",
+							"utf16le"
+						]
+					},
+					diffs: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								path: {
+									type: "string",
+									required: true
+								},
+								oldText: {
+									type: "string",
+									required: true
+								},
+								newText: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					},
+					beyondBasis: { type: "boolean" },
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => text(value.ok ? [
+				`<path>${value.path ?? ""}</path>`,
+				"<type>file</type>",
+				"<content>",
+				`${value.operation === "update" ? "Updated" : "Created"} file (${value.bytes ?? 0} bytes)`,
+				"</content>"
+			].join("\n") : `write failed: ${value.error ?? "unknown error"}`),
+			presentationMeta: (args, value) => value.ok ? {
+				card: "winrm-write",
+				path: value.path ?? args.remotePath,
+				operation: value.operation ?? "update",
+				bytes: value.bytes ?? 0,
+				encoding: value.encoding ?? "utf8",
+				diffs: value.diffs ?? [],
+				beyondBasis: value.beyondBasis === true,
+				error: ""
+			} : {
+				card: "winrm-write",
+				path: args.remotePath,
+				operation: "update",
+				bytes: 0,
+				encoding: "",
+				diffs: [],
+				beyondBasis: false,
+				error: value.error ?? "unknown error"
+			}
+		},
+		async execute(args) {
+			try {
+				const outcome = await engine.writeFile(args.alias, args.remotePath, args.content, args.encoding ?? "utf8");
+				const diffs = outcome.before !== null ? boundedHunkDiffs(outcome.path, outcome.before, outcome.after) : outcome.operation === "create" ? boundedHunkDiffs(outcome.path, "", outcome.after) : [];
+				return {
+					ok: true,
+					path: outcome.path,
+					operation: outcome.operation,
+					bytes: outcome.bytes,
+					encoding: outcome.encoding,
+					diffs,
+					beyondBasis: outcome.operation === "update" && outcome.before === null
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		}
+	});
+}
+/** The remote edit tool: replace an exact string inside a file on the target. */
+function winrmEditTool(engine) {
+	return defineTool({
+		name: "winrm_edit",
+		description: "Replace an exact string in a text file ON A REMOTE Windows host, preserving the file encoding. The path is on the Windows host, not this machine — use `edit` for local files. `oldString` must match the file byte for byte, including indentation and line endings, and must be unique unless `replaceAll` is set; read the file with winrm_read first. Triggers: edit file on Windows server, patch remote config, change remote script.",
+		parameters: {
+			alias: {
+				type: "string",
+				required: true,
+				description: "Host alias from winrm_list."
+			},
+			remotePath: {
+				type: "string",
+				required: true,
+				description: "Path on the remote host, e.g. C:\\temp\\app.config."
+			},
+			oldString: {
+				type: "string",
+				required: true,
+				description: "Exact text to replace. Must not be empty."
+			},
+			newString: {
+				type: "string",
+				required: true,
+				description: "Replacement text. Must differ from oldString."
+			},
+			replaceAll: {
+				type: "boolean",
+				description: "Replace every occurrence instead of requiring exactly one. Defaults to false."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					path: { type: "string" },
+					encoding: { type: "string" },
+					replacements: { type: "integer" },
+					size: { type: "integer" },
+					diffs: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								path: {
+									type: "string",
+									required: true
+								},
+								oldText: {
+									type: "string",
+									required: true
+								},
+								newText: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					},
+					beyondBasis: { type: "boolean" },
+					error: { type: "string" }
+				}
+			},
+			render: (_args, value) => text(value.ok ? (value.replacements ?? 0) > 1 ? `The file ${value.path ?? ""} has been updated. All ${value.replacements ?? 0} occurrences were successfully replaced.` : `The file ${value.path ?? ""} has been updated successfully.` : `edit failed: ${value.error ?? "unknown error"}`),
+			presentationMeta: (args, value) => value.ok ? {
+				card: "winrm-edit",
+				path: value.path ?? args.remotePath,
+				replacements: value.replacements ?? 0,
+				size: value.size ?? 0,
+				encoding: value.encoding ?? "utf8",
+				diffs: value.diffs ?? [],
+				beyondBasis: value.beyondBasis === true,
+				error: ""
+			} : {
+				card: "winrm-edit",
+				path: args.remotePath,
+				replacements: 0,
+				size: 0,
+				encoding: "",
+				diffs: [],
+				beyondBasis: false,
+				error: value.error ?? "unknown error"
+			}
+		},
+		async execute(args) {
+			try {
+				const outcome = await engine.editFile(args.alias, args.remotePath, args.oldString, args.newString, args.replaceAll ?? false);
+				const diffs = outcome.before !== null && outcome.after !== null ? boundedHunkDiffs(outcome.path, outcome.before, outcome.after) : [];
+				return {
+					ok: true,
+					path: outcome.path,
+					encoding: outcome.encoding,
+					replacements: outcome.replacements,
+					size: outcome.size,
+					diffs,
+					beyondBasis: outcome.before === null
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		}
+	});
+}
 //#endregion
 //#region src/mount-once.ts
 /**
@@ -3435,7 +4258,7 @@ 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. */
-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 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。";
+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 文件传输（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 远程 / 服务管理 / 进程管理」时即指本插件，请据此协作。";
 /**
 * Mount the WinRM engine, routes, tools, and announcement.
 * @param ctx - host plugin context carrying webServer/tools/systemPrompt.
@@ -3458,6 +4281,9 @@ function applyImpl(ctx, config) {
 		winrmExecTool(engine),
 		winrmServiceTool(engine),
 		winrmProcessTool(engine),
+		winrmReadTool(engine),
+		winrmWriteTool(engine),
+		winrmEditTool(engine),
 		winrmUploadTool(engine),
 		winrmDownloadTool(engine),
 		winrmClusterTool(engine)