dsh-session-curator 0.1.1 → 0.2.0

package/lib/host/fs-utils.js

@@ -0,0 +1,105 @@
+/** 文件系统小工具 + 错误消息归一化。 */
+import { promises as fsp } from "node:fs";
+import { dirname, join } from "node:path";
+/** 任何抛出物 → 一句人话（宿主 logger 与端点错误信封都用它）。 */
+export function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/**
+ * 最多 `limit` 个任务同时在跑；返回值**按入参顺序**排列。
+ *
+ * 为什么不用 `Promise.all(items.map(...))`：快照要一次给上百个目录做 `readdir` + `stat`，
+ * 无上限并发会把磁盘打成一锅粥（Windows 上尤其明显，还会跟 DSH 自己的会话扫描抢 IO）。
+ * 这里只做"有上限的并发"，超出的任务排队，单项抛错照原样往外冒（由调用方决定怎么办）。
+ */
+export async function mapLimit(items, limit, worker) {
+    const size = items.length;
+    const results = new Array(size);
+    if (size === 0)
+        return results;
+    const width = Math.max(1, Math.min(Math.floor(limit) || 1, size));
+    let next = 0;
+    const run = async () => {
+        while (next < size) {
+            const index = next;
+            next += 1;
+            results[index] = await worker(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: width }, run));
+    return results;
+}
+/** 跨卷 rename 会抛 EXDEV，退回 copy + rm。 */
+export async function moveDir(from, to) {
+    await fsp.mkdir(dirname(to), { recursive: true });
+    try {
+        await fsp.rename(from, to);
+        return;
+    }
+    catch (error) {
+        if (error?.code !== "EXDEV")
+            throw error;
+    }
+    await fsp.cp(from, to, { recursive: true, force: true });
+    await fsp.rm(from, { recursive: true, force: true });
+}
+const DIR_STATS_CACHE = new Map();
+/** 缓存上限：超过就整个清掉。磁盘目录数远小于它，这里只是防止长期运行无限增长。 */
+const DIR_STATS_CACHE_LIMIT = 2000;
+/** 给自检用：清掉缓存后重新统计（`scripts/smoke.mjs` 要断言"同一次快照内命中缓存"）。 */
+export function forgetDirStats() {
+    DIR_STATS_CACHE.clear();
+}
+/** 只统计顶层文件：会话目录里就是那几份日志。目录 mtime 没变就直接回缓存。 */
+export async function dirStats(dir) {
+    let mtimeMs;
+    let entries;
+    try {
+        const info = await fsp.stat(dir);
+        mtimeMs = info.mtimeMs;
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return { bytes: 0, files: 0 };
+    }
+    const cached = DIR_STATS_CACHE.get(dir);
+    if (cached !== undefined && cached.mtimeMs === mtimeMs && cached.entryCount === entries.length) {
+        return { bytes: cached.bytes, files: cached.files };
+    }
+    let bytes = 0;
+    let files = 0;
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        try {
+            const stat = await fsp.stat(join(dir, entry.name));
+            bytes += stat.size;
+            files += 1;
+        }
+        catch {
+            // 竞态：文件刚好消失，忽略
+        }
+    }
+    if (DIR_STATS_CACHE.size >= DIR_STATS_CACHE_LIMIT)
+        DIR_STATS_CACHE.clear();
+    DIR_STATS_CACHE.set(dir, { mtimeMs, entryCount: entries.length, bytes, files });
+    return { bytes, files };
+}
+export async function readProjectionFile(file) {
+    try {
+        const parsed = JSON.parse(await fsp.readFile(file, "utf8"));
+        const rows = parsed?.record?.rows;
+        const identity = parsed?.record?.identity;
+        const title = rows?.title?.val;
+        return {
+            title: typeof title === "string" && title !== "" ? title : null,
+            cwd: typeof identity?.cwd === "string" ? identity.cwd : null,
+            createdAt: typeof identity?.createdAt === "number" ? identity.createdAt : null
+        };
+    }
+    catch {
+        return { title: null, cwd: null, createdAt: null };
+    }
+}

package/lib/host/manifest.js

