@dsh-electron/dsh-plugin-multi-root-workspace 0.1.0

package/lib/types/contract.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The wire contract between the browser panel and this plugin's host half.
+ *
+ * It is deliberately transport-agnostic plain data: the host registers one
+ * Connection RPC channel (see `command.ts`) and the client bundle inlines this
+ * module, so both sides agree on endpoint names and payload shapes without
+ * sharing any runtime identity. Error codes are the stable half of the
+ * contract; `message` is only a fallback the panel does not have to show.
+ *
+ * Two properties this module owns:
+ *
+ * - **One shape per endpoint.** {@link PanelResponseMap} is the single mapping
+ *   from endpoint to response type, so the panel cannot silently decode one
+ *   endpoint's answer as another's. `reveal` answers with
+ *   {@link RevealedView}; every other endpoint answers with a whole
+ *   {@link RootsView}. The host builds those answers in `command.ts` and the
+ *   panel parses them here — one definition, two consumers.
+ * - **Runtime validation at the boundary.** The payload arrives from a browser
+ *   and the answer arrives from the host; neither is trusted to match the
+ *   TypeScript types. {@link parsePanelCall} and the `parse*View` functions
+ *   check the shapes and report structural failures as a message, so a
+ *   mismatch becomes a visible, localized error instead of a crash or a
+ *   silently wrong render.
+ *
+ * Nothing here may import `node:*` or `@deepseek-ai/*`: this module is inlined
+ * into the browser bundle.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/contract
+ */
+/** The absolute logical channel both halves speak over. */
+export declare const PANEL_CHANNEL = "/multi-root-workspace";
+/** Endpoint names, relative to {@link PANEL_CHANNEL}. */
+export type PanelEndpoint = 'list' | 'add' | 'remove' | 'alias' | 'move' | 'reveal';
+/** Every endpoint name, for exhaustive iteration in tests and callers. */
+export declare const PANEL_ENDPOINTS: readonly PanelEndpoint[];
+/**
+ * How one registered root currently stands, as the panel renders it. Kept in
+ * step with the root vocabulary in `src/roots.ts` deliberately: this module is
+ * inlined into the browser bundle and must not pull in `node:*`, so the one
+ * value the two sides share is spelled out rather than imported.
+ */
+export type RootState = 'available' | 'missing' | 'redirected' | 'invalid';
+/** One root as the panel renders it. */
+export interface RootView {
+    /** 1-based position in the returned snapshot. */
+    readonly ordinal: number;
+    /** Stable identity, used by every mutating endpoint. */
+    readonly id: string;
+    /** Canonical absolute directory. */
+    readonly path: string;
+    /** Display alias as stored; absent when cleared. */
+    readonly alias?: string;
+    /** ISO-8601 registration instant. */
+    readonly addedAt: string;
+    /** Whether the directory is writable right now, withheld, or unusable. */
+    readonly state: RootState;
+    /** Why the root is not `available`; a code the panel localizes. */
+    readonly detail?: string;
+}
+/** Exact identity of one row in a returned list snapshot. */
+export interface RootEntryView {
+    readonly ordinal: number;
+    readonly id: string;
+    readonly path: string;
+    readonly addedAt: string;
+}
+/** The panel's whole view of one workspace root; every endpoint but `reveal` answers with this. */
+export interface RootsView {
+    /** The canonical workspace root these registrations belong to. */
+    readonly primaryRoot: string;
+    /**
+     * Display name of the primary root: the workspace's upstream title when the
+     * host could resolve one; absent means the panel falls back to the path's
+     * basename.
+     */
+    readonly primaryName?: string;
+    /** The additional roots, in registry order. */
+    readonly roots: readonly RootView[];
+    /** Set when the store itself could not be read; the panel shows this verbatim. */
+    readonly unavailable?: string;
+}
+/** What `reveal` answers with: the directory the host asked the file manager to show. */
+export interface RevealedView {
+    /** Canonical path of the revealed root. */
+    readonly revealed: string;
+}
+/** The response type of every endpoint — the mapping the panel is typed against. */
+export interface PanelResponseMap {
+    readonly list: RootsView;
+    readonly add: RootsView;
+    readonly remove: RootsView;
+    readonly alias: RootsView;
+    readonly move: RootsView;
+    readonly reveal: RevealedView;
+}
+/**
+ * The fields a request may carry. `primaryRoot` and `sessionId` are shared by
+ * every endpoint (a client may name the workspace root directly or let the host
+ * resolve it from the session); the remaining fields are used per endpoint and
+ * the host asserts which ones that endpoint requires.
+ */
+export interface PanelRequest {
+    /** The workspace root to act on; the host validates that it is an existing directory. */
+    readonly primaryRoot?: string;
+    /** The session whose workspace root should be used when `primaryRoot` is absent. */
+    readonly sessionId?: string;
+    /** Exact target row from the most recent list snapshot. */
+    readonly entry?: RootEntryView;
+    /** Compatibility reference; accepted only when the id is unique. */
+    readonly id?: string;
+    /** Candidate directory (add). */
+    readonly path?: string;
+    /** Display alias (add/alias); empty clears it. */
+    readonly alias?: string;
+    /** Exact anchor row (move): the target is placed in front of it; absent moves it last. */
+    readonly beforeEntry?: RootEntryView;
+    /** Compatibility anchor; accepted only when the id is unique. */
+    readonly beforeId?: string;
+}
+/** One validated call: the endpoint plus the request fields it may use. */
+export interface PanelCall extends PanelRequest {
+    /** The endpoint to call. */
+    readonly endpoint: PanelEndpoint;
+}
+/** A failure the panel renders by `code`. */
+export interface PanelFailure {
+    /** Stable code from the root vocabulary, or `panel/bad-request`. */
+    readonly code: string;
+    /** Human-readable fallback text. */
+    readonly message: string;
+}
+/** One parse result: the value, or one sentence naming what was wrong. */
+export type Parsed<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Validate the payload the host received for one endpoint.
+ * @param endpoint - the endpoint the channel dispatched (the RPC method).
+ * @param payload - the raw channel payload (the request body).
+ * @returns the call the host may act on, or the reason it is not one.
+ */
+export declare function parsePanelCall(endpoint: string, payload: unknown): Parsed<PanelCall>;
+/**
+ * Validate a `RootsView` when it arrives.
+ * @param value - the raw endpoint value.
+ * @returns the view, or the reason it is not one.
+ */
+export declare function parseRootsView(value: unknown): Parsed<RootsView>;
+/**
+ * Validate a `RevealedView` when it arrives.
+ * @param value - the raw endpoint value.
+ * @returns the view, or the reason it is not one.
+ */
+export declare function parseRevealedView(value: unknown): Parsed<RevealedView>;
+/**
+ * Validate the `{ code, message }` envelope of a failed call.
+ * @param value - the raw error value.
+ * @returns the failure, or `undefined` when the value is not one.
+ */
+export declare function parseErrorView(value: unknown): PanelFailure | undefined;

