@jingyi0605/codingns4dsh 0.1.0

package/data/build/dist/host/terminal/terminal-service.js

@@ -0,0 +1,528 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * 持久终端生命周期服务。
+ *
+ * store 决定“终端是什么”，runtime manager 决定“当前如何连上它”。插件停用时
+ * dispose 只释放后者；只有 close 会调用 backend.terminate。
+ */
+export class CodingNsTerminalService {
+    store;
+    runtimes;
+    now;
+    controllers = new Map();
+    followers = new Map();
+    operations = new Map();
+    exitCallbacks = new Map();
+    initialized = false;
+    constructor(store, runtimes, now = () => new Date()) {
+        this.store = store;
+        this.runtimes = runtimes;
+        this.now = now;
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.store.load();
+        this.initialized = true;
+    }
+    list(scope) {
+        this.requireInitialized();
+        return this.store.list(scope)
+            .filter((record) => record.state !== 'closed')
+            .map((record) => this.info(record));
+    }
+    /** 兼容旧调用名；真正的持久归属只按 Host + workspace 查询。 */
+    listSession(hostId, dshSessionId, workspaceId) {
+        this.requireInitialized();
+        if (workspaceId !== undefined)
+            return this.listWorkspace(hostId, workspaceId);
+        return this.store.list()
+            .filter((record) => record.hostId === hostId && record.dshSessionId === dshSessionId && record.state !== 'closed')
+            .map((record) => this.info(record));
+    }
+    listWorkspace(hostId, workspaceId) {
+        this.requireInitialized();
+        return this.store.list({ hostId, workspaceId })
+            .filter((record) => record.state !== 'closed')
+            .map((record) => this.info(record));
+    }
+    findIdentity(hostId, dshSessionId, terminalId, workspaceId) {
+        this.requireInitialized();
+        const matches = this.store.list().filter((record) => record.hostId === hostId
+            && (workspaceId === undefined ? record.dshSessionId === dshSessionId : record.workspaceId === workspaceId)
+            && record.terminalId === terminalId
+            && record.state !== 'closed');
+        if (matches.length !== 1)
+            throw new TerminalServiceError('TERMINAL_UNAVAILABLE', '终端不存在或作用域不唯一');
+        const record = matches[0];
+        return {
+            hostId: record.hostId,
+            workspaceId: record.workspaceId,
+            dshSessionId,
+            terminalId: record.terminalId,
+        };
+    }
+    async create(input) {
+        this.requireInitialized();
+        validateTerminalId(input.terminalId);
+        validateSize(input.cols, input.rows);
+        const identity = { ...input.scope, terminalId: input.terminalId };
+        return this.enqueue(identity, async () => {
+            const existing = this.store.get(identity);
+            if (existing !== undefined) {
+                if (existing.state === 'closed' || existing.state === 'closing') {
+                    throw new TerminalServiceError('TERMINAL_UNAVAILABLE', '终端已关闭，不能复用相同标识');
+                }
+                const runtime = await this.runtimes.inspect(existing);
+                if (runtime.alive) {
+                    const running = existing.state === 'running'
+                        ? existing
+                        : await this.update(existing, { state: 'running', error: '' });
+                    return this.info(running);
+                }
+                await this.update(existing, { state: 'lost', error: '持久终端运行时不存在' });
+                throw new TerminalServiceError('TERMINAL_RUNTIME_LOST', '持久终端运行时不存在');
+            }
+            const timestamp = this.now().toISOString();
+            const record = {
+                ...input.scope,
+                terminalId: input.terminalId,
+                runtimeSessionKey: randomUUID(),
+                runtimeType: input.runtimeType,
+                shellPath: input.shell.path,
+                shellProfileId: input.shell.profileId,
+                shellName: input.shell.name,
+                shellArgs: [...input.shell.args],
+                ...(input.commandPath === undefined ? {} : { commandPath: input.commandPath }),
+                ...(input.commandArgs === undefined ? {} : { commandArgs: [...input.commandArgs] }),
+                ...(input.commandEnv === undefined ? {} : { commandEnv: { ...input.commandEnv } }),
+                ...(input.launchProfileId === undefined ? {} : { launchProfileId: input.launchProfileId }),
+                cwd: input.cwd,
+                title: input.title?.trim() || input.shell.name,
+                cols: input.cols,
+                rows: input.rows,
+                state: 'starting',
+                exitCode: null,
+                createdAt: timestamp,
+                updatedAt: timestamp,
+            };
+            await this.store.put(record);
+            try {
+                const runtime = await this.runtimes.create(record);
+                if (!runtime.alive)
+                    throw new Error('backend 创建后未报告存活状态');
+                if (input.onExit !== undefined)
+                    this.exitCallbacks.set(identityKey(identity), input.onExit);
+                const running = await this.update(record, { state: 'running', error: '' });
+                if (input.onExit !== undefined)
+                    await this.runtimes.monitor(running, (exitCode) => { void this.markExited(identity, exitCode); });
+                return this.info(running);
+            }
+            catch (error) {
+                this.exitCallbacks.delete(identityKey(identity));
+                await this.update(record, { state: 'error', error: errorMessage(error) });
+                throw error;
+            }
+        });
+    }
+    /** 返回 Host 侧完整记录，供进程服务读取 runtimeSessionKey 和运行身份。 */
+    getRecord(identity) {
+        this.requireInitialized();
+        return this.store.get(identity);
+    }
+    async inspect(identity) {
+        const record = this.getRecord(identity);
+        if (record === undefined)
+            throw new TerminalServiceError('TERMINAL_UNAVAILABLE', '终端不存在');
+        return this.runtimes.inspect(record);
+    }
+    async recover() {
+        this.requireInitialized();
+        for (const record of this.store.list()) {
+            if (record.state === 'closed' || record.state === 'exited')
+                continue;
+            await this.enqueue(record, async () => {
+                const current = this.store.get(record);
+                if (current === undefined || current.state === 'closed')
+                    return;
+                if (current.state === 'closing') {
+                    await this.runtimes.terminate(current);
+                    await this.runtimes.detachTerminal(current);
+                    await this.update(current, { state: 'closed', exitCode: null, error: '' });
+                    return;
+                }
+                try {
+                    const identity = await this.runtimes.inspect(current);
+                    await this.update(current, identity.alive
+                        ? { state: 'running', error: '' }
+                        : { state: 'lost', error: identity.detail ?? '持久终端运行时不存在' });
+                }
+                catch (error) {
+                    await this.update(current, { state: 'error', error: errorMessage(error) });
+                }
+            });
+        }
+    }
+    async *retain(identity, signal) {
+        this.requireAvailable(identity);
+        signal.throwIfAborted();
+        yield { type: 'retained' };
+        await untilAborted(signal);
+    }
+    async *follow(input) {
+        const record = this.requireAvailable(input.identity);
+        const key = identityKey(input.identity);
+        const queue = new TerminalFrameQueue(2 * 1024 * 1024);
+        const follower = { attachmentId: input.attachmentId, generation: input.generation, queue };
+        this.addFollower(key, follower);
+        // 无论 backend attach 是否同步吐出恢复画面，wire 的第一帧都必须是 snapshot。
+        queue.pushSnapshot(this.info(record));
+        let attachment;
+        try {
+            attachment = await this.runtimes.attach(record, {
+                identity: input.identity,
+                generation: input.generation,
+                streamId: input.attachmentId,
+                requestedAttachmentId: input.attachmentId,
+                cols: record.cols,
+                rows: record.rows,
+                onData: (data) => queue.pushOutput(data),
+                onExit: (exitCode) => { void this.handleRuntimeExit(input.identity, exitCode, queue); },
+            });
+        }
+        catch (error) {
+            this.removeFollower(key, follower);
+            queue.finish();
+            throw error;
+        }
+        this.controllers.set(key, {
+            attachmentId: input.attachmentId,
+            subscriptionId: attachment.subscriptionId,
+            generation: input.generation,
+        });
+        this.broadcastState(input.identity);
+        const abort = () => queue.finish();
+        input.signal.addEventListener('abort', abort, { once: true });
+        if (input.signal.aborted)
+            abort();
+        try {
+            yield* queue.read();
+        }
+        finally {
+            input.signal.removeEventListener('abort', abort);
+            this.removeFollower(key, follower);
+            if (this.controllers.get(key)?.subscriptionId === attachment.subscriptionId) {
+                this.controllers.delete(key);
+                this.broadcastState(input.identity);
+            }
+            await this.runtimes.detach(attachment.subscriptionId);
+        }
+    }
+    async write(identity, attachmentId, data) {
+        const controller = this.requireController(identity, attachmentId);
+        await this.runtimes.write(controller.subscriptionId, data);
+    }
+    /** Host 内部向持久终端发送一次输入，不改变浏览器 attach 控制权。 */
+    async writeInitialInput(identity, data) {
+        if (data.length === 0)
+            throw new TypeError('终端输入不能为空');
+        this.requireInitialized();
+        await this.enqueue(identity, async () => {
+            const record = this.requireAvailable(identity);
+            await this.runtimes.writeSession(record, data);
+        });
+    }
+    async resize(identity, attachmentId, cols, rows) {
+        validateSize(cols, rows);
+        const controller = this.requireController(identity, attachmentId);
+        const record = this.requireAvailable(identity);
+        // ResizeObserver 可能重复报告同一尺寸；相同尺寸不应再次向 PTY 发送 SIGWINCH。
+        if (record.cols === cols && record.rows === rows)
+            return;
+        await this.runtimes.resize(controller.subscriptionId, cols, rows);
+        await this.update(record, { cols, rows });
+        this.broadcastState(identity);
+    }
+    async rename(identity, title) {
+        const normalized = title.trim();
+        if (normalized.length === 0 || normalized.length > 120)
+            throw new TypeError('终端标题必须包含 1 到 120 个字符');
+        const record = this.requireAvailable(identity);
+        await this.update(record, { title: normalized });
+        this.broadcastState(identity);
+    }
+    async close(identity) {
+        this.requireInitialized();
+        await this.enqueue(identity, async () => {
+            const record = this.store.get(identity);
+            if (record === undefined || record.state === 'closed')
+                return;
+            const closing = record.state === 'closing' ? record : await this.update(record, { state: 'closing' });
+            this.broadcastState(identity);
+            await this.runtimes.terminate(closing);
+            await this.runtimes.detachTerminal(identity);
+            this.controllers.delete(identityKey(identity));
+            this.exitCallbacks.delete(identityKey(identity));
+            const closed = await this.update(closing, { state: 'closed', exitCode: null, error: '' });
+            this.broadcastState(identity, closed);
+            this.finishFollowers(identityKey(identity));
+        });
+    }
+    async detachGeneration(generation) {
+        await this.runtimes.detachGeneration(generation);
+        const changed = new Set();
+        for (const [key, binding] of this.controllers) {
+            if (binding.generation !== generation)
+                continue;
+            this.controllers.delete(key);
+            changed.add(key);
+        }
+        for (const [key, followers] of this.followers) {
+            for (const follower of followers) {
+                if (follower.generation === generation)
+                    follower.queue.finish();
+            }
+            if ([...followers].some((follower) => follower.generation === generation))
+                changed.add(key);
+        }
+        for (const key of changed)
+            this.broadcastStateByKey(key);
+    }
+    /** 插件卸载只断开 attach，持久 backend 必须继续运行。 */
+    async dispose() {
+        for (const followers of this.followers.values())
+            for (const follower of followers)
+                follower.queue.finish();
+        this.followers.clear();
+        this.controllers.clear();
+        this.exitCallbacks.clear();
+        await this.runtimes.dispose();
+    }
+    requireController(identity, attachmentId) {
+        this.requireAvailable(identity);
+        const controller = this.controllers.get(identityKey(identity));
+        if (controller?.attachmentId !== attachmentId) {
+            throw new TerminalServiceError('TERMINAL_CONTROL_UNAVAILABLE', '当前 attach 没有终端输入控制权');
+        }
+        return controller;
+    }
+    requireAvailable(identity) {
+        this.requireInitialized();
+        const record = this.store.get(identity);
+        if (record === undefined || record.state !== 'running') {
+            throw new TerminalServiceError('TERMINAL_UNAVAILABLE', '终端不存在或当前不可用');
+        }
+        return record;
+    }
+    async refreshRuntimeState(identity) {
+        const record = this.store.get(identity);
+        if (record === undefined || record.state !== 'running')
+            return;
+        try {
+            const runtime = await this.runtimes.inspect(record);
+            if (!runtime.alive) {
+                const lost = await this.update(record, { state: 'lost', error: runtime.detail ?? '持久终端运行时不存在' });
+                this.broadcastState(identity, lost);
+            }
+        }
+        catch (error) {
+            const failed = await this.update(record, { state: 'error', error: errorMessage(error) });
+            this.broadcastState(identity, failed);
+        }
+    }
+    async handleRuntimeExit(identity, exitCode, queue) {
+        try {
+            await this.markExited(identity, exitCode);
+        }
+        finally {
+            // 先发 exited 元数据，再结束 Remote 流；否则官方 Client 会把正常退出误判为 attach 故障。
+            queue.finish();
+        }
+    }
+    async markExited(identity, exitCode) {
+        await this.enqueue(identity, async () => {
+            const record = this.store.get(identity);
+            if (record === undefined || record.state !== 'running')
+                return;
+            const exited = await this.update(record, { state: 'exited', exitCode, error: '' });
+            this.broadcastState(identity, exited);
+            const callback = this.exitCallbacks.get(identityKey(identity));
+            this.exitCallbacks.delete(identityKey(identity));
+            await callback?.(exitCode);
+        });
+    }
+    info(record) {
+        const controllerId = this.controllers.get(identityKey(record))?.attachmentId;
+        const state = record.state === 'running' || record.state === 'starting'
+            ? 'running'
+            : record.state === 'closed' || record.state === 'exited'
+                ? 'exited'
+                : 'failed';
+        return {
+            id: record.terminalId,
+            title: record.title,
+            shell: shellInfo(record),
+            cwd: record.cwd,
+            cols: record.cols,
+            rows: record.rows,
+            state,
+            exitCode: record.exitCode,
+            ...(record.error && record.state !== 'closed' ? { error: record.error } : {}),
+            ...(controllerId === undefined ? {} : { controllerId }),
+        };
+    }
+    async update(record, patch) {
+        const next = await this.store.patch(record, { ...patch, updatedAt: this.now().toISOString() });
+        if (next === undefined)
+            throw new Error('终端记录在更新期间消失');
+        return next;
+    }
+    broadcastState(identity, record = this.store.get(identity)) {
+        if (record === undefined)
+            return;
+        const info = this.info(record);
+        for (const follower of this.followers.get(identityKey(identity)) ?? [])
+            follower.queue.pushState(info);
+    }
+    broadcastStateByKey(key) {
+        const record = this.store.list().find((candidate) => identityKey(candidate) === key);
+        if (record !== undefined)
+            this.broadcastState(record, record);
+    }
+    addFollower(key, follower) {
+        let followers = this.followers.get(key);
+        if (followers === undefined) {
+            followers = new Set();
+            this.followers.set(key, followers);
+        }
+        followers.add(follower);
+    }
+    removeFollower(key, follower) {
+        const followers = this.followers.get(key);
+        followers?.delete(follower);
+        if (followers?.size === 0)
+            this.followers.delete(key);
+    }
+    finishFollowers(key) {
+        for (const follower of this.followers.get(key) ?? [])
+            follower.queue.finish();
+    }
+    enqueue(identity, operation) {
+        const key = identityKey(identity);
+        const previous = this.operations.get(key) ?? Promise.resolve();
+        const pending = previous.then(operation, operation);
+        const tail = pending.then(() => undefined, () => undefined);
+        this.operations.set(key, tail);
+        void tail.finally(() => {
+            if (this.operations.get(key) === tail)
+                this.operations.delete(key);
+        });
+        return pending;
+    }
+    requireInitialized() {
+        if (!this.initialized)
+            throw new Error('终端服务尚未初始化');
+    }
+}
+export class TerminalServiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TerminalServiceError';
+    }
+}
+class TerminalFrameQueue {
+    maxBytes;
+    frames = [];
+    bytes = 0;
+    sequence = 0;
+    wake;
+    ended = false;
+    failure;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+    }
+    pushSnapshot(info) {
+        this.push({ type: 'snapshot', sequence: this.sequence, screen: '', info });
+    }
+    pushOutput(data) {
+        this.sequence += 1;
+        this.push({ type: 'output', sequence: this.sequence, data });
+    }
+    pushState(info) {
+        this.push({ type: 'state', info });
+    }
+    finish() {
+        this.ended = true;
+        this.wake?.();
+    }
+    async *read() {
+        while (!this.ended || this.frames.length > 0) {
+            const frame = this.frames.shift();
+            if (frame !== undefined) {
+                this.bytes -= frameBytes(frame);
+                yield frame;
+                continue;
+            }
+            await new Promise((resolve) => { this.wake = resolve; });
+            this.wake = undefined;
+        }
+        if (this.failure !== undefined)
+            throw this.failure;
+    }
+    push(frame) {
+        if (this.ended)
+            return;
+        const bytes = frameBytes(frame);
+        if (this.bytes + bytes > this.maxBytes) {
+            this.failure = new Error('终端输出消费者超过缓冲上限，请重新连接以恢复当前屏幕');
+            this.frames.length = 0;
+            this.bytes = 0;
+            this.finish();
+            return;
+        }
+        this.frames.push(frame);
+        this.bytes += bytes;
+        this.wake?.();
+    }
+}
+function shellInfo(record) {
+    const profileId = record.shellProfileId ?? (record.runtimeType === 'tmux'
+        ? record.shellPath.endsWith('/bash') ? 'bash' : 'zsh'
+        : record.runtimeType === 'conpty-cmd'
+            ? 'cmd'
+            : record.runtimeType === 'conpty-git-bash'
+                ? 'git-bash'
+                : 'powershell');
+    return {
+        profileId,
+        path: record.shellPath,
+        args: record.shellArgs ?? (profileId === 'cmd' ? [] : profileId === 'powershell' ? ['-NoLogo'] : ['-i']),
+        name: record.shellName ?? profileId,
+    };
+}
+function identityKey(identity) {
+    return JSON.stringify([identity.hostId, identity.workspaceId, identity.terminalId]);
+}
+function validateTerminalId(id) {
+    if (!/^[\w-]{1,128}$/u.test(id))
+        throw new TypeError('终端标识无效');
+}
+function validateSize(cols, rows) {
+    if (!Number.isSafeInteger(cols) || cols < 2 || cols > 500 || !Number.isSafeInteger(rows) || rows < 1 || rows > 300) {
+        throw new TypeError('终端尺寸超过允许范围');
+    }
+}
+function frameBytes(frame) {
+    return new TextEncoder().encode(JSON.stringify(frame)).byteLength;
+}
+function untilAborted(signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => signal.addEventListener('abort', () => resolve(), { once: true }));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=terminal-service.js.map

