dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/host/domain/session/session-admin.d.ts

@@ -0,0 +1,345 @@
+/**
+ * Session administration: inventory, hierarchy classification, delete plans and restore plans — pure logic only.
+ *
+ * Requirement FR-3.3–3.10 asks for a *session* recycle bin, which is a different thing from the existing
+ * *file-level* recycle bin in [`recycle-bin.ts`](./recycle-bin.ts) (see ADR-0009): that one moves one path
+ * inside a root, this one moves a whole session directory out of the platform's session store.
+ *
+ * ## The two facts everything here is built on
+ *
+ *  1. **`projectKey` is lossy.** The platform folds separators and truncates at 251 chars, so a directory
+ *     name **cannot** be decoded back into a `cwd`. Every classification therefore reads the session
+ *     **header**, never the directory name. (The encoder is reproduced in {@link projectKey} and was checked
+ *     against the real store 6/6 — see ADR-0009.)
+ *  2. **A bin entry has two directory names.** `segment` is where it lives *inside the bin*; `originalSegment` A top-level session id carries a `session-` prefix while a
+ *     sub-session id is a bare uuid, but the requirement is explicit that this must **not** be used to infer
+ *     hierarchy: `origin`/`parentSession` from the header is the only authority.
+ *
+ * Everything in this module is a pure function over already-read data: no filesystem, no clock, no I/O.
+ *
+ * @module dsh-over-ssh/domain/session-admin
+ */
+/**
+ * Reproduce the platform's `projectKey(cwd)` (source: `dsh-session-persistence-jsonl` `projectKey`).
+ *
+ * Rules: runs of `/`, `\` and `:` collapse to one `-`; `[A-Za-z0-9._-]` (except `~`) stay; everything else
+ * becomes `~XXXX` (4 uppercase hex digits of the UTF-16 code unit); leading `-` are dropped; empty becomes
+ * `root`; the body is truncated to 251 chars; the result is wrapped in `--…--`.
+ *
+ * **Lossy on purpose** (the platform says so too): two different `cwd` values can share one key. This
+ * function exists so the plugin can *compute* the directory a session lives in, never to decode one.
+ *
+ * @param cwd - the session's project directory (an absolute path).
+ * @returns the project directory name.
+ * @throws SshDevError `ROOT_INVALID` for an empty path (the platform refuses it too).
+ */
+export declare function projectKey(cwd: string): string;
+/**
+ * Reproduce the platform's `encodeSegment(id)` (source: `dsh-session-persistence-jsonl`).
+ *
+ * Unlike {@link projectKey} this one is **injective**: `.` becomes `~002E` (so `.`/`..` cannot escape the
+ * directory), safe characters pass through, everything else becomes `~XXXX`. A `session-` prefix is
+ * therefore preserved verbatim — which is exactly why hierarchy must not be read from it.
+ *
+ * @param id - the session id.
+ * @returns the directory name.
+ */
+export declare function encodeSegment(id: string): string;
+/**
+ * The directory one session lives in, relative to the sessions root.
+ *
+ * `cwd === undefined` selects the platform's `_no-cwd` bucket (the platform's own convention).
+ *
+ * @param cwd - the session's project directory, or `undefined` for the no-cwd bucket.
+ * @param id - the session id.
+ * @returns the path segments, root-relative.
+ */
+export declare function sessionSegments(cwd: string | undefined, id: string): readonly string[];
+/**
+ * Classify one inventory record.
+ *
+ * The only authority is the header: `parentSessionId` present ⇒ sub-session. A record whose header could not
+ * be read is `unreadable`. The directory name is deliberately **not** consulted — `session-`-prefixed ids are
+ * top-level sessions, but the requirement forbids inferring hierarchy from that, and a future id scheme would
+ * silently break such an inference.
+ *
+ * @param record - a record without its `classification` field.
+ * @returns the class.
+ */
+export declare function classifySession(record: Omit<SessionRecord, 'classification'> & {
+    readonly readable?: boolean;
+}): SessionClass;
+/** How one session relates to the rest of the store. */
+export type SessionClass = 
+/** A normal, independently-visible session. */
+'normal'
+/** A sub-session: its lifecycle follows its parent, so it must not be deleted on its own. */
+ | 'subsession'
+/** A directory whose header could not be read (corrupt or unsupported format). */
+ | 'unreadable';
+/** One session as the inventory sees it. */
+export interface SessionRecord {
+    readonly id: string;
+    /** Project directory the log was found under, as spelled on disk. */
+    readonly projectDir: string;
+    /** Directory name (`encodeSegment(id)`) the log was found under. */
+    readonly segment: string;
+    /** `cwd` from the header; `undefined` for the no-cwd bucket. */
+    readonly cwd: string | undefined;
+    /** The session's own title (the platform's `title` projection), when one was ever generated. */
+    readonly title: string | undefined;
+    /**
+     * Display title of the workspace owning {@link cwd}, resolved from the platform's workspace registry.
+     *
+     * `undefined` when the caller supplied no resolver or no registered workspace owns the directory. The
+     * directory itself is still on the wire (`cwd`), so a reader falls back to its own leaf name.
+     */
+    readonly workspaceTitle: string | undefined;
+    /** Parent session id from the header, when this is a sub-session. */
+    readonly parentSessionId: string | undefined;
+    /** Total bytes of the log files in the session directory (0 when unknown). */
+    readonly bytes: number;
+    /** Modification time of the newest log file, in ms since the epoch. */
+    readonly updatedAtMs: number;
+    /**
+     * True when the host holds this session in its store — it was opened in this DSH process.
+     *
+     * Loaded is **not** running: the platform keeps an agent for every session opened since the process
+     * started, and an idle agent is doing nothing. The panel renders this as 已打开, and an idle loaded
+     * session stays deletable.
+     */
+    readonly live: boolean;
+    /**
+     * True when this session's agent is running a turn (`agents.get(id)?.status === 'running'`).
+     *
+     * This is the platform's own "运行中" signal — the one the session list uses for a row's status — and the
+     * only state that must refuse deletion (FR-3.6).
+     */
+    readonly running: boolean;
+    /** How this session relates to the store (see {@link classifySession}). */
+    readonly classification: SessionClass;
+}
+/** Why one session may not be deleted. */
+export type DeleteRefusal = 
+/** Its agent is running a turn: the platform has no public way to unload one (see FR-3.6). */
+'running'
+/** It is a sub-session: delete its parent instead. */
+ | 'subsession'
+/** Its log could not be read, so deleting it would be guesswork. */
+ | 'unreadable'
+/** The caller asked to keep a session that this operation would have removed. */
+ | 'protected';
+/** The pure decision for one deletion. */
+export interface DeleteDecision {
+    /** Ids to delete, **children before parents** (so a parent never outlives its children). */
+    readonly delete: readonly string[];
+    /** One refusal per skipped id, in the order the ids were considered. */
+    readonly refusals: readonly {
+        readonly id: string;
+        readonly reason: DeleteRefusal;
+    }[];
+    /** Total bytes the deletion will free, counting only the ids in `delete`. */
+    readonly bytes: number;
+}
+/**
+ * Decide what a deletion request would actually do, without touching anything.
+ *
+ * The rules, in order:
+ *
+ *  1. an id that is not in the inventory is refused as `unreadable` (it was never a session here);
+ *  2. a **running** session is refused (`running`) — FR-3.6 requires blocking rather than killing, because the
+ *     platform exposes no way to unload a live agent, and the requirement is explicit that
+ *     "stop and delete" is *not* offered this round. Loaded-but-idle is **not** refused: the host keeps an
+ *     agent for every session opened since it started, so refusing those would make nearly every session
+ *     undeletable, and a session that is doing nothing cannot be interrupted;
+ *  3. an `unreadable` record is refused (`unreadable`) — deleting a directory we could not identify is
+ *     exactly the kind of irreversible guess this feature must not make;
+ *  4. a sub-session is refused (`subsession`) when it is selected **on its own** (FR-3.3: 子会话随父会话管理，
+ *     默认不可被单独删除);
+ *  5. selecting a parent **always** takes its whole descendant subtree along, ordered **children first**.
+ *
+ * Rule 5 is unconditional on purpose. It used to be an opt-in `includeSubsessions` switch, and that was the
+ * wrong shape: leaving a parent's children behind orphans their logs — the parent is gone, so nothing
+ * navigates to them, and the platform's listing hides them by `parentId` nesting, so the bytes stay on disk
+ * and invisible forever. FR-3.3 asks for sub-sessions to be "随父会话管理" and the requirement's own §7
+ * recommendation is "删除父会话时提示将一并处理 N 个子会话": always together, with the count shown.
+ *
+ * A sub-session that was explicitly requested *and* pulled in by its parent is deleted and **not** reported
+ * as a refusal — otherwise the caller would see a row refused and deleted in the same answer.
+ *
+ * **A subtree is atomic.** If any descendant of a requested session is running or protected, the whole
+ * request for that session is refused instead of deleting the ancestor and orphaning the descendant: a
+ * running child whose parent is gone can never be reached again (the listing nests children under their
+ * parent), and a protected one was explicitly asked to be spared. Refusing the parent is the only outcome
+ * that keeps both promises (FR-3.6 never interrupts a running agent; `keep` is honoured).
+ *
+ * `keep` wins over everything: an id listed there is refused as `protected` even if it is an idle normal
+ * session. It exists so a UI can show a preview and let the user uncheck rows.
+ *
+ * @param records - the full inventory.
+ * @param request - ids to delete, plus the optional keep list.
+ * @returns the decision; `delete` is empty when everything was refused.
+ */
+export declare function planDelete(records: readonly SessionRecord[], request: {
+    readonly ids: readonly string[];
+    readonly keep?: readonly string[];
+}): DeleteDecision;
+/** Index file name inside the session bin root. */
+export declare const SESSION_TRASH_INDEX_FILE = "index.json";
+/** Version stamped into the session bin index; a different version is a hard parse failure. */
+export declare const SESSION_TRASH_INDEX_VERSION = 1;
+/** Opaque identity of one session-bin entry. */
+export type SessionTrashEntryId = string & {
+    readonly __sessionTrashEntryId: 'SessionTrashEntryId';
+};
+/** One entry in the session recycle bin: everything a restore needs. */
+export interface SessionTrashEntry {
+    readonly id: SessionTrashEntryId;
+    /** The deleted session's id. */
+    readonly sessionId: string;
+    /**
+     * The session's `cwd` as recorded in its header, or `undefined` for the no-cwd bucket.
+     *
+     * Kept **verbatim** rather than as a `projectKey`: the key is lossy, so restoring from it could land the
+     * session under a different project directory than it came from.
+     */
+    readonly cwd: string | undefined;
+    /** Project directory name the session was moved out of. */
+    readonly projectDir: string;
+    /**
+     * Directory name **inside the bin**; the session directory is moved here wholesale.
+     *
+     * Equals the entry id in practice, and is **not** the store-side name — see `originalSegment`. Keeping the
+     * two apart is what makes a restore land back where it came from: using one for both would make the
+     * restored session appear under the entry id.
+     */
+    readonly segment: string;
+    /**
+     * The session's directory name **in the store** (`encodeSegment(sessionId)`), captured before the move.
+     *
+     * Stored rather than recomputed: `encodeSegment` is injective so recomputing would work today, but recording
+     * what was actually observed means a restore never depends on the encoder staying byte-identical.
+     */
+    readonly originalSegment: string;
+    readonly title: string | undefined;
+    /** Total bytes of the moved log files, for the retention policy. */
+    readonly bytes: number;
+    readonly deletedAtMs: number;
+    /** How the bytes were moved. `copy` means the move crossed a filesystem boundary. */
+    readonly movedBy: 'rename' | 'copy';
+    /** Who confirmed the deletion, when the caller supplied it (FR-3.10 auditability). */
+    readonly confirmedBy: string | undefined;
+}
+/**
+ * Derive a stable, filesystem-safe entry id.
+ *
+ * Deterministic on `(sessionId, deletedAtMs)` so a retried deletion of the same session at the same instant
+ * lands on the same entry instead of leaving two copies; {@link allocateSessionTrashEntryId} breaks genuine
+ * collisions.
+ *
+ * @param input - identity inputs.
+ * @returns the entry id.
+ */
+export declare function makeSessionTrashEntryId(input: {
+    readonly sessionId: string;
+    readonly deletedAtMs: number;
+}): SessionTrashEntryId;
+/**
+ * Allocate an id that is not already taken, by appending a counter.
+ *
+ * @param existing - ids already in the bin.
+ * @param input - identity inputs.
+ * @returns a free id.
+ * @throws SshDevError `TRASH_NOT_FOUND` when the counter space is exhausted (never returns a taken id).
+ */
+export declare function allocateSessionTrashEntryId(existing: Iterable<string>, input: {
+    readonly sessionId: string;
+    readonly deletedAtMs: number;
+}): SessionTrashEntryId;
+/** The persisted session-bin index document. */
+export interface SessionTrashIndex {
+    readonly version: number;
+    readonly entries: readonly SessionTrashEntry[];
+}
+/** One index record the parser refused. */
+export interface SkippedSessionTrashRecord {
+    readonly index: number;
+    readonly reason: string;
+}
+/** Result of {@link parseSessionTrashIndex}. */
+export interface ParsedSessionTrashIndex {
+    readonly entries: readonly SessionTrashEntry[];
+    readonly skipped: readonly SkippedSessionTrashRecord[];
+}
+/**
+ * Serialize the session-bin index.
+ *
+ * Entries are sorted by id so the same set is byte-identical every time (diffable, testable).
+ *
+ * @param entries - entries to persist.
+ * @returns JSON text.
+ */
+export declare function serializeSessionTrashIndex(entries: readonly SessionTrashEntry[]): string;
+/**
+ * Parse the session-bin index.
+ *
+ * A malformed document or unknown version is a **hard failure** (the bin cannot be trusted, and guessing
+ * could delete the wrong directory); a single unusable record is skipped and reported, so one corrupt entry
+ * never hides the rest.
+ *
+ * @param text - index file content.
+ * @returns usable entries plus skipped records.
+ * @throws SshDevError `TRASH_NOT_FOUND` when the document cannot be read as an index.
+ */
+export declare function parseSessionTrashIndex(text: string): ParsedSessionTrashIndex;
+/** The pure decision for restoring one entry. */
+export type RestoreSessionPlan = {
+    readonly kind: 'restore';
+    readonly entryId: SessionTrashEntryId;
+    readonly sessionId: string;
+    readonly projectDir: string;
+    /** Where it goes back to in the store (the original directory name). */
+    readonly originalSegment: string;
+} | {
+    readonly kind: 'refuse';
+    readonly reason: 'occupied';
+    readonly entryId: SessionTrashEntryId;
+    readonly suggestedId: string;
+};
+/**
+ * Decide how to restore one entry.
+ *
+ * Restoring onto an occupied path is **refused** with a suggestion rather than silently restored under a
+ * different name: the platform keys a session by `(id, cwd)`, so a renamed directory would either be
+ * invisible or (worse) look like a second copy of a session that still exists.
+ *
+ * @param entry - the bin entry.
+ * @param options - whether the original path is currently occupied.
+ * @returns the plan.
+ */
+export declare function planRestoreSession(entry: SessionTrashEntry, options: {
+    readonly occupied: boolean;
+}): RestoreSessionPlan;
+/**
+ * Build one entry from a deletion that has already been performed.
+ *
+ * Pure: the caller has moved the bytes and passes the observed facts. Keeping this separate from the move
+ * means the recorded `bytes`/`movedBy` are what actually happened, not what was planned.
+ *
+ * @param input - observed facts.
+ * @returns the entry.
+ */
+export declare function makeSessionTrashEntry(input: {
+    readonly id: SessionTrashEntryId;
+    readonly sessionId: string;
+    readonly cwd: string | undefined;
+    readonly projectDir: string;
+    readonly segment: string;
+    readonly originalSegment: string;
+    readonly title: string | undefined;
+    readonly bytes: number;
+    readonly deletedAtMs: number;
+    readonly movedBy: 'rename' | 'copy';
+    readonly confirmedBy?: string | undefined;
+}): SessionTrashEntry;
+//# sourceMappingURL=session-admin.d.ts.map