package/lib/types/dialects.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Dialect adaptation: widening a confined argv with additional workspace roots.
+ *
+ * The upstream kernel-sandbox provider expresses `workspace-write` as a
+ * per-dialect profile built from the SINGLE policy root (plus the platform temp
+ * areas). Widening that profile is the one thing this plugin must do outside the
+ * filesystem fence, and it is deliberately done by OBSERVATION: the upstream
+ * dialect profile builders are unreachable in the published package (only
+ * `lib/index.js` and `lib/types/**` ship — see ADR-0002), and
+ * `@deepseek-ai/dsh-sandbox-local`'s `runnerArgv` / `landlockLauncher` /
+ * `seatbeltExec` members are TS-private, so `confine()` and the `internals` test
+ * hook are the ONLY public surface.
+ *
+ * Every dialect is therefore handled by
+ * 1. splitting the wrapped argv at the separator `confine` itself inserted,
+ * 2. recognizing the dialect from STRUCTURAL markers in the profile arguments,
+ * 3. cloning the grant spelling — and the insertion point — from the arguments
+ *    the upstream provider actually produced, and
+ * 4. failing loudly (never silently confining to the primary root alone) when
+ *    the shape is not one this module knows.
+ *
+ * The per-dialect profile shapes this recognizes (verified against dsh
+ * `0.1.5-rc.2`, recorded in `docs/reference/multi-root-workspace-research.md`
+ * §10) are:
+ *
+ * ```text
+ * seatbelt     [sandbox-exec, -p, "<SBPL>" ]                 SBPL allow-forms
+ * bwrap        [bwrap, --ro-bind / /, …, --bind <root> <root>]
+ * landlock     [<launcher>, --ro /, --rw /dev/null, --rw <root>]
+ * windows-acl  [node, <runner>, --workspace …, --mode <mode>]
+ * runnerCommand is spelled exactly like bwrap (the upstream config contract
+ * appends bwrap-compatible profile arguments to the operator's runner).
+ * ```
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/dialects
+ */
+import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox';
+/** The kernel runner dialects a confined argv can speak. */
+export type RunnerDialect = 'seatbelt' | 'bwrap' | 'landlock' | 'windows-acl';
+/**
+ * Raised when a confined argv cannot be recognized or widened. The provider
+ * converts this into the fail-closed `SandboxUnavailableError`: an unrecognized
+ * dialect must never degrade into "the primary root was granted after all".
+ */
+export declare class DialectUnrecognizedError extends Error {
+    constructor(message: string);
+}
+/** One wrapped argv split into its runner/profile part and the caller's argv. */
+export interface ConfinedShape {
+    /** The recognized dialect. */
+    dialect: RunnerDialect;
+    /** Everything before the separator: runner program plus profile arguments. */
+    profileArgs: string[];
+    /** Index of the `--` separator `confine` inserted. */
+    separator: number;
+    /** The caller's argv, verbatim, after the separator. */
+    commandArgs: string[];
+}
+/**
+ * Split a `confine()` result at the separator by arithmetic, then VERIFY the
+ * split: `confine` builds `[...profileArgs, '--', ...argv]`, so the separator
+ * sits exactly one element before the caller's argv. A mismatch means the
+ * provider no longer wraps argv the way this module assumes.
+ * @param confinedArgv - the argv `confine` returned.
+ * @param commandArgv - the argv the caller passed to `confine`.
+ * @returns the recognized dialect and the split parts.
+ */
+export declare function splitConfined(confinedArgv: readonly string[], commandArgv: readonly string[]): ConfinedShape;
+/**
+ * Recognize the runner dialect from the profile arguments alone. Exactly one
+ * marker must match; zero or several are both unrecognized.
+ * @param profileArgs - everything before the separator.
+ * @returns the dialect.
+ */
+export declare function detectDialect(profileArgs: readonly string[]): RunnerDialect;
+/**
+ * Widen one dialect's profile arguments with the additional roots.
+ *
+ * Only `workspace-write` grants roots, mirroring the upstream mode meaning and
+ * the filesystem fence: `read-only` grants nothing, and `danger-full-access`
+ * never confines at all (bash and the PTY backend skip `confine` in that mode).
+ *
+ * A root the dialect ALREADY grants is not granted twice — that keeps this
+ * function aligned with the fence's own deduplication and, on bwrap, avoids
+ * binding the real `/tmp` over the ephemeral `--tmpfs /tmp` mount.
+ * @param dialect - the recognized dialect.
+ * @param profileArgs - the profile arguments to widen.
+ * @param policy - the per-call policy (its root is the policy root, never a new grant).
+ * @param additionalRoots - canonical additional roots, in scope order.
+ * @returns the widened profile arguments.
+ */
+export declare function widenProfileArgs(dialect: RunnerDialect, profileArgs: readonly string[], policy: SandboxPolicy, additionalRoots: readonly string[]): string[];

