dsh-plugin-tool-management 0.10.0 → 0.12.0

package/lib/sessions/history.js

@@ -0,0 +1,323 @@
+// 归档会话域（原 index.ts apply() 闭包内六段，2026-09-19 抽出）。
+//
+// 这一域管的是「归档会话的外围」：侧车账本的落点与搬迁、保留期设置、到期清扫、
+// 批量操作目标的校验、归档列表的分组视图。会话本身的归档 / 恢复 / 删除走宿主
+// 注册表（./workspace.ts 的 ArchiveWorkspaceRegistry），这里只做围绕它的记账与投影。
+//
+// 为什么抽出来：这些内容此前散在 apply() 闭包的六个不相邻段落里（1041 / 1093 /
+// 1152 / 1172 / 1683 / 1711），彼此靠闭包隐式共享 `sessions` 实例与侧车路径。抽成
+// 工厂后私有状态（实例、目录存在性缓存）收在内部，只经返回对象的七个出口暴露；
+// 对外依赖（config / pluginRoot / message / ctx）改为显式入参。
+//
+// 一处必须守住的语义：侧车三件套放 hub 根（`$DSH_HOME/tool-management/`）而**不是**
+// 插件目录 —— npm 安装下 `dsh plugin update` 会整体替换插件目录，账本一丢，保留期
+// 基线就从 archivedAt 退回 createdAt，归档会话会被提前清掉。旧位置启动时一次性搬入。
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { hubPath, hubRoot, relocateEntries } from '../hub.js';
+import { ArchiveWorkspaceRegistry as SessionsService, workspaceBaseName, workspacePathKey } from './workspace.js';
+/**
+ * 建归档会话域。副作用（构造注册表实例、首次清扫、挂周期定时器）都在工厂内完成 ——
+ * 它们原本就写在 apply() 的同一位置，语义是「这个服务自己的启动逻辑」，不是组装层的接线。
+ */
+export function createHistoryDomain(deps) {
+    const { ctx, config, pluginRoot, message } = deps;
+    // ---------- independent history facade ----------
+    // Keep the active workspaceRegistry/sessionProjectionCache instances intact.
+    // Native archive extensions are delegated by capability, not package name.
+    // Official gaps use a checked adapter (sessions/bridge.ts); no service or
+    // storage-domain replacement. Retention uses the existing sidecar ledger.
+    // 历史侧车三件套（归档时刻账本 / 保留期设置 / 工作区登记快照）统一放 hub 根
+    // （`$DSH_HOME/tool-management/`），**不放插件目录**：npm 安装下插件目录会被
+    // `dsh plugin update` 整体替换，放那里等于"升级即丢账本"——账本一丢，保留期基线
+    // 就从 archivedAt 退回 createdAt，归档会话会被提前清掉（v0.4 把提示词预设
+    // 搬进 hub 是同一条理由，见上方注释；这三个是当时漏掉的）。
+    // 旧位置（插件目录 data/）在启动时一次性搬入：只搬不删、绝不覆盖、失败下次再试。
+    const historyArchivedAtFile = String(config?.archivedAtFile || hubPath('history-archived-at.json'));
+    const historyWorkspaceSnapshotFile = String(config?.workspaceSnapshotFile || hubPath('history-workspaces.json'));
+    const historyRetentionPath = String(config?.historyRetentionPath || hubPath('history-retention.json'));
+    const historySidecarFiles = new Set(['history-archived-at.json', 'history-retention.json', 'history-workspaces.json']);
+    const historyStandby = relocateEntries(join(pluginRoot, 'data'), hubRoot(), (name) => historySidecarFiles.has(name))
+        .catch(() => 0);
+    const sweepIntervalMs = Number(config?.sweepIntervalMs || 0) || 6 * 60 * 60 * 1000;
+    let sessions;
+    ctx.effect(() => {
+        const registry = ctx.get('workspaceRegistry');
+        if (registry && typeof registry.archiveSession === 'function') {
+            sessions = new SessionsService(ctx, registry, {
+                archivedAtFile: historyArchivedAtFile,
+                workspaceSnapshotFile: historyWorkspaceSnapshotFile,
+                ready: historyStandby,
+            });
+        }
+        return async () => { const current = sessions; sessions = undefined; await current?.dispose(); };
+    }, 'dsh-plugin-tool-management: independent history');
+    function getSessionsRegistry() {
+        return sessions;
+    }
+    /**
+     * 恢复归档后的**归属恢复**（best-effort，绝不阻断恢复本身）：按会话 cwd 找到或重建
+     * 工作区登记，并把会话挂回该登记的 `sessionIds`。恢复成功但归属恢复失败时返回 undefined，
+     * 由客户端按"会话已恢复、工作区归属未恢复"如实呈现。
+     */
+    async function restoreWorkspaceAccounting(sessionIds) {
+        const registry = getSessionsRegistry();
+        if (!registry || typeof registry.ensureWorkspaceAccounting !== 'function' || !sessionIds.length)
+            return undefined;
+        try {
+            return await registry.ensureWorkspaceAccounting(sessionIds);
+        }
+        catch (e) {
+            ctx.logger?.warn?.(`history: workspace accounting after restore failed: ${message(e)}`);
+            return undefined;
+        }
+    }
+    async function readHistoryRetention() {
+        try {
+            await historyStandby;
+            const raw = await readFile(historyRetentionPath, 'utf8');
+            const obj = JSON.parse(raw);
+            const days = Number((obj && obj.retentionDays) ?? 0);
+            const updatedAt = Number((obj && obj.updatedAt) ?? 0);
+            return {
+                retentionDays: Number.isFinite(days) && days >= 0 ? days : 0,
+                updatedAt: Number.isFinite(updatedAt) && updatedAt > 0 ? updatedAt : 0,
+            };
+        }
+        catch {
+            return { retentionDays: 0, updatedAt: 0 };
+        }
+    }
+    async function writeHistoryRetention(retentionDays) {
+        await historyStandby;
+        const dir = dirname(historyRetentionPath);
+        await mkdir(dir, { recursive: true });
+        // updatedAt = 修改时刻：每次改保留期，已归档会话的到期基线重置为此时刻。
+        await writeFile(historyRetentionPath, JSON.stringify({ retentionDays, updatedAt: Date.now() }), 'utf8');
+    }
+    /**
+     * 计算到期应删的归档会话。基线 = max(archivedAt（账本）?? createdAt（元数据),
+     * updatedAt（最近一次修改保留期的时刻）)。改保留期即重置倒计时：到期时刻从
+     * 修改时刻起按新天数重新计算；updatedAt 缺失（旧配置）时退回归档时刻语义。
+     * retentionDays <= 0 表示永久不删除，返回空集。纯函数：便于测试。
+     */
+    /** 一天的毫秒数（保留期按"天"配置，比较按毫秒）。 */
+    const MS_PER_DAY = 24 * 60 * 60 * 1000;
+    function expiredArchivedIds(items, retentionDays, now, updatedAt = 0) {
+        if (!(retentionDays > 0))
+            return [];
+        const cutoff = now - retentionDays * MS_PER_DAY;
+        const out = [];
+        for (const it of items) {
+            const archived = (typeof it.archivedAt === 'number' && Number.isFinite(it.archivedAt))
+                ? it.archivedAt
+                : (typeof it.createdAt === 'number' && Number.isFinite(it.createdAt) ? it.createdAt : undefined);
+            if (archived === undefined)
+                continue;
+            const baseline = updatedAt > 0 ? Math.max(archived, updatedAt) : archived;
+            if (baseline <= cutoff)
+                out.push(it.sessionId);
+        }
+        return out;
+    }
+    async function sweepHistory() {
+        const registry = getSessionsRegistry();
+        if (!registry)
+            return { swept: [] };
+        const { retentionDays, updatedAt } = await readHistoryRetention();
+        if (!(retentionDays > 0))
+            return { swept: [] };
+        try {
+            const details = (typeof registry.archivedSessionDetails === 'function')
+                ? (await registry.archivedSessionDetails()).items
+                : (await registry.archivedSessionMetadata()).items.map((i) => ({ sessionId: i.sessionId, createdAt: i.createdAt, archivedAt: registry.archivedAt?.(i.sessionId) }));
+            const expired = expiredArchivedIds(details, retentionDays, Date.now(), updatedAt);
+            if (expired.length === 0)
+                return { swept: [] };
+            const res = await registry.deleteArchivedSessions({ scope: 'sessions', sessionIds: expired });
+            return { swept: res.deletedSessionIds || [] };
+        }
+        catch (e) {
+            console.error('[dsh-plugin-tool-management] history sweep failed:', message(e));
+            return { swept: [] };
+        }
+    }
+    // 启动时扫一次，再周期复跑。fake-ctx 测试里 ctx.effect 立即调用并 dispose，
+    // interval 未提供时退化为不挂钟（不阻塞测试）。
+    try {
+        void sweepHistory();
+    }
+    catch { /* 非致命 */ }
+    try {
+        ctx.effect(() => {
+            const timer = ctx;
+            const fn = typeof timer.interval === 'function' ? timer.interval : (typeof timer.setInterval === 'function' ? timer.setInterval : undefined);
+            if (!fn)
+                return () => { };
+            return fn(() => { void sweepHistory(); }, sweepIntervalMs);
+        }, 'dsh-plugin-tool-management: history sweep');
+    }
+    catch { /* timer 缺失时静默 */ }
+    // 批量操作目标校验：scope 白名单；sessions 需非空 sessionIds；workspace 需
+    // workspaceId。与 ArchiveWorkspaceRegistry.archivedBatchTargetSchema 语义一致。
+    function parseHistoryBatchTarget(raw) {
+        const t = raw && typeof raw === 'object' ? raw : null;
+        if (!t)
+            return { ok: false, error: '缺少 target' };
+        const scope = t.scope;
+        if (scope !== 'all' && scope !== 'ungrouped' && scope !== 'sessions' && scope !== 'workspace') {
+            return { ok: false, error: 'target.scope 不合法' };
+        }
+        if (scope === 'sessions') {
+            if (!Array.isArray(t.sessionIds) || t.sessionIds.length === 0 ||
+                t.sessionIds.some((id) => typeof id !== 'string' || !String(id).trim())) {
+                return { ok: false, error: 'scope=sessions 需要非空的 sessionIds 数组' };
+            }
+        }
+        if (scope === 'workspace' && !(typeof t.workspaceId === 'string' && String(t.workspaceId).trim())) {
+            return { ok: false, error: 'scope=workspace 需要 workspaceId' };
+        }
+        return {
+            ok: true,
+            target: {
+                scope,
+                ...(scope === 'sessions' ? { sessionIds: t.sessionIds.map((s) => String(s).trim()) } : {}),
+                ...(scope === 'workspace' ? { workspaceId: String(t.workspaceId).trim() } : {}),
+            },
+        };
+    }
+    /**
+     * 归档会话的归属解析（三级，宿主侧算好再给客户端）：
+     *   1. 活登记的 sessionIds 命中            → 组 = 该登记；
+     *   2. 未命中但规范路径命中某活登记        → 组 = 该登记（会话不在其记账里，属正常）；
+     *   3. 没有任何活登记                      → 按会话目录重建分组（`path:<归一化路径>`），
+     *      目录仍在则可一键重新登记（写回宿主），目录已不在则退到 header 里的原始 cwd。
+     * 宿主删除工作区是硬删、不留墓碑，登记一没，`workspaceId` 就再也查不到；但会话目录
+     * （`registry.sessionPaths` / header.cwd）还在，所以归属可以按目录重建、并在目录回来时
+     * 自动并回同一组。除插件自己 `data/` 下的「见过的登记」快照外，本函数不写任何宿主状态。
+     * 任何一步失败都降级为「不分组」，绝不阻断列表。
+     */
+    async function buildHistoryGroups(registry, items) {
+        const groups = [];
+        const workspaces = {};
+        try {
+            const groupsById = new Map();
+            const liveByPath = new Map();
+            const owned = new Map();
+            const liveRecords = [];
+            const table = typeof registry.requireTable === 'function' ? registry.requireTable() : undefined;
+            const state = typeof registry.requireState === 'function' ? registry.requireState() : undefined;
+            if (table) {
+                const ids = state && Array.isArray(state.workspaceIds) && state.workspaceIds.length
+                    ? state.workspaceIds
+                    : [...table.entries()].map(([id]) => id);
+                for (const wid of ids) {
+                    const rec = table.get(wid);
+                    if (!rec || !Array.isArray(rec.sessionIds))
+                        continue;
+                    const path = typeof rec.path === 'string' && rec.path ? rec.path : undefined;
+                    const title = (rec.title && String(rec.title)) || (path ? workspaceBaseName(path) : String(wid));
+                    for (const sid of rec.sessionIds)
+                        if (!owned.has(sid))
+                            owned.set(sid, wid);
+                    if (path) {
+                        liveByPath.set(workspacePathKey(path), wid);
+                        liveRecords.push({ id: String(wid), path, title });
+                    }
+                    const view = { id: 'ws:' + wid, title, kind: 'live', registered: true, ...(path ? { path } : {}) };
+                    groupsById.set(view.id, view);
+                    groups.push(view);
+                    workspaces[wid] = { title, ...(path ? { path } : {}) };
+                }
+            }
+            // 「见过的登记」快照：登记被删后仍能给出原命名，并区分「已移除」与「从未登记」。
+            const snapshot = typeof registry.workspaceSnapshot === 'function' ? await registry.workspaceSnapshot() : undefined;
+            if (liveRecords.length && typeof registry.rememberWorkspaces === 'function') {
+                try {
+                    await registry.rememberWorkspaces(liveRecords);
+                }
+                catch { /* 快照写失败不影响分组 */ }
+            }
+            const sessionPaths = registry.sessionPaths instanceof Map ? registry.sessionPaths : undefined;
+            const headers = registry.headers instanceof Map ? registry.headers : undefined;
+            // 「目录真实存在」检查缓存：canRegister 从「宿主 sessionPaths 命中」放宽为
+            // 「目录存在」时，同一目录只 stat 一次；结果按归一化键缓存，避免每次刷新重复探盘。
+            const dirExistsCache = new Map();
+            async function directoryExists(p) {
+                const k = workspacePathKey(p);
+                const hit = dirExistsCache.get(k);
+                if (hit !== undefined)
+                    return hit;
+                let ok = false;
+                try {
+                    ok = (await stat(p)).isDirectory();
+                }
+                catch {
+                    ok = false;
+                }
+                dirExistsCache.set(k, ok);
+                return ok;
+            }
+            for (const it of items) {
+                const sid = it.sessionId;
+                let wid = owned.get(sid);
+                const canonical = sessionPaths ? sessionPaths.get(sid) : undefined;
+                if (wid === undefined && typeof canonical === 'string' && canonical) {
+                    const byPath = liveByPath.get(workspacePathKey(canonical));
+                    if (byPath !== undefined)
+                        wid = byPath;
+                }
+                if (wid !== undefined) {
+                    it.workspaceId = wid;
+                    it.groupId = 'ws:' + wid;
+                    continue;
+                }
+                let path = typeof canonical === 'string' && canonical ? canonical : undefined;
+                if (path === undefined && it.cwd)
+                    path = it.cwd;
+                if (path === undefined && headers) {
+                    const cwd = headers.get(sid)?.cwd;
+                    if (typeof cwd === 'string' && cwd)
+                        path = cwd;
+                }
+                if (!path)
+                    continue;
+                const key = 'path:' + workspacePathKey(path);
+                it.groupId = key;
+                const known = snapshot ? snapshot.get(workspacePathKey(path)) : undefined;
+                const existing = groupsById.get(key);
+                if (existing) {
+                    // 同目录的多个会话：宿主索引命中，或磁盘目录真实存在，即可重新登记。
+                    if (canonical !== undefined || (await directoryExists(path))) {
+                        existing.canRegister = true;
+                        existing.dirMissing = false;
+                    }
+                    continue;
+                }
+                const canRegister = canonical !== undefined || (await directoryExists(path));
+                const view = {
+                    id: key,
+                    title: known?.title || workspaceBaseName(path) || path,
+                    kind: 'detached',
+                    registered: known !== undefined,
+                    canRegister,
+                    dirMissing: !canRegister,
+                    path: known?.path || path,
+                };
+                groupsById.set(key, view);
+                groups.push(view);
+            }
+        }
+        catch { /* 分组是增强：任何异常都退回扁平列表 */ }
+        return { groups, workspaces };
+    }
+    return {
+        getSessionsRegistry,
+        restoreWorkspaceAccounting,
+        readHistoryRetention,
+        writeHistoryRetention,
+        sweepHistory,
+        parseHistoryBatchTarget,
+        buildHistoryGroups,
+    };
+}

package/lib/{history → sessions}/tombstone.js

@@ -1,7 +1,7 @@
 //#region lib/types/tombstone.js
 /**
  * 通用墓碑簿记：登记一个已删除 id，并按 FIFO 在上限处淘汰最旧项。
- * 工作区注册表（lib/history/workspace.js）在用；淘汰策略集中在这里，避免各处拷贝分叉。
+ * 工作区注册表（lib/sessions/workspace.js）在用；淘汰策略集中在这里，避免各处拷贝分叉。
  */
 /**
  * 登记已删除 id 并执行上限淘汰。