dsh-over-ssh 0.1.0 → 0.2.0

package/lib/types/src/host/integration/bin-root-resolver.d.ts

@@ -1,81 +0,0 @@
-/**
- * Decide, per root, where its file-level recycle bin lives — and make that place resolvable.
- *
- * The bin must sit **outside** the caller's repository (a "safe delete" that pollutes `git status` is not safe),
- * yet it must be reachable by the router, which only resolves paths inside a registered root (ADR-0011). So the
- * bin directory is registered as a **hidden root**: routable, but absent from `RootRegistry.records` and
- * therefore from every user-facing list.
- *
- * This module owns the one decision that cannot be pure — *is the chosen directory usable?* — and it answers by
- * measuring rather than assuming: the bin's parent must exist and must be on the **same device** as the root,
- * because a cross-device `rename` is refused outright and the file-level bin has no copy fallback
- * (`fs-commands.ts`, `recycle-bin-service.ts`). If a measurement fails, the bin stays inside the root — the old
- * behaviour — and the reason is recorded, so a fallback is **visible** rather than silent.
- *
- * @module dsh-remote-workspace/integration/bin-root-resolver
- */
-import { type RootRef } from '../domain/root.ts';
-import type { RootRecord } from './root-registry.ts';
-/** Where one root's bin ended up, and why. */
-export interface BinRootChoice {
-    /** Absolute bin directory. */
-    readonly binRoot: string;
-    /** `beside` = outside the repository (the goal); `inside` = the documented fallback. */
-    readonly placement: 'beside' | 'inside';
-    /** Whether a hidden root was registered for it (only for `beside`). */
-    readonly hidden: boolean;
-    /** Human-readable reason for a fallback, or for an inconclusive measurement. */
-    note?: string;
-}
-/** What the resolver needs from its owner. */
-export interface BinRootResolverDeps {
-    /** Register a hidden root; returns the record. */
-    readonly addHiddenRoot: (root: RootRef) => RootRecord;
-    /** Drop a hidden root by key; used when a migration fails and the new location is abandoned. */
-    readonly removeHiddenRoot?: (key: string) => void;
-    /** The configured bin directory name (`limits.binDir`). */
-    readonly binDir: string;
-    /**
-     * Whether two paths are on the same device.
-     *
-     * `undefined` means **unknown**, and unknown is treated as *usable*: refusing to move a file into the bin is
-     * worse than putting the bin in an untidy place, and a transport without a working `stat` cannot answer.
-     */
-    readonly sameDevice: (root: RootRef, left: string, right: string) => Promise<boolean | undefined>;
-    /** Whether a directory exists. */
-    readonly exists: (root: RootRef, path: string) => Promise<boolean>;
-    /**
-     * Move a directory, creating the destination's parents.
-     *
-     * Only ever called for the **old bin → new bin** migration, where the two are on one device (already
-     * measured), so a plain `rename` is the whole implementation.
-     */
-    readonly moveDirectory: (root: RootRef, from: string, to: string) => Promise<void>;
-}
-/** The resolver handed to the recycle-bin wiring. */
-export interface BinRootResolver {
-    /**
-     * The bin directory for one root, registering a hidden root on first use.
-     *
-     * Synchronous by contract: the bin service asks repeatedly and cannot await (`binRootFor`). The measurement
-     * therefore happens in {@link BinRootResolver.prepare}, which the composition calls when a root is registered.
-     *
-     * @param root - the root being served.
-     * @returns its bin directory.
-     */
-    binRootFor: (root: RootRef) => string;
-    /** Measure and register a root's bin placement; call this when the root is added. */
-    prepare: (root: RootRef) => Promise<BinRootChoice>;
-    /** The choice made for one root, if any (for diagnostics). */
-    choiceFor: (root: RootRef) => BinRootChoice | undefined;
-    /** Drop one root's cached choice (its root was removed, or its connection changed). */
-    forget: (key: string) => void;
-}
-/**
- * Build the resolver.
- *
- * @param deps - injected registration, configuration and measurement seams.
- * @returns the resolver.
- */
-export declare function createBinRootResolver(deps: BinRootResolverDeps): BinRootResolver;
-//# sourceMappingURL=bin-root-resolver.d.ts.map

