dsh-plugin-wsl-env 0.7.5 → 0.8.0

package/lib/fs-substrate.js

@@ -27,268 +27,268 @@
  * 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 { applyLiteralEdit, FsCodedError, normalizeLineEndings, restoreLineEndings } from "./fsio-text.js";
 import { DistroFs } from "./fsio-agent.js";
 import { posixToUnc, uncToPosix } from "./paths.js";
-
-/** The provider's stat/lstat row, type-spelled the way the tool layer reads it. */
+/**
+ * The provider's stat/lstat row, type-spelled the way the tool layer reads it.
+ *
+ * @param info - the distro stat row.
+ * @returns the provider-shaped row.
+ */
 function toInfo({ version, type, size }) {
-  return {
-    version,
-    type: type === "f" ? "file" : type === "d" ? "directory" : type === "l" ? "symlink" : "other",
-    size,
-  };
+    return {
+        version,
+        type: type === "f" ? "file" : type === "d" ? "directory" : type === "l" ? "symlink" : "other",
+        size,
+    };
 }
-
 /**
  * One distro's provider-shaped filesystem face.
  */
 export class AgentSubstrate {
-  /**
-   * @param {object} deps - the substrate's collaborators.
-   * @param {import("./agent.js").WslAgent} deps.agent - the resident in-distro agent reads ride.
-   * @param {string} deps.distro - the pinned distro name, for UNC identity.
-   * @param {number} [deps.diffBasisMaxBytes] - the overwrite-diff bound, mirroring the provider config.
-   * @param {(policy: {mode: string, workspaceRoot: string}|undefined) => Promise<import("./agent.js").WslAgent>} [deps.agentFor]
-   *   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.
-   */
-  constructor({ agent, agentFor, distro, diffBasisMaxBytes = 10 * 1024 * 1024 }) {
-    this.distro = distro;
-    this.diffBasisMaxBytes = diffBasisMaxBytes;
-    this.agent = agent;
-    this.agentFor = agentFor;
-    this.fs = new DistroFs({ agent, distro });
-    /** Per-targetKey tail promise: the host backend's mutation serialization. */
-    this.locks = new Map();
-  }
-
-  /**
-   * The agent a mutation runs on under this resolved policy.
-   * @param {{mode: string, workspaceRoot: string}|undefined} policy - the
-   *   resolved file-effect policy, or undefined when the caller pre-checked.
-   * @returns {Promise<object>} the agent to publish through.
-   */
-  async mutationAgent(policy) {
-    if (this.agentFor === undefined) return this.agent;
-    return this.agentFor(policy);
-  }
-
-  /** Run `op` with exclusive access to `targetKey` (FIFO per key). */
-  async lock(targetKey, op) {
-    const run = (this.locks.get(targetKey) ?? Promise.resolve()).then(op, op);
-    const tail = run.then(() => undefined, () => undefined);
-    this.locks.set(targetKey, tail);
-    try {
-      return await run;
-    } finally {
-      if (this.locks.get(targetKey) === tail) this.locks.delete(targetKey);
+    /**
+     * @param deps - the substrate's collaborators.
+     */
+    constructor({ agent, agentFor, distro, diffBasisMaxBytes = 10 * 1024 * 1024 }) {
+        this.distro = distro;
+        this.diffBasisMaxBytes = diffBasisMaxBytes;
+        this.agent = agent;
+        this.agentFor = agentFor;
+        this.fs = new DistroFs({ agent, distro });
+        this.locks = new Map();
     }
-  }
-
-  /** The Linux path a resolved target names, falling back to its display. */
-  linuxOf(target) {
-    return uncToPosix(target.targetKey)?.linuxPath ?? target.displayPath;
-  }
-
-  /**
-   * 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 {string} linuxPath - the absolute Linux path to resolve.
-   * @param {AbortSignal} [signal] - cancels the round trip.
-   * @returns {Promise<{displayPath: string, targetKey: string}>}
-   */
-  async resolve(linuxPath, signal) {
-    const canonical = await this.fs.canonicalPath(linuxPath, signal);
-    return { displayPath: canonical, targetKey: posixToUnc(this.distro, canonical) };
-  }
-
-  /**
-   * Follow-stat one target; `undefined` when absent.
-   * @param {object} target - the resolved target.
-   * @param {AbortSignal} [signal] - cancels the round trip.
-   * @returns {Promise<{version: string, type: string, size: number}|undefined>}
-   */
-  async stat(target, signal) {
-    const info = await this.fs.stat(this.linuxOf(target), { signal });
-    return info === null ? undefined : toInfo(info);
-  }
-
-  /**
-   * No-follow stat one path; `undefined` when absent, `symlink` for a link.
-   * @param {string} linuxPath - the absolute Linux path to inspect.
-   * @param {AbortSignal} [signal] - cancels the round trip.
-   * @returns {Promise<{version: string, type: string, size: number}|undefined>}
-   */
-  async lstat(linuxPath, signal) {
-    if (String(linuxPath).trim().length === 0) {
-      throw new FsCodedError("file_path must be a non-empty string", "FS_NOT_FOUND");
+    /**
+     * 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.
+     */
+    async mutationAgent(policy) {
+        if (this.agentFor === undefined)
+            return this.agent;
+        return this.agentFor(policy);
     }
-    const info = await this.fs.stat(linuxPath, { follow: false, signal });
-    return info === null ? undefined : toInfo(info);
-  }
-
-  /**
-   * Read a whole regular UTF-8 file.
-   * @param {object} target - the resolved target.
-   * @param {AbortSignal} [signal] - aborts the read.
-   * @returns {Promise<string>} the full decoded text.
-   */
-  async readText(target, signal) {
-    return this.fs.readWholeText(target, signal);
-  }
-
-  /**
-   * Stream a whole regular UTF-8 file as decoded chunks.
-   * @param {object} target - the resolved target.
-   * @param {AbortSignal} [signal] - aborts the stream.
-   * @returns {Promise<AsyncGenerator<string>>} the chunk stream.
-   */
-  async streamText(target, signal) {
-    return this.fs.streamWholeText(target, signal);
-  }
-
-  /**
-   * Read a whole regular file as raw bytes, bounded.
-   * @param {object} target - the resolved target.
-   * @param {AbortSignal|undefined} signal - aborts the read.
-   * @param {number} maxBytes - inclusive byte cap.
-   * @returns {Promise<Uint8Array>} the bytes.
-   */
-  async readBytes(target, signal, maxBytes) {
-    return this.fs.readWholeBytes(target, signal, maxBytes);
-  }
-
-  /**
-   * Read one byte window of a regular file.
-   * @param {object} target - the resolved target.
-   * @param {{offset: number, length: number}} range - the window.
-   * @param {AbortSignal} [signal] - aborts the read.
-   * @returns {Promise<Uint8Array>} the window's bytes.
-   */
-  async readByteRange(target, range, signal) {
-    return this.fs.readByteWindow(target, range, signal);
-  }
-
-  /**
-   * List one directory's direct children.
-   * @param {object} target - the resolved directory.
-   * @param {AbortSignal} [signal] - aborts between children.
-   * @returns {Promise<Array<{name: string, type: string, target: {displayPath: string, targetKey: string}, version?: string, size?: number}>>}
-   */
-  async listDir(target, signal) {
-    return this.fs.listChildren(target, signal);
-  }
-
-  /**
-   * 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 {object} target - the resolved target.
-   * @param {string} content - the full new file content.
-   * @param {{kind: string, version?: string}|undefined} expected - the write intent.
-   * @param {AbortSignal} [signal] - cancels the write.
-   * @param {{mode: string, workspaceRoot: string}|undefined} [policy] - the
-   *   resolved policy this write was fenced with; selects the confined
-   *   resident when stage-two routing is wired.
-   * @returns {Promise<{operation: string, version: string, before: string|null, after: string}>}
-   */
-  async writeText(target, content, expected, signal, policy) {
-    const mutationAgent = await this.mutationAgent(policy);
-    return this.lock(target.targetKey, async () => {
-      const linuxPath = this.linuxOf(target);
-      const existing = await this.fs.stat(linuxPath, { signal });
-      if (existing && existing.type !== "f") {
-        throw new FsCodedError(`cannot write "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
-      }
-      if (expected?.kind === "replaceIfVersion") {
-        if (!existing) throw new FsCodedError(`cannot write "${target.displayPath}": file no longer exists`, "FS_STALE_VERSION");
-        if (existing.version !== expected.version) {
-          throw new FsCodedError(`cannot write "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+    /**
+     * 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.
+     */
+    async lock(targetKey, op) {
+        const run = (this.locks.get(targetKey) ?? Promise.resolve()).then(op, op);
+        const tail = run.then(() => undefined, () => undefined);
+        this.locks.set(targetKey, tail);
+        try {
+            return await run;
+        }
+        finally {
+            if (this.locks.get(targetKey) === tail)
+                this.locks.delete(targetKey);
         }
-      } else if (expected?.kind === "createIfAbsent" && existing) {
-        throw new FsCodedError(`cannot overwrite existing "${target.displayPath}" without reading it first`, "FS_NOT_OBSERVED");
-      }
-      const before =
-        existing !== null && Buffer.byteLength(content, "utf8") < this.diffBasisMaxBytes
-          ? await this.fs.readTextForDiff(target, this.diffBasisMaxBytes, signal)
-          : null;
-      await this.fs.writeFileAtomic(linuxPath, content, {
-        mode: existing?.mode,
-        createIfAbsent: expected?.kind === "createIfAbsent" ? { displayPath: target.displayPath } : undefined,
-        expectedVersion: expected?.kind === "replaceIfVersion" ? expected.version : undefined,
-        signal,
-        agent: mutationAgent,
-      });
-      const after = await this.fs.stat(linuxPath, { signal });
-      return {
-        operation: existing ? "update" : "create",
-        version: after ? after.version : `missing:${target.targetKey}`,
-        before,
-        after: normalizeLineEndings(content),
-      };
-    });
-  }
-
-  /**
-   * 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 {object} target - the resolved target.
-   * @param {{oldString: string, newString: string, replaceAll?: boolean}} edit - the literal request.
-   * @param {{version: string}|undefined} expected - the version guard.
-   * @param {AbortSignal} [signal] - cancels the edit.
-   * @param {{mode: string, workspaceRoot: string}|undefined} [policy] - the
-   *   resolved policy this edit was fenced with; selects the confined
-   *   resident when stage-two routing is wired.
-   * @returns {Promise<{version: string, before: string, after: string}>}
-   */
-  async editText(target, edit, expected, signal, policy) {
-    const mutationAgent = await this.mutationAgent(policy);
-    return this.lock(target.targetKey, async () => {
-      const linuxPath = this.linuxOf(target);
-      const existing = await this.fs.stat(linuxPath, { signal });
-      if (!existing) {
-        // A file that is not there NOW splits by evidence: an edit grounded
-        // in a read (it carries the expected version) lost its file, so the
-        // guard is stale; an edit with no read behind it names a file that
-        // never answered the stat - the read path's missing-file dialect.
-        if (expected) {
-          throw new FsCodedError(`cannot edit "${target.displayPath}": file no longer exists`, "FS_STALE_VERSION");
+    }
+    /**
+     * 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) {
+        return uncToPosix(target.targetKey)?.linuxPath ?? target.displayPath;
+    }
+    /**
+     * 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.
+     */
+    async resolve(linuxPath, signal) {
+        const canonical = await this.fs.canonicalPath(linuxPath, signal);
+        return { displayPath: canonical, targetKey: posixToUnc(this.distro, canonical) };
+    }
+    /**
+     * Follow-stat one target; `undefined` when absent.
+     *
+     * @param target - the resolved target.
+     * @param signal - cancels the round trip.
+     */
+    async stat(target, signal) {
+        const info = await this.fs.stat(this.linuxOf(target), { signal });
+        return info === null ? undefined : toInfo(info);
+    }
+    /**
+     * 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.
+     */
+    async lstat(linuxPath, signal) {
+        if (String(linuxPath).trim().length === 0) {
+            throw new FsCodedError("file_path must be a non-empty string", "FS_NOT_FOUND");
         }
-        throw new FsCodedError(`cannot edit "${target.displayPath}": file does not exist`, "FS_NOT_FOUND");
-      }
-      if (existing.type !== "f") {
-        throw new FsCodedError(`cannot edit "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
-      }
-      if (expected && existing.version !== expected.version) {
-        throw new FsCodedError(`cannot edit "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
-      }
-      const original = await this.fs.readForEdit(target, signal);
-      const edited = applyLiteralEdit(original.content, edit.oldString, edit.newString, edit.replaceAll, target.displayPath);
-      const content = restoreLineEndings(edited.content, original.lineEndings);
-      await this.fs.writeFileAtomic(linuxPath, content, { mode: existing.mode, expectedVersion: existing.version, signal, agent: mutationAgent });
-      const after = await this.fs.stat(linuxPath, { signal });
-      return {
-        version: after ? after.version : `missing:${target.targetKey}`,
-        before: original.content,
-        after: edited.content,
-      };
-    });
-  }
+        const info = await this.fs.stat(linuxPath, { follow: false, signal });
+        return info === null ? undefined : toInfo(info);
+    }
+    /**
+     * Read a whole regular UTF-8 file.
+     *
+     * @param target - the resolved target.
+     * @param signal - aborts the read.
+     * @returns the full decoded text.
+     */
+    async readText(target, signal) {
+        return this.fs.readWholeText(target, signal);
+    }
+    /**
+     * Stream a whole regular UTF-8 file as decoded chunks.
+     *
+     * @param target - the resolved target.
+     * @param signal - aborts the stream.
+     * @returns the chunk stream.
+     */
+    async streamText(target, signal) {
+        return this.fs.streamWholeText(target, signal);
+    }
+    /**
+     * 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.
+     */
+    async readBytes(target, signal, maxBytes) {
+        return this.fs.readWholeBytes(target, signal, maxBytes);
+    }
+    /**
+     * 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.
+     */
+    async readByteRange(target, range, signal) {
+        return this.fs.readByteWindow(target, range, signal);
+    }
+    /**
+     * List one directory's direct children.
+     *
+     * @param target - the resolved directory.
+     * @param signal - aborts between children.
+     */
+    async listDir(target, signal) {
+        return this.fs.listChildren(target, signal);
+    }
+    /**
+     * 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.
+     */
+    async writeText(target, content, expected, signal, policy) {
+        const mutationAgent = await this.mutationAgent(policy);
+        return this.lock(target.targetKey, async () => {
+            const linuxPath = this.linuxOf(target);
+            const existing = await this.fs.stat(linuxPath, { signal });
+            if (existing && existing.type !== "f") {
+                throw new FsCodedError(`cannot write "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
+            }
+            if (expected?.kind === "replaceIfVersion") {
+                if (!existing)
+                    throw new FsCodedError(`cannot write "${target.displayPath}": file no longer exists`, "FS_STALE_VERSION");
+                if (existing.version !== expected.version) {
+                    throw new FsCodedError(`cannot write "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+                }
+            }
+            else if (expected?.kind === "createIfAbsent" && existing) {
+                throw new FsCodedError(`cannot overwrite existing "${target.displayPath}" without reading it first`, "FS_NOT_OBSERVED");
+            }
+            const before = existing !== null && Buffer.byteLength(content, "utf8") < this.diffBasisMaxBytes
+                ? await this.fs.readTextForDiff(target, this.diffBasisMaxBytes, signal)
+                : null;
+            await this.fs.writeFileAtomic(linuxPath, content, {
+                mode: existing?.mode,
+                createIfAbsent: expected?.kind === "createIfAbsent" ? { displayPath: target.displayPath } : undefined,
+                expectedVersion: expected?.kind === "replaceIfVersion" ? expected.version : undefined,
+                signal,
+                agent: mutationAgent,
+            });
+            const after = await this.fs.stat(linuxPath, { signal });
+            return {
+                operation: existing ? "update" : "create",
+                version: after ? after.version : `missing:${target.targetKey}`,
+                before,
+                after: normalizeLineEndings(content),
+            };
+        });
+    }
+    /**
+     * 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.
+     */
+    async editText(target, edit, expected, signal, policy) {
+        const mutationAgent = await this.mutationAgent(policy);
+        return this.lock(target.targetKey, async () => {
+            const linuxPath = this.linuxOf(target);
+            const existing = await this.fs.stat(linuxPath, { signal });
+            if (!existing) {
+                // A file that is not there NOW splits by evidence: an edit grounded
+                // in a read (it carries the expected version) lost its file, so the
+                // guard is stale; an edit with no read behind it names a file that
+                // never answered the stat - the read path's missing-file dialect.
+                if (expected) {
+                    throw new FsCodedError(`cannot edit "${target.displayPath}": file no longer exists`, "FS_STALE_VERSION");
+                }
+                throw new FsCodedError(`cannot edit "${target.displayPath}": file does not exist`, "FS_NOT_FOUND");
+            }
+            if (existing.type !== "f") {
+                throw new FsCodedError(`cannot edit "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
+            }
+            if (expected && existing.version !== expected.version) {
+                throw new FsCodedError(`cannot edit "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+            }
+            const original = await this.fs.readForEdit(target, signal);
+            const edited = applyLiteralEdit(original.content, edit.oldString, edit.newString, edit.replaceAll, target.displayPath);
+            const content = restoreLineEndings(edited.content, original.lineEndings);
+            await this.fs.writeFileAtomic(linuxPath, content, { mode: existing.mode, expectedVersion: existing.version, signal, agent: mutationAgent });
+            const after = await this.fs.stat(linuxPath, { signal });
+            return {
+                version: after ? after.version : `missing:${target.targetKey}`,
+                before: original.content,
+                after: edited.content,
+            };
+        });
+    }
 }
-
 export default AgentSubstrate;

package/lib/fs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `ctx.fs` entrypoint — load as `dsh-plugin-wsl/fs` in a profile patch.
+ *
+ * This is a TypeScript source built to `lib/fs.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
+ */
+export { WslFileSystem as default, WslFileSystem } from "./index.js";

package/lib/fs.js

@@ -1,5 +1,10 @@
 /**
  * `ctx.fs` entrypoint — load as `dsh-plugin-wsl/fs` in a profile patch.
+ *
+ * This is a TypeScript source built to `lib/fs.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
  */
 export { WslFileSystem as default, WslFileSystem } from "./index.js";