dsh-over-ssh 0.1.0 → 0.1.1

package/lib/types/src/host/app/roots-api-contract.d.ts

@@ -1,339 +0,0 @@
-/**
- * The same-origin HTTP route a client panel uses to **edit** roots and connections.
- *
- * Why a plain HTTP route instead of a Typert `@Remote` service (the shape audit 0021 used for reads):
- *
- *  - every action here carries **parameters**, and a Client Remote descriptor with parameters requires a
- *    generated strict codec that this repository cannot produce (`doc/02-platform/client-plugin.md` §4);
- *  - the panel is served from the GUI's own origin, so a relative `fetch` is same-origin: no CORS
- *    concession, no code generation, no `@Remote` registration — exactly the shape the third-party
- *    `dsh-plugin-stock-market` uses (`ctx.webServer.register({ kind: 'exact', path, handler })`).
- *
- * This module is a **handler factory decoupled from cordis**: everything it needs arrives through
- * {@link RootsApiDeps}, so it can be unit-tested with fake dependencies and fake request/response objects.
- * The Lead performs the actual registration:
- *
- * ```ts
- * const api = createRootsApi({ ... })
- * disposers.push(webServer.register({ kind: 'exact', path: ROOTS_API_PATH, handler: api.handle }))
- * ```
- *
- * Contract:
- *
- * | Request | Answer |
- * |---|---|
- * | `GET` | `200 { ok: true, roots, connections, userRoots, warnings }` |
- * | `POST` `{ action: 'add-root' \| 'remove-root' \| 'add-connection' \| 'update-connection' \| 'remove-connection', ... }` | `200 { ok: true, action, state }` |
- * | `POST` `{ action: 'add-root', location, path, connectionId?, workspaces?, reuseExisting? }` | `200 { ok: true, action, state, anchorPath? }` — `reuseExisting: true` makes an already-persisted root idempotent and answers its anchor instead of `400 该根已存在` |
- * | `POST` `{ action: 'remove-root', key, workspace? }` | `200 { ok: true, action, state }` — `workspace` removes the root from that workspace only; the root disappears when the last one drops it |
- * | `POST` `{ action: 'update-connection', id, newId?, host?, user?, port?, authKind?, keyPath?, credentialKey?, transport?, password? }` | `200 { ok: true, action, state }` — absent fields keep their value; `newId` renames and migrates the connection's roots (keeping their anchors) |
- * | `POST` `{ action: 'list-remote', connectionId, path }` | `200 { ok: true, action, connectionId, path, entries: [{ name, kind }], truncated }` |
- * | `POST` `{ action: 'list-local', path? }` | `200 { ok: true, action, path, entries: [{ name, kind }], crumbs, truncated }` |
- * | `POST` `{ action: 'list-ssh-config' }` | `200 { ok: true, action, candidates: [{ alias, host, user?, port?, hasIdentityFile, hasProxyJump, suggestedId }], skipped: [{ pattern, reason, line }] }` (FR-2.1.4) |
- * | `POST` `{ action: 'import-ssh-config', aliases: [alias, …] }` | `200 { ok: true, action, imported: [id, …], refused: [{ alias, reason }], state }` — the body names **aliases**, never ids/hosts/paths: every field is re-derived from the config |
- * | any validation / trust / body failure | `400`/`403` `{ ok: false, error, reason? }` |
- * | any other method | `405` `{ ok: false, error }` + `Allow: GET, HEAD, POST` |
- *
- * Two invariants this layer owns:
- *
- *  1. **Credentials never come back out.** `connections` (live and persisted), the `state` echoed by
- *     `POST` and every directory row (`list-remote` and `list-local`) are whitelist projections:
- *     `{ id, host, user, port, authKind, transport? }` and `{ name, kind }` respectively. `keyPath`, `password`,
- *     `passphrase`, `credentialKey`, `alias`, `proxyJump`, sizes, times, modes and symlink targets are
- *     never serialised, and no file content is readable through this route at all.
- *  2. **Parameters are taken from a whitelist, one field at a time** — the body is never spread into a
- *     call. A field the UI does not own cannot reach the seam, however the body is shaped.
- *
- * @module dsh-remote-workspace/integration/roots-api
- */
-import { type UserConnectionRecord, type UserRootEntry, type UserRootsState } from './user-roots.ts';
-/** The one path this plugin claims on the host HTTP carrier. */
-export declare const ROOTS_API_PATH = "/api/remote-workspace/roots";
-/** Largest accepted request body. A root/connection edit is a few hundred bytes; 64 KiB is a ceiling, not a budget. */
-export declare const ROOTS_API_MAX_BODY_BYTES: number;
-/** Entries one `list-remote` answer carries at most; the tail is dropped and `truncated` says so. */
-export declare const REMOTE_LIST_MAX_ENTRIES = 2000;
-/** Entries one `list-local` answer carries at most (the same budget as `list-remote`). */
-export declare const LOCAL_LIST_MAX_ENTRIES = 2000;
-/**
- * One remote directory row as the wire may carry it.
- *
- * **Names and kinds only.** A browsing client needs to render a list and decide what is enterable, and
- * nothing else: no sizes, no times, no symlink targets, no file contents, no credentials. The projection
- * below is what enforces that, field by field, exactly like `publicConnection` does for connections.
- */
-export interface RemoteDirectoryEntry {
-    /** Base name of the entry. */
-    readonly name: string;
-    /** What the row is; anything the listing cannot classify is reported as `file`. */
-    readonly kind: 'directory' | 'file' | 'symlink';
-}
-/** Where one `list-remote` request points. */
-export interface RemoteListRequest {
-    /** Connection the directory lives behind. */
-    readonly connectionId: string;
-    /** Absolute POSIX path on that host. */
-    readonly path: string;
-}
-/**
- * One **local** directory row as the wire may carry it.
- *
- * The same discipline as {@link RemoteDirectoryEntry} with a narrower vocabulary: a local `readdir` can
- * report sizes, modes, owners and times without a second syscall, and it can only tell a link from a
- * directory by following it — which this route never does. So anything that is neither a plain file nor a
- * plain directory is answered as `other`, and no field but the name and the kind ever leaves the host.
- */
-export interface LocalDirectoryEntry {
-    /** Base name of the entry. */
-    readonly name: string;
-    /** What the row is: a plain file, a plain directory, or something else (a symlink, a socket, a device). */
-    readonly kind: 'file' | 'directory' | 'other';
-}
-/** Where one `list-local` request points. */
-export interface LocalListRequest {
-    /** Absolute, `..`-free path on **this** machine, already defaulted and canonicalised by the handler. */
-    readonly path: string;
-}
-/** One action `POST` accepts; anything else is refused with the list. */
-export declare const ROOTS_API_ACTIONS: readonly ["add-root", "remove-root", "add-connection", "update-connection", "test-connection", "remove-connection", "list-remote", "list-local", "list-ssh-config", "import-ssh-config", "mkdir-remote", "rename-remote", "remove-remote", "list-transfers", "clear-transfers"];
-/** One accepted action. */
-export type RootsApiAction = (typeof ROOTS_API_ACTIONS)[number];
-/**
- * The request surface this handler consumes: a structural subset of `node:http`'s `IncomingMessage`, so a
- * test can pass a `Readable` with `method`/`url`/`headers` and no cast, while a real `IncomingMessage`
- * still satisfies it (asserted at compile time in `tests/roots-api.test.ts`).
- */
-export interface RootsApiRequest {
-    readonly method?: string | undefined;
-    readonly url?: string | undefined;
-    readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
-    [Symbol.asyncIterator](): AsyncIterator<unknown>;
-}
-/** The response surface this handler consumes: a structural subset of `ServerResponse`. */
-export interface RootsApiResponse {
-    statusCode: number;
-    setHeader(name: string, value: string): void;
-    end(chunk?: string): void;
-}
-/** The seams the handler needs. All of them are the Lead's wiring; none of them is imported from cordis. */
-export interface RootsApiDeps {
-    /** Live roots (the registry snapshot), as roots — credentials are stripped here anyway. */
-    listRoots(): Promise<readonly unknown[]> | readonly unknown[];
-    /** Live connections (profiles), which **do** carry credentials; only the whitelist is answered. */
-    listConnections(): Promise<readonly unknown[]> | readonly unknown[];
-    /** The persisted panel-owned state plus its warnings (see `createUserRootsStore().load`). */
-    loadUserState(): Promise<{
-        readonly state: UserRootsState;
-        readonly warnings: readonly string[];
-    }> | {
-        readonly state: UserRootsState;
-        readonly warnings: readonly string[];
-    };
-    /** Persist a whole state; returns what was written (normalised). */
-    saveUserState(next: UserRootsState): Promise<UserRootsState> | UserRootsState;
-    /** Make a root live **and** remember it. The handler reconciles the file afterwards, so persisting here is expected but not required (a second write is skipped when the content already matches). */
-    registerRoot(entry: UserRootEntry): Promise<unknown> | unknown;
-    /** Drop a root from the live side (and, if the wiring persists there, from the file). */
-    unregisterRoot(key: string): Promise<unknown> | unknown;
-    /** Remember a connection. Applying it to a live profile is a reload concern, not this handler's. */
-    addConnection(entry: UserConnectionRecord): Promise<unknown> | unknown;
-    /**
-     * Optional: apply a patched connection to the **live** profile map (and, if the wiring chooses, forget what
-     * was cached for it: the agent installation state and the probed remote home are properties of the account,
-     * so a changed host must not keep the previous host's answers).
-     *
-     * The handler already made the rename coherent for the *roots* (see {@link updateConnectionInState}); this
-     * seam is what makes it coherent for the live transports. Absent means the change is persisted only, and
-     * takes effect after a restart — which is why the wiring provides it.
-     */
-    applyConnection?: ((entry: UserConnectionRecord, previousId: string) => Promise<unknown> | unknown) | undefined;
-    /**
-     * Optional: forget a connection on the **live** side after it was removed.
-     *
-     * The mirror image of {@link RootsApiDeps.applyConnection}, and it exists for a reason that is easy to miss:
-     * the `GET` answer lists connections from the **live** profile map, not from the file. Dropping the record
-     * from `user-roots.json` alone therefore leaves the connection on screen — the panel would show a row that
-     * no longer exists in any file and whose 「删除」 button reports success forever. Everything the plugin caches
-     * **per connection** belongs to this call too: the live transport (a real SSH master or agent child process),
-     * the remote index, the installed-agent bookkeeping, the stored askpass secret and its temp directory, the
-     * probed remote home. A connection the user deleted must stop costing memory and processes.
-     *
-     * Absent means the removal is persisted only and the connection stays visible until a restart, which is why
-     * the wiring provides it.
-     */
-    removeConnection?: ((id: string) => Promise<unknown> | unknown) | undefined;
-    /**
-     * Optional: hands back the credential store for **this** request; it writes and drops, never reads.
-     *
-     * A getter rather than a value on purpose: a service read while the entry activates can still be absent —
-     * `ctx.get('webServer')` behaved exactly that way on the packaged runtime — and capturing `undefined` once
-     * would disable password connections for the whole process. A composition that never provides one refuses
-     * `authKind: 'password'` with an explicit message instead of storing a password in a file the user was told
-     * holds no secrets.
-     */
-    credentials?: (() => CredentialsSeam | undefined) | undefined;
-    /**
-     * Optional: really connect to one saved connection and run one command, for the panel's 「测试」 button.
-     *
-     * Optional for the same reason as every other capability here: a composition without a transport service
-     * answers the action with an explicit failure instead of pretending the connection is fine. The result is
-     * projected field by field, so a wiring that returns extra facts cannot leak them.
-     */
-    testConnection?: ((id: string) => Promise<unknown> | unknown) | undefined;
-    /**
-     * Optional: list one directory on a connection, for the browsing action (`list-remote`).
-     *
-     * The wiring implements it with the transport's own directory primitive; a composition that does not
-     * provide it answers `list-remote` with an explicit failure instead of failing to activate. Whatever it
-     * returns is projected to `{ name, kind }` before it reaches the wire.
-     */
-    listRemoteDirectory?: ((input: RemoteListRequest) => Promise<readonly unknown[]> | readonly unknown[]) | undefined;
-    /**
-     * Optional: the directory a remote browse starts at when the client names none.
-     *
-     * A getter rather than a value for the same reason as {@link credentials}: resolving it may need a live
-     * transport, which can appear after this entry activates. When absent, an empty `path` degrades to `/`.
-     */
-    remoteHomeDirectory?: ((connectionId: string) => Promise<string> | string) | undefined;
-    /**
-     * Optional: list one directory **on this machine**, for the browsing action (`list-local`).
-     *
-     * Same contract as {@link RootsApiDeps.listRemoteDirectory} — rows in, `{ name, kind }` out — and injected
-     * for the same two reasons: the domain layer imports no `@deepseek-ai/*` (and no `node:fs`), and a test can
-     * assert what the seam was asked for without touching the disk. The wiring implements it with `node:fs`,
-     * so a machine whose platform directory picker has no `browse` capability still has a working browser.
-     *
-     * Whatever it throws must carry the filesystem's own `errno` code (`ENOENT`, `ENOTDIR`, `EACCES`, …): that
-     * is how the handler turns "there is no such directory" into a machine-readable `400 reason` instead of an
-     * empty listing. A row without a usable name is dropped before it reaches the wire.
-     */
-    listLocalDirectory?: ((input: LocalListRequest) => Promise<readonly unknown[]> | readonly unknown[]) | undefined;
-    /**
-     * Optional: read the user's own `~/.ssh/config` for the import action (FR-2.1.4).
-     *
-     * Injected for the same two reasons as the directory seams: the domain layer reads no files, and a test can
-     * answer with a fixture instead of depending on the developer's home directory. It returns the **text**, not
-     * parsed entries, so the parsing (`domain/ssh-config.ts`) stays a pure function under test.
-     *
-     * Absent means the action answers an explicit "this composition cannot read the file" failure rather than
-     * silently importing nothing.
-     */
-    readSshConfig?: (() => Promise<string | undefined> | string | undefined) | undefined;
-    /**
-     * Optional: the remote-file operations the file tree needs (FR-2.2.2).
-     *
-     * One seam rather than three, because all three are the same capability from this route's point of view
-     * ("change the remote filesystem") and a composition either has it or does not. `rename` must refuse to
-     * clobber and `remove` must refuse a directory without `recursive` — the contract is in `app/backend.ts`.
-     */
-    remoteFiles?: RemoteFileOperations | undefined;
-    /**
-     * Optional: the in-flight and recent transfers (FR-2.6.4).
-     *
-     * A **pull** seam, not a push one: the client half has exactly one HTTP route, so "what is happening" is a
-     * question it asks, not a stream it subscribes to. Absent means the two transfer actions answer an explicit
-     * refusal instead of an empty list — "nothing is running" and "this composition cannot tell you" are
-     * different answers, and only one of them is honest.
-     */
-    transfers?: TransferReport | undefined;
-}
-/** What the route needs from the tracker, without importing it (the handler stays decoupled). */
-export interface TransferReport {
-    list(): readonly unknown[];
-    clearFinished(): number;
-}
-/** The three mutating remote-file operations (FR-2.2.2). */
-export interface RemoteFileOperations {
-    mkdir(input: {
-        readonly connectionId: string;
-        readonly path: string;
-        readonly recursive: boolean;
-    }): Promise<void> | void;
-    rename(input: {
-        readonly connectionId: string;
-        readonly from: string;
-        readonly to: string;
-        readonly createParents: boolean;
-    }): Promise<void> | void;
-    remove(input: {
-        readonly connectionId: string;
-        readonly path: string;
-        readonly recursive: boolean;
-    }): Promise<void> | void;
-}
-/**
- * The credential store as this route needs it: **write, drop, and nothing else**.
- *
- * There is deliberately no read here. The route must not be able to answer with a stored secret, so the only
- * operations it can ask for are the two that leave the value in the store.
- */
-export interface CredentialsSeam {
-    /** Store one value under a reference name (the platform rejects an empty one). */
-    set(ref: string, value: string): Promise<void> | void;
-    /** Drop one stored value; a no-op when the name is not present. */
-    unset(ref: string): Promise<void> | void;
-}
-/** The handler pair the Lead registers. */
-export interface RootsApi {
-    /**
-     * Serve one request. Never throws: a handler that rejects would leave the socket without a status.
-     *
-     * Bound as an arrow property so `handler: api.handle` can be passed directly.
-     */
-    readonly handle: (req: RootsApiRequest, res: RootsApiResponse) => Promise<void>;
-    /** No resources are held; the route registration belongs to the caller. */
-    dispose(): void;
-}
-/** Reasons a request is refused before any action runs. */
-export type TrustVerdict = 'ok' | 'no-host' | 'bad-host' | 'cross-site' | 'bad-origin';
-/** Fields a root action may carry. Everything else in the body is ignored. */
-export declare const ROOT_FIELDS: readonly ["location", "path", "connectionId", "label", "writable", "workspaces"];
-/**
- * Fields a connection action may carry.
- *
- * `password` is deliberately **not** here: it is not part of a connection record. `add-connection` takes it out
- * of the body separately, writes it to the credential store, and persists only the reference name.
- * `passphrase` is not here either — nothing in this feature has a representation for it.
- *
- * `transport` **is** here, and it has to be: the panel's form sends the user's explicit choice, and this
- * whitelist is what decides which fields survive to `normalizeConnectionEntry`. Leaving it out would drop the
- * field silently — the connection would be persisted with no transport and every reader would fall back to
- * the default, which is exactly the "no escape hatch from the agent" bug this field exists to fix.
- */
-export declare const CONNECTION_FIELDS: readonly ["id", "host", "user", "port", "authKind", "keyPath", "credentialKey", "transport"];
-/**
- * Fields `update-connection` may patch.
- *
- * `id` is deliberately **not** here. In `add-connection` it names the connection being created; in an edit it
- * is the *lookup* key ("which connection am I changing"), so reusing it for the new name would make the two
- * meanings collide and a rename impossible to express. The new id therefore travels in its own field,
- * **`newId`** (optional; absent means "keep the id").
- */
-export declare const UPDATE_CONNECTION_FIELDS: readonly ["host", "user", "port", "authKind", "keyPath", "credentialKey", "transport"];
-/**
- * Decide whether a request is same-origin enough to serve.
- *
- * The rule, and why it is not stricter:
- *
- *  - **A missing `Origin` is allowed.** Non-browser clients do not send it: `curl`, a Node-side `fetch`, and
- *    the DSH desktop shell's own calls. Browsers always send `Origin` on a `POST` (including a cross-site
- *    `no-cors` form post), which is the case this fence exists for, so "absent" cannot be produced by a
- *    cross-site page.
- *  - **`Origin: null` is refused** (sandboxed iframe, `file:` document).
- *  - **`Origin` must match `Host`.** A different port or hostname is a different origin.
- *  - **A port-less loopback spelling is accepted** when the `Origin` carried no port at all: some Chromium
- *    builds serialise a loopback page as `http://127.0.0.1` even when the page is on a non-default port
- *    (observed in this workspace by the `dsh-remote-ssh` plugin, which fences the same way). A *different*
- *    explicit port still fails, because that path compares full `host`.
- *  - **`Sec-Fetch-Site: cross-site` is refused** even if the two headers were somehow consistent.
- *
- * The host allowlist itself (loopback / trusted hosts) is **not** re-implemented here: the carrier already
- * decides what it serves. See the audit's unverified list.
- *
- * @param req - incoming request.
- * @returns `'ok'`, or the reason to refuse.
- */
-export declare function trustVerdict(req: RootsApiRequest): TrustVerdict;
-/** User-facing text for one {@link TrustVerdict}. */
-export declare function trustMessage(verdict: TrustVerdict): string;
-//# sourceMappingURL=roots-api-contract.d.ts.map