package/lib/types/fs.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `MultiRootFileSystem`: the multi-root filesystem provider mounted as `ctx.fs`.
+ *
+ * It extends the local backend so every text-storage mechanic — resolve, stat,
+ * read/stream, listing, the atomic write and the read-match-write edit critical
+ * section — stays the upstream implementation's, verbatim; this class adds only
+ * the per-call POLICY fence on the two mutations, exactly as the upstream
+ * `SandboxedFileSystem` does, widened from one workspace root to the scope's
+ * root set.
+ *
+ * Why not `extends SandboxedFileSystem`: its `checkedTarget` is TS-private, so a
+ * cross-package subclass can neither reuse nor override it in a type-safe way.
+ * Why the fence is implemented here rather than delegated: with zero additional
+ * roots this class must behave exactly like the upstream provider, and the
+ * differential suite in `tests/fs-parity.spec.ts` pins that equality against the
+ * real upstream class for every mode and path class.
+ *
+ * Reads are untouched: no mode confines reading, upstream or here.
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace/fs
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsEditOutcome, FsEditRequest, FsTarget, FsVersion, FsWriteIntent, FsWriteOutcome } from '@deepseek-ai/dsh-fs';
+import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local';
+import type { Config as LocalConfig } from '@deepseek-ai/dsh-fs-local';
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox';
+/** Plugin config: the local backend's knobs verbatim (see `dsh-fs-local`). */
+export type Config = LocalConfig;
+/**
+ * Sandbox-enforcing filesystem backend over the multi-root scope. Registers as
+ * `ctx.fs`; `ctx.sandboxPolicy` still owns the mode and the primary root, and
+ * this class only widens the writable root set with the scope's additional
+ * roots.
+ */
+export declare class MultiRootFileSystem extends LocalFileSystem {
+    static inject: string[];
+    private readonly defaultMode;
+    constructor(ctx: Context, config: Config);
+    /** The deployment default mode — the capability fact the tool layer reads to advertise escalation. */
+    get sandboxMode(): SandboxMode;
+    /**
+     * Fence the write by the per-call policy, then delegate to the inherited
+     * atomic write.
+     * @param target - the resolved target to write.
+     * @param content - the full new file content.
+     * @param expected - the write intent guarding the write; omit for unconditional.
+     * @param signal - aborts before atomic publication takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root; omit to use
+     *   the deployment fallback.
+     * @returns the write outcome from the inherited backend.
+     */
+    writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsWriteOutcome>;
+    /**
+     * Fence the edit by the per-call policy, then delegate to the inherited
+     * atomic edit.
+     * @param target - the resolved target to edit.
+     * @param edit - the literal search/replace request.
+     * @param expected - the version guard; omit for an unconditional edit.
+     * @param signal - aborts before atomic publication takes effect.
+     * @param sandboxPolicy - the per-call mode and workspace root; omit to use
+     *   the deployment fallback.
+     * @returns the edit outcome from the inherited backend.
+     */
+    editText(target: FsTarget, edit: FsEditRequest, expected?: {
+        version: FsVersion;
+    }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy): Promise<FsEditOutcome>;
+    /**
+     * The writable roots of one workspace-write call: the upstream derivation
+     * (primary root plus the platform temp areas, canonical and deduplicated)
+     * widened by the scope's additional roots, in scope order.
+     * @param policy - the per-call policy.
+     * @param scope - the scope resolved once for this call; both the fence and
+     *   the denial message below share it instead of re-resolving.
+     * @returns the canonical writable roots; empty under `read-only`.
+     */
+    private rootsFor;
+    /**
+     * Enforce the per-call policy against `target` and return the EXACT target the
+     * mutation must use, so the checked identity is the mutated one (no
+     * check-here-write-there TOCTOU). `read-only` denies; `workspace-write`
+     * re-canonicalizes NOW (reflecting a concurrently swapped symlink ancestor),
+     * requires containment under one of the scope's writable roots, and returns
+     * THAT fresh target; `danger-full-access` returns the caller's target unfenced.
+     * @param target - the resolved target about to be mutated.
+     * @param sandboxPolicy - the per-call policy; omit for the deployment fallback.
+     * @returns the fresh canonical target the mutation must use.
+     */
+    private checkedTarget;
+}
+export default MultiRootFileSystem;