package/lib/types/src/host/domain/session/terminal-target.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Which terminal a session gets: the remote host, or the local machine.
+ *
+ * The platform's only official extension point for the Web terminal is `terminalController.Config.shell`
+ * (`{ path, name, args }`), so this plugin ships a **wrapper** as that shell: the wrapper decides at launch
+ * time whether to `exec ssh` or the local login shell. See `doc/02-platform/terminal.md` §5 for the evidence
+ * and the accepted costs.
+ *
+ * This module is the decision itself, kept pure (no filesystem, no spawn) so it can be tested in
+ * milliseconds — the wrapper script is a thin `spawn` around it.
+ *
+ * Two inputs decide it, in this order:
+ *
+ *  1. **the session's recorded target** (`state/<sessionId>.json`): the host writes it when it resolves a
+ *     remote root for that session, so it works even when the core hands us an unrelated cwd;
+ *  2. **the root manifest** (`roots.json`): a directory→connection map, used when the wrapper has no session
+ *     id (a terminal opened by hand) — a cwd under a remote root's anchor means the user is working remotely.
+ *
+ * @module dsh-over-ssh/domain/terminal-target
+ */
+import { quote as posixQuote } from '../shell.ts';
+/** How the wrapper reaches a connection's host: pre-built ssh arguments the host already resolved. */
+export interface SshInvocation {
+    /** `user@host` or a `~/.ssh/config` alias. */
+    readonly destination: string;
+    /** Extra arguments (`-i`, `-o UserKnownHostsFile=…`, `-p`, jump options…), already credential-resolved. */
+    readonly args: readonly string[];
+}
+/** One remote root as the wrapper needs it. */
+export interface ManifestRoot {
+    readonly connectionId: string;
+    /** Backend-absolute remote path (POSIX). */
+    readonly remoteRoot: string;
+    /** Local anchor directory that maps to this remote root. */
+    readonly anchorPath: string;
+    /** How to reach the host. */
+    readonly ssh: SshInvocation;
+}
+/** The root manifest the host writes for the wrapper. */
+export interface RootManifest {
+    /** Manifest format version; a wrapper that does not know the version falls back to local. */
+    readonly version: number;
+    readonly roots: readonly ManifestRoot[];
+}
+/** One session's recorded remote target. */
+export interface SessionState {
+    readonly sessionId: string;
+    readonly connectionId: string;
+    readonly remoteRoot: string;
+    readonly ssh: SshInvocation;
+    /** Epoch milliseconds; the wrapper ignores entries older than {@link SESSION_STATE_MAX_AGE_MS}. */
+    readonly recordedAt: number;
+}
+/** Current manifest version. */
+export declare const MANIFEST_VERSION = 1;
+/** A session state older than this is ignored (a stale file must not send the user to the wrong host). */
+export declare const SESSION_STATE_MAX_AGE_MS: number;
+/** The decision the wrapper acts on. */
+export type TerminalDecision = {
+    readonly kind: 'remote';
+    readonly connectionId: string;
+    readonly remoteRoot: string;
+    /** Full argv to spawn: `[ssh, -tt, …args, destination, --, command]`. */
+    readonly argv: readonly string[];
+    /** Remote command: `cd <root> && exec <login shell> -l`. */
+    readonly remoteCommand: string;
+    /** Why this decision was taken (for diagnostics and tests). */
+    readonly reason: 'session' | 'anchor';
+} | {
+    readonly kind: 'local';
+    /** Full argv to spawn: the local login shell. */
+    readonly argv: readonly string[];
+    readonly reason: 'no-target' | 'state-unusable' | 'manifest-unusable';
+};
+/** Options for {@link decideTerminal}. */
+export interface DecideTerminalOptions {
+    /** Working directory the terminal was launched in. */
+    readonly cwd: string;
+    /** Manifest, when readable and valid. */
+    readonly manifest?: RootManifest;
+    /** This session's state, when readable and valid. */
+    readonly sessionState?: SessionState;
+    /** Local login shell to fall back to (platform default resolved by the caller). */
+    readonly localShell: string;
+    /** Remote login shell; `$SHELL` expands remotely, which is the right default. */
+    readonly remoteShell?: string;
+    /** Clock, injected for the staleness check. */
+    readonly now?: number;
+}
+/**
+ * Quote one word for a POSIX shell.
+ *
+ * Re-exported from {@link ../shell.ts}: this module builds `cd … && exec …`, which is a remote shell command,
+ * and the shared implementation is the one that refuses NUL bytes.
+ */
+export { posixQuote };
+/**
+ * Parse a root manifest.
+ *
+ * @param raw - file contents.
+ * @returns the manifest, or `undefined` when it is unusable (wrong version, malformed, empty).
+ */
+export declare function parseRootManifest(raw: string): RootManifest | undefined;
+/**
+ * Parse one session state file.
+ *
+ * @param raw - file contents.
+ * @returns the state, or `undefined` when malformed.
+ */
+export declare function parseSessionState(raw: string): SessionState | undefined;
+/** Serialize a manifest for the wrapper (stable key order, so the file diff is readable). */
+export declare function serializeRootManifest(manifest: RootManifest): string;
+/** Serialize one session state. */
+export declare function serializeSessionState(state: SessionState): string;
+/** Build the command the remote shell runs: enter the workspace and be a login shell. */
+export declare function remoteCommandFor(remoteRoot: string, remoteShell?: string): string;
+/**
+ * Build the ssh argv for one remote target.
+ *
+ * `-tt` is what makes an interactive terminal work through the wrapper (the child needs a TTY on both
+ * sides). `--` ends option parsing before the destination, and the remote command is a single argument.
+ *
+ * @param ssh - resolved destination and credential arguments.
+ * @param remoteCommand - command to run remotely.
+ * @returns the argv to spawn.
+ */
+export declare function sshArgvFor(ssh: SshInvocation, remoteCommand: string): readonly string[];
+/**
+ * Decide which terminal to open.
+ *
+ * @param options - cwd, manifest, session state, local shell, clock.
+ * @returns the decision, always total (never throws): an unusable input degrades to the local shell, with
+ *   `reason` naming why.
+ */
+export declare function decideTerminal(options: DecideTerminalOptions): TerminalDecision;
+//# sourceMappingURL=terminal-target.d.ts.map