dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,102 @@
+/**
+ * 根路由的**投影层**：把内部状态/后端条目压成对外的 DTO，以及路径面包屑与失败文案。
+ *
+ * 从 `roots-api-support.ts` 拆出（审计 0079）：纯函数，输入输出都是普通对象，
+ * 因此可以单独断言「哪些字段能出网」。
+ *
+ * @module dsh-over-ssh/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/roots-api-roots.d.ts

@@ -0,0 +1,13 @@
+/**
+ * roots-api-roots
+ *
+ * 根的两个 action：add-root / remove-root，以及根的存活判定与锚点解析。
+ *
+ * 从 `roots-api-roots.ts` 拆出（审计 0077）：根与连接是两套独立的状态机，
+ * 原先共处一个 switch，各自的辅助函数也互不相干。
+ *
+ * @module dsh-over-ssh/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/roots-api-state.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 根路由的**状态读取**：取当前用户状态、在其上做一次可串行化的变更。
+ *
+ * 从 `roots-api-support.ts` 拆出（审计 0079）：它是根与连接两族 handler 的公共入口，
+ * 与 HTTP 原语、DTO 投影互不相干。
+ *
+ * @module dsh-over-ssh/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

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

@@ -0,0 +1,26 @@
+/**
+ * roots-api-transfers
+ *
+ * 传输面板的 2 个 action：列表与清空。
+ *
+ * 从 `roots-api.ts` 的 `serveAction`（543 行 / 15 个 case）拆出（审计 0076）：
+ * case 体逐字搬移，只把 `return;` 改成 `return true;`，未命中时返回 `false` 由分发器报 400。
+ *
+ * ## `list-transfers` 的长轮询（task-19）
+ *
+ * 面板以前按 1 s / 5 s 定时全量拉取，进度条于是按「间隔 × 速率」跳格——这就是用户报的「一顿一顿」。
+ * 现在请求可以带 `waitMs`：宿主在**没有变化**时挂起，变化或预算用尽时返回当前快照。
+ *
+ * 三条实现规则：
+ *
+ *  1. **没有挂起的请求时什么都不做**：不缓存、不攒状态，`waitMs` 缺省/为 0 直接返回快照（旧行为）。
+ *  2. **超时是正常答案**：不是错误，回答里带 `waitedMs`，客户端据此立刻再发下一次。
+ *  3. **挂起不占配额**：平台载体（`dsh-host-webserver`）只有路由表、每个请求一个独立处理函数，没有
+ *     「每条路由的在飞配额」可以被挂起请求占住；真正会累积的是 socket，所以同时挂起数被
+ *     {@link MAX_TRANSFER_WAITERS} 封顶，超出的请求**立即**返回快照并标记 `degraded`，绝不排队。
+ *
+ * @module dsh-over-ssh/app/roots-api-transfers
+ */
+import type { RootsApiRequest, RootsApiResponse, RootsApiDeps } from './roots-api-contract.ts';
+export declare function handleTransferActions(action: string, body: Record<string, unknown>, req: RootsApiRequest, res: RootsApiResponse, deps: RootsApiDeps): Promise<boolean>;
+//# sourceMappingURL=roots-api-transfers.d.ts.map

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

@@ -0,0 +1,55 @@
+/**
+ * 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-over-ssh/integration/roots-api
+ */
+import type { RootsApiDeps, RootsApi } from './roots-api-contract.ts';
+export * from './roots-api-contract.ts';
+export { localPathCrumbs } from './roots-api-projections.ts';
+export { connectionIdFromAlias } from './roots-api-http.ts';
+export type { PublicRoot, PublicConnection } from './roots-api-projections.ts';
+export declare function createRootsApi(deps: RootsApiDeps): RootsApi;
+//# sourceMappingURL=roots-api.d.ts.map