package/lib/types/src/host/app/roots-api-directories.d.ts

@@ -1,13 +0,0 @@
-/**
- * roots-api-directories
- *
- * 目录与文件操作的 5 个 action：mkdir/rename/remove、远端列举、本机列举。
- *
- * 从 `roots-api.ts` 的 `serveAction`（543 行 / 15 个 case）拆出（审计 0076）：
- * case 体逐字搬移，只把 `return;` 改成 `return true;`，未命中时返回 `false` 由分发器报 400。
- *
- * @module dsh-remote-workspace/app/roots-api-directories
- */
-import type { RootsApiRequest, RootsApiResponse, RootsApiDeps } from './roots-api-contract.ts';
-export declare function handleDirectoryActions(action: string, body: Record<string, unknown>, req: RootsApiRequest, res: RootsApiResponse, deps: RootsApiDeps): Promise<boolean>;
-//# sourceMappingURL=roots-api-directories.d.ts.map

package/lib/types/src/host/app/roots-api-http.d.ts

@@ -1,77 +0,0 @@
-/**
- * 根路由的**请求/响应原语**：读 body、发 JSON、字段校验、凭据字段拦截。
- *
- * 从 `roots-api-support.ts` 拆出（审计 0079）：这一层只认 HTTP 与 body 形状，
- * 不知道任何 DTO，也不读用户状态。
- *
- * @module dsh-remote-workspace/app/roots-api-http
- */
-import { type UserRootEntry } from './user-roots.ts';
-import type { RootsApiRequest, RootsApiResponse, RootsApiDeps } from './roots-api-contract.ts';
-export declare function readBody(req: RootsApiRequest): Promise<string>;
-export declare function toBytes(chunk: unknown): Uint8Array;
-export declare function send(req: RootsApiRequest, res: RootsApiResponse, status: number, value: unknown): void;
-export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
-export declare function messageOf(error: unknown): string;
-/** The machine-readable reason a refusal carries in its details, when it has one. */
-export declare function reasonOf(error: unknown): string | undefined;
-export declare function isValidationFailure(error: unknown): boolean;
-/** One required non-empty string field of a body. */
-export declare function requiredString(value: unknown, field: string): string;
-export declare function requiredKey(value: unknown): string;
-/**
- * The optional `path` field of a `list-local` body.
- *
- * Absent and empty (or blank) both mean "the host default", which is the user's home directory. Anything else
- * that is not a string — `null` included — is the caller's fault and is refused before a directory is chosen:
- * silently browsing the home directory because a client sent `null` would look like the request succeeded.
- */
-export declare function optionalPath(value: unknown): string | undefined;
-/** Take only the named fields from a body; the body itself is never handed to a seam. */
-export declare function pick(source: Record<string, unknown>, fields: readonly string[]): Record<string, unknown>;
-/**
- * The one body field this route refuses outright, whatever the action.
- *
- * `passphrase` has no representation anywhere in this feature, so accepting it would be a lie — and silently
- * dropping it would tell the user their passphrase was stored.
- *
- * `password` is **not** refused any more: `add-connection` and `update-connection` take it, write it into the
- * credential store and keep only the reference (FR-2.1.2). `credentialKey` is a *name*, not a secret, and
- * travels normally.
- */
-export declare function firstCredentialField(body: Record<string, unknown>, action: string): string | undefined;
-/**
- * The live registry's own key for one persisted entry, or `undefined` when it is not live.
- *
- * The comparison goes through `sameUserRootKey` rather than `===`: the registry lower-cases Windows local
- * paths (`domain/root.ts`'s `rootKey`), the persisted file keeps the caller's case, and the client rebuilds
- * the key from the `path` the answer carried. Comparing them verbatim made a Windows local root impossible to
- * remove - the file entry went, the live root stayed, and the row then had no delete button because it was no
- * longer in the file.
- *
- * @param deps - the injected seams (only `listRoots` is read).
- * @param entry - the entry to look for.
- * @returns the key the registry holds it under, or `undefined`.
- */
-export declare function matchedLiveKey(deps: RootsApiDeps, entry: UserRootEntry): Promise<string | undefined>;
-/**
- * Read one live record as a root key, matching it against `entry`.
- *
- * @param raw - a `RootRecord` (key + root) or a bare `RootRef`.
- * @param entry - the entry to match.
- * @returns the record's own key when it names `entry`, else `undefined`.
- */
-export declare function liveKeyOfRecord(raw: unknown, entry: UserRootEntry): string | undefined;
-/**
- * Turn an alias into a connection id that passes {@link isValidConnectionId}.
- *
- * `~/.ssh/config` aliases routinely contain characters this plugin's ids reject (`@`, `:`, `/`, spaces) —
- * `deploy@bastion` is a perfectly normal alias. Importing one verbatim would be refused by
- * {@link normalizeConnectionEntry} with a message about id grammar, which reads as "the import is broken".
- * The alias is therefore **kept as the ssh target** (`alias`), and only the *id* is sanitised.
- *
- * @param alias - the literal alias from the config.
- * @returns a valid id, or `undefined` when sanitising leaves nothing usable.
- */
-export declare function connectionIdFromAlias(alias: string): string | undefined;
-//# sourceMappingURL=roots-api-http.d.ts.map

