@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/ide-channel.js

@@ -0,0 +1,556 @@
+/**
+ * IDE selection channel (PR-B groundwork): the dsh-tui side of a loopback
+ * WebSocket link with a companion IDE extension (dsh-tui-vscode). The
+ * extension broadcasts caret-selection changes; the TUI consumes them to
+ * attach `<attached-file …>` blocks at submit time (ADR-001).
+ *
+ * Discovery has two paths (DESIGN D4):
+ *   1. env direct — DSH_TUI_IDE_PORT + DSH_TUI_IDE_TOKEN, injected when the
+ *      extension spawns this TUI itself;
+ *   2. lock scan — `~/.dsh-tui/ide/*.lock` files written by the extension
+ *      ({port, token, workspaceFolders, pid}); locks whose workspaceFolders
+ *      match the session cwd connect first.
+ *
+ * Both paths fail → silent degradation (AC-4): no error, no retry,
+ * connected=false, every other TUI feature unaffected. The client is Node's
+ * native WebSocket global (engines ^22.19 || >=24, D5) — zero dependencies
+ * and no auto-reconnect (degrade-on-drop is the design).
+ *
+ * Protocol constants here are a cross-repo contract (the extension's server
+ * side implements the mirror); changing them requires updating both ends
+ * plus ADR-001 (DESIGN §9.5). Protocol version 2:
+ * - Handshake: the client's first frame is
+ *   `{"method":"ide/hello","params":{"token","protocolVersion"}}`; the
+ *   server validates the token and answers
+ *   `{"method":"ide/hello_ack","params":{"protocolVersion",
+ *   "workspaceFolders"}}`. The client is connected only after a valid ack —
+ *   a wrong token closes the socket and the client tries its next
+ *   candidate.
+ * - Notifications: `{"method":"selection_changed","params":{path,
+ *   startLine, endLine, isEmpty, text, documentVersion}}` — coordinates are
+ *   0-based, and `text` carries the editor buffer's own selection text
+ *   (unsaved edits included); the TUI attaches that text verbatim and only
+ *   falls back to reading the file from disk for protocol-1 pushes.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from '../utils/paths.js';
+/** Env var carrying the extension's loopback WS port (spawn-injected). */
+export const IDE_PORT_ENV = 'DSH_TUI_IDE_PORT';
+/** Env var carrying the extension's handshake token (spawn-injected). */
+export const IDE_TOKEN_ENV = 'DSH_TUI_IDE_TOKEN';
+/** Handshake frame the client must send as its very first message. */
+const HELLO_METHOD = 'ide/hello';
+/**
+ * Ack frame a protocol-2 server must answer with once the hello token is
+ * validated. Until it arrives the client is NOT connected: a server that
+ * rejects the token just closes, and the client moves on to the next
+ * candidate instead of mistaking an open socket for an authenticated one
+ * (maintainer review round 3).
+ */
+const HELLO_ACK_METHOD = 'ide/hello_ack';
+/** Wire protocol this client speaks; hello_ack carries the server's value. */
+export const IDE_PROTOCOL_VERSION = 2;
+/** Selection notification method broadcast by the extension. */
+const SELECTION_METHOD = 'selection_changed';
+/** Total connection budget across all candidates, in milliseconds. */
+const CONNECT_BUDGET_MS = 300;
+/** Where the extension advertises its loopback server (`~/.dsh-tui/ide`). */
+export function ideLockDir(dataDir = DATA_DIR) {
+    return join(dataDir, 'ide');
+}
+/**
+ * Parse the direct-connect environment. Returns undefined when the pair is
+ * absent or malformed — port must be an integer within 1..65535 and the
+ * token non-empty — so a bad env degrades to lock discovery instead of
+ * throwing.
+ */
+export function envDirect(env) {
+    const portRaw = env[IDE_PORT_ENV];
+    const token = env[IDE_TOKEN_ENV];
+    if (typeof portRaw !== 'string' || portRaw === '')
+        return undefined;
+    if (typeof token !== 'string' || token === '')
+        return undefined;
+    const port = Number(portRaw);
+    if (!Number.isSafeInteger(port))
+        return undefined;
+    if (port < 1 || port > 65535)
+        return undefined;
+    return { port, token };
+}
+/**
+ * Validate an inbound `ide/hello_ack` frame. Returns the server's protocol
+ * version and workspace folders, or undefined for anything else — wrong
+ * method, malformed envelope, or a version this client does not speak (both
+ * ends ship together, so a mismatch is a foreign server and must not be
+ * treated as connected).
+ */
+export function parseHelloAck(message) {
+    if (message === null || typeof message !== 'object')
+        return undefined;
+    const record = message;
+    if (record.method !== HELLO_ACK_METHOD)
+        return undefined;
+    const params = record.params;
+    if (params === null || typeof params !== 'object' || Array.isArray(params))
+        return undefined;
+    const payload = params;
+    const version = payload.protocolVersion;
+    const folders = payload.workspaceFolders;
+    if (typeof version !== 'number' || !Number.isSafeInteger(version))
+        return undefined;
+    if (version !== IDE_PROTOCOL_VERSION)
+        return undefined;
+    if (!Array.isArray(folders) || !folders.every(folder => typeof folder === 'string')) {
+        return undefined;
+    }
+    return { protocolVersion: version, workspaceFolders: folders };
+}
+/**
+ * Normalize a path for comparison: backslashes folded to forward slashes,
+ * trailing slashes stripped, case folded when the platform's filesystem is
+ * case-insensitive (same semantics as channel.ts normalizeCwd — sessions.ts
+ * precedent). Exported so verifiers can pin the Windows behavior.
+ */
+export function normalizeIdePath(path, caseInsensitive) {
+    const normalized = path === '/' ? '/' : path.replace(/\\/g, '/').replace(/\/+$/, '');
+    return caseInsensitive ? normalized.toLowerCase() : normalized;
+}
+function platformCaseInsensitive() {
+    return process.platform === 'win32' || process.platform === 'darwin';
+}
+/**
+ * Read and parse one lock file. Returns undefined for unreadable or
+ * malformed content (broken JSON, wrong field types) — a single bad lock
+ * must never break the whole scan.
+ */
+export function readLockEntry(file) {
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const port = record.port;
+    const token = record.token;
+    const folders = record.workspaceFolders;
+    if (typeof port !== 'number' || !Number.isSafeInteger(port) || port < 1 || port > 65535) {
+        return undefined;
+    }
+    if (typeof token !== 'string' || token === '')
+        return undefined;
+    if (!Array.isArray(folders) || !folders.every(folder => typeof folder === 'string')) {
+        return undefined;
+    }
+    const pid = record.pid;
+    if (typeof pid !== 'number' || !Number.isSafeInteger(pid))
+        return undefined;
+    return { port, token, workspaceFolders: folders, pid };
+}
+/**
+ * True when a process id is currently alive (used to skip stale locks whose
+ * owning extension already exited). `process.kill(pid, 0)` probes existence
+ * without signalling; a missing process throws ESRCH and reads as dead.
+ * Same user, so no permission false-negatives for the loopback's own locks.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Scan a lock directory and return the candidates whose workspaceFolders
+ * actually CONTAIN the session cwd, most-specific root first; ties keep
+ * directory order (stable sort). Malformed and stale locks are skipped, and
+ * an unmatched lock is NOT a candidate at all — dialing another workspace's
+ * IDE would attach that project's selections here (maintainer review round 3:
+ * "unmatched trails every match" used to make start() connect to an
+ * unrelated window when nothing matched). Never throws — an unreadable
+ * directory degrades to an empty list.
+ *
+ * `pid` is part of the lock contract and reserved for future disambiguation
+ * (DESIGN R5); matching currently relies on workspaceFolders only.
+ */
+export function pickLockCandidates(lockDir, cwd, pid) {
+    void pid;
+    let names;
+    try {
+        names = readdirSync(lockDir)
+            .filter(name => name.endsWith('.lock'))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    const caseInsensitive = platformCaseInsensitive();
+    const cwdNorm = normalizeIdePath(cwd, caseInsensitive);
+    const entries = [];
+    for (const name of names) {
+        const entry = readLockEntry(join(lockDir, name));
+        // Stale lock: the extension that wrote it has already exited — a dead
+        // process can no longer own the handshake token, so never dial it
+        // (maintainer review round 2: stale locks could otherwise win discovery).
+        if (entry === undefined || !isProcessAlive(entry.pid))
+            continue;
+        // Boundary-checked prefix: `/repo/a` must NOT match a cwd of `/repo/abc`
+        // (another workspace's window), only `/repo/a` itself or a path under it.
+        // Without the separator guard the wrong window's lock is dialed first and
+        // its selections attach here. The POSIX root `/` matches every absolute
+        // cwd WITHOUT a `//` boundary. `matchLength` records the longest matching
+        // workspace root so candidates rank most-specific-first below.
+        let matchLength = 0;
+        for (const folder of entry.workspaceFolders) {
+            const root = normalizeIdePath(folder, caseInsensitive);
+            if (root === '')
+                continue;
+            const hits = root === '/'
+                ? cwdNorm.startsWith('/')
+                : cwdNorm === root || cwdNorm.startsWith(`${root}/`);
+            if (hits && root.length > matchLength)
+                matchLength = root.length;
+        }
+        // No workspace folder covers the session cwd → not a candidate. Keeping
+        // unmatched locks "for later" is how a foreign project's selections ended
+        // up attachable here (see the doc comment above).
+        if (matchLength === 0)
+            continue;
+        entries.push({ entry, matchLength });
+    }
+    // Most-specific-first: a `/repo` workspace lock must precede the root `/`
+    // fallback when both match the same cwd (coderabbit review).
+    return entries
+        .sort((left, right) => right.matchLength - left.matchLength)
+        .map(item => item.entry);
+}
+/**
+ * Validate one inbound notification as a `selection_changed` frame. Returns
+ * undefined for anything else — wrong method, malformed envelope, missing or
+ * out-of-range coordinates (endLine >= startLine >= 0, non-empty path).
+ */
+export function parseSelectionChanged(message) {
+    if (message === null || typeof message !== 'object')
+        return undefined;
+    const record = message;
+    if (record.method !== SELECTION_METHOD)
+        return undefined;
+    const params = record.params;
+    if (params === null || typeof params !== 'object' || Array.isArray(params))
+        return undefined;
+    const payload = params;
+    const path = payload.path;
+    const startLine = payload.startLine;
+    const endLine = payload.endLine;
+    const isEmpty = payload.isEmpty;
+    if (typeof path !== 'string' || path === '')
+        return undefined;
+    if (typeof startLine !== 'number' || !Number.isSafeInteger(startLine) || startLine < 0) {
+        return undefined;
+    }
+    if (typeof endLine !== 'number' || !Number.isSafeInteger(endLine) || endLine < startLine) {
+        return undefined;
+    }
+    if (typeof isEmpty !== 'boolean')
+        return undefined;
+    // Protocol 2 optional fields. A v2 extension always sends text; the
+    // fallback when it is missing is the disk read (see SelectionSnapshot).
+    const text = payload.text;
+    const documentVersion = payload.documentVersion;
+    const snapshot = { path, startLine, endLine, isEmpty };
+    if (typeof text === 'string' && text !== '')
+        snapshot.text = text;
+    if (typeof documentVersion === 'number' && Number.isSafeInteger(documentVersion)) {
+        snapshot.documentVersion = documentVersion;
+    }
+    return snapshot;
+}
+/**
+ * Connection lifecycle (DESIGN §3): idle → connecting (env first, then lock
+ * candidates under one shared budget) → connected, or silently disconnected.
+ * Once connected, an error or drop degrades to disconnected — no retry.
+ * The latest non-empty selection stays available after consumption so
+ * consecutive submits can reuse it; an isEmpty notification clears it.
+ */
+export class IdeChannel {
+    socket = null;
+    pendingSocket = null;
+    state = 'idle';
+    current = undefined;
+    /** Bumped on every connect attempt and on stop(): in-flight dials check it
+     *  in `finish` and the discovery loop checks it before every next dial, so
+     *  a stopped channel can neither be revived by a late onopen/ack nor keep
+     *  dialing further candidates (maintainer review rounds 2–3). */
+    generation = 0;
+    /** Env/lockDir of the last start(), reused by rebind() so a cwd change
+     *  rediscovers against the same environment it originally connected in. */
+    startEnv = process.env;
+    startLockDir = ideLockDir();
+    /** Workspace folders the connected server reported in hello_ack. */
+    ackedWorkspaceFolders = undefined;
+    listeners = new Set();
+    /** True only while the loopback link is up. */
+    get connected() {
+        return this.state === 'connected';
+    }
+    /** Workspace folders the connected server acked with, or undefined while
+     *  not connected (test/introspection seam for the cwd-coverage rule). */
+    get workspaceFolders() {
+        return this.ackedWorkspaceFolders;
+    }
+    /** Latest non-empty selection, or undefined (never consumed-clearing). */
+    get selection() {
+        return this.current;
+    }
+    /**
+     * Subscribe to every selection notification, including empty ones.
+     * @returns An unsubscribe handle.
+     */
+    onSelection(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Discover and connect. All arguments are injectable so callers (and
+     * verifiers) can pin the environment, lock directory and session cwd;
+     * defaults read the live process values. Resolves without throwing in
+     * every outcome — check `connected` afterwards.
+     */
+    async start(env = process.env, lockDir = ideLockDir(), cwd = process.cwd()) {
+        if (this.state !== 'idle')
+            return;
+        this.generation++;
+        // Operation token for the WHOLE discovery loop (maintainer review round
+        // 3): stop()/rebind() bump the generation; dials in flight check it in
+        // `finish`, and the loop below checks it before every next dial — a stop
+        // mid-discovery cancels the entire start, not just the one dial it
+        // interrupted (later candidates used to still connect after a stop).
+        const operation = this.generation;
+        this.startEnv = env;
+        this.startLockDir = lockDir;
+        const targets = [];
+        const direct = envDirect(env);
+        if (direct !== undefined)
+            targets.push(direct);
+        for (const lock of pickLockCandidates(lockDir, cwd)) {
+            targets.push({ port: lock.port, token: lock.token });
+        }
+        if (targets.length === 0) {
+            this.state = 'disconnected';
+            return;
+        }
+        this.state = 'connecting';
+        const deadline = Date.now() + CONNECT_BUDGET_MS;
+        for (const target of targets) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                break;
+            if (operation !== this.generation)
+                return;
+            if (await this.tryConnect(target, remaining, operation))
+                return;
+        }
+        if (operation === this.generation)
+            this.state = 'disconnected';
+    }
+    /** Drop the link (if any) and mark the channel disconnected. Cancels any
+     *  dial still pending: the generation bump invalidates its finish, and the
+     *  pending socket is aborted so a late onopen/ack can never re-connect.
+     *  Cached selection state goes with the link — a stopped channel must not
+     *  keep serving the old window's snapshot to anyone who reads `selection` /
+     *  `workspaceFolders` (degradeToDisconnected already does this; stop() used
+     *  to leave both behind, contradicting rebind()'s own contract). */
+    stop() {
+        this.generation++;
+        this.teardown();
+        this.state = 'disconnected';
+        this.current = undefined;
+        this.ackedWorkspaceFolders = undefined;
+    }
+    /**
+     * Re-target the channel after the session cwd changed (/workspace, /resume
+     * adopting another session, ...). The old link belongs to the old
+     * workspace — a selection pushed there must never attach into the new one
+     * — so drop it (stop() clears the cached selection and the acked folders)
+     * and rediscover against the new cwd with the env/lockDir start() was last
+     * given (maintainer review
+     * round 3: clearing the cached selection used to keep the stale link, and
+     * the terminal-on-disconnect design meant a plain stop() could never
+     * reconnect; rebind() is the one sanctioned way back to idle).
+     */
+    async rebind(cwd) {
+        this.stop();
+        this.state = 'idle';
+        await this.start(this.startEnv, this.startLockDir, cwd);
+    }
+    teardown() {
+        const socket = this.socket;
+        this.socket = null;
+        const pending = this.pendingSocket;
+        this.pendingSocket = null;
+        if (socket !== null) {
+            this.detach(socket);
+            this.abort(socket);
+        }
+        if (pending !== null && pending !== socket) {
+            this.detach(pending);
+            this.abort(pending);
+        }
+    }
+    detach(socket) {
+        socket.onopen = null;
+        socket.onmessage = null;
+        socket.onerror = null;
+        socket.onclose = null;
+    }
+    /** Close without waiting; closing a CONNECTING socket cancels the dial. */
+    abort(socket) {
+        try {
+            socket.close();
+        }
+        catch {
+            // Already closed or half-open — degradation must never throw.
+        }
+    }
+    /**
+     * Dial one candidate and complete the token handshake. Resolves true only
+     * when the server answered `ide/hello_ack` with a matching protocol
+     * version — an OPEN socket alone proves nothing: a wrong-token server
+     * accepts the WS upgrade and then closes, and treating open as connected
+     * used to strand the client on a rejected candidate (maintainer review
+     * round 3). Anything slower than `timeoutMs`, any error, or any first
+     * frame that is not a valid v2 ack resolves false and cleans up.
+     */
+    tryConnect(target, timeoutMs, operation) {
+        return new Promise(resolve => {
+            let settled = false;
+            let helloSent = false;
+            const gen = operation;
+            let socket;
+            try {
+                socket = new WebSocket(`ws://127.0.0.1:${target.port}`);
+            }
+            catch {
+                resolve(false);
+                return;
+            }
+            // Track the in-flight dial so stop() can abort it directly (not just
+            // via the generation guard) — cancel the CONNECTING socket to unblock
+            // the promise instead of letting it spin until the budget ends.
+            this.pendingSocket = socket;
+            const finish = (connected) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.detach(socket);
+                // A stop() between dial and ack bumped the generation: this dial
+                // belongs to a cancelled session — drop it, never become connected.
+                if (gen !== this.generation) {
+                    this.abort(socket);
+                    resolve(false);
+                    return;
+                }
+                if (this.pendingSocket === socket)
+                    this.pendingSocket = null;
+                if (!connected) {
+                    this.abort(socket);
+                    resolve(false);
+                    return;
+                }
+                this.socket = socket;
+                this.state = 'connected';
+                this.attachMessageHandler(socket);
+                resolve(true);
+            };
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            socket.onopen = () => {
+                try {
+                    socket.send(JSON.stringify({
+                        method: HELLO_METHOD,
+                        params: { token: target.token, protocolVersion: IDE_PROTOCOL_VERSION },
+                    }));
+                    helloSent = true;
+                }
+                catch {
+                    finish(false);
+                }
+            };
+            socket.onmessage = event => {
+                if (!helloSent || settled)
+                    return;
+                let parsed;
+                try {
+                    parsed = JSON.parse(String(event.data));
+                }
+                catch {
+                    finish(false);
+                    return;
+                }
+                const ack = parseHelloAck(parsed);
+                // Both ends ship together: a first frame that is not a valid v2 ack
+                // (wrong version, wrong method, garbage) fails this candidate.
+                if (ack === undefined) {
+                    finish(false);
+                    return;
+                }
+                this.ackedWorkspaceFolders = ack.workspaceFolders;
+                finish(true);
+            };
+            socket.onerror = () => finish(false);
+            socket.onclose = () => finish(false);
+        });
+    }
+    attachMessageHandler(socket) {
+        socket.onmessage = event => {
+            let parsed;
+            try {
+                parsed = JSON.parse(String(event.data));
+            }
+            catch {
+                return;
+            }
+            const snapshot = parseSelectionChanged(parsed);
+            if (snapshot === undefined)
+                return;
+            this.current = snapshot.isEmpty ? undefined : snapshot;
+            for (const listener of [...this.listeners])
+                listener(snapshot);
+        };
+        socket.onclose = () => this.degradeToDisconnected(socket);
+        socket.onerror = () => this.degradeToDisconnected(socket);
+    }
+    degradeToDisconnected(socket) {
+        if (this.socket !== socket)
+            return;
+        this.socket = null;
+        this.detach(socket);
+        this.state = 'disconnected';
+        this.ackedWorkspaceFolders = undefined;
+        // A dead connection's selection is stale: clear the cached snapshot and
+        // tell subscribers — the badge and submit auto-attach must not keep
+        // using whatever was selected before the disconnect.
+        const stale = this.current;
+        this.current = undefined;
+        if (stale !== undefined) {
+            for (const listener of [...this.listeners])
+                listener({ ...stale, isEmpty: true });
+        }
+    }
+}