package/lib/types/src/host/integration/connection-test.d.ts

@@ -1,73 +0,0 @@
-/**
- * The connectivity probe behind the panel's 「测试」 button.
- *
- * What "testing a connection" means here, and why it is a real connection rather than a TCP ping:
- *
- *  - it goes through the **same transport service** the rest of the plugin uses, so it answers the only question
- *    that matters to the user  - "would a remote operation work right now"  - including the transport the
- *    selector picked and whether that pick was a degradation;
- *  - the last step is an actual command round-trip (`printf`), so a host that accepts TCP but has no usable
- *    shell (or a transport that cannot execute) is reported as a failure, not as a success;
- *  - the probe **warms the connection** the caller will use next, because `acquire` is memoized per connection.
- *
- * Everything it needs is injected (红线 3: 外部依赖走注入), so the whole classification is testable without a
- * server, and the entry is the only place that knows about profiles.
- *
- * @module dsh-remote-workspace/integration/connection-test
- */
-/** The slice of `Transport` the probe uses. Narrow on purpose: the probe must not be able to do more. */
-export interface ProbeTransport {
-    readonly id: string;
-    connect(signal?: AbortSignal): Promise<void>;
-    exec(request: {
-        readonly argv: readonly string[];
-        readonly maxBytes?: number;
-    }, signal?: AbortSignal): Promise<{
-        readonly exitCode: number;
-        readonly stdout: string;
-    }>;
-}
-/** One acquisition: the transport plus the decision that produced it. */
-export interface ProbeAcquisition {
-    readonly transport: ProbeTransport;
-    readonly decision: {
-        readonly kind: string;
-        readonly degradations?: readonly {
-            readonly code: string;
-        }[];
-    };
-}
-/** What the probe needs. */
-export interface ConnectionProbeDeps {
-    /** Acquire (and, on first use, connect) the connection's transport. Rejects with `CONNECTION_NOT_FOUND` for an unknown id. */
-    readonly acquire: (connectionId: string) => Promise<ProbeAcquisition>;
-    /** Budget for the whole probe; each transport keeps its own timeouts on top of it. */
-    readonly timeoutMs?: number;
-    /** Clock, injected so a test can assert the reported milliseconds. */
-    readonly now?: () => number;
-}
-/** The wire answer: success carries the facts the row shows, failure carries a reason it can print. */
-export type ConnectionProbeResult = {
-    readonly ok: true;
-    readonly transport: string;
-    readonly degraded: boolean;
-    readonly degradation?: string;
-    readonly ms: number;
-} | {
-    readonly ok: false;
-    readonly code: string;
-    readonly message: string;
-    readonly ms: number;
-};
-/**
- * Probe one connection.
- *
- * Never throws: a refused or broken connection is a **result** the panel prints, because a button that rejects
- * leaves the user with nothing to read.
- *
- * @param connectionId - the connection to test.
- * @param deps - the injected acquisition, clock and budget.
- * @returns the outcome, with the elapsed milliseconds either way.
- */
-export declare function probeConnection(connectionId: string, deps: ConnectionProbeDeps): Promise<ConnectionProbeResult>;
-//# sourceMappingURL=connection-test.d.ts.map

package/lib/types/src/host/integration/file-reference-provider.d.ts