@@ -0,0 +1,22 @@
+/**
+ * 版本号与插件名：都从**自己的 manifest** 读。
+ *
+ * 路径按编译后的位置算：本文件编译成 `lib/host/manifest.js`，所以包根是它的上两级
+ * （无论插件是装在 `node_modules` 里还是被 junction 指过来，`import.meta.url` 都指向
+ * 真实文件）。名字用字面量而不是读 manifest：DSH 拿它当插件 id，一旦 manifest 读失败
+ * 也必须还是对的；版本号读不到就回 `null`（界面上显示成 "—"），不影响加载。
+ */
+import { readFileSync } from "node:fs";
+/** 插件名 == DSH 的插件 id == npm 包名。 */
+export const PLUGIN_NAME = "dsh-session-curator";
+function readLocalVersion() {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+        return typeof manifest?.version === "string" && manifest.version !== "" ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 本地版本（`package.json` 的 `version`）。 */
+export const LOCAL_VERSION = readLocalVersion();

package/lib/host/open.js

@@ -0,0 +1,104 @@
+/**
+ * 「复制路径 / 在资源管理器中显示」的宿主侧：**只认自己算出来的目录**。
+ *
+ * 安全边界（这一段是这个文件存在的全部理由）：
+ *   - 路径**不接受客户端传**：只吃 `sessionId`，由宿主自己按 `<DSH_HOME>/sessions/<slug>/<id>`
+ *     或回收站目录拼出来。客户端就算传了别的路径也没用 —— 入参里根本没有路径字段。
+ *   - 拼出来之后再 `resolve()` 一次并断言它落在**允许的两个根**（`<DSH_HOME>/sessions`、
+ *     回收站根）之下。这一道是为了挡住 `../` 之类的 id（线协议的 `idsOf()` 只保证是
+ *     非空字符串，不保证它不是一个相对路径）。
+ *   - 只有 `target: "reveal"` 才会真的去叫系统文件管理器，而且只用**固定的可执行名**
+ *     （`explorer.exe` / `open` / `xdg-open`），参数是那个已经校验过的目录。不拼 shell 字符串，
+ *     走 `spawn` + 参数数组，所以路径里的空格 / 引号 / `&` 都不会被解释成命令。
+ *
+ * 为什么不用 `shell.openPath`（Electron 的 API）：宿主半区跑在 DSH 的 Electron 主进程里，
+ * 但插件是普通 ESM 模块，拿不到 `electron` 模块（那是 DSH 自己的依赖，junction 挂载下
+ * Node 按 realpath 解析根本找不到 —— 与 AGENTS.md §5 禁止裸导入 `@deepseek-ai/*` 同一条
+ * 理由）。所以这里退到"用平台自带的文件管理器命令"，零依赖。
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { messageOf } from "./fs-utils.js";
+import { sessionsRoot, trashRoot } from "./paths.js";
+/** `path` / `reveal`：`reveal` 之外的任何值都当成 `path`（只读，最保守的那条）。 */
+export function openTargetOf(value) {
+    return value === "reveal" ? "reveal" : "path";
+}
+/**
+ * 两个允许的根：会话目录与回收站。`resolve()` 之后比较，且要求"相等或以 `<root>+分隔符`
+ * 开头" —— 单比 `startsWith(root)` 会把 `<DSH_HOME>/sessions-evil` 放进来。
+ */
+function allowedRoots() {
+    return [resolve(sessionsRoot()), resolve(trashRoot())];
+}
+function inside(root, target) {
+    return target === root || target.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+/** 平台对应的文件管理器命令；不支持的平台返回 null（`path` 仍然可用）。 */
+function revealCommand() {
+    if (process.platform === "win32")
+        return { command: "explorer.exe", args: [] };
+    if (process.platform === "darwin")
+        return { command: "open", args: [] };
+    if (process.platform === "linux")
+        return { command: "xdg-open", args: [] };
+    return null;
+}
+/**
+ * 把文件管理器叫起来。**不等它退出**：`explorer.exe` 会立刻返回、`xdg-open` 可能一直活着，
+ * 等它就会把端点请求挂住。所以 `detached` + `stdio: "ignore"` + `unref()`，
+ * 只监听 `error`（命令不存在那种）；真正"有没有打开"由用户自己看得到。
+ */
+function reveal(path) {
+    const command = revealCommand();
+    if (command === null)
+        return { ok: false, reason: `不支持的平台：${process.platform}` };
+    try {
+        const child = spawn(command.command, [...command.args, path], { detached: true, stdio: "ignore" });
+        child.on("error", () => {
+            // 没有文件管理器（无头环境）不该让请求失败：路径已经回了，界面提示用户手动打开。
+        });
+        child.unref();
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, reason: messageOf(error) };
+    }
+}
+/**
+ * `open` 端点：算路径 → 校验 → （可选）叫文件管理器。
+ *
+ * `sessionId` 必须能在磁盘或回收站里找到；找不到就抛错，由信封兜住（与 `describe` 一致）。
+ */
+export async function openSession(host, ids, target) {
+    const sessionId = ids[0];
+    if (typeof sessionId !== "string" || sessionId === "")
+        throw new Error("缺少会话 id");
+    // 磁盘优先，其次回收站：同一个 id 不可能同时在两处（删除时目录被搬走了）。
+    const dirs = await host.scanSessionDirs();
+    let path = dirs.get(sessionId)?.dir ?? null;
+    if (path === null) {
+        const inTrash = resolve(trashRoot(), sessionId);
+        if (existsSync(inTrash))
+            path = inTrash;
+    }
+    if (path === null)
+        throw new Error("找不到这个会话的日志目录（磁盘和回收站里都没有）");
+    const resolved = resolve(path);
+    const roots = allowedRoots();
+    if (!roots.some((root) => inside(root, resolved))) {
+        // 到不了这里才说明 id 里有 `../` 之类的东西 —— 直接拒绝，别去碰根目录外面的路径。
+        throw new Error("拒绝打开：这个路径不在 DSH 的会话目录里");
+    }
+    if (!existsSync(resolved))
+        throw new Error("日志目录已经不在了");
+    if (target !== "reveal")
+        return { sessionId, path: resolved, revealed: false };
+    const opened = reveal(resolved);
+    return opened.ok
+        ? { sessionId, path: resolved, revealed: true }
+        : { sessionId, path: resolved, revealed: false, reason: opened.reason };
+}
+/** 允许的根（导出给自检断言"路径校验真的挡得住 `../`"）。 */
+export { allowedRoots, inside as insideRoot };

package/lib/host/paths.js

@@ -0,0 +1,47 @@
+/**
+ * DSH home 解析与插件用到的全部路径。
+ *
+ * 这里刻意**不 import** `@deepseek-ai/dsh-home-paths`：那个包只在 DSH 自己的
+ * node_modules 里，而插件可能以 junction/symlink 形式挂在 profile 下 —— 此时 Node 会
+ * 按 realpath 解析裸标识符，从插件源码目录向上找不到它，插件就加载不了。语义与那个包
+ * 一致（`$DSH_HOME` 优先，否则 `~/.dsh`），几行就够，换来的是"插件放哪都能跑"。
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export function resolveDshHome() {
+    const configured = process.env.DSH_HOME;
+    if (typeof configured === "string" && configured.trim() !== "") {
+        const expanded = configured.trim();
+        if (expanded === "~")
+            return homedir();
+        if (expanded.startsWith("~/") || expanded.startsWith("~\\"))
+            return resolve(join(homedir(), expanded.slice(2)));
+        return resolve(expanded);
+    }
+    return resolve(join(homedir(), ".dsh"));
+}
+/** 每次都重新解析：`smoke.mjs` 会在同一进程里换掉 `DSH_HOME` 来用临时 home。 */
+export function dshHomePath(...segments) {
+    return join(resolveDshHome(), ...segments);
+}
+/**
+ * 回收站根目录：`<DSH_HOME>/storages/session-manager/trash`。
+ *
+ * 这里的 `session-manager` 是**故意不改的旧名**：插件从 `dsh-session-manager` 改名成
+ * `dsh-session-curator` 时，回收站里可能还躺着用户已经删掉的会话（本机就有一个）——
+ * 改路径会把它们变成孤儿。数据目录用历史名、其余 id 用新名，是权衡后的结果。
+ */
+export const TRASH_SUBPATH = ["storages", "session-manager", "trash"];
+/** 回收站条目的元数据：原 slug / cwd / 标题 / 删除时间 / 删除前是否已归档。 */
+export const META_FILE = "__trash.json";
+/** 从投影缓存搬进来的那份文件（恢复时要搬回原位）。 */
+export const PROJ_FILE = "__projcache.json";
+export function trashRoot() {
+    return dshHomePath(...TRASH_SUBPATH);
+}
+export function sessionsRoot() {
+    return dshHomePath("sessions");
+}
+export function projCacheFile(sessionId) {
+    return dshHomePath("storages", "session_projcache", "sessions", `${sessionId}.json`);
+}

package/lib/host/retention.js

@@ -0,0 +1,24 @@
+/**
+ * 保留天数 → 截止时间戳：**严格早于**它的条目才算过期。
+ *
+ * 上限 3650 天（10 年）只是防呆：`days` 来自线协议，客户端算错、或有人手工构造请求时，
+ * 别让它退化成"把整个回收站清空"；`NaN` / 负数一律夹到 1 天（而不是 0：0 会让截止时间
+ * 变成"此刻"，语义上等于清空）。
+ */
+export function retentionCutoff(days) {
+    const safe = Number.isFinite(days) ? Math.min(Math.max(Math.floor(days), 1), 3650) : 1;
+    return Date.now() - safe * 24 * 60 * 60 * 1000;
+}
+/**
+ * 一条回收站条目该不该被"清理 N 天前"带走。
+ *
+ * 三个条件缺一不可：
+ *   - `restorable`：老版本留下的、没有 `__trash.json` 的条目连原 slug 都不知道，
+ *     `deletedAt` 也就无从谈起（`listTrash()` 会给它 0）。它们只能由用户在界面上
+ *     逐条「永久删除」，绝不能被一个按时间的批量操作顺手带走；
+ *   - `deletedAt > 0`：同上，缺删除时间的条目不参与时间判断；
+ *   - `deletedAt < cutoff`：**严格**早于截止时间，边界那一条留着。
+ */
+export function isExpired(row, cutoff) {
+    return row.restorable && row.deletedAt > 0 && row.deletedAt < cutoff;
+}

package/lib/host/routes.js

@@ -0,0 +1,134 @@
+/**
+ * 传输 / 分发：十一个端点 → 十一条精确 Fetch 路由。
+ *
+ * ── 为什么**不用** `ctx.connection.rpc.handle()`（踩过的坑，改回去之前先读）──
+ *
+ * 它内部把路由交给 `owner.effect(() => owner.webServer.register(route))`，而那个
+ * `owner` 是 `this.ctx` —— **Connection 服务自己的 ctx**，不是读服务的插件 ctx。
+ * cordis 的服务调用会带 shadow（`Context[symbols.shadow]` 指向提供者作用域），所以
+ * 服务解析从"提供者的 fiber"开始；Connection 自己的 inject 只有 `["credentials"]`，
+ * 于是必然抛：
+ *
+ *     cannot get property "webServer" without inject
+ *     （@deepseek-ai/dsh-client-connection/lib/index.js:656）
+ *
+ * 结果：插件 fiber 直接变 `failed`、一条路由都没挂上，客户端每个 POST 落到 SPA 静态
+ * 兜底，由 `@deepseek-ai/dsh-host-frontend-static` 对非 GET/HEAD 回 **HTTP 405** ——
+ * 就是 `transport failure for /session-manager/trash: HTTP 405`。
+ * 注意：**在插件自己的 inject 里加 `webServer` 修不了它**，因为报错的那个 ctx 不是插件的。
+ *
+ * 改走同样由 Connection 公布的 `ctx.connection.fetch.register()`：精确 Fetch 路由挂在
+ * 共享 `/api` 前缀下，`admit()`（Host/Origin/`sec-fetch-site` + 浏览器会话 cookie）与
+ * 请求体上限都仍由 Connection 的 `/api` 前缀路由先执行，插件依旧零鉴权代码。
+ */
+import { messageOf } from "./fs-utils.js";
+/** DSH 的共享 API 通道：唯一带 Host/Origin 信任栅栏与浏览器会话鉴权的 HTTP 面。 */
+export const API_CHANNEL = "/api";
+/** 频道下属于本插件的路径前缀（`/api/session-curator/<endpoint>`）。 */
+export const ROUTE_PREFIX = "session-curator";
+/** 端点只读 / 只写，一律 POST（Connection 的精确路由按方法集合匹配）。 */
+const ROUTE_METHODS = ["POST"];
+/** 一个频道（`/api/session-curator`）：精确路由表按完整 pathname 命中，所以每个端点一条。 */
+export const ENDPOINTS = {
+    snapshot: (manager) => manager.snapshot(),
+    describe: (manager, payload) => manager.describe(payload.ids ?? []),
+    archive: (manager, payload) => manager.archive(payload.ids ?? [], payload.stopActivity),
+    unarchive: (manager, payload) => manager.unarchive(payload.ids ?? []),
+    pin: (manager, payload) => manager.pin(payload.ids ?? []),
+    unpin: (manager, payload) => manager.unpin(payload.ids ?? []),
+    trash: (manager, payload) => manager.trash(payload.ids ?? []),
+    restore: (manager, payload) => manager.restore(payload.ids ?? []),
+    purge: (manager, payload) => manager.purge(payload.ids ?? []),
+    // 保留策略的两条都只吃 `days`（不是 id 列表）：预览只读，清理是永久删除。
+    "trash-stats": (manager, payload) => manager.trashStats(daysOf(payload)),
+    "purge-older-than": (manager, payload) => manager.purgeOlderThan(daysOf(payload)),
+    // 磁盘占用视图（只读）与"复制路径 / 在资源管理器中显示"。
+    usage: (manager) => manager.usage(),
+    // `target` 只认字面量 `"reveal"`；其余一律当 `"path"`（只读，最保守的那条）。
+    open: (manager, payload) => manager.open(payload.ids ?? [], payload.target === "reveal" ? "reveal" : "path"),
+    "check-update": (manager, payload) => manager.checkUpdate(payload.force === true)
+};
+/** 只接受字符串数组；其余一律忽略，避免把宿主路径当 id 传来的越权尝试。 */
+export function idsOf(payload) {
+    return Array.isArray(payload.ids) ? payload.ids.filter((value) => typeof value === "string" && value !== "") : [];
+}
+/**
+ * 保留天数：越界 / 非数字一律退回 **30 天**（界面的默认值）。
+ *
+ * 这里只做"是不是个正常数字"的粗校验，真正的夹取在 `retention.ts` 的
+ * `retentionCutoff()`（预览与真删共用那一份）。为什么退回 30 而不是 0：`0` 会让截止时间
+ * 变成"此刻"，等于把整个回收站当成过期 —— 缺字段的请求绝不能有这种后果。
+ */
+export function daysOf(payload) {
+    const value = payload.days;
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return 30;
+    return Math.min(Math.max(Math.floor(value), 1), 3650);
+}
+/**
+ * 一个端点处理器。返回 Connection 的固定信封：处理器自身的业务失败走
+ * `{ok:false, error}`，端点内部的逐项失败则留在 `value.results` 里。
+ */
+export async function handle(manager, endpoint, payload) {
+    const run = ENDPOINTS[endpoint];
+    if (run === undefined) {
+        return { ok: false, error: { code: "session-curator/unknown-endpoint", message: `unknown endpoint ${endpoint}`, details: {} } };
+    }
+    const safe = payload !== null && typeof payload === "object" ? payload : {};
+    // 越过线协议边界之后客户端发来的一切都不可信：这里如实标成 EndpointPayload，
+    // 具体字段仍由各处理器自己判（`idsOf()` 已经归一化过 ids）。
+    const normalized = { ...safe, ids: idsOf(safe) };
+    try {
+        return { ok: true, value: await run(manager, normalized) };
+    }
+    catch (error) {
+        return { ok: false, error: { code: "session-curator/error", message: messageOf(error), details: {} } };
+    }
+}
+/** `{type:'server-response', rpcId, result}` —— 与 Connection 自己回的信封逐字一致。 */
+function envelope(rpcId, result) {
+    return Response.json({ type: "server-response", rpcId, result });
+}
+function badRequest(rpcId, message) {
+    // 与 Connection 的 `invalidEnvelopeResponse` 一致：坏信封也回 200 + 错误信封，
+    // 这样客户端读到的是人话，而不是一个传输层异常。
+    return envelope(rpcId ?? "invalid-request", {
+        ok: false,
+        error: { code: "session-curator/bad-request", message, details: {} }
+    });
+}
+/** `/api` 已在前面做完信任与鉴权，这里只校验信封、分发、回包。 */
+export async function respond(manager, endpoint, request) {
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        return badRequest(null, "body is not JSON");
+    }
+    const message = body !== null && typeof body === "object" ? body : null;
+    const rpcId = typeof message?.rpcId === "string" ? message.rpcId : null;
+    if (rpcId === null || message?.type !== "client-request" || typeof message.method !== "string") {
+        return badRequest(rpcId, "invalid client-request message");
+    }
+    const target = `${ROUTE_PREFIX}/${endpoint}`;
+    if (message.method !== target) {
+        return badRequest(rpcId, `method ${JSON.stringify(message.method)} does not match endpoint ${JSON.stringify(target)}`);
+    }
+    return envelope(rpcId, await handle(manager, endpoint, message.payload));
+}
+/** 为每个端点挂一条精确路由；注册挂在**插件自己的 fiber** 上，卸载时一起摘掉。 */
+export function registerRoutes(ctx, manager) {
+    // 只知道"精确路由登记处"这一个面；命名避开全局 fetch。
+    const fetchRoutes = ctx.connection.fetch;
+    for (const endpoint of Object.keys(ENDPOINTS)) {
+        const route = {
+            path: `${API_CHANNEL}/${ROUTE_PREFIX}/${endpoint}`,
+            methods: ROUTE_METHODS,
+            requestBody: "buffered",
+            fetch: (request) => respond(manager, endpoint, request)
+        };
+        // `registerFetchRoute` 用的是调用方的 `owner.effect`，所以这里传的是插件的 ctx。
+        ctx.effect(() => fetchRoutes.register(route), `dsh-session-curator: ${route.path}`);
+    }
+}