package/lib/types/src/host/app/roots-api-projections.d.ts

@@ -1,102 +0,0 @@
-/**
- * 根路由的**投影层**：把内部状态/后端条目压成对外的 DTO，以及路径面包屑与失败文案。
- *
- * 从 `roots-api-support.ts` 拆出（审计 0079）：纯函数，输入输出都是普通对象，
- * 因此可以单独断言「哪些字段能出网」。
- *
- * @module dsh-remote-workspace/app/roots-api-projections
- */
-import { type ConnectionPatch, type UserRootEntry, type UserRootsState } from './user-roots.ts';
-/**
- * Whitelist one live root, dropping everything else it carries (argv, anchor paths, transports).
- *
- * Both spellings the Lead may hand over are accepted: a bare `RootRef` and a `RootRecord`
- * (`{ key, root, backend }` — what `RootRegistry.records` returns). Reading the nested `root` here is what
- * keeps a wiring mistake from showing every root as `location: "unknown", path: ""`.
- */
-export declare function publicRoot(raw: unknown): PublicRoot;
-/**
- * Whitelist one live connection.
- *
- * This is the only place the host's connection profiles are turned into wire data, so it is the one place
- * that must never copy a field it was not explicitly told to copy: `auth`, `keyPath`, `credentialKey`,
- * `password`, `alias`, `proxyJump` and everything added later stay behind.
- */
-export declare function publicConnection(raw: unknown): PublicConnection;
-/** The persisted state as the panel may see it: same connection projection, so `keyPath` never travels. */
-export declare function publicUserState(state: UserRootsState): {
-    readonly version: number;
-    readonly roots: readonly UserRootEntry[];
-    readonly connections: readonly PublicConnection[];
-};
-/**
- * The wire shape of one tracked transfer.
- *
- * Whitelisted field by field, like every other projection on this route: the tracker's own object is a
- * host-side value, and a field added there must be a deliberate decision to publish, not a leak.
- *
- * @param value - one entry from the tracker.
- * @returns the row the client may see.
- */
-export declare function publicTransfer(value: unknown): Record<string, unknown>;
-/**
- * The absolute chain from the filesystem root down to `absolute`, inclusive.
- *
- * The client renders "up" and "home" from this instead of composing a parent path itself: drive letters, UNC
- * shares and `/` are exactly the dialects a web client gets wrong, and one wrong guess sends `list-local` to a
- * directory the user never asked for. Every element is an ancestor of the path the answer already carries, so
- * the field discloses nothing the `path` field did not.
- *
- * @param absolute - an absolute, resolved path (what the handler answers with).
- * @returns the chain, root first; empty when the platform reports no root (impossible for a resolved path).
- */
-export declare function localPathCrumbs(absolute: string): readonly string[];
-/** The machine-readable reason for one local listing failure, or `undefined` when it is not the caller's fault. */
-export declare function localFailureReason(error: unknown): LocalFailureReason | undefined;
-/** The human text for one {@link LocalFailureReason}; the path is always named so the message is actionable. */
-export declare function localFailureMessage(reason: LocalFailureReason, path: string): string;
-/**
- * Narrow a whitelisted body down to the fields of a {@link ConnectionPatch} (never the id: see
- * {@link UPDATE_CONNECTION_FIELDS}).
- *
- * **Absent means "keep what is there"** for every field, and this function is what makes that true rather than
- * accidental: only keys the body actually carries are copied, so a body that names three fields cannot blank
- * the four it did not mention.
- *
- * `port: ''`/`null` becomes `null`, which is the one value that means **drop the field** (back to the ssh
- * default). Every other value is passed through untouched and judged by `normalizeConnectionEntry`; nothing is
- * coerced here, because a bad port must be reported, not silently rounded.
- *
- * @param source - the whitelisted fields of the request body.
- * @returns the patch.
- */
-export declare function connectionPatchOf(source: Record<string, unknown>): Omit<ConnectionPatch, 'id'>;
-/** One root as the panel may see it: no credential can appear in a root, but the shape is still fixed. */
-export interface PublicRoot {
-    readonly key?: string;
-    readonly location: string;
-    readonly connectionId?: string;
-    readonly path: string;
-    readonly label?: string;
-    readonly writable?: boolean;
-}
-/**
- * One connection as the panel may see it. **Deliberately without `keyPath`.**
- *
- * `transport` **is** projected, and it has to be: the edit form is filled from this answer and submits what it
- * was filled with, so omitting the field silently rewrote every `alias`/`ssh2` connection to the default
- * (`agent`) on the next save - even when the operator only changed the host.
- */
-export interface PublicConnection {
-    readonly id: string;
-    readonly host: string;
-    readonly user: string;
-    readonly port?: number;
-    readonly authKind: string;
-    /** The transport this connection asks for; absent only for a record that names none. */
-    readonly transport?: string;
-}
-/** The reasons a local listing of a syntactically valid path can be refused with. */
-type LocalFailureReason = 'not-found' | 'not-a-directory' | 'unreadable';
-export {};
-//# sourceMappingURL=roots-api-projections.d.ts.map