@@ -1,115 +0,0 @@
-/**
- * Multi-root implementation of the core `ctx.fileReferences` seam.
- *
- * The core ships [`@deepseek-ai/dsh-file-reference-local`] for **one** local workspace. This plugin's whole
- * point is several roots of two kinds, so this provider answers the same contract for both:
- *
- *  - a **remote** root is enumerated by {@link RemoteIndex} (Tier 2 `index.scan` when the connection has an
- *    agent, else one bounded `find`/`git ls-files`), cached per root;
- *  - a **local** root is enumerated here with a bounded walk, because installing this provider **replaces**
- *    the core's local one — returning nothing for local agents would be a regression, not a feature.
- *
- * Candidate paths use the router's display spelling (`ssh://<connection>/abs` for remote roots) so a token
- * stays unambiguous in a multi-root workspace; the local case keeps ordinary host paths.
- *
- * @module dsh-remote-workspace/integration/file-reference-provider
- */
-import { Context } from '@deepseek-ai/cordis';
-import FileReferenceService, { type FileReferenceCandidate } from '@deepseek-ai/dsh-file-reference';
-import type { Agent } from '@deepseek-ai/dsh-agent';
-/** What the provider needs from the index layer (provided as `ctx.sshDevIndex`). */
-export interface FileReferenceIndex {
-    /**
-     * Rank candidates for a partially typed `@` query inside one remote root.
-     *
-     * @param connectionId - connection that owns the root.
-     * @param root - backend-absolute remote root path.
-     * @param query - text after `@`.
-     * @param signal - caller cancellation.
-     * @returns ranked candidates whose `path` is a router-resolvable spelling
-     *   (`ssh://<connection>/abs`), so a token stays unambiguous across roots.
-     */
-    complete(connectionId: string, root: string, query: string, signal: AbortSignal): Promise<readonly FileReferenceCandidate[]>;
-}
-declare module '@deepseek-ai/cordis' {
-    interface Context {
-        /** Remote index used by the file-reference provider. */
-        sshDevIndex: FileReferenceIndex;
-    }
-}
-/** Directory names never traversed by the local walk (same intent as the core's exclusion list). */
-export declare const LOCAL_EXCLUDED_DIRECTORIES: readonly string[];
-/** Default cap for the local walk; the core uses a comparable bound for its own index. */
-export declare const LOCAL_MAX_ENTRIES = 20000;
-/** How deep the local walk may go before it gives up (protects against pathological trees). */
-export declare const LOCAL_MAX_DEPTH = 12;
-/**
- * How long a local enumeration may be reused before the tree is walked again.
- *
- * **Short on purpose, and much shorter than the remote branch's 30 s** (`RemoteIndex` `ttlMs`). That cache
- * exists to avoid a *network round trip*; this one exists only to collapse **one typing burst** into a single
- * walk. A burst is a few keystrokes a couple of hundred milliseconds apart, so a quarter second folds the
- * whole burst while keeping staleness below the threshold where a user could notice — creating a file and
- * typing `@` again within 250 ms is not something a person does.
- *
- * The failure mode is deliberately the cheap one: a miss costs a walk, i.e. exactly today's behaviour, so
- * this can never be *slower* than not caching, only less fresh for at most this long.
- *
- * Measured (`.verify/probe-local-fref-cache.ts`, 10 000-entry tree): typing `@module` walked the whole tree
- * **6 times** and cost 413 ms; the walk is ~68 ms each, and it is paid per keystroke, on the host's event loop.
- */
-export declare const LOCAL_CACHE_TTL_MS = 250;
-/**
- * Cap for the local enumeration cache.
- *
- * Keys are registry root paths, so the set is bounded by how many roots the user registered — but it is
- * capped anyway, for the same reason `RemoteIndex` bounds its own caches: a bound that depends on "the
- * caller will not do that" is not a bound.
- */
-export declare const LOCAL_MAX_CACHED_ROOTS = 8;
-/** How many candidates one query returns (the core's local provider uses the same order of magnitude). */
-export declare const DEFAULT_MAX_RESULTS = 50;
-/** One locally enumerated entry, with the kind completion needs. */
-export interface LocalEntry {
-    readonly path: string;
-    readonly kind: 'file' | 'directory';
-}
-/** Construction options; `walk` is injected so tests never touch a real filesystem. */
-export interface RemoteFileReferenceOptions {
-    /** Maximum entries collected in one local walk. Default {@link LOCAL_MAX_ENTRIES}. */
-    readonly maxEntries?: number;
-    /** Maximum depth of the local walk. Default {@link LOCAL_MAX_DEPTH}. */
-    readonly maxDepth?: number;
-    /** Maximum candidates returned per query. Default {@link DEFAULT_MAX_RESULTS}. */
-    readonly maxResults?: number;
-    /** Local enumerator, injected for tests. Defaults to a real bounded `readdir` walk. */
-    readonly walk?: (root: string, signal: AbortSignal) => Promise<readonly LocalEntry[]>;
-    /** How long a local enumeration stays reusable. Default {@link LOCAL_CACHE_TTL_MS}. */
-    readonly localTtlMs?: number;
-    /** Cap for the local enumeration cache. Default {@link LOCAL_MAX_CACHED_ROOTS}. */
-    readonly maxCachedRoots?: number;
-    /** Injectable clock, so the TTL is testable without sleeping. */
-    readonly now?: () => number;
-}
-/**
- * The provider.
- *
- * Lifecycle note: it is registered as a **separate module** (`dsh-remote-workspace/file-references`) so the
- * composition decides whether to replace the core's local service — enabling it is an explicit choice.
- */
-export declare class RemoteFileReferenceService extends FileReferenceService {
-    #private;
-    static inject: string[];
-    constructor(ctx: Context, options?: RemoteFileReferenceOptions);
-    /**
-     * List candidates for one agent's working directory.
-     *
-     * @param agent - target agent; its session cwd decides which root answers.
-     * @param query - text after `@` (may be empty: "show the shallowest entries").
-     * @param signal - caller cancellation.
-     * @returns ranked candidates, best first; empty when the cwd is outside every registered root.
-     */
-    list(agent: Agent, query: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
-}
-export default RemoteFileReferenceService;
-//# sourceMappingURL=file-reference-provider.d.ts.map

package/lib/types/src/host/integration/fs/git-status-wiring.d.ts

@@ -1,21 +0,0 @@
-/**
- * Compose remote git status from the services the main entry already publishes.
- *
- * This is the only glue the fs entry needs: the cache/route live in `infra/transport` (they are HTTP/data-plane
- * concerns), while *where a connection's transport comes from* and *which root covers a path* are facts of this
- * plugin's composition. Keeping the glue here (rather than in the main entry's wiring) means the `./fs` row is
- * self-contained: enabling it is enough for the browser's badge route to appear, with no second wiring edit.
- *
- * Everything is read through `ctx.get` at call time, not captured at activation: the fs row may activate before
- * a later composition layer provides `webServer`, and the transport service installs its entries lazily.
- *
- * @module dsh-over-ssh/integration/fs/git-status-wiring
- */
-import type { Context } from '@deepseek-ai/cordis';
-/**
- * Wire the badge route onto this composition (no-op when the needed services are absent).
- *
- * @param ctx - the `./fs` plugin context (it sees the main entry's services at root scope).
- */
-export declare function wireGitStatus(ctx: Context): void;
-//# sourceMappingURL=git-status-wiring.d.ts.map

package/lib/types/src/host/integration/fs/platform-errors.d.ts

@@ -1,94 +0,0 @@
-/**
- * Build filesystem errors with **the host's own `FsError` class**, not ours.
- *
- * Why this exists: this plugin and the harness each resolve their own copy of `@deepseek-ai/dsh-fs`
- * (`dsh-over-ssh/node_modules/…` versus `…/dsh/node_modules/…`), so `new FsError(…)` here produces an
- * object that fails the platform's `error instanceof FsError` test. Measured consequences of that mismatch:
- *
- *  - `dsh-api-session-controller/lib/index.js:2459` re-throws anything that is not an `FsError`, so serving a
- *    missing or oversized workspace file answered **500** instead of 404/413;
- *  - `dsh-tools/lib/index.js:2711` (`errorInfo`) reports `{ name, code }` only for its own `HarnessError`, so tool
- *    results lost the structured code and the model saw prose only;
- *  - `dsh-tool-fs`'s `remediateFsError` hints never matched, so "read the file first" style guidance disappeared.
- *
- * The fix cannot be an import: our specifier resolves to our copy. It can be a **runtime lookup of the host's
- * copy**, which is what this module does once, at startup, and then reuses for every error that crosses the
- * boundary. The lookup asks Node (`createRequire(<harness entry>).resolve(…)`) rather than guessing directories,
- * so it follows the harness wherever it is installed. When the host copy cannot be found (unit tests, a bundled deployment, a future layout) the local
- * class is used and behaviour is exactly what it was — the detection is an improvement, never a dependency.
- *
- * @module dsh-over-ssh/integration/fs/platform-errors
- */
-import { FsError } from '@deepseek-ai/dsh-fs';
-/** What one `FsError` construction needs; the third argument is the standard `{ cause }` bag. */
-type FsErrorConstructor = new (message: string, code: string, options?: {
-    readonly cause?: unknown;
-}) => FsError;
-/**
- * Ask Node where the harness itself would resolve `@deepseek-ai/dsh-fs`.
- *
- * This is the authoritative lookup, and it is **layout-free**: `createRequire(<harness entry>)` makes Node apply
- * exactly the rules the harness applies when it imports the package (its `node_modules` chain, its `exports`
- * map). The directory candidates below only exist as a fallback for a harness whose entry is not a real file
- * path, because guessing a layout is what makes a fix like this rot.
- *
- * @param entryScript - `process.argv[1]`, the harness entry point.
- * @returns the resolved file path, or `undefined` when the harness cannot see the package.
- */
-export declare function resolveHostFsPath(entryScript: string | undefined): string | undefined;
-/**
- * Where the host's copy of `@deepseek-ai/dsh-fs` may live, given the executable that booted us.
- *
- * Only a fallback for {@link resolveHostFsPath}: used when Node cannot resolve the specifier from the entry
- * script (a harness booted from a virtual path, say). Kept as a pure function so a test can pin the layout
- * instead of the developer's machine.
- *
- * @param entryScript - `process.argv[1]`, the harness entry point.
- * @returns candidate file URLs, nearest first.
- */
-export declare function hostFsCandidates(entryScript: string | undefined): readonly string[];
-/**
- * Detect the host's `FsError` class once, in the background.
- *
- * Fire-and-forget on purpose: the provider is constructed synchronously during plugin load, and an error thrown
- * before detection finishes simply uses the local class (the pre-existing behaviour).
- *
- * @param entryScript - override for tests; defaults to `process.argv[1]`.
- */
-export declare function startHostErrorDetection(entryScript?: string | undefined): void;
-/**
- * Look for the host's `FsError` class under one entry script and adopt it when found.
- *
- * Exported so a contract test can drive the detection deterministically instead of depending on how the test
- * runner was invoked.
- *
- * @param entryScript - the harness entry point to search around.
- * @returns the adopted class, or `undefined` when no other copy exists.
- */
-export declare function detectHostFsError(entryScript: string | undefined): Promise<FsErrorConstructor | undefined>;
-/**
- * Whether an error is an `FsError` from **either** copy.
- *
- * Both copies exist in a real host (see the module note), so a bare `error instanceof FsError` is only half the
- * question: after detection our own boundary errors are the host's class, and the local check would no longer
- * recognise them — which silently re-wrapped codes that were already correct.
- *
- * @param error - anything caught.
- * @returns true when the error already carries an `FS_*` code from either class.
- */
-export declare function isFsError(error: unknown): boolean;
-/** The class boundary errors are built from: the host's when detected, ours otherwise. */
-export declare function activeFsErrorClass(): FsErrorConstructor;
-/**
- * Build one error for the platform boundary.
- *
- * @param message - human-readable text.
- * @param code - the `FS_*` code the platform maps to an HTTP status.
- * @param options - `{ cause }` when wrapping another error.
- * @returns an `FsError` the **platform's** `instanceof` accepts, whenever its class could be detected.
- */
-export declare function platformFsError(message: string, code: string, options?: {
-    readonly cause?: unknown;
-}): FsError;
-export {};
-//# sourceMappingURL=platform-errors.d.ts.map