dsh-session-cloud 0.1.1 → 0.1.3

package/lib/dsh-types.d.ts

@@ -20,6 +20,11 @@ export interface SessionLocationLike {
     readonly kind: string;
     readonly path: string;
 }
+/**
+ * 引擎/恢复消费的持久化端口。宿主可能是 v0（rc.1：listSnapshots/locate 齐备）
+ * 或 v1（0.1.3-alpha.1+：list() 返回快照、locate 私有化），由
+ * sync/persistence-port.ts 做运行时归一；本接口始终是 v0 形态。
+ */
 export interface SessionPersistenceLike {
     listSnapshots(signal?: AbortSignal): Promise<SessionSnapshotLike[]>;
     list(signal?: AbortSignal): Promise<SessionHeaderLike[]>;

package/lib/index.js

@@ -5,6 +5,7 @@ import { runConnectionCheck } from './status.js';
 import { SyncEngine } from './sync/engine.js';
 import { ProtocolError, SyncClient } from './sync/http-client.js';
 import { bootstrapKdf } from './sync/kdf.js';
+import { createPersistencePort } from './sync/persistence-port.js';
 import { countRemoteOnlySessions, decodeMappingDelete, decodeRestoreRequest, deleteMapping, encodeCatalog, encodeMappings, encodeRestoreResult, encodeStartupNotice, fetchCatalog, markRestoredSynced, restoreSessions, } from './sync/restore.js';
 import { DomainStateStore, JsonFileStateStore, cloudSyncDomainSpec } from './sync/state.js';
 export const name = 'cloud-sync';
@@ -146,6 +147,10 @@ export async function apply(ctx, config) {
     function selfDevice() {
         return current().deviceName || os.hostname();
     }
+    /** sessionPersistence 双版本端口（v0 透传 / v1 list+布局推导，见 persistence-port.ts）。 */
+    function persistencePort() {
+        return createPersistencePort(ctx.sessionPersistence, path.join(dshHome(ctx), 'sessions'));
+    }
     /** 本机工作区 canonical path 列表（workspaceRegistry 可选注入，缺失即无尾段建议）。 */
     function workspacePaths() {
         return ctx.get('workspaceRegistry')?.list().map((workspace) => workspace.path) ?? [];
@@ -160,7 +165,7 @@ export async function apply(ctx, config) {
         return {
             client,
             key,
-            persistence: ctx.sessionPersistence,
+            persistence: persistencePort(),
             state: stateStore,
             workspacePaths: workspacePaths(),
             // 恢复落位后的 workspace 挂载（web 侧边栏可见性）。复刻 dsh 自己创建会话的
@@ -275,7 +280,7 @@ export async function apply(ctx, config) {
             salt,
             device,
             state: stateStore,
-            persistence: ctx.sessionPersistence,
+            persistence: persistencePort(),
             getConfig: () => current(),
             onEvent: (event) => {
                 if (event.kind === 'error' || event.kind === 'conflict') {

package/lib/sync/engine.js

@@ -248,7 +248,20 @@ export class SyncEngine {
             await store.putSession(id, state);
             return;
         }
-        const stat = await fsp.stat(location.path);
+        let stat;
+        try {
+            stat = await fsp.stat(location.path);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            // v1 宿主 list() 含「已创建未物化」的会话（首个 append 前无文件），
+            // 也可能撞上并发删除。记 revision 静默跳过：物化或内容变更会改
+            // revision，下一轮 scan 自然重新调度。
+            state.localRevision = revision;
+            await store.putSession(id, state);
+            return;
+        }
         if (stat.size < state.uploadedBytes) {
             // 文件变短（防御：正常不可达）——回退全量重传
             Object.assign(state, freshSessionState());

package/lib/sync/persistence-port.d.ts

@@ -0,0 +1,39 @@
+import type { SessionHeaderLike, SessionLocationLike, SessionSnapshotLike } from '../dsh-types.js';
+/**
+ * 宿主原始形态：v0 时 `listSnapshots` 存在且 `list()` 返回 header 数组；
+ * v1（0.1.3-alpha.1+）时 `listSnapshots` 缺失且 `list()` 返回快照数组。
+ * 运行时以 `listSnapshots` 探测分支，`list()` 元素类型按分支收窄。
+ */
+interface RawPersistence {
+    listSnapshots?(signal?: AbortSignal): Promise<SessionSnapshotLike[]>;
+    list(signal?: AbortSignal): Promise<readonly unknown[]>;
+    locate?(meta: SessionHeaderLike): SessionLocationLike | undefined;
+}
+/**
+ * 复刻 dsh session-persistence-jsonl 的 projectKey（format.ts:228）：
+ * 分隔符折叠为 `-`，不安全码位转 `~XXXX`（大写十六进制 4 位），
+ * 首部 `-` 剥离、截断到 251 码位、整体包 `--…--`。
+ */
+export declare function projectKeyOf(cwd: string): string;
+/**
+ * 复刻 dsh 的 encodeSegment（format.ts:202）：安全字符直通，其余转
+ * `~XXXX`；`.`/`..` 整体转义。会话 id（session-<uuid>）实际恒为直通。
+ */
+export declare function encodeSegmentOf(raw: string): string;
+/**
+ * 推导 jsonl 后端的会话目录（不动文件系统）：无 cwd 落 `_no-cwd`。
+ * 与 dsh projectDir/sessionDir（format.ts:257/270）同构。
+ */
+export declare function sessionDirOf(root: string, cwd: string | undefined, id: string): string;
+/**
+ * 把宿主 sessionPersistence 归一为引擎/恢复消费的端口。
+ * @param raw - ctx.sessionPersistence 原始服务（v0 或 v1 形态）。
+ * @param sessionsRoot - jsonl 后端 root（dsh bundle 恒配 dshHomePath('sessions')）。
+ * @returns 端口对象；v0 的 locate 缺失且非 v1 布局可推导时 listSnapshots 仍可用。
+ */
+export declare function createPersistencePort(raw: RawPersistence, sessionsRoot: string): {
+    listSnapshots(signal?: AbortSignal): Promise<SessionSnapshotLike[]>;
+    list(signal?: AbortSignal): Promise<SessionHeaderLike[]>;
+    locate(meta: SessionHeaderLike): SessionLocationLike | undefined;
+};
+export {};

package/lib/sync/persistence-port.js

@@ -0,0 +1,114 @@
+/**
+ * sessionPersistence 双版本适配层（docs/02 §6 集成面的版本兼容）。
+ *
+ * 背景：dsh 0.1.3-alpha.1 起 SessionPersistence 收敛了消费者 API——
+ * `listSnapshots()` 并入 `list()`（直接返回带 revision 的快照），`locate()`
+ * 被私有化（上游注释明确「日志访问走 session handle 的 read」）。插件按
+ * 发布版 rc.1 的 API 编写，这里在运行时探测宿主形态并归一到引擎/恢复
+ * 消费的 SessionPersistenceLike 端口：
+ * - v0（rc.1 及以前）：listSnapshots/list/locate 原样透传；
+ * - v1（0.1.3-alpha.1 起）：list() 即快照枚举；落位路径无法再问宿主，
+ *   按 jsonl 后端的磁盘布局推导（<root>/<projectKey>/<id>/session.jsonl[.zstd]，
+ *   复刻 dsh format.ts 的 projectKey/encodeSegment 编码）。
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * 复刻 dsh session-persistence-jsonl 的 projectKey（format.ts:228）：
+ * 分隔符折叠为 `-`，不安全码位转 `~XXXX`（大写十六进制 4 位），
+ * 首部 `-` 剥离、截断到 251 码位、整体包 `--…--`。
+ */
+export function projectKeyOf(cwd) {
+    if (cwd.length === 0)
+        throw new Error('cannot encode an empty project path');
+    let readable = '';
+    let separatorRun = false;
+    for (let i = 0; i < cwd.length; i++) {
+        const code = cwd.charCodeAt(i);
+        const ch = String.fromCharCode(code);
+        if (ch === '/' || ch === '\\' || ch === ':') {
+            if (!separatorRun)
+                readable += '-';
+            separatorRun = true;
+        }
+        else if (ch !== '~' && /^[A-Za-z0-9._-]$/.test(ch)) {
+            readable += ch;
+            separatorRun = false;
+        }
+        else {
+            readable += '~' + code.toString(16).toUpperCase().padStart(4, '0');
+            separatorRun = false;
+        }
+    }
+    const slug = readable.replace(/^-+/, '') || 'root';
+    return `--${slug.slice(0, 251)}--`;
+}
+/**
+ * 复刻 dsh 的 encodeSegment（format.ts:202）：安全字符直通，其余转
+ * `~XXXX`；`.`/`..` 整体转义。会话 id（session-<uuid>）实际恒为直通。
+ */
+export function encodeSegmentOf(raw) {
+    if (raw.length === 0)
+        throw new Error('cannot encode an empty path segment');
+    if (raw === '.')
+        return '~002E';
+    if (raw === '..')
+        return '~002E~002E';
+    let out = '';
+    for (let i = 0; i < raw.length; i++) {
+        const code = raw.charCodeAt(i);
+        const ch = String.fromCharCode(code);
+        if (ch !== '~' && /^[A-Za-z0-9._-]$/.test(ch)) {
+            out += ch;
+        }
+        else {
+            out += '~' + code.toString(16).toUpperCase().padStart(4, '0');
+        }
+    }
+    return out;
+}
+/**
+ * 推导 jsonl 后端的会话目录（不动文件系统）：无 cwd 落 `_no-cwd`。
+ * 与 dsh projectDir/sessionDir（format.ts:257/270）同构。
+ */
+export function sessionDirOf(root, cwd, id) {
+    const project = cwd === undefined ? join(root, '_no-cwd') : join(root, projectKeyOf(cwd));
+    return join(project, encodeSegmentOf(id));
+}
+/** 推导会话 artifact 位置：zstd 存在优先；仅明文存在则指明文（引擎会标记 skipped-plain）。 */
+function locateDerived(root, meta) {
+    const dir = sessionDirOf(root, meta.cwd, meta.id);
+    const zstd = join(dir, 'session.jsonl.zstd');
+    if (existsSync(zstd) || !existsSync(join(dir, 'session.jsonl')))
+        return { kind: 'jsonl', path: zstd };
+    return { kind: 'jsonl', path: join(dir, 'session.jsonl') };
+}
+/**
+ * 把宿主 sessionPersistence 归一为引擎/恢复消费的端口。
+ * @param raw - ctx.sessionPersistence 原始服务（v0 或 v1 形态）。
+ * @param sessionsRoot - jsonl 后端 root（dsh bundle 恒配 dshHomePath('sessions')）。
+ * @returns 端口对象；v0 的 locate 缺失且非 v1 布局可推导时 listSnapshots 仍可用。
+ */
+export function createPersistencePort(raw, sessionsRoot) {
+    const v0 = typeof raw.listSnapshots === 'function';
+    return {
+        async listSnapshots(signal) {
+            if (v0)
+                return await raw.listSnapshots(signal);
+            // v1：list() 即快照枚举（header + revision）
+            return (await raw.list(signal));
+        },
+        async list(signal) {
+            const entries = await raw.list(signal);
+            // v0 返回 header 数组，v1 返回快照数组——按形态归一为 header
+            return v0
+                ? entries
+                : entries.map((snapshot) => snapshot.header);
+        },
+        locate(meta) {
+            if (v0)
+                return raw.locate?.(meta);
+            return locateDerived(sessionsRoot, meta);
+        },
+    };
+}

package/lib/sync/restore.js

@@ -3,7 +3,9 @@
  * 经 locate() 落位、映射学习。与 cordis 解耦，纯函数 + 显式 deps 便于单测。
  *
  * 硬约束（§4.3）：
- * - 落位路径一律由 persistence.locate(header) 计算，绝不自行复刻 projectKey 编码；
+ * - 落位路径一律由 persistence 端口的 locate(header) 计算，本模块绝不自行
+ *   复刻 projectKey 编码——v0 宿主透传服务方法，v1 宿主（locate 已私有化）
+ *   由 persistence-port.ts 的布局推导兜底；
  * - 对文件字节的唯一改写是首帧 JSON 的 cwd 字段，事件正文一字节不动；
  * - 落位后唯一的 dsh 调用是 workspaceRegistry 挂载（公开服务方法）——
  *   sessionQuery 的 list() 走 persistence.list() 扫盘，文件就位即被发现；

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-cloud",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "E2E-encrypted cloud mirror plugin for deepseek-harness sessions",
   "type": "module",
   "publishConfig": {