dsh-plugin-wsl-env 0.7.5 → 0.8.0

package/lib/fs-routing.js

@@ -24,14 +24,15 @@
  * containment — the distro side kernel-enforced). If a root-plane write
  * consumer appears, its fence rides with that consumer.
  *
+ * This is a TypeScript source built to `lib/fs-routing.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ *
  * @module dsh-plugin-wsl/fs-routing
  */
-
-import { isWslUnc, uncToPosix, windowsToLinuxMount } from "./paths.js";
+import { isWslUnc, uncToPosix } from "./paths.js";
 import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
-import { linuxJoin } from "./workspace-files-route.js";
 import { WslFileSystem } from "./index.js";
-
 /**
  * Whether a resolved target identity belongs to the distro.
  *
@@ -39,9 +40,8 @@ import { WslFileSystem } from "./index.js";
  * @returns true when the target lives inside a WSL distro.
  */
 export function targetIsDistro(targetKey) {
-  return isWslUnc(targetKey);
+    return isWslUnc(targetKey);
 }
-
 /**
  * Whether a raw path-or-cwd input names the distro (used by the operations
  * that take paths before a target exists: resolve, lstat).
@@ -50,17 +50,8 @@ export function targetIsDistro(targetKey) {
  * @returns true when the input names a distro UNC.
  */
 export function inputIsDistro(value) {
-  return value !== undefined && isWslUnc(value);
+    return value !== undefined && isWslUnc(value);
 }
-
-/**
- * The Linux working path for one request: UNC absolutes map onto their Linux
- * paths, POSIX absolutes and relative paths join onto the root.
- *
- * @param linuxRoot - the workspace root in Linux form.
- * @param path - the requested path, any coordinate system.
- * @returns the absolute Linux path.
- */
 /**
  * The root-plane filesystem with coordinate routing.
  *
@@ -69,108 +60,174 @@ export function inputIsDistro(value) {
  * mode the distro side reports through `sandboxMode`).
  */
 export class WslRoutingFileSystem extends LocalFileSystem {
-  static Config = LocalFileSystem.Config;
-
-  /** The lazy distro backend, built on first routed use. */
-  #distro;
-  /** The distro knobs, verbatim from the row config. */
-  #distroConfig;
-
-  constructor(ctx, config) {
-    super(ctx, config);
-    this.#distroConfig = {
-      distro: config.distro ?? "",
-      wslPath: config.wslPath ?? "wsl.exe",
-      cwd: config.distroCwd ?? "",
-      diffBasisMaxBytes: config.diffBasisMaxBytes,
-      sandbox: config.sandbox ?? true,
-      maskWindowsDrive: config.maskWindowsDrive ?? false,
-      restrictToDistro: config.restrictToDistro ?? true,
-      watchMaxDepth: config.watchMaxDepth ?? 0,
-    };
-  }
-
-  /** The distro backend for routed targets, built on first use. */
-  distro() {
-    return (this.#distro ??= new WslFileSystem(this.ctx, this.#distroConfig));
-  }
-
-  async resolve(path, opts) {
-    if (inputIsDistro(path) || inputIsDistro(opts?.cwd)) return (await this.distro()).resolve(path, opts);
-    return super.resolve(path, opts);
-  }
-
-  async lstat(path, opts, signal) {
-    if (inputIsDistro(path) || inputIsDistro(opts?.cwd)) return (await this.distro()).lstat(path, opts, signal);
-    return super.lstat(path, opts, signal);
-  }
-
-  async stat(target, signal) {
-    if (targetIsDistro(target.targetKey)) return (await this.distro()).stat(target, signal);
-    return super.stat(target, signal);
-  }
-
-  async readText(target, signal) {
-    if (targetIsDistro(target.targetKey)) return (await this.distro()).readText(target, signal);
-    return super.readText(target, signal);
-  }
-
-  async streamText(target, signal) {
-    if (targetIsDistro(target.targetKey)) return (await this.distro()).streamText(target, signal);
-    return super.streamText(target, signal);
-  }
-
-  async readBytes(target, signal, maxBytes) {
-    if (targetIsDistro(target.targetKey)) return (await this.distro()).readBytes(target, signal, maxBytes);
-    return super.readBytes(target, signal, maxBytes);
-  }
-
-  async readByteRange(target, range, signal) {
-    if (targetIsDistro(target.targetKey)) return (await this.distro()).readByteRange(target, range, signal);
-    return super.readByteRange(target, range, signal);
-  }
-
-  async listDir(target, signal) {
-    if (targetIsDistro(target.targetKey)) return (await this.distro()).listDir(target, signal);
-    return super.listDir(target, signal);
-  }
-
-  async writeText(target, content, expected, signal, sandboxPolicy) {
-    if (targetIsDistro(target.targetKey)) {
-      return (await this.distro()).writeText(target, content, expected, signal, sandboxPolicy);
+    static Config = LocalFileSystem.Config;
+    /**
+     * The lazy distro backend, built on first routed use, typed as the concrete
+     * class: these routing calls are that class's own surface, and the
+     * `processPathFromHostPath` seam it once could not satisfy (async against the
+     * peer interface's synchronous contract) is closed — the backend maps
+     * synchronously now, from what it already knows.
+     */
+    #distro;
+    /** The distro knobs, verbatim from the row config. */
+    #distroConfig;
+    /**
+     * @param ctx - the cordis context.
+     * @param config - the row config, host knobs plus distro knobs.
+     */
+    constructor(ctx, config) {
+        super(ctx, config);
+        this.#distroConfig = {
+            distro: config.distro ?? "",
+            wslPath: config.wslPath ?? "wsl.exe",
+            cwd: config.distroCwd ?? "",
+            diffBasisMaxBytes: config.diffBasisMaxBytes,
+            sandbox: config.sandbox ?? true,
+            maskWindowsDrive: config.maskWindowsDrive ?? false,
+            restrictToDistro: config.restrictToDistro ?? true,
+            watchMaxDepth: config.watchMaxDepth ?? 0,
+        };
+    }
+    /** The distro backend for routed targets, built on first use. */
+    distro() {
+        return (this.#distro ??= new WslFileSystem(this.ctx, this.#distroConfig));
+    }
+    /**
+     * @param path - the requested path.
+     * @param opts - the resolve options.
+     */
+    async resolve(path, opts) {
+        if (inputIsDistro(path) || inputIsDistro(opts?.cwd))
+            return (await this.distro()).resolve(path, opts);
+        return super.resolve(path, opts);
+    }
+    /**
+     * @param path - the requested path.
+     * @param opts - the lstat options.
+     * @param signal - cancels the round trip.
+     */
+    async lstat(path, opts, signal) {
+        if (inputIsDistro(path) || inputIsDistro(opts?.cwd))
+            return (await this.distro()).lstat(path, opts, signal);
+        return super.lstat(path, opts, signal);
+    }
+    /**
+     * @param target - the resolved target.
+     * @param signal - cancels the round trip.
+     */
+    async stat(target, signal) {
+        if (targetIsDistro(target.targetKey))
+            return (await this.distro()).stat(target, signal);
+        return super.stat(target, signal);
+    }
+    /**
+     * @param target - the resolved target.
+     * @param signal - cancels the round trip.
+     */
+    async readText(target, signal) {
+        if (targetIsDistro(target.targetKey))
+            return (await this.distro()).readText(target, signal);
+        return super.readText(target, signal);
+    }
+    /**
+     * @param target - the resolved target.
+     * @param signal - cancels the stream.
+     */
+    async streamText(target, signal) {
+        if (targetIsDistro(target.targetKey))
+            return (await this.distro()).streamText(target, signal);
+        return super.streamText(target, signal);
+    }
+    /**
+     * @param target - the resolved target.
+     * @param signal - cancels the read.
+     * @param maxBytes - the inclusive byte cap.
+     */
+    async readBytes(target, signal, maxBytes) {
+        if (targetIsDistro(target.targetKey))
+            return (await this.distro()).readBytes(target, signal, maxBytes);
+        return super.readBytes(target, signal, maxBytes);
+    }
+    /**
+     * @param target - the resolved target.
+     * @param range - the byte window.
+     * @param signal - cancels the read.
+     */
+    async readByteRange(target, range, signal) {
+        if (targetIsDistro(target.targetKey))
+            return (await this.distro()).readByteRange(target, range, signal);
+        return super.readByteRange(target, range, signal);
+    }
+    /**
+     * @param target - the resolved directory.
+     * @param signal - cancels the listing.
+     */
+    async listDir(target, signal) {
+        if (targetIsDistro(target.targetKey))
+            return (await this.distro()).listDir(target, signal);
+        return super.listDir(target, signal);
+    }
+    /**
+     * @param target - the resolved target.
+     * @param content - the full new content.
+     * @param expected - the guarded-write intent.
+     * @param signal - cancels the write.
+     * @param sandboxPolicy - the confined policy the distro side honors; the
+     *   host backend takes no such parameter.
+     */
+    async writeText(target, content, expected, signal, sandboxPolicy) {
+        if (targetIsDistro(target.targetKey)) {
+            return (await this.distro()).writeText(target, content, expected, signal, sandboxPolicy);
+        }
+        return super.writeText(target, content, expected, signal);
+    }
+    /**
+     * @param target - the resolved target.
+     * @param edit - the literal edit.
+     * @param expected - the version the edit was based on.
+     * @param signal - cancels the edit.
+     * @param sandboxPolicy - the confined policy the distro side honors; the
+     *   host backend takes no such parameter.
+     */
+    async editText(target, edit, expected, signal, sandboxPolicy) {
+        if (targetIsDistro(target.targetKey)) {
+            return (await this.distro()).editText(target, edit, expected, signal, sandboxPolicy);
+        }
+        return super.editText(target, edit, expected, signal);
+    }
+    /**
+     * @param target - the resolved target.
+     * @param changed - the change callback.
+     * @param signal - cancels the watch.
+     */
+    async watch(target, changed, signal) {
+        if (targetIsDistro(target.targetKey))
+            return (await this.distro()).watch(target, changed, signal);
+        return super.watch(target, changed, signal);
     }
-    return super.writeText(target, content, expected, signal, sandboxPolicy);
-  }
-
-  async editText(target, edit, expected, signal, sandboxPolicy) {
-    if (targetIsDistro(target.targetKey)) {
-      return (await this.distro()).editText(target, edit, expected, signal, sandboxPolicy);
+    /**
+     * @param parent - the container.
+     * @param child - the contained candidate.
+     */
+    contains(parent, child) {
+        if (targetIsDistro(parent.targetKey)) {
+            // Both targets came from this router's distro resolve, so the plain
+            // POSIX containment over their process paths is the same check the
+            // distro substrate performs for its own guarded writes.
+            const base = this.processPath(parent);
+            const full = this.processPath(child);
+            return full === base || full.startsWith(base.endsWith("/") ? base : `${base}/`);
+        }
+        return super.contains(parent, child);
     }
-    return super.editText(target, edit, expected, signal, sandboxPolicy);
-  }
-
-  async watch(target, changed, signal) {
-    if (targetIsDistro(target.targetKey)) return (await this.distro()).watch(target, changed, signal);
-    return super.watch(target, changed, signal);
-  }
-
-  contains(parent, child) {
-    if (targetIsDistro(parent.targetKey)) {
-      // Both targets came from this router's distro resolve, so the plain
-      // POSIX containment over their process paths is the same check the
-      // distro substrate performs for its own guarded writes.
-      const base = this.processPath(parent);
-      const full = this.processPath(child);
-      return full === base || full.startsWith(base.endsWith("/") ? base : `${base}/`);
+    /**
+     * @param target - the resolved target.
+     */
+    processPath(target) {
+        const parsed = uncToPosix(target.targetKey);
+        if (parsed !== undefined)
+            return parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+        return super.processPath(target);
     }
-    return super.contains(parent, child);
-  }
-
-  processPath(target) {
-    const parsed = uncToPosix(target.targetKey);
-    if (parsed !== undefined) return parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
-    return super.processPath(target);
-  }
 }
-
 export default WslRoutingFileSystem;

package/lib/fs-substrate.d.ts

@@ -0,0 +1,258 @@
+/**
+ * The agent-backed filesystem substrate: the provider-shaped operations the
+ * model's file tools call, orchestrated over the distro's FS frames.
+ *
+ * This is the `ctx.fs` seam's mechanics for `substrate: "agent"` — resolve,
+ * stat, reads, and the write/edit orchestration the host backend owns on a
+ * share-backed session (probe, guards, diff basis, publication, outcome
+ * shape), mirroring `@deepseek-ai/dsh-fs-local`'s `writeText` and `editText`
+ * byte-for-byte in message and code. Two deliberate differences from the share
+ * backend it replaces:
+ *
+ * 1. **The mutation guard survives to the write — per intent.** A guarded
+ *    create publishes with the distro-side no-replace link, a real atomic
+ *    primitive that refuses to replace. An overwrite or edit carries the
+ *    version it was based on INTO the write op, and the agent re-verifies it
+ *    with a fresh stat one syscall before the rename: a concurrent writer
+ *    (an editor save, `git stash`, another session) wins, and the stale
+ *    write refuses with `FS_STALE_VERSION` instead of clobbering. That
+ *    narrows the share backend's check-then-write window from a host round
+ *    trip to kernel-adjacent — the honest wording; "closed" was true only
+ *    for the create case.
+ * 2. A symlink needs no retry machinery: every identity is resolved where the
+ *    symlinks live.
+ *
+ * Peer-free by construction: refusals are `FsCodedError`s from
+ * `lib/fsio-text.js`, mapped onto the peer's `FsError` at the provider
+ * boundary, so this module is unit-testable in a bare checkout against the
+ * real agent script.
+ *
+ * This is a TypeScript source built to `lib/fs-substrate.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/fs-substrate
+ */
+import { DistroFs } from "./fsio-agent.js";
+import type { WslAgent } from "./agent.js";
+/**
+ * A resolved target: the Linux spelling the model sees and the UNC identity
+ * the harness keys on, as returned by {@linkcode AgentSubstrate#resolve}.
+ */
+export interface ResolvedTarget {
+    /** The canonical Linux path spelling. */
+    displayPath: string;
+    /** The UNC identity this target keys on. */
+    targetKey: string;
+}
+/**
+ * One distro's provider-shaped filesystem face.
+ */
+export declare class AgentSubstrate {
+    /** The pinned distro name, for UNC identity. */
+    distro: string;
+    /** The overwrite-diff bound, mirroring the provider config. */
+    diffBasisMaxBytes: number;
+    /** The resident in-distro agent reads ride. */
+    agent: WslAgent;
+    /** Stage-two routing: the agent a mutation must run on for the resolved policy, when wired. */
+    agentFor: ((policy: {
+        mode: string;
+        workspaceRoot: string;
+    } | undefined) => Promise<WslAgent>) | undefined;
+    /** The distro-side filesystem face. */
+    fs: DistroFs;
+    /** Per-targetKey tail promise: the host backend's mutation serialization. */
+    locks: Map<string, Promise<void>>;
+    /**
+     * @param deps - the substrate's collaborators.
+     */
+    constructor({ agent, agentFor, distro, diffBasisMaxBytes }: {
+        /** The resident in-distro agent reads ride. */
+        agent: WslAgent;
+        /** The pinned distro name, for UNC identity. */
+        distro: string;
+        /** The overwrite-diff bound, mirroring the provider config. */
+        diffBasisMaxBytes?: number;
+        /**
+         * Stage-two routing: the agent a MUTATION must run on for this resolved
+         * policy — the confined resident whose mount table matches the granted
+         * rights. Omitted (or resolving to `deps.agent`) keeps every op on the
+         * plain resident, which is stage one's posture.
+         */
+        agentFor?: (policy: {
+            mode: string;
+            workspaceRoot: string;
+        } | undefined) => Promise<WslAgent>;
+    });
+    /**
+     * The agent a mutation runs on under this resolved policy.
+     *
+     * @param policy - the resolved file-effect policy, or undefined when the
+     *   caller pre-checked.
+     * @returns the agent to publish through.
+     */
+    mutationAgent(policy: {
+        mode: string;
+        workspaceRoot: string;
+    } | undefined): Promise<WslAgent>;
+    /**
+     * Run `op` with exclusive access to `targetKey` (FIFO per key).
+     *
+     * @template T
+     * @param targetKey - the mutation's serialization key.
+     * @param op - the exclusive section.
+     * @returns the section's outcome.
+     */
+    lock<T>(targetKey: string, op: () => Promise<T>): Promise<T>;
+    /**
+     * The Linux path a resolved target names, falling back to its display.
+     *
+     * @param target - the resolved target.
+     * @returns the Linux path to operate on.
+     */
+    linuxOf(target: ResolvedTarget): string;
+    /**
+     * Resolve one absolute Linux path to the target shape the provider returns:
+     * the canonical Linux spelling the model sees and the UNC identity the
+     * harness keys on. Symlinks resolve here, where they live.
+     *
+     * @param linuxPath - the absolute Linux path to resolve.
+     * @param signal - cancels the round trip.
+     */
+    resolve(linuxPath: string, signal?: AbortSignal): Promise<{
+        displayPath: string;
+        targetKey: string;
+    }>;
+    /**
+     * Follow-stat one target; `undefined` when absent.
+     *
+     * @param target - the resolved target.
+     * @param signal - cancels the round trip.
+     */
+    stat(target: ResolvedTarget, signal?: AbortSignal): Promise<{
+        version: string;
+        type: string;
+        size: number;
+    } | undefined>;
+    /**
+     * No-follow stat one path; `undefined` when absent, `symlink` for a link.
+     *
+     * @param linuxPath - the absolute Linux path to inspect.
+     * @param signal - cancels the round trip.
+     */
+    lstat(linuxPath: string, signal?: AbortSignal): Promise<{
+        version: string;
+        type: string;
+        size: number;
+    } | undefined>;
+    /**
+     * Read a whole regular UTF-8 file.
+     *
+     * @param target - the resolved target.
+     * @param signal - aborts the read.
+     * @returns the full decoded text.
+     */
+    readText(target: ResolvedTarget, signal?: AbortSignal): Promise<string>;
+    /**
+     * Stream a whole regular UTF-8 file as decoded chunks.
+     *
+     * @param target - the resolved target.
+     * @param signal - aborts the stream.
+     * @returns the chunk stream.
+     */
+    streamText(target: ResolvedTarget, signal?: AbortSignal): Promise<AsyncGenerator<string>>;
+    /**
+     * Read a whole regular file as raw bytes, bounded.
+     *
+     * @param target - the resolved target.
+     * @param signal - aborts the read.
+     * @param maxBytes - inclusive byte cap.
+     * @returns the bytes.
+     */
+    readBytes(target: ResolvedTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>;
+    /**
+     * Read one byte window of a regular file.
+     *
+     * @param target - the resolved target.
+     * @param range - the window.
+     * @param signal - aborts the read.
+     * @returns the window's bytes.
+     */
+    readByteRange(target: ResolvedTarget, range: {
+        offset: number;
+        length: number;
+    }, signal?: AbortSignal): Promise<Uint8Array>;
+    /**
+     * List one directory's direct children.
+     *
+     * @param target - the resolved directory.
+     * @param signal - aborts between children.
+     */
+    listDir(target: ResolvedTarget, signal?: AbortSignal): Promise<Array<{
+        name: string;
+        type: string;
+        target: {
+            displayPath: string;
+            targetKey: string;
+        };
+        version?: string;
+        size?: number;
+    }>>;
+    /**
+     * Write a whole text file with the host backend's orchestration: probe,
+     * guard, best-effort diff basis, atomic publication, outcome shape. The
+     * guard is FORWARDED — a guarded create publishes with the distro-side
+     * no-replace link (atomic), and a `replaceIfVersion` write carries its
+     * version into the op, where the agent re-verifies it one syscall before
+     * the rename and refuses with `FS_STALE_VERSION` on a mismatch.
+     *
+     * @param target - the resolved target.
+     * @param content - the full new file content.
+     * @param expected - the write intent.
+     * @param signal - cancels the write.
+     * @param policy - the resolved policy this write was fenced with; selects
+     *   the confined resident when stage-two routing is wired.
+     */
+    writeText(target: ResolvedTarget, content: string, expected: {
+        kind: string;
+        version?: string;
+    } | undefined, signal?: AbortSignal, policy?: {
+        mode: string;
+        workspaceRoot: string;
+    } | undefined): Promise<{
+        operation: string;
+        version: string;
+        before: string | null;
+        after: string;
+    }>;
+    /**
+     * Edit a text file with the host backend's orchestration: probe, version
+     * guard, LF-normalized read, literal replacement, line-ending restore,
+     * atomic publication, outcome shape. The version the edit was based on
+     * rides the write op and is re-verified distro-side one syscall before the
+     * rename, so a concurrent writer wins instead of being clobbered.
+     *
+     * @param target - the resolved target.
+     * @param edit - the literal request.
+     * @param expected - the version guard.
+     * @param signal - cancels the edit.
+     * @param policy - the resolved policy this edit was fenced with; selects
+     *   the confined resident when stage-two routing is wired.
+     */
+    editText(target: ResolvedTarget, edit: {
+        oldString: string;
+        newString: string;
+        replaceAll?: boolean;
+    }, expected: {
+        version: string;
+    } | undefined, signal?: AbortSignal, policy?: {
+        mode: string;
+        workspaceRoot: string;
+    } | undefined): Promise<{
+        version: string;
+        before: string;
+        after: string;
+    }>;
+}
+export default AgentSubstrate;