package/data/build/dist/host/terminal/terminal-store.d.ts

@@ -0,0 +1,49 @@
+import type { PersistentTerminalRecord, TerminalOwnerScope, TerminalRecordIdentity } from '../../shared/contracts/terminal.js';
+declare const STORE_VERSION = 1;
+interface TerminalStoreDocument {
+    readonly version: typeof STORE_VERSION;
+    readonly records: readonly PersistentTerminalRecord[];
+}
+export interface TerminalStorePersistence {
+    load(): Promise<unknown>;
+    save(document: TerminalStoreDocument): Promise<void>;
+}
+/** JSON 文件写入采用同目录临时文件加 rename，避免崩溃留下半截记录。 */
+export declare class JsonFileTerminalStorePersistence implements TerminalStorePersistence {
+    private readonly filename;
+    constructor(filename: string);
+    load(): Promise<unknown>;
+    save(document: TerminalStoreDocument): Promise<void>;
+}
+/**
+ * 持久终端记录表。
+ *
+ * 所有修改在一条 promise 队列中执行；调用完成代表新状态已经落盘。这样 create、
+ * recover 与 close 不会用最后写入者覆盖彼此的结果。
+ */
+export declare class CodingNsTerminalStore {
+    private readonly persistence;
+    private readonly records;
+    private writeTail;
+    private loaded;
+    constructor(persistence: TerminalStorePersistence);
+    load(): Promise<void>;
+    list(scope?: TerminalOwnerScope): readonly PersistentTerminalRecord[];
+    get(identity: TerminalRecordIdentity): PersistentTerminalRecord | undefined;
+    put(record: PersistentTerminalRecord): Promise<void>;
+    patch(identity: TerminalRecordIdentity, patch: Partial<Pick<PersistentTerminalRecord, 'state' | 'title' | 'cols' | 'rows' | 'exitCode' | 'error' | 'updatedAt'>>): Promise<PersistentTerminalRecord | undefined>;
+    remove(identity: TerminalRecordIdentity): Promise<boolean>;
+    private enqueue;
+    private persist;
+    private requireLoaded;
+}
+export declare class InMemoryTerminalStorePersistence implements TerminalStorePersistence {
+    private document;
+    constructor(initial?: unknown);
+    load(): Promise<unknown>;
+    save(document: TerminalStoreDocument): Promise<void>;
+    snapshot(): unknown;
+}
+export declare function terminalStorePath(settingsDocumentPath: string): string;
+export {};
+//# sourceMappingURL=terminal-store.d.ts.map