package/lib/types/src/host/app/roots-api-roots.d.ts

@@ -1,13 +0,0 @@
-/**
- * roots-api-roots
- *
- * 根的两个 action：add-root / remove-root，以及根的存活判定与锚点解析。
- *
- * 从 `roots-api-roots.ts` 拆出（审计 0077）：根与连接是两套独立的状态机，
- * 原先共处一个 switch，各自的辅助函数也互不相干。
- *
- * @module dsh-remote-workspace/app/roots-api-roots
- */
-import type { RootsApiRequest, RootsApiResponse, RootsApiDeps } from './roots-api-contract.ts';
-export declare function handleRootActions(action: string, body: Record<string, unknown>, req: RootsApiRequest, res: RootsApiResponse, deps: RootsApiDeps): Promise<boolean>;
-//# sourceMappingURL=roots-api-roots.d.ts.map

package/lib/types/src/host/app/roots-api-state.d.ts

@@ -1,22 +0,0 @@
-/**
- * 根路由的**状态读取**：取当前用户状态、在其上做一次可串行化的变更。
- *
- * 从 `roots-api-support.ts` 拆出（审计 0079）：它是根与连接两族 handler 的公共入口，
- * 与 HTTP 原语、DTO 投影互不相干。
- *
- * @module dsh-remote-workspace/app/roots-api-state
- */
-import { type UserRootsState } from './user-roots.ts';
-import type { RootsApiDeps } from './roots-api-contract.ts';
-/** The persisted state, read fresh for every check (the file is the source of truth, not a cache). */
-export declare function currentUserState(deps: RootsApiDeps): Promise<UserRootsState>;
-/**
- * Converge the persisted state on a target shape and return it.
- *
- * The handler never assumes who persisted what: it consults the file **after** the live seam ran, computes
- * the state the request implies, and writes only when that differs. So a wiring whose `registerRoot` already
- * persists produces no second write, and a wiring that only touches the live registry still ends with a file
- * that matches reality.
- */
-export declare function reconcile(deps: RootsApiDeps, transition: (state: UserRootsState) => UserRootsState): Promise<UserRootsState>;
-//# sourceMappingURL=roots-api-state.d.ts.map