dsh-plugin-wsl-env 0.2.0 → 0.4.0

package/lib/fs-decisions.js

@@ -0,0 +1,132 @@
+/**
+ * The filesystem provider's POLICY DECISIONS, extracted from
+ * `lib/index.js` so they are unit-testable in a bare checkout: which paths are
+ * refused for naming another distro, which mode refuses a mutation outright,
+ * which write guards refuse which intents, and how a substrate failure maps
+ * onto the refusal the tool layer surfaces. Pure in, descriptor out — no I/O,
+ * no peers (the provider wraps these descriptors in `FsError` at one choke
+ * point, keeping the peer import out of this module and the decisions honest).
+ *
+ * Every message here is model-facing and must stay byte-identical to what the
+ * provider produced before the extraction — the tool layer and the model match
+ * on these strings.
+ *
+ * @module dsh-plugin-wsl/fs-decisions
+ */
+
+import { isAnotherDistrosUnc } from "./paths.js";
+
+/** A refusal descriptor the provider wraps in `FsError` at one choke point. */
+const refusal = (message, code) => ({ message, code });
+
+/**
+ * The worldPath decision: a path that resolves into another WSL distro is
+ * refused while `restrictToDistro` holds — deliberately NOT a sandbox denial,
+ * because no wider permission can lift a configuration choice.
+ * @param {object} input - the decision's inputs.
+ * @param {string} input.path - the path as the caller spelled it.
+ * @param {string} input.world - the resolved world path (a UNC for distro paths).
+ * @param {string} input.distro - the pinned distro name.
+ * @param {boolean} input.restrictToDistro - the configuration fence.
+ * @returns {{message: string, code: string}|null} the refusal, or null to proceed.
+ */
+export function outsideDistroRefusal({ path, world, distro, restrictToDistro }) {
+  if (!restrictToDistro || !isAnotherDistrosUnc(world, distro)) return null;
+  return refusal(
+    `"${path}" names a path in another WSL distro, and this profile pins its filesystem to "${distro}" ` +
+      `(restrictToDistro: true). Open a session in that distro, or set restrictToDistro: false.`,
+    "FS_OUTSIDE_DISTRO",
+  );
+}
+
+/**
+ * The mutationAgent decision: does THIS mutation route to the confined
+ * resident? An absent policy (caller pre-checked), a disabled sandbox, and an
+ * approved escalation all address the plain resident — which is what those
+ * mean.
+ * @param {object} input - the decision's inputs.
+ * @param {{mode: string, workspaceRoot: string}|undefined} input.policy - the
+ *   resolved file-effect policy.
+ * @param {boolean} input.sandboxEnabled - the provider's `sandbox` configuration.
+ * @returns {boolean} true when the mutation belongs to the confined resident.
+ */
+export function isConfinedMutation({ policy, sandboxEnabled }) {
+  return Boolean(policy) && Boolean(sandboxEnabled) && policy.mode !== "danger-full-access";
+}
+
+/**
+ * The mode-level mutation decision: `read-only` refuses every write outright;
+ * `danger-full-access` is the approved escalation and refuses nothing.
+ * `workspace-write` refuses nothing HERE — its containment check needs the
+ * fresh target and runs in the provider.
+ * @param {string} mode - the resolved policy mode.
+ * @param {string} displayPath - the caller-facing path for the message.
+ * @returns {{message: string, code: string}|null} the refusal, or null to proceed.
+ */
+export function mutationModeRefusal(mode, displayPath) {
+  if (mode !== "read-only") return null;
+  return refusal(`cannot write "${displayPath}": file access denied under read-only mode`, "FS_SANDBOX_DENIED");
+}
+
+/**
+ * The containment denial for a `workspace-write` mutation whose fresh target
+ * sat under no writable root.
+ * @param {string} displayPath - the caller-facing path for the message.
+ * @returns {{message: string, code: string}} the refusal descriptor.
+ */
+export function workspaceWriteDenial(displayPath) {
+  return refusal(`cannot write "${displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
+}
+
+/**
+ * The write/edit guard: compare the intent (`expected`) with what is on disk
+ * NOW (`existing`, a stat row or `undefined`) and refuse the stale or
+ * unobserved intent. The peer's dialect, byte for byte.
+ * @param {object|undefined} expected - the write intent (`replaceIfVersion`
+ *   with a `version`, or `createIfAbsent`), or `undefined` for an unguarded write.
+ * @param {{version: string}|undefined} existing - what stat found, or undefined.
+ * @param {string} displayPath - the caller-facing path for the message.
+ * @returns {{message: string, code: string}|null} the refusal, or null to proceed.
+ */
+export function guardRefusal(expected, existing, displayPath) {
+  if (expected === undefined) return null;
+  if (expected.kind === "replaceIfVersion") {
+    if (existing === undefined) return refusal(`cannot write "${displayPath}": file no longer exists`, "FS_STALE_VERSION");
+    if (existing.version !== expected.version) {
+      return refusal(`cannot write "${displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+    }
+    return null;
+  }
+  if (expected.kind === "createIfAbsent" && existing !== undefined) {
+    return refusal(`cannot overwrite existing "${displayPath}" without reading it first`, "FS_NOT_OBSERVED");
+  }
+  return null;
+}
+
+/**
+ * The substrate failure mapping: what the tool layer should surface for an
+ * error that crossed the `ctx.fs` seam. A coded refusal keeps its code and
+ * message byte-for-byte; anything else is the substrate being UNAVAILABLE —
+ * the share backend's "distro is gone" case wearing the agent substrate's
+ * wording — and the message names the documented opt-out, so an operator hit
+ * by the fail-closed posture can reach the old behaviour without a doc trip.
+ * @param {unknown} error - what the substrate raised.
+ * @returns {{message: string, code: string, cause: unknown}} the refusal the
+ *   provider wraps in `FsError`.
+ */
+export function substrateFailure(error) {
+  if (isCoded(error)) return { message: error.message, code: error.code, cause: error };
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    message:
+      `the distro file substrate is unavailable: ${message}. ` +
+      `Set "substrate: \\"share\\"" in the provider config to work on the Windows-side share while the agent is out.`,
+    code: "FS_IO_ERROR",
+    cause: error instanceof Error ? error : undefined,
+  };
+}
+
+/** A coded refusal: our `FsCodedError` duck (a message, a string `FS_*` code). */
+function isCoded(error) {
+  return error instanceof Error && typeof error.code === "string" && error.code.startsWith("FS_");
+}

package/lib/fs-substrate.js

@@ -0,0 +1,285 @@
+/**
+ * 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.
+ *
+ * @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. */
+function toInfo({ version, type, 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);
+    }
+  }
+
+  /** 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");
+    }
+    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");
+        }
+      } 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) throw new FsCodedError(`cannot edit "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+      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;