@akms/mcp-wsl 0.0.1

package/lib/index.d.ts

@@ -0,0 +1,456 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SshPolicy, GuardVerdict, RemotePathAccess } from '@akms/mcp-ssh';
+export { GuardRejectionError, GuardVerdict } from '@akms/mcp-ssh';
+import { Readable, Writable } from 'node:stream';
+
+/**
+ * Guard rules applied to every command / file operation in the distro.
+ *
+ * The `@akms/mcp-ssh` policy verbatim, so its guards accept it unchanged. `connectTimeoutMs`
+ * has no meaning here (nothing connects) and is carried as 0.
+ */
+type WslPolicy = SshPolicy;
+/** The registered distro: which one, as whom, what is permitted. */
+interface WslHostProfile {
+    /** Alias shown to the model, from `WSL_NAME`; defaults to the distro name. */
+    name: string;
+    /** Distro name as `wsl -l -q` prints it. */
+    distro: string;
+    /** Linux user passed as `wsl -u`; the distro's default user when absent. */
+    username?: string;
+    description?: string;
+    /** Directory every session starts in; falls back to the login shell's default. */
+    defaultCwd?: string;
+    /**
+     * Whether the agent may leave the distro for Windows — run interop executables, or
+     * write under `/mnt/<drive>/`. Off by default: those paths reach the machine that runs
+     * this server and holds its configuration.
+     */
+    allowWindows: boolean;
+    policy: WslPolicy;
+}
+/** View of the profile handed back to the model. */
+interface WslHostSummary {
+    name: string;
+    distro: string;
+    /** The configured user, or the distro default when none was set. */
+    username: string;
+    description?: string;
+    readonly: boolean;
+    allowSudo: boolean;
+    allowWindows: boolean;
+    allowedPaths: string[];
+    allowCommands: string[];
+}
+
+/** Outcome of one command in the distro. */
+interface WslExecResult {
+    stdout: string;
+    stderr: string;
+    /** Exit status of the Linux command; null when `wsl.exe` was killed before it reported one. */
+    exitCode: number | null;
+    /** Signal that killed `wsl.exe`, e.g. "SIGTERM". */
+    signal?: string;
+    /** True when the timeout fired before the command finished. */
+    timedOut: boolean;
+    /** True when stdout or stderr hit `maxOutputCharacters` and was cut. */
+    truncated: boolean;
+    /** Working directory after the command ran; only tracked for session-bound execs. */
+    cwd?: string;
+    durationMs: number;
+}
+/** Live session as reported by `wsl_list_sessions`. */
+interface WslSessionInfo {
+    sessionId: string;
+    profileName: string;
+    distro: string;
+    username: string;
+    cwd: string;
+    /** ISO-8601 timestamps. */
+    openedAt: string;
+    lastUsedAt: string;
+    execCount: number;
+}
+/** One entry of a directory listing. */
+interface WslDirectoryEntry {
+    name: string;
+    type: "file" | "directory" | "symlink" | "other";
+    sizeBytes: number;
+    /** Octal permission string, e.g. "0644". */
+    mode: string;
+    modifiedAt: string;
+}
+/** What `wsl.exe -l -v` and a probe inside the distro report — the facts infra-wsl reasoning needs. */
+interface WslDistroStatus {
+    /** False when `wsl -l -v` does not list the distro at all. */
+    installed: boolean;
+    state: "Running" | "Stopped" | "Installing" | "unknown";
+    /** WSL 1 or 2, from the listing. */
+    wslVersion?: number;
+    /** `wslinfo --networking-mode`: nat / mirrored / …; only probed while the distro runs. */
+    networkingMode?: string;
+    /** True when PID 1 is systemd. */
+    systemd?: boolean;
+    kernel?: string;
+}
+
+interface WslExecOptions {
+    command: string;
+    /** Directory to `cd` into first; the login shell's default is used when absent. */
+    cwd?: string;
+    timeoutMs: number;
+    maxOutputCharacters: number;
+    /** Appends a `$PWD` marker so a session can follow `cd` between commands. */
+    trackCwd: boolean;
+}
+/** A fixed script run without the command guard — the file operations, whose only variable part is a quoted path. */
+interface WslProcessOptions {
+    script: string;
+    /** Fed to the process and then closed; absent means stdin is closed from the start. */
+    stdin?: Buffer | Readable;
+    /** When set, stdout streams here instead of being buffered, and `stdout` comes back empty. */
+    stdoutSink?: Writable;
+    timeoutMs: number;
+    /** Bytes buffered per stream before the process is killed. */
+    maxCapturedBytes: number;
+}
+interface WslProcessOutput {
+    stdout: Buffer;
+    stderr: Buffer;
+    /** Bytes that went to `stdoutSink`, when one was given. */
+    sinkBytes: number;
+    exitCode: number | null;
+    signal?: string;
+    timedOut: boolean;
+    capExceeded: boolean;
+    durationMs: number;
+}
+/**
+ * One distro + user, plus the operations run in it. Every call is its own `wsl.exe`
+ * process; nothing is held between calls.
+ *
+ * This class is the chokepoint: it holds the profile, so it applies the command guard
+ * itself rather than trusting each caller to remember — the same reasoning as
+ * `SshConnection` in `@akms/mcp-ssh`.
+ */
+declare class WslHost {
+    readonly profile: WslHostProfile;
+    constructor(profile: WslHostProfile);
+    /**
+     * Screens a command against this profile's policy, then runs it.
+     *
+     * The canonical form is what gets screened *and* what gets sent — validating one
+     * string while executing another is a bypass by construction.
+     *
+     * @throws {GuardRejectionError} If the policy refuses the command or the cwd.
+     * @throws {Error} If `wsl.exe` itself fails (unknown distro, service down) or cannot be spawned.
+     */
+    exec(options: WslExecOptions): Promise<WslExecResult>;
+    /**
+     * Spawns `wsl.exe` for one script and collects what it produced.
+     *
+     * Not guarded — callers own that: `exec` screens the command, the file operations
+     * screen the path and build the script themselves. stdin is closed (or fed and then
+     * closed) so anything that waits for input fails at once instead of hanging until the
+     * timeout.
+     *
+     * @throws {Error} If the process ceiling is reached, `wsl.exe` cannot be started, or
+     *                 `wsl.exe` reports a failure of its own rather than the command's exit
+     *                 status — that message (unknown distro, service down) is the whole diagnosis.
+     */
+    runProcess(options: WslProcessOptions): Promise<WslProcessOutput>;
+}
+
+/**
+ * The `wsl.exe` argument vector for running `script` in the profile's distro as its user.
+ *
+ * `--exec`, never `--`. With `--`, wsl.exe hands the arguments to the distro's *default
+ * shell* for a second parse: backslashes vanish (`printf '\n'` breaks, `find … \;`
+ * breaks) and `$HOME` / `$PATH` are expanded before bash ever sees the script — that is,
+ * before the text the guard screened is the text that runs. `--exec` is a straight
+ * execve, so the argument arrives byte for byte; `bash -lc` then gives the login
+ * environment (PATH from `.profile`, nvm) that `--exec` alone would skip.
+ */
+declare function buildWslArguments(profile: WslHostProfile, script: string): string[];
+/**
+ * Wraps the user command so bash reports where it ended up.
+ *
+ * The `cd` is done inside the script rather than with `wsl --cd`: a missing directory
+ * makes `--cd` fall back to `/` with exit 0 and a warning on stderr, so the command
+ * would run in the wrong place and look successful.
+ *
+ * `$?` is captured before the marker is printed and replayed via `exit`, so the exit
+ * status the caller sees is the command's, not `printf`'s.
+ *
+ * `cwd` appears exactly once, inside `quoteShellArgument`. It must never be interpolated
+ * anywhere else — echoing it into a double-quoted diagnostic would let
+ * `cwd: '/x"; rm -rf /; #'` run arbitrary commands with every guard bypassed. The
+ * failure message is therefore a fixed string.
+ */
+declare function buildDistroScript(command: string, cwd: string | undefined, trackCwd: boolean): string;
+/** Splits the trailing `$PWD` marker off stdout. */
+declare function extractCwdMarker(stdout: string): {
+    output: string;
+    cwd?: string;
+};
+
+/**
+ * Shell state carried across commands — the working directory. Nothing else persists:
+ * each command is its own `wsl.exe` process, so the session is the memory, not a channel.
+ */
+declare class WslSession {
+    readonly sessionId: string;
+    readonly host: WslHost;
+    /** Empty until the first command reports `$PWD`; then the real distro path. */
+    cwd: string;
+    lastUsedAt: Date;
+    execCount: number;
+    readonly openedAt: Date;
+    /** Tail of the serialized operation chain; see `runExclusive`. */
+    private operationChain;
+    private activeOperationCount;
+    constructor(sessionId: string, host: WslHost);
+    get profile(): WslHostProfile;
+    /** True while an operation is running, so the idle sweeper leaves it alone. */
+    get isBusy(): boolean;
+    touch(): void;
+    /**
+     * Runs `operation` with exclusive use of this session.
+     *
+     * Serialized because `cwd` is read-modify-write across a process run: two concurrent
+     * calls both read the old directory, and the one that finishes second writes it back —
+     * silently undoing the other's `cd`.
+     */
+    runExclusive<T>(operation: (host: WslHost) => Promise<T>): Promise<T>;
+    /**
+     * Runs a command in this session's working directory and adopts wherever it ended up,
+     * so a `cd` in one call is still in effect on the next.
+     *
+     * Passing `cwd` runs this command elsewhere *and* moves the session there — same
+     * result as prefixing `cd <cwd> &&`, which is what a shell user would expect.
+     */
+    exec(command: string, options?: {
+        cwd?: string;
+        timeoutMs?: number;
+    }): Promise<WslExecResult>;
+    toInfo(): WslSessionInfo;
+}
+/** Owns every open session: creation, lookup, idle expiry and shutdown. */
+declare class WslSessionManager {
+    private readonly sessions;
+    private sequence;
+    private sweepTimer;
+    /**
+     * Registers a session. Nothing is opened — the caller probes with `pwd` to prove
+     * the distro answers and to settle the starting directory.
+     *
+     * @throws {Error} If the session ceiling is reached.
+     */
+    open(host: WslHost): WslSession;
+    /**
+     * Looks up a session, failing with the list of live ids so the caller can self-correct.
+     *
+     * @throws {Error} If no session matches `sessionId`.
+     */
+    require(sessionId: string): WslSession;
+    close(sessionId: string): boolean;
+    closeAll(): void;
+    list(): WslSessionInfo[];
+    /** Starts the idle sweeper; the timer is unref'd so it never holds the process open. */
+    startIdleSweeper(): void;
+    stopIdleSweeper(): void;
+}
+
+interface DirectoryListing {
+    entries: WslDirectoryEntry[];
+    /** Entries the distro reported, before the cap was applied. */
+    totalCount: number;
+    truncated: boolean;
+}
+interface FileContent {
+    content: string;
+    /** Size `stat` reported; 0 for virtual files that do not declare one. */
+    sizeBytes: number;
+    /** Bytes actually read. */
+    readBytes: number;
+    truncated: boolean;
+}
+/**
+ * Lists a directory, directories first then files, each group alphabetical, capped at
+ * `MAX_DIRECTORY_ENTRIES`. One `find -printf` call; `%y` is the type letter, `%m` the
+ * octal mode, `%s` bytes, `%T+` the mtime.
+ */
+declare function listDirectory(host: WslHost, distroPath: string): Promise<DirectoryListing>;
+/**
+ * Reads the leading `maxBytes` of a file. Two processes — `stat` for the declared size,
+ * then `head -c` — because mixing a size line into the content stream would need
+ * escaping that a fixed script should not have.
+ */
+declare function readFile(host: WslHost, distroPath: string, maxBytes: number): Promise<FileContent>;
+/**
+ * Writes or appends UTF-8 text. Content goes through stdin, so nothing in it is ever
+ * shell-parsed; only the path is interpolated, quoted.
+ *
+ * @returns Bytes written.
+ */
+declare function writeFile(host: WslHost, args: {
+    distroPath: string;
+    content: string;
+    append: boolean;
+}): Promise<number>;
+/**
+ * Local → distro. The local file is streamed into the process's stdin, so size is bounded
+ * by the distro's disk, not this server's memory.
+ *
+ * @returns Bytes sent, from the local file's size.
+ */
+declare function uploadFile(host: WslHost, localPath: string, distroPath: string): Promise<number>;
+/**
+ * Distro → local. stdout streams straight into the destination file, so a large download
+ * never sits in memory. The destination's parent must already exist — the tool creates
+ * no directories on the operator's machine.
+ *
+ * @returns Bytes received.
+ */
+declare function downloadFile(host: WslHost, distroPath: string, localPath: string): Promise<number>;
+
+/**
+ * What `wsl.exe -l -v` says about the distro. Does not start it — that is what makes
+ * this safe to call from `wsl_list_hosts` and `--check` without side effects.
+ *
+ * @throws {Error} If `wsl.exe` cannot be started at all.
+ */
+declare function queryDistroListing(distro: string): Promise<WslDistroStatus>;
+/**
+ * Facts only visible from inside: networking mode, whether systemd is PID 1, the kernel.
+ * Starts the distro when it is stopped, so callers check the listing first and skip this
+ * for a stopped distro unless starting it is the intent.
+ *
+ * Runs as a fixed script through `runProcess`, bypassing the command guard — the script
+ * has no variable part and an allow-list profile must still be able to describe itself.
+ */
+declare function probeDistroFacts(host: WslHost): Promise<Pick<WslDistroStatus, "networkingMode" | "systemd" | "kernel">>;
+
+interface WslMcpServerInstance {
+    server: McpServer;
+    sessions: WslSessionManager;
+    /** The distro read from the `WSL_*` variables at startup, or null when none is set. */
+    readonly profile: WslHostProfile | null;
+    /** Stops the sweeper and forgets every open session. Call before the process exits. */
+    shutdown(): void;
+}
+/**
+ * Builds the MCP server: reads the distro from the environment, wires the session
+ * manager, registers tools.
+ *
+ * Transport is deliberately left to the caller — `cli.ts` attaches stdio, tests can attach
+ * an in-memory pair.
+ *
+ * @throws {Error} If the `WSL_*` variables are malformed (a bad policy value must not
+ *                 silently degrade into "no guard").
+ */
+declare function createWslMcpServer(): WslMcpServerInstance;
+
+/**
+ * Builds the profile from the `WSL_*` variables, or null when `WSL_DISTRO` is unset.
+ *
+ * The distro is required by name rather than falling back to `wsl --set-default`'s pick:
+ * that default is a machine-wide setting anyone can change, and a server silently
+ * following it would one day run every command in a different distro than the entry
+ * says. A malformed value aborts startup rather than being ignored, because silently
+ * dropping `WSL_READONLY` would leave a distro the operator believed was read-only
+ * fully writable.
+ *
+ * Flow:
+ *  1) Guard: no `WSL_DISTRO` means nothing is registered — the server still starts and says so
+ *  2) Resolve the policy over the built-in permissive stance; each variable is opt-in restriction
+ *  3) Assemble the profile
+ *
+ * @throws {Error} If a typed value is malformed.
+ */
+declare function loadHostProfile(): WslHostProfile | null;
+/** The profile as described back to the model. Nothing secret lives in a WSL profile, but the shape mirrors mcp-ssh. */
+declare function toHostSummary(profile: WslHostProfile): WslHostSummary;
+
+/**
+ * Screens a command for a WSL host: the `@akms/mcp-ssh` guard first (catastrophe rules,
+ * read-only, sudo, allow-list, deny patterns), then what only matters here.
+ *
+ * The WSL additions exist because one assumption of the base guard does not hold: that
+ * the remote account is the real boundary. In WSL the "remote" is the machine running
+ * this server. Through interop (`powershell.exe`) or a write under `/mnt/c/Users/…`, a
+ * mistaken agent can reach `~/.claude.json` — the file that defines this very guard — so
+ * both routes are closed unless `WSL_ALLOW_WINDOWS` opens them, and the operator's
+ * credential and configuration paths stay closed either way.
+ *
+ * Flow:
+ *  1) Base guard on the whole command
+ *  2) Per segment (and per `$(…)` substitution, recursively): WSL catastrophe rules
+ *  3) Per segment: interop binary
+ *  4) Per segment: `/mnt/<drive>/` references — write shape, then protected Windows paths
+ */
+declare function inspectWslCommand(canonicalCommand: string, profile: WslHostProfile, depth?: number): GuardVerdict;
+/**
+ * Decides whether a file tool may touch a path in the distro: the base path guard
+ * (`allowedPaths`, read-only), then the Windows rules for anything under `/mnt/<drive>/`.
+ */
+declare function inspectWslPath(distroPath: string, profile: WslHostProfile, access: RemotePathAccess): GuardVerdict;
+
+/** Everything the tool handlers share: the configured distro and the live sessions. */
+interface ToolContext {
+    /** The distro from the `WSL_*` variables, or null when none is registered. */
+    host: WslHost | null;
+    sessions: WslSessionManager;
+}
+
+/** Registers every tool this server exposes, in the order the model should discover them. */
+declare function registerAllTools(server: McpServer, context: ToolContext): void;
+
+type LogLevel = "silent" | "debug" | "info" | "warn" | "error";
+interface Logger {
+    /** Returns a logger that appends `meta` to every record it writes. */
+    child(meta: Record<string, unknown>): Logger;
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(error: unknown, message: string, meta?: Record<string, unknown>): void;
+}
+declare const $logger: Logger;
+
+/** Env var overriding the stderr log level ("debug" | "info" | "warn" | "error" | "silent"). */
+declare const LOG_LEVEL_ENV = "WSL_MCP_LOG_LEVEL";
+declare const SERVER_NAME = "akms-mcp-wsl";
+declare const SERVER_VERSION = "0.0.1";
+
+/**
+ * Environment variables that define the distro, one MCP server entry per distro + user.
+ *
+ * The `SSH_*` surface of `@akms/mcp-ssh` with the connection and authentication
+ * variables removed — there is no connection, `wsl.exe` is the transport.
+ */
+declare const SINGLE_HOST_ENV: {
+    /** Presence of this variable is what registers a distro at all. Name as `wsl -l -q` prints it. */
+    readonly DISTRO: "WSL_DISTRO";
+    /** Linux user to run as (`wsl -u`); the distro's default user when unset. */
+    readonly USER: "WSL_USER";
+    /** Alias shown to the model; defaults to the distro name. */
+    readonly NAME: "WSL_NAME";
+    readonly DESCRIPTION: "WSL_DESCRIPTION";
+    /** Directory new sessions start in. */
+    readonly CWD: "WSL_CWD";
+    readonly READONLY: "WSL_READONLY";
+    readonly ALLOW_SUDO: "WSL_ALLOW_SUDO";
+    /** Interop `.exe` execution and writes under `/mnt/<drive>/`. Default false. */
+    readonly ALLOW_WINDOWS: "WSL_ALLOW_WINDOWS";
+    /** Comma-separated binary names. */
+    readonly ALLOW_COMMANDS: "WSL_ALLOW_COMMANDS";
+    /** Comma-separated regex sources. */
+    readonly DENY_PATTERNS: "WSL_DENY_PATTERNS";
+    /** Comma-separated absolute path prefixes. */
+    readonly ALLOWED_PATHS: "WSL_ALLOWED_PATHS";
+    readonly EXEC_TIMEOUT_MS: "WSL_EXEC_TIMEOUT_MS";
+    readonly MAX_OUTPUT_CHARACTERS: "WSL_MAX_OUTPUT";
+    readonly MAX_READ_FILE_BYTES: "WSL_MAX_READ_BYTES";
+};
+
+export { $logger, type DirectoryListing, type FileContent, LOG_LEVEL_ENV, type LogLevel, type Logger, SERVER_NAME, SERVER_VERSION, SINGLE_HOST_ENV, type ToolContext, type WslDirectoryEntry, type WslDistroStatus, type WslExecOptions, type WslExecResult, WslHost, type WslHostProfile, type WslHostSummary, type WslMcpServerInstance, type WslPolicy, type WslProcessOptions, type WslProcessOutput, WslSession, type WslSessionInfo, WslSessionManager, buildDistroScript, buildWslArguments, createWslMcpServer, downloadFile, extractCwdMarker, inspectWslCommand, inspectWslPath, listDirectory, loadHostProfile, probeDistroFacts, queryDistroListing, readFile, registerAllTools, toHostSummary, uploadFile, writeFile };