dsh-winrm 0.1.1 → 0.3.0

package/lib/types/engine/client.d.ts

@@ -2,11 +2,11 @@
  * WinRM transport bridge.
  *
  * Runs each PowerShell payload over a native Node.js WinRM client
- * (winrm-client) — no Python/pywinrm subprocess. The script rides the
- * UTF-8 base64 envelope (marker + base64 of UTF-8 output) so Chinese and
- * any codepage output survives the WinRM transport losslessly; the envelope
- * is base64-encoded with `-EncodedCommand`, keeping the command line a
- * single ASCII-safe line that WinRS/cmd.exe cannot mangle.
+ * (winrm-client) — no Python/pywinrm subprocess. The script is delivered on
+ * the WinRS **stdin** stream and answers on the UTF-8 base64 envelope, so
+ * Chinese and any codepage output survives the transport losslessly and the
+ * command line stays a constant, ASCII-safe line that WinRS/cmd.exe cannot
+ * mangle. See powershell.ts for why the command line cannot carry the script.
  *
  * Auth is chosen per attempt (HTTPS: Basic first, then NTLM; HTTP: NTLM
  * first, then Basic) with fallback, so a host that only enables one scheme
@@ -44,6 +44,53 @@ export declare function testConnection(conn: WinRMParams): Promise<{
     error?: string;
 }>;
 export declare const TRANSFER_CHUNK: number;
-export declare function remoteFileSize(conn: WinRMParams, remotePath: string, timeoutMs?: number): Promise<number>;
+/**
+ * Size of a remote file, or null when the path does not exist or is a
+ * directory. The distinction matters: a caller that treats "absent" as "empty"
+ * writes an empty local file and reports success for a download that copied
+ * nothing.
+ */
+export declare function remoteFileSize(conn: WinRMParams, remotePath: string, timeoutMs?: number): Promise<number | null>;
 export declare function downloadChunks(conn: WinRMParams, remotePath: string, onChunk: (b64: string, bytes: number) => void, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number>;
 export declare function uploadBuffer(conn: WinRMParams, remotePath: string, data: Buffer, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number>;
+/**
+ * Upload a buffer over a single WinRS stdin stream.
+ *
+ * This replaces the per-chunk shell cycle: one shell, one command and one
+ * `Send` per 256 KiB, against a receiver that drains the stream straight into
+ * the file. Measured at ~10 s for 2 MiB where the old path took 310 s.
+ *
+ * Returns null — rather than throwing — when the transport this path depends
+ * on is unavailable (a future `winrm-client` layout that drops the internal
+ * module it borrows), so the caller can fall back to {@link uploadBuffer}
+ * instead of failing the transfer.
+ * @param conn - connection parameters.
+ * @param remotePath - destination path on the target.
+ * @param data - the file contents to send.
+ * @param onProgress - called with cumulative bytes after each frame.
+ * @param timeoutMs - whole-transfer budget.
+ * @returns bytes written, or null when the streaming path is unavailable.
+ */
+export declare function uploadStream(conn: WinRMParams, remotePath: string, data: Buffer, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number | null>;
+/**
+ * Stream a remote file to a consumer, in parallel byte ranges.
+ *
+ * The old path asked for 48 KiB per shell lifecycle, so a 2 MiB file cost 43
+ * round-trip cycles and 129 s. Measured against this target, one `Receive`
+ * returns at most 128 KiB no matter how large an envelope is declared, which
+ * makes a download latency-bound rather than bandwidth-bound; the fix is
+ * therefore to run several ranges at once. Each worker opens its own shell and
+ * streams its range gzip-compressed, and because ranges are absolute, the
+ * caller can place each piece by offset and completion order does not matter.
+ *
+ * The remote side compresses unconditionally: a compressible 16 MiB file
+ * arrives in one round trip (2.0 s), and an incompressible file was measured no
+ * slower than raw (9457 ms vs 9582 ms).
+ * @param conn - connection parameters.
+ * @param remotePath - file to read.
+ * @param onData - receives each decompressed piece with its absolute file offset.
+ * @param onProgress - receives cumulative bytes delivered and the total size.
+ * @param timeoutMs - budget for the whole download.
+ * @returns the number of bytes delivered, or null when streaming is unavailable.
+ */
+export declare function downloadStream(conn: WinRMParams, remotePath: string, onData: (offset: number, data: Buffer) => void, onProgress?: (transferred: number, total: number) => void, timeoutMs?: number): Promise<number | null>;

package/lib/types/engine/wsman.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Raw WSMan `Send` for the streaming upload path.
+ *
+ * The bundled `winrm-client` can only put text on the WinRS stdin stream: its
+ * `doSendInput` base64-encodes the input *again* on top of whatever the caller
+ * already encoded, and it has no way to close the stream. Both are fatal for a
+ * bulk transfer — double base64 costs 1.78x the bytes on the wire, and a
+ * stdin stream that never ends cannot tell the remote receiver "that is all".
+ *
+ * This module therefore builds the `Send` envelope itself and posts it through
+ * the library's own `sendHttp`, which keeps Basic/NTLM/SPNEGO and the HTTPS
+ * options exactly as the rest of the transport uses them. The stream carries
+ * raw file bytes, so the wire cost is 1.0x plus the envelope.
+ *
+ * The library is reached through `createRequire` rather than a static import
+ * because `dist/src/utils/http.js` is an internal CommonJS path with no
+ * `exports` map behind it. `loadSendHttp` returns null when that path is gone
+ * (a future `winrm-client` layout change), which lets the caller fall back to
+ * the old chunked path instead of failing the transfer.
+ */
+/** Connection parameters for one target (mirrors `WinRMParams` in client.ts). */
+export interface WsmanTarget {
+    host: string;
+    port: number;
+    path: string;
+    username: string;
+    password: string;
+    authMethod: 'basic' | 'ntlm';
+    useHttps?: boolean;
+    rejectUnauthorized?: boolean;
+}
+/** `sendHttp` as the bundled library declares it. */
+type SendHttp = (data: string, host: string, port: number, path: string, username: string, password: string, authMethod: 'basic' | 'ntlm', timeout?: number, useHttps?: boolean, rejectUnauthorized?: boolean) => Promise<unknown>;
+/**
+ * Envelope ceiling declared on every Send, in bytes.
+ *
+ * This is what the *client* promises the server it will never exceed, and the
+ * server enforces its own `MaxEnvelopeSizekb` on top. 512000 is the value the
+ * target host reports, and it is far above the library's hardcoded 153600 —
+ * raising it is what makes 256 KiB chunks legal.
+ */
+export declare const WS_MAX_ENVELOPE_BYTES = 512000;
+/**
+ * Bytes of XML wrapper around one base64 chunk.
+ *
+ * Measured against the envelope this module emits: fixed header, selector set,
+ * body tags and the message id. Used to size chunks against the ceiling before
+ * sending, so a normal transfer never needs a size rejection to converge.
+ */
+export declare const SEND_ENVELOPE_OVERHEAD_BYTES = 1600;
+/** The largest raw slice whose base64 form still fits `WS_MAX_ENVELOPE_BYTES`. */
+export declare const MAX_SEND_SLICE_BYTES: number;
+/**
+ * Resolve the library's `sendHttp`, or null when the internal path is absent.
+ * @returns the send function, or null when it cannot be loaded.
+ */
+export declare function loadSendHttp(): SendHttp | null;
+/**
+ * Build one WSMan `Send` envelope carrying `chunk` on the stdin stream.
+ *
+ * The header mirrors what the library emits, with three deliberate changes:
+ * `MaxEnvelopeSize` is raised to `limit`, the `Send` action replaces the
+ * command's, and the stream body is the caller's base64 verbatim — no second
+ * encode. `Name="stdin"` and `CommandId` are what bind the bytes to the
+ * running receiver's standard input.
+ * @param shellId - target shell from `Shell.doCreateShell`.
+ * @param commandId - target command from `Command.doExecuteCommand`.
+ * @param chunk - raw bytes to place on the remote stdin stream.
+ * @param limit - envelope ceiling to declare.
+ * @returns the SOAP envelope as a UTF-8 string.
+ */
+export declare function buildSendEnvelope(shellId: string, commandId: string, chunk: Buffer, limit: number): string;
+/**
+ * Push one raw slice onto the remote stdin stream.
+ *
+ * A rejection here is safe to retry with a smaller slice: the server validates
+ * the envelope size before dispatching it to the shell, so nothing reached the
+ * receiver's stdin when the call fails on size.
+ * @param target - connection parameters (auth already selected).
+ * @param shellId - target shell.
+ * @param commandId - target command.
+ * @param chunk - raw bytes to send.
+ * @param sendHttp - the resolved library function.
+ * @param timeoutMs - per-request HTTP timeout.
+ */
+export declare function sendStdinChunk(target: WsmanTarget, shellId: string, commandId: string, chunk: Buffer, sendHttp: SendHttp, timeoutMs: number): Promise<void>;
+/**
+ * Whether a failed Send was refused for exceeding the envelope ceiling.
+ *
+ * WSMan reports this as a SOAP fault rather than a status code, and the exact
+ * wording differs between the HTTP and HTTPS stacks, so the test looks for any
+ * of the size-related phrasings plus the plain 413 status. It deliberately
+ * does not match a bare "size" in unrelated text.
+ * @param error - the rejection to classify.
+ * @returns true when retrying with a smaller slice is the right response.
+ */
+export declare function isEnvelopeTooLarge(error: unknown): boolean;
+/**
+ * Build one WSMan `Receive` envelope asking for stdout and stderr.
+ *
+ * The library's own `buildReceiveOutputRequest` cannot be reused here because
+ * it hardcodes `MaxEnvelopeSize` at 153600 in its shared header. Measured
+ * against this target, that ceiling is what caps each response at 128 KiB —
+ * raising it to 512000 lets one `Receive` return 128 KiB per stream, which is
+ * the most the server will put in a single response regardless.
+ * @param shellId - target shell.
+ * @param commandId - target command whose streams are wanted.
+ * @param limit - envelope ceiling to declare.
+ * @returns the SOAP envelope as a UTF-8 string.
+ */
+export declare function buildReceiveEnvelope(shellId: string, commandId: string, limit: number): string;
+/** One decoded `rsp:Stream` element from a Receive response. */
+export interface ReceivedStream {
+    /** `Name` attribute: `stdout` or `stderr`. */
+    name: string;
+    /** Decoded payload bytes; empty for a stream element that carried no text. */
+    data: Buffer;
+    /** True when the `End` attribute marks this stream closed. */
+    end: boolean;
+}
+/** A decoded Receive response: its streams plus the command's exit code once known. */
+export interface ReceiveResult {
+    streams: ReceivedStream[];
+    /** `rsp:CommandState.rsp:ExitCode`, or undefined while the command still runs. */
+    exitCode?: number;
+}
+/**
+ * Read the streams and exit code out of a Receive response.
+ *
+ * The library's `extractStreams` cannot be used for binary payloads: it decodes
+ * every stream through `extractText`, which falls back to `String(obj)` for an
+ * element that has attributes but no text node — turning the terminal
+ * `End="true"` marker into the literal string `'[object Object]'` — and the
+ * library's `doReceiveOutputNonBlocking` then `.trim()`s the decoded text,
+ * which would eat whitespace bytes at either end of a real payload. This
+ * reader keeps the distinction between "no text" (zero bytes) and "text" and
+ * never trims.
+ * @param response - the parsed XML object returned by `sendHttp`.
+ * @returns the decoded streams and exit code.
+ * @throws when a stream's text node cannot be decoded as base64.
+ */
+export declare function readReceiveResult(response: unknown): ReceiveResult;
+/**
+ * Fetch one Receive response for a running command.
+ * @param target - connection parameters (auth already selected).
+ * @param shellId - target shell.
+ * @param commandId - target command.
+ * @param sendHttp - the resolved library function.
+ * @param timeoutMs - per-request HTTP timeout.
+ * @returns the decoded streams and exit code.
+ */
+export declare function receiveOutput(target: WsmanTarget, shellId: string, commandId: string, sendHttp: SendHttp, timeoutMs: number): Promise<ReceiveResult>;
+export {};

package/lib/types/engine.d.ts

@@ -1,9 +1,9 @@
 /**
  * The WinRM engine facade: host lookup, PowerShell exec (UTF-8 envelope),
- * service & process management, directory listing, base64-chunked file
- * transfer, cluster execution and the streaming console. The heavy lifting
- * lives in engine/ (client, console); this class composes them behind one
- * WinRmEngine instance per plugin apply.
+ * service & process management, directory listing, file transfer, cluster
+ * execution and the streaming console. The heavy lifting lives in engine/
+ * (client, console); this class composes them behind one WinRmEngine instance
+ * per plugin apply.
  */
 import type { ClusterResult, ExecResult, ProcessInfo, RemoteDirEntry, ServiceInfo, TestResult, TransferProgress, WinHostSummary } from './protocol.ts';
 import type { HostStore } from './store.ts';

package/lib/types/powershell.d.ts

@@ -1,28 +1,89 @@
 /**
- * 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.
+ * PowerShell snippet builders and the WinRM UTF-8 envelope.
+ *
+ * The user script is delivered on the WinRS **stdin** stream, not on the
+ * command line. WinRS hands the command line to cmd.exe, which caps it at
+ * ~8191 characters; `-EncodedCommand` inflates a script by 2.67x
+ * (UTF-16LE → base64), so the command line can carry only about 1.5 KB of
+ * script. That silently broke every large payload — most visibly the 48 KiB
+ * transfer chunk, whose embedded base64 alone is ~65K characters.
+ *
+ * So the command line is now a *constant* outer script and the user script
+ * rides stdin, which has no such limit (verified to 200 KB).
+ *
+ * The outer script reads a byte count, then that many bytes, starts a child
+ * `powershell.exe` and feeds it the script on its stdin. The process boundary
+ * is what makes `exit N` and an uncaught `throw` survivable: they terminate
+ * the *child*, and the outer script is still alive to print the envelope.
+ * `-EncodedCommand` for the child also sidesteps the execution policy
+ * entirely — the policy governs `.ps1` files, not encoded commands — so no
+ * temp file is written and no policy block can lose the envelope.
+ *
+ * The child body is `& (...) 2>&1 | Out-String -Stream`. Both halves matter:
+ * `2>&1` pulls error records into the success stream, `Out-String -Stream`
+ * stringifies them onto stdout *line by line*. Plain `Out-String` would also
+ * stringify them but buffers the whole pipeline, discarding everything
+ * produced before a mid-script `exit`; bare `2>&1` without `Out-String`
+ * leaves the records to be re-serialized as CLIXML on stderr, where the
+ * envelope's CLIXML stripping deletes the text outright.
+ *
+ * The envelope is three lines — a marker with the exit code, then one base64
+ * line per stream:
+ *
+ *     __DSH_WINRM__<code>
+ *     O:<base64 of UTF-8 stdout>
+ *     E:<base64 of UTF-8 stderr>
+ *
+ * Every payload is ASCII, so the transport cannot corrupt it and Chinese
+ * output survives losslessly. The `O:` / `E:` labels are load-bearing: the
+ * WinRM client trims each response chunk, which can eat the newline between
+ * two lines, and base64 never contains `:`, so the labels stay parseable
+ * even when the separators vanish.
  */
 /** Marker line prefix carrying the exit code: '__DSH_WINRM__<code>'. */
 export declare const ENVELOPE_MARKER = "__DSH_WINRM__";
+/** Max characters per stdin Send; split on code points, never mid-surrogate-pair. */
+export declare const STDIN_CHUNK_CHARS = 16384;
 /** PS single-quoted literal (doubles embedded quotes). */
 export declare function sq(value: string): string;
 /** Base64 of a UTF-16LE PowerShell script, for -EncodedCommand. */
 export declare function encodeCommand(script: string): string;
 /**
- * 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.
+ * The constant powershell.exe command line that runs the envelope.
+ *
+ * Deliberately takes no payload: keeping the command line under cmd.exe's
+ * ~8191-character cap is the whole point of the stdin channel.
  */
-export declare function wrapEnvelope(userScript: string): string;
-/** One-shot script body for the PowerShell session already created by WinRM. */
-export declare function winrmPowerShellScript(userScript: string): string;
-/** The full powershell.exe command line (ASCII-safe) for a script body. */
-export declare function powershellCommandLine(script: string): string;
-/** One-shot non-interactive PowerShell command line (envelope-wrapped). */
-export declare function execCommandLine(userScript: string): string;
-/** Interactive bootstrap for the streaming console (keeps the shell alive). */
-export declare function consoleCommandLine(): string;
+export declare function powershellCommandLine(): string;
+/**
+ * The constant powershell.exe command line for a streaming upload.
+ *
+ * The receiver travels on stdin right behind it, so this stays well clear of
+ * cmd.exe's cap and does not change when the receiver does.
+ */
+export declare function streamCommandLine(): string;
+/**
+ * The stdin payload for one command: the UTF-8 **byte** count, a newline, then
+ * the raw script.
+ *
+ * The count is in bytes, not characters, because the outer script sizes its
+ * receive buffer from it — a script with multi-byte characters would otherwise
+ * be truncated mid-character.
+ * @param userScript - the PowerShell script to run.
+ * @returns the payload to send on WinRS stdin.
+ */
+export declare function scriptPayload(userScript: string): string;
+/**
+ * Split a payload into Send-sized pieces without cutting a surrogate pair.
+ *
+ * `Command.doSendInput` encodes each piece to UTF-8 independently, so a lone
+ * surrogate at a chunk boundary would be replaced with U+FFFD and corrupt the
+ * script. Iterating with `for…of` yields whole code points, so a pair always
+ * stays in one piece.
+ * @param payload - the full stdin payload.
+ * @returns the pieces to send in order; never empty.
+ */
+export declare function splitScriptPayload(payload: string): string[];
 /** JSON: full service table (CIM). */
 export declare function psListServices(): string;
 /** JSON: one service after an action. */
@@ -33,7 +94,12 @@ export declare function psListProcesses(): string;
 export declare function psKillProcess(id: number): string;
 /** JSON: directory listing. */
 export declare function psListDir(dir: string): string;
-/** Plain: remote file size in bytes (0 when missing). */
+/**
+ * Plain: remote file size in bytes. Emits nothing at all when the path is
+ * missing or is a directory, so the caller can tell "absent" from "empty" —
+ * both used to collapse to the string "0", which made a download of a
+ * nonexistent file look like a successful transfer of a zero-byte one.
+ */
 export declare function psFileSize(p: string): string;
 /** Plain: base64 of up to `count` bytes at `offset` (download chunk). */
 export declare function psReadChunk(p: string, offset: number, count: number): string;
@@ -42,21 +108,121 @@ export declare function psReadChunk(p: string, offset: number, count: number): s
  * prints the number of bytes written.
  */
 export declare function psWriteChunk(p: string, b64: string, append: boolean): string;
+/** Magic stamped into the frame header that precedes every stream chunk. */
+export declare const STREAM_FRAME_MAGIC = "DSHZ";
+/** Frame header size: 4 magic bytes + 4 little-endian length bytes + 1 mode byte + 1 reserved. */
+export declare const STREAM_FRAME_HEADER_BYTES = 10;
+/** Frame mode: the payload after the header is a gzip member. */
+export declare const STREAM_FRAME_GZIP = 1;
+/** Frame mode: the payload after the header is raw file bytes. */
+export declare const STREAM_FRAME_RAW = 0;
+/** Frame mode: the payload after the header is the transfer's metadata. */
+export declare const STREAM_FRAME_HEADER = 2;
+/**
+ * Wrap one payload in a stream frame: `DSHZ` + uint32LE length + mode + pad.
+ *
+ * The frame is what makes a compressed stream legal on a pipe. stdin cannot
+ * seek, so the receiver has to be handed the exact byte count of the next gzip
+ * member before it lets `GZipStream` touch it; otherwise the inflater would
+ * read into the member that follows and the stream would desynchronize. The
+ * mode byte travels with the payload so the client can switch between gzip and
+ * raw per chunk.
+ * @param payload - gzip member bytes or raw file bytes.
+ * @param mode - `STREAM_FRAME_GZIP` or `STREAM_FRAME_RAW`.
+ * @returns the framed chunk to place on the stdin stream.
+ */
+export declare function buildStreamFrame(payload: Buffer, mode: number): Buffer;
+/**
+ * Streaming receiver: drain framed stdin chunks into the file named by the
+ * header frame, until the declared byte count lands.
+ *
+ * This is the fast upload path. Instead of shipping base64 text inside a
+ * PowerShell script — which costs one full shell create/command/delete cycle
+ * per 48 KiB — the remote shell starts this script once and the client then
+ * pushes bytes straight down the WinRS stdin stream. The only per-chunk cost
+ * left is a single `Send`, so a whole file costs one shell and one command no
+ * matter how large it is.
+ *
+ * The script deliberately takes **no arguments**. The destination path and
+ * total byte count arrive as the first frame on stdin, which keeps the command
+ * line a constant size: WinRS hands the command line to cmd.exe, whose limit
+ * is about 8191 characters, and a long remote path interpolated into the
+ * script would eat into that budget (the script is base64-of-UTF-16 on the
+ * wire, so every character costs 2.67). Reading them from the stream removes
+ * the limit entirely and mirrors how `powershellCommandLine` stays constant.
+ *
+ * Every wire chunk is a frame: `DSHZ` + 4-byte little-endian payload length +
+ * 1 mode byte + 1 reserved, followed by exactly that many payload bytes. The
+ * explicit frame is what makes a *pipe* usable for a compressed stream: stdin
+ * cannot seek, so the receiver must be told how long the next gzip member is
+ * before it hands the bytes to `GZipStream`, or the inflater would read into
+ * the member that follows. The mode byte lets the client pick per chunk — gzip
+ * when it actually shrinks the data, raw bytes when it would not — so
+ * incompressible files never pay compression overhead.
+ *
+ * The script prints the three-line envelope on stdout with the byte count as
+ * its payload, so the caller can prove the transfer landed complete.
+ * @returns a PowerShell script suitable for `-EncodedCommand`.
+ */
+export declare function psReceiveStream(): string;
+/**
+ * Streaming sender: write one byte range of the file to standard output,
+ * gzip-compressed, for the download path.
+ *
+ * This is the mirror of {@link psReceiveStream}. The old download path asked
+ * for 48 KiB at a time, and every chunk cost a full shell create / command /
+ * delete cycle — five HTTP round trips each — so a 2 MiB file took 129 s. Here
+ * the shell is created once and the client then simply receives; the only
+ * per-chunk cost left is one `Receive`, and the target streams the file as fast
+ * as the transport will drain it.
+ *
+ * Two details make this work:
+ *
+ * - **Only stderr may carry text.** Anything written to the PowerShell success
+ *   stream would be merged into the payload and corrupt the file, so the byte
+ *   count and any error go to `[Console]::Error` and the exit code, not stdout.
+ * - **The range is positional.** `Position` plus a byte count lets several
+ *   shells serve different parts of one file concurrently; each writes to its
+ *   own offset on the client, so completion order does not matter.
+ *
+ * Output is gzip-compressed unconditionally. Measured against this target, a
+ * compressible 16 MiB file collapsed from 121 round trips to 1 (2.0 s), and an
+ * incompressible 2 MiB file was no slower than raw (9457 ms vs 9582 ms), so the
+ * compression pays for itself or costs nothing.
+ * @param remotePath - file to read on the target.
+ * @param start - first byte offset of this worker's range.
+ * @param length - number of bytes this worker must send.
+ * @returns a PowerShell script suitable for `-EncodedCommand`.
+ */
+export declare function psSendStream(remotePath: string, start: number, length: number): string;
+/**
+ * Wrap an arbitrary script in the constant powershell.exe invocation.
+ *
+ * Only safe for scripts that fit cmd.exe's ~8191 character command line (the
+ * script is base64-of-UTF-16 on the wire, so it costs 2.67 characters each);
+ * {@link psReceiveStream} outgrew that and travels on stdin instead.
+ * @param script - the PowerShell script to run.
+ * @returns the command line to hand to WinRS.
+ */
+export declare function scriptCommandLine(script: string): string;
 /**
- * Parse the envelope output: { exitCode, text } or null when absent.
+ * Parse the three-line envelope: { exitCode, stdout, stderr } 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.
+ * Fields are located by their `O:` / `E:` labels rather than by splitting on
+ * newlines, because the WinRM client trims every response chunk and can drop
+ * the newline that separated two lines. base64's alphabet has no colon, so a
+ * label can only ever be a delimiter and the search cannot land on payload
+ * data. The exit code is signed because `$LASTEXITCODE` can be negative.
+ * @param output - the raw stdout accumulated from the WinRS stdout stream.
+ * @returns the decoded envelope, or null when the marker is missing.
  */
 export declare function parseEnvelope(output: string): {
     exitCode: number;
-    text: string;
+    stdout: string;
+    stderr: string;
 } | null;
 /**
- * Remove PowerShell's CLIXML host records from the WinRS stderr stream.
+ * Remove PowerShell's CLIXML host records from a stderr stream.
  *
  * PowerShell marks its stderr stream with a `#< CLIXML` header line and
  * serializes the remote host's own progress/verbose records into `<Objs>`
@@ -65,9 +231,10 @@ export declare function parseEnvelope(output: string): {
  * 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.
+ * The script's own PowerShell errors are already stringified into the
+ * envelope's stdout by `Out-String -Stream`, so this only removes
+ * transport-level noise such as module-load progress.
+ * @param stderr - raw stderr text captured from the WinRS stream or the envelope.
  * @returns the stderr text without CLIXML host records.
  */
 export declare function stripClixml(stderr: string): string;

package/lib/types/smb.d.ts

@@ -1,11 +1,11 @@
 /**
  * SMB transfer bridge.
  *
- * The WinRM base64 chunk bridge is reliable for small files but breaks for
- * large artifacts (the WinRM/HTTP envelope rejects large payloads), so whole
- * files ride the remote admin share. This module mounts the remote host's
- * admin share with `net use` (password passed via stdin, never argv), copies
- * whole files with node:fs, then verifies the SHA-256 on both ends.
+ * SMB is the fast channel when the admin share is reachable, so `auto` tries it
+ * first and falls back to the WinRM streaming path. This module mounts the
+ * remote host's admin share with `net use` (password passed via stdin, never
+ * argv), copies whole files with node:fs, then verifies the SHA-256 on both
+ * ends.
  */
 import type { WinHostEntry } from './protocol.ts';
 /** Per-transfer channel selector. */
@@ -19,6 +19,25 @@ export interface SmbTransferResult {
  * D:\\dir\\file -> \\\\host\\D$\\dir\\file
  */
 export declare function adminSharePath(host: string, remotePath: string): string;
+/**
+ * Whether the target's SMB port (445) accepts a connection.
+ *
+ * `net use` is the only way to mount the admin share, but it has no useful
+ * timeout: against a host whose 445 is filtered or whose SMB service is down it
+ * spends a full minute before failing. That minute was being paid on *every*
+ * `auto` upload before the WinRM fallback could even start — measured at 61 s
+ * and 58 s on the test host, against a 12 s streaming transfer. A bare TCP
+ * connect answers the same question in milliseconds.
+ *
+ * A negative verdict is cached briefly so a burst of transfers does not re-probe
+ * for each one; a positive verdict is cached too, but the `net use` that follows
+ * still reports its own failure if the share turns out to be unmountable.
+ * @param host - target hostname or address.
+ * @returns true when port 445 accepted a connection.
+ */
+export declare function smbReachable(host: string): Promise<boolean>;
+/** Error thrown when SMB was requested or probed and the target is not listening. */
+export declare function smbUnavailable(host: string): Error;
 /**
  * Copy one local file to a remote Windows host over SMB, verifying the
  * remote SHA-256 matches the local source.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-winrm",
-  "description": "Remote Windows administration for the dsh web GUI: WinRM/PowerShell Remoting host config store (~/.dsh/dsh-winrm.json), PowerShell exec / streaming console / service & process management / base64-chunked file transfer / cluster execution, plus agent tools (winrm_list, winrm_exec, winrm_service, winrm_process, winrm_upload, winrm_download, winrm_cluster). Runs entirely on a native Node.js WinRM client (winrm-client) — no Python/pywinrm required. Standalone Cordis plugin — mounted via cordis.patch.yml + a profile node_modules link, no dsh source changes.",
-  "version": "0.1.1",
+  "description": "Remote Windows administration for the dsh web GUI: WinRM/PowerShell Remoting host config store (~/.dsh/dsh-winrm.json), PowerShell exec / streaming console / service & process management / streamed file transfer / cluster execution, plus agent tools (winrm_list, winrm_exec, winrm_service, winrm_process, winrm_upload, winrm_download, winrm_cluster). Runs entirely on a native Node.js WinRM client (winrm-client) — no Python/pywinrm required. Standalone Cordis plugin — mounted via cordis.patch.yml + a profile node_modules link, no dsh source changes.",
+  "version": "0.3.0",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {
@@ -44,25 +44,25 @@
     "ws": "^8.18.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-host-webserver": "^0.1.7-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.7-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.7-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.7-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-alpha.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.7-alpha.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.7-alpha.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.7-alpha.2 || ^0.2.0-rc.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.5",
-    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-layout": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.7-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
     "@deepseek-ai/schemastery": "^3.18.4",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
@@ -89,7 +89,8 @@
     "build": "tsc -p tsconfig.build.json && tsdown && node scripts/postbuild.mjs",
     "bundle": "tsdown",
     "watch": "tsdown --watch",
-    "test": "node --experimental-strip-types --test tests/*.test.ts tests/*.test.mjs",
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "verify:live": "node --experimental-strip-types scripts/verify-live.mts",
     "check": "npm run typecheck && npm run build && npm test",
     "pack:check": "npm pack --dry-run --json",
     "prepack": "npm run check",