package/lib/types/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Barrel for the multi-root workspace bundle's host half.
+ *
+ * The loader mounts the plugin's responsibilities through the subpath entries
+ * declared in `package.json` and `cordis.patch.yml` (`./fs`, `./sandbox`,
+ * `./scope`, `./registry`, `./command`); this entry carries only the no-op
+ * `apply` below. The patch still inserts a row with THIS specifier (the bare
+ * package name) because the web client-module scan reads a package's
+ * `dsh.client` declaration solely from a loader row mounted at its package
+ * root — subpath rows are never client rows — so without that row the browser
+ * is never served `lib/client.js` and the sidebar footer action never
+ * registers. The barrel itself stays side-effect free so tests can import the
+ * whole public surface from a single specifier.
+ *
+ * The two facts worth remembering about this surface: a registration carries the
+ * canonical directory it was GRANTED for (`recordedPath`), and the panel channel
+ * has one declared response shape per endpoint (`PanelResponseMap`).
+ *
+ * @module @dsh-electron/dsh-plugin-multi-root-workspace
+ */
+export { MultiRootFileSystem } from './fs.ts';
+export type { Config as FileSystemConfig } from './fs.ts';
+export { MultiRootSandboxProvider } from './sandbox.ts';
+export type { Config as SandboxConfig } from './sandbox.ts';
+export { MultiRootScopeService, sanitizeAdditionalRoots, renderWorkspaceRootsContext } from './scope.ts';
+export type { AdditionalWorkspaceRoot, FilesystemScope } from './scope.ts';
+export { MultiRootRegistry, DOMAIN_NAME, MAX_ALIAS_LENGTH, multiRootDomainSpec } from './registry.ts';
+export type { AddRootInput, PersistedPrimaryRoot } from './registry.ts';
+export { availableRoots, canonicalRoot, classifyStoredRoots, expandRootInput, indexedStatuses, isCanonicallyUnder, additionalRootId, removeStatusAt, resolveRootRef, RootValidationError, validateRootCandidate, } from './roots.ts';
+export type { AdditionalRootId, RegisteredRoot, RootRef, RootState, RootStatus, RootValidationCode, } from './roots.ts';
+export { COMMAND_NAME, parseFoldersCommand, renderRootsReport, revealArgv } from './command.ts';
+export type { FoldersCommand } from './command.ts';
+export { PANEL_CHANNEL, PANEL_ENDPOINTS, parsePanelCall, parseRevealedView, parseRootsView } from './contract.ts';
+export type { PanelCall, PanelEndpoint, PanelFailure, PanelRequest, PanelResponseMap, RevealedView, RootView, RootsView, } from './contract.ts';
+/**
+ * Carrier plugin face for the bare-package-name loader row (see the module
+ * doc). It deliberately provides nothing: every host responsibility is owned
+ * by a subpath entry, and this row exists only so the web client-module scan
+ * can locate the package root and read its `dsh.client` declaration.
+ */
+export declare const inject: string[];
+export declare function apply(): void;