dsh-plugin-wsl-env 0.7.5 → 0.9.0

package/lib/fs-decisions.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ *
+ * This is a TypeScript source built to `lib/fs-decisions.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-decisions
+ */
+/** A refusal descriptor the provider wraps in `FsError` at one choke point. */
+export interface Refusal {
+    /** The model-facing refusal text. */
+    message: string;
+    /** The `FS_*` token. */
+    code: string;
+}
+/**
+ * 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 input - the decision's inputs.
+ * @returns the refusal, or null to proceed.
+ */
+export declare function outsideDistroRefusal({ path, world, distro, restrictToDistro }: {
+    path: string;
+    world: string;
+    distro: string;
+    restrictToDistro: boolean;
+}): Refusal | null;
+/**
+ * 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 input - the decision's inputs.
+ * @returns true when the mutation belongs to the confined resident.
+ */
+export declare function isConfinedMutation({ policy, sandboxEnabled }: {
+    policy: {
+        mode: string;
+        workspaceRoot: string;
+    } | undefined;
+    sandboxEnabled: boolean;
+}): boolean;
+/**
+ * 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 mode - the resolved policy mode.
+ * @param displayPath - the caller-facing path for the message.
+ * @returns the refusal, or null to proceed.
+ */
+export declare function mutationModeRefusal(mode: string, displayPath: string): Refusal | null;
+/**
+ * The containment denial for a `workspace-write` mutation whose fresh target
+ * sat under no writable root.
+ *
+ * @param displayPath - the caller-facing path for the message.
+ * @returns the refusal descriptor.
+ */
+export declare function workspaceWriteDenial(displayPath: string): Refusal;
+/**
+ * The substrate configuration decision: the Windows-side share no longer
+ * serves the file tools. Every distro read and write runs on the resident
+ * agent, so no model-facing I/O crosses the 9p share at all — the share
+ * backend it replaces was the one path that still could. The provider throws
+ * this at construction time, before any session forms, so a profile carrying
+ * the old value fails loudly with the migration instead of silently serving
+ * I/O the configuration did not mean to allow.
+ *
+ * @param substrate - the configured substrate value; absent on a
+ *   direct construction, which is not the retired share.
+ * @returns the refusal, or null to proceed.
+ */
+export declare function shareSubstrateRefusal(substrate?: string): {
+    message: string;
+} | 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 resident agent that serves every distro read and write is out — and the
+ * message names the recovery path, because there is no fallback I/O for it to
+ * point at.
+ *
+ * @param error - what the substrate raised.
+ * @returns the refusal the provider wraps in `FsError`.
+ */
+export declare function substrateFailure(error: unknown): {
+    message: string;
+    code: string;
+    cause: unknown;
+};

package/lib/fs-decisions.js

@@ -11,73 +11,72 @@
  * provider produced before the extraction — the tool layer and the model match
  * on these strings.
  *
+ * This is a TypeScript source built to `lib/fs-decisions.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-decisions
  */
-
 import { isAnotherDistrosUnc } from "./paths.js";
-
-/** A refusal descriptor the provider wraps in `FsError` at one choke point. */
+/**
+ * Build one refusal descriptor.
+ *
+ * @param message - the model-facing refusal text.
+ * @param code - the `FS_*` token.
+ * @returns the descriptor.
+ */
 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.
+ *
+ * @param input - the decision's inputs.
+ * @returns 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",
-  );
+    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.
+ *
+ * @param input - the decision's inputs.
+ * @returns true when the mutation belongs to the confined resident.
  */
 export function isConfinedMutation({ policy, sandboxEnabled }) {
-  return Boolean(policy) && Boolean(sandboxEnabled) && policy.mode !== "danger-full-access";
+    return policy !== undefined && 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.
+ *
+ * @param mode - the resolved policy mode.
+ * @param displayPath - the caller-facing path for the message.
+ * @returns 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");
+    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.
+ *
+ * @param displayPath - the caller-facing path for the message.
+ * @returns the refusal descriptor.
  */
 export function workspaceWriteDenial(displayPath) {
-  return refusal(`cannot write "${displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
+    return refusal(`cannot write "${displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
 }
-
 /**
  * The substrate configuration decision: the Windows-side share no longer
  * serves the file tools. Every distro read and write runs on the resident
@@ -86,19 +85,20 @@ export function workspaceWriteDenial(displayPath) {
  * this at construction time, before any session forms, so a profile carrying
  * the old value fails loudly with the migration instead of silently serving
  * I/O the configuration did not mean to allow.
- * @param {string} substrate - the configured substrate value.
- * @returns {{message: string}|null} the refusal, or null to proceed.
+ *
+ * @param substrate - the configured substrate value; absent on a
+ *   direct construction, which is not the retired share.
+ * @returns the refusal, or null to proceed.
  */
 export function shareSubstrateRefusal(substrate) {
-  if (substrate !== "share") return null;
-  return {
-    message:
-      'wsl-fs: substrate "share" is no longer available — the resident agent serves every ' +
-      "distro read and write, and no file tool crosses the 9p share. Delete the substrate " +
-      'line from the provider config, or set it to "agent".',
-  };
+    if (substrate !== "share")
+        return null;
+    return {
+        message: 'wsl-fs: substrate "share" is no longer available — the resident agent serves every ' +
+            "distro read and write, and no file tool crosses the 9p share. Delete the substrate " +
+            'line from the provider config, or set it to "agent".',
+    };
 }
-
 /**
  * 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
@@ -106,24 +106,28 @@ export function shareSubstrateRefusal(substrate) {
  * the resident agent that serves every distro read and write is out — and the
  * message names the recovery path, because there is no fallback I/O for it to
  * point at.
- * @param {unknown} error - what the substrate raised.
- * @returns {{message: string, code: string, cause: unknown}} the refusal the
- *   provider wraps in `FsError`.
+ *
+ * @param error - what the substrate raised.
+ * @returns 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}. ` +
-      `The resident agent serves every distro read and write; check the distro is running ` +
-      `("wsl.exe -l -v") and restart the session if it stays out.`,
-    code: "FS_IO_ERROR",
-    cause: error instanceof Error ? error : undefined,
-  };
+    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}. ` +
+            `The resident agent serves every distro read and write; check the distro is running ` +
+            `("wsl.exe -l -v") and restart the session if it stays out.`,
+        code: "FS_IO_ERROR",
+        cause: error instanceof Error ? error : undefined,
+    };
 }
-
-/** A coded refusal: our `FsCodedError` duck (a message, a string `FS_*` code). */
+/**
+ * A coded refusal: our `FsCodedError` duck (a message, a string `FS_*` code).
+ *
+ * @param error - what the substrate raised.
+ * @returns true when `error` carries a string `FS_*` code.
+ */
 function isCoded(error) {
-  return error instanceof Error && typeof error.code === "string" && error.code.startsWith("FS_");
+    return error instanceof Error && typeof error.code === "string" && error.code.startsWith("FS_");
 }

package/lib/fs-routing.d.ts

@@ -0,0 +1,182 @@
+/**
+ * The root-plane filesystem with coordinate routing: targets under a
+ * `\\wsl.localhost\<distro>` identity are served by the distro substrate
+ * (the resident agent, on ext4); every other target — drive-letter paths,
+ * the deployment cwd — is served by the host `LocalFileSystem` this class
+ * extends, unchanged.
+ *
+ * ## Why a router, and why here
+ *
+ * The root `ctx.fs` is session-less: it cannot be switched per session the
+ * way a preset's isolated `fs` can, so the two workspace kinds share one
+ * backend — and the stock backend serves the distro workspace across the 9p
+ * share, in its slow direction, with no usable change notifications. Routing
+ * by coordinate makes every root consumer (the workspace-files change feed
+ * among them) correct on both workspace kinds without per-consumer patches.
+ *
+ * The design note is `docs/root-fs-routing.md` (the operation routing table,
+ * the intended behavior differences, and the dormant-root-fence rationale).
+ *
+ * ## What is intentionally not here
+ *
+ * No write fence: the root plane has no write consumers (the model's writes
+ * ride the per-session preset filesystems, which enforce their own
+ * 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 { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
+import { WslFileSystem } from "./index.js";
+import type { Context } from "@deepseek-ai/cordis";
+import type { FsTarget, FsVersion, FsWriteIntent, FsEditRequest } from "@deepseek-ai/dsh-fs";
+import type { SandboxExecutionPolicy } from "@deepseek-ai/dsh-sandbox";
+/**
+ * The router's config: the host backend's own knobs plus the distro knobs the
+ * routed backend reads. The distro keys are `??`-defaulted, so a host-only
+ * config stays valid.
+ */
+export interface RoutingConfig {
+    /** The host backend's base directory. */
+    cwd?: string;
+    /** The host backend's overwrite-diff byte bound. */
+    diffBasisMaxBytes?: number;
+    /** The pinned distro for routed targets; empty resolves WSL's default. */
+    distro?: string;
+    /** The `wsl.exe` path, used only to resolve the default distro. */
+    wslPath?: string;
+    /** The routed backend's default workdir. */
+    distroCwd?: string;
+    /** Whether the routed backend fences mutations by `ctx.sandboxPolicy`. */
+    sandbox?: boolean;
+    /** Whether confined profiles shadow `/mnt`. */
+    maskWindowsDrive?: boolean;
+    /** Whether the routed backend refuses paths outside the distro. */
+    restrictToDistro?: boolean;
+    /** How deep the in-distro watch scan walks. */
+    watchMaxDepth?: number;
+}
+/**
+ * Whether a resolved target identity belongs to the distro.
+ *
+ * @param targetKey - the target's identity (a UNC for distro paths).
+ * @returns true when the target lives inside a WSL distro.
+ */
+export declare function targetIsDistro(targetKey: string): boolean;
+/**
+ * Whether a raw path-or-cwd input names the distro (used by the operations
+ * that take paths before a target exists: resolve, lstat).
+ *
+ * @param value - a path in any coordinate system, or undefined.
+ * @returns true when the input names a distro UNC.
+ */
+export declare function inputIsDistro(value: string | undefined): boolean;
+/**
+ * The root-plane filesystem with coordinate routing.
+ *
+ * The distro backend is built lazily on the first routed target, sharing this
+ * context (the root `sandboxPolicy` service provides the deployment default
+ * mode the distro side reports through `sandboxMode`).
+ */
+export declare class WslRoutingFileSystem extends LocalFileSystem {
+    #private;
+    static Config: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/dsh-fs-local").Config>;
+    /**
+     * @param ctx - the cordis context.
+     * @param config - the row config, host knobs plus distro knobs.
+     */
+    constructor(ctx: Context, config: RoutingConfig);
+    /** The distro backend for routed targets, built on first use. */
+    distro(): WslFileSystem;
+    /**
+     * @param path - the requested path.
+     * @param opts - the resolve options.
+     */
+    resolve(path: string, opts?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<FsTarget>;
+    /**
+     * @param path - the requested path.
+     * @param opts - the lstat options.
+     * @param signal - cancels the round trip.
+     */
+    lstat(path: string, opts?: {
+        cwd?: string;
+    }, signal?: AbortSignal): Promise<import("@deepseek-ai/dsh-fs").FsPathInfo | undefined>;
+    /**
+     * @param target - the resolved target.
+     * @param signal - cancels the round trip.
+     */
+    stat(target: FsTarget, signal?: AbortSignal): Promise<import("@deepseek-ai/dsh-fs").FsInfo | undefined>;
+    /**
+     * @param target - the resolved target.
+     * @param signal - cancels the round trip.
+     */
+    readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
+    /**
+     * @param target - the resolved target.
+     * @param signal - cancels the stream.
+     */
+    streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
+    /**
+     * @param target - the resolved target.
+     * @param signal - cancels the read.
+     * @param maxBytes - the inclusive byte cap.
+     */
+    readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array<ArrayBufferLike>>;
+    /**
+     * @param target - the resolved target.
+     * @param range - the byte window.
+     * @param signal - cancels the read.
+     */
+    readByteRange(target: FsTarget, range: {
+        offset: number;
+        length: number;
+    }, signal?: AbortSignal): Promise<Uint8Array<ArrayBufferLike>>;
+    /**
+     * @param target - the resolved directory.
+     * @param signal - cancels the listing.
+     */
+    listDir(target: FsTarget, signal?: AbortSignal): Promise<import("@deepseek-ai/dsh-fs").FsDirEntry[]>;
+    /**
+     * @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.
+     */
+    writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<import("@deepseek-ai/dsh-fs").FsWriteOutcome>;
+    /**
+     * @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.
+     */
+    editText(target: FsTarget, edit: FsEditRequest, expected?: {
+        version: FsVersion;
+    }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<import("@deepseek-ai/dsh-fs").FsEditOutcome>;
+    /**
+     * @param target - the resolved target.
+     * @param changed - the change callback.
+     * @param signal - cancels the watch.
+     */
+    watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>;
+    /**
+     * @param parent - the container.
+     * @param child - the contained candidate.
+     */
+    contains(parent: FsTarget, child: FsTarget): boolean;
+    /**
+     * @param target - the resolved target.
+     */
+    processPath(target: FsTarget): string;
+}
+export default WslRoutingFileSystem;