@logictan/dsh-config-manager 0.1.60

package/lib/sync/github-auth.js

@@ -0,0 +1,264 @@
+/**
+ * m-github-oauth：GitHub OAuth device flow（设备码流程）认证模块。
+ *
+ * 插件场景选择 device flow 而非授权码+回调：无需注册回调 URL，天然适合本地 GUI
+ * 插件 —— 用户点「使用 GitHub 登录」→ 宿主向 GitHub 请求设备码 → UI 展示一次性
+ * 用户码 + 授权页 URL → 用户在浏览器确认 → 宿主轮询换取 access token → 存入
+ * DSH credentials（SYNC_CREDENTIAL_REF，与手动 token 同一凭据槽位）→ git 通道
+ * 的 getToken provider 从那里读取，token 永不进 argv / repoUrl / 日志 / 浏览器。
+ *
+ * 安全不变量：
+ * - 本模块不接触任何秘密的持久化：startDeviceFlow 产出设备码（宿主侧内存登记），
+ *   pollForToken 只返回 access token（由宿主立即写入 credentials，绝不回传 UI）；
+ * - 错误消息只携带 GitHub 返回的 error/error_description，绝不内嵌 token 值；
+ * - fetcher / now 可注入：测试全程 mock，不碰真实网络。
+ *
+ * 流程（GitHub 官方 device flow）：
+ *   1. POST https://github.com/login/device/code  { client_id, scope }
+ *      → { device_code, user_code, verification_uri, expires_in, interval }
+ *   2. 用户访问 verification_uri 输入 user_code 授权
+ *   3. POST https://github.com/login/oauth/access_token
+ *      { client_id, device_code, grant_type=urn:ietf:params:oauth:grant-type:device_code
+ *        [, client_secret] } → { access_token } 或 { error, error_description }
+ *      error ∈ authorization_pending | slow_down | expired_token | access_denied | ...
+ */
+import { randomUUID } from 'node:crypto';
+import { defaultFetcher } from '../utils/proxy.js';
+/** GitHub device flow 第一步：请求设备码 */
+export const GITHUB_DEVICE_CODE_URL = 'https://github.com/login/device/code';
+/** GitHub device flow 第三步：轮询换取 access token */
+export const GITHUB_ACCESS_TOKEN_URL = 'https://github.com/login/oauth/access_token';
+/** 缺省 scope：repo（读写私有仓库，同步通道需要） */
+export const GITHUB_DEVICE_FLOW_SCOPE = 'repo';
+/** GitHub 缺省轮询间隔（秒） */
+export const GITHUB_DEFAULT_INTERVAL = 5;
+/** slow_down 时按 RFC 8628 额外增加的等待秒数 */
+export const SLOW_DOWN_EXTRA_SECONDS = 5;
+/** 设备码过期秒数上限兜底（GitHub 默认 900s） */
+const DEVICE_CODE_MAX_EXPIRES_IN = 3600;
+/** GitHub OAuth 可预期错误：code = GitHub error / 固定内部码，status = HTTP 状态（网络层无） */
+export class GitHubAuthError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = 'GitHubAuthError';
+        this.code = code;
+        this.status = status;
+    }
+}
+/** 解析 GitHub 表单/JSON 混合响应：优先 JSON（Accept: application/json 时 GitHub 返回 JSON） */
+async function parseGitHubJson(response, context) {
+    const text = await response.text();
+    if (text.trim() === '') {
+        throw new GitHubAuthError(`${context}: GitHub 返回空响应（HTTP ${response.status}）`, 'empty_response', response.status);
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('not a JSON object');
+        }
+        return parsed;
+    }
+    catch {
+        throw new GitHubAuthError(`${context}: GitHub 返回了无法解析的响应（HTTP ${response.status}），请稍后重试`, 'invalid_json', response.status);
+    }
+}
+/**
+ * GitHub OAuth device flow 客户端。
+ * 无状态（设备码登记由宿主侧的 DeviceFlowStore 负责），fetch 可注入。
+ */
+export class GitHubAuthClient {
+    fetcher;
+    now;
+    constructor(options = {}) {
+        this.fetcher = options.fetcher ?? defaultFetcher();
+        this.now = options.now ?? (() => Date.now());
+    }
+    /**
+     * 用给定 token 验证身份并取回当前用户（GET /user）。
+     *
+     * 供 /sync/github/validate 判定「已存 token 是否仍有效」：401 → `unauthorized`，
+     * 其余错误按 `http_error` 抛出（调用方据此区分「未登录」与「真实故障」，不误判登出）。
+     * token 只作为本次请求的 Authorization 头，绝不回传、不落盘、不进日志。
+     */
+    async getUser(token) {
+        if (typeof token !== 'string' || token === '') {
+            throw new GitHubAuthError('token 必须是非空字符串', 'no_token');
+        }
+        let response;
+        try {
+            response = await this.fetcher('https://api.github.com/user', {
+                method: 'GET',
+                headers: {
+                    accept: 'application/vnd.github+json',
+                    authorization: `Bearer ${token}`,
+                    'user-agent': 'dsh-config-manager',
+                },
+            });
+        }
+        catch (err) {
+            throw new GitHubAuthError(`校验 GitHub token 失败：${err instanceof Error ? err.message : String(err)}`, 'network_error');
+        }
+        if (response.status === 401) {
+            throw new GitHubAuthError('GitHub token 无效或已过期', 'unauthorized', 401);
+        }
+        if (!response.ok) {
+            throw new GitHubAuthError(`GitHub 返回 HTTP ${response.status}`, 'http_error', response.status);
+        }
+        const parsed = await parseGitHubJson(response, '校验 token');
+        const login = parsed['login'];
+        const id = parsed['id'];
+        if (typeof login !== 'string' || login === '' || typeof id !== 'number') {
+            throw new GitHubAuthError('GitHub /user 响应缺少 login/id', 'invalid_response', response.status);
+        }
+        return { login, id };
+    }
+    /**
+     * 第一步：请求设备码。产出一次性 user_code + 授权页 URL + device_code
+     * （device_code 由宿主登记，只在本模块与宿主间流转，绝不发给浏览器）。
+     */
+    async startDeviceFlow(clientId, scope = GITHUB_DEVICE_FLOW_SCOPE) {
+        if (typeof clientId !== 'string' || clientId === '') {
+            throw new GitHubAuthError('client_id 必须是非空字符串', 'invalid_client_id');
+        }
+        const body = new URLSearchParams();
+        body.set('client_id', clientId);
+        body.set('scope', scope);
+        let response;
+        try {
+            response = await this.fetcher(GITHUB_DEVICE_CODE_URL, {
+                method: 'POST',
+                headers: { accept: 'application/json', 'content-type': 'application/x-www-form-urlencoded' },
+                body: body.toString(),
+            });
+        }
+        catch (err) {
+            throw new GitHubAuthError(`请求 GitHub 设备码失败：${err instanceof Error ? err.message : String(err)}`, 'network_error');
+        }
+        const parsed = await parseGitHubJson(response, '请求设备码');
+        const ghError = parsed['error'];
+        if (typeof ghError === 'string' && ghError !== '') {
+            const desc = parsed['error_description'];
+            throw new GitHubAuthError(`GitHub 拒绝了设备码请求：${typeof desc === 'string' && desc !== '' ? desc : ghError}`, ghError, response.status);
+        }
+        const deviceCode = parsed['device_code'];
+        const userCode = parsed['user_code'];
+        const verificationUri = parsed['verification_uri'];
+        if (typeof deviceCode !== 'string' || deviceCode === ''
+            || typeof userCode !== 'string' || userCode === ''
+            || typeof verificationUri !== 'string' || verificationUri === '') {
+            throw new GitHubAuthError('GitHub 设备码响应缺少必要字段（device_code/user_code/verification_uri）', 'invalid_response', response.status);
+        }
+        const expiresIn = typeof parsed['expires_in'] === 'number' && Number.isFinite(parsed['expires_in'])
+            ? Math.min(Math.max(Math.floor(parsed['expires_in']), 1), DEVICE_CODE_MAX_EXPIRES_IN)
+            : 900;
+        const interval = typeof parsed['interval'] === 'number' && Number.isFinite(parsed['interval'])
+            ? Math.max(Math.floor(parsed['interval']), 1)
+            : GITHUB_DEFAULT_INTERVAL;
+        return { deviceCode, userCode, verificationUri, expiresIn, interval };
+    }
+    /**
+     * 单次 token 交换（device flow 第三步的原子操作）。
+     * 返回类型化结果：成功 = access token；失败 = GitHub error code（pending/slow_down
+     * 等由 pollForToken 归并为轮询状态）。
+     */
+    async exchangeDeviceCode(params) {
+        const body = new URLSearchParams();
+        body.set('client_id', params.clientId);
+        body.set('device_code', params.deviceCode);
+        body.set('grant_type', 'urn:ietf:params:oauth:grant-type:device_code');
+        if (params.clientSecret !== undefined && params.clientSecret !== '') {
+            body.set('client_secret', params.clientSecret);
+        }
+        let response;
+        try {
+            response = await this.fetcher(GITHUB_ACCESS_TOKEN_URL, {
+                method: 'POST',
+                headers: { accept: 'application/json', 'content-type': 'application/x-www-form-urlencoded' },
+                body: body.toString(),
+            });
+        }
+        catch (err) {
+            throw new GitHubAuthError(`交换 GitHub token 失败：${err instanceof Error ? err.message : String(err)}`, 'network_error');
+        }
+        const parsed = await parseGitHubJson(response, '交换 token');
+        const accessToken = parsed['access_token'];
+        if (typeof accessToken === 'string' && accessToken !== '') {
+            return { ok: true, accessToken };
+        }
+        const ghError = parsed['error'];
+        const desc = parsed['error_description'];
+        return {
+            ok: false,
+            error: typeof ghError === 'string' && ghError !== '' ? ghError : 'unknown_error',
+            errorDescription: typeof desc === 'string' && desc !== '' ? desc : undefined,
+        };
+    }
+    /**
+     * 轮询换取 access token，把 GitHub 错误码归并为 UI 可消费的轮询状态：
+     * - authorization_pending → pending（按 interval 继续等）
+     * - slow_down → pending（interval + 5s，RFC 8628）
+     * - expired_token → expired（终止，重新开始）
+     * - access_denied → denied（终止）
+     * - 其他 error → error（终止，携带 errorCode + 描述）
+     */
+    async pollForToken(params) {
+        const result = await this.exchangeDeviceCode(params);
+        if (result.ok) {
+            return { status: 'success', accessToken: result.accessToken };
+        }
+        const intervalMs = Math.max(params.interval ?? GITHUB_DEFAULT_INTERVAL, 1) * 1000;
+        switch (result.error) {
+            case 'authorization_pending':
+                return { status: 'pending', pollDelayMs: intervalMs };
+            case 'slow_down':
+                return { status: 'pending', pollDelayMs: intervalMs + SLOW_DOWN_EXTRA_SECONDS * 1000 };
+            case 'expired_token':
+                return { status: 'expired' };
+            case 'access_denied':
+                return { status: 'denied' };
+            default:
+                return { status: 'error', errorCode: result.error, message: result.errorDescription };
+        }
+    }
+}
+/**
+ * 宿主内存设备码登记表（进程生命周期，跨请求共享 —— 与 RunRegistry 同模式）。
+ * device_code 的持有者是宿主：UI 只拿 flowId（随机 id），轮询时宿主凭 flowId 取回
+ * device_code 去 GitHub 换 token。过期条目惰性清理，防止无限增长。
+ */
+export class DeviceFlowStore {
+    flows = new Map();
+    now;
+    constructor(now) {
+        this.now = now ?? (() => Date.now());
+    }
+    get size() {
+        return this.flows.size;
+    }
+    /** 登记一个设备码流；flowId 由调用方生成（随机，不可猜） */
+    set(flowId, entry) {
+        this.flows.set(flowId, entry);
+    }
+    /** 取回设备码流；过期条目视为不存在并立即清理 */
+    get(flowId) {
+        const entry = this.flows.get(flowId);
+        if (entry === undefined)
+            return undefined;
+        if (this.now() > entry.expiresAt) {
+            this.flows.delete(flowId);
+            return undefined;
+        }
+        return entry;
+    }
+    /** 主动移除（取消/完成后清理） */
+    delete(flowId) {
+        this.flows.delete(flowId);
+    }
+    /** 生成不可猜的 flowId（路由层用） */
+    static newFlowId() {
+        return randomUUID();
+    }
+}
+//# sourceMappingURL=github-auth.js.map

package/lib/sync/layout.d.ts

@@ -0,0 +1,43 @@
+import type { SectionId } from '../schema/types.ts';
+import type { SnapshotFs } from './fs.ts';
+import type { SyncSnapshot } from './transport.ts';
+export declare const SNAPSHOT_MANIFEST_FILE = "manifest.json";
+/**
+ * 空文件类分区的 git 占位文件（git 不跟踪空目录）：
+ * 上传方（GitTransport.upload）给 files 为空的文件类分区目录写入本占位文件，
+ * 保证远端仓库保留该目录；读回时仅当「文件名 + 内容」同时匹配才过滤，
+ * 避免吞掉用户真实同名文件。占位文件不参与 sectionHashes（基于传入数据计算）。
+ * 注意：占位内容不得含换行 —— Windows core.autocrlf 会把 LF 转 CRLF，内容校验会失败。
+ */
+export declare const SNAPSHOT_KEEP_FILE = ".gitkeep";
+export declare const SNAPSHOT_KEEP_CONTENT = "DSH Config Manager sync placeholder (keep empty section dir)";
+/** 快照根目录下的 manifest.json 结构 */
+export interface SnapshotDirManifest {
+    id: string;
+    createdAt: string;
+    manifest: SyncSnapshot['manifest'];
+    /** 各分区内容 hash（写入时由 hashSection 计算） */
+    sectionHashes: Partial<Record<SectionId, string>>;
+}
+/**
+ * 文件相对路径安全检查：拒绝空/'.'/'..'、绝对路径、Windows 盘符、反斜杠、
+ * 含 '..' 或 '.' 片段（防穿越快照根目录）。
+ */
+export declare function isSafeRelPath(rel: string): boolean;
+/** 递归列出 dir 下的全部文件（相对 dir 的正斜杠路径，字典序）；目录不存在 → [] */
+export declare function listSnapshotFiles(fsx: SnapshotFs, dir: string): Promise<string[]>;
+/**
+ * 将快照写入散文件目录。
+ * 非法输入（不支持的子分区 / 穿越路径）在任何写入发生前抛错，不留半成品目录。
+ */
+export declare function writeSnapshotToDir(snapshot: SyncSnapshot, dir: string, fsx?: SnapshotFs): Promise<SnapshotDirManifest>;
+/**
+ * 从散文件目录读回快照。
+ * manifest 声明的分区必须可解析：JSON 分区文件缺失 / 文件分区目录缺失 → 抛错（不静默降级），
+ * 但 opts.missingFileDir='empty' 时文件分区目录缺失降级为空分区
+ * （git 通道专用：git 不跟踪空目录，目录缺失 = 空文件分区；提交原子性保证非空目录不会缺失）。
+ * 读回时过滤 git 占位文件（SNAPSHOT_KEEP_FILE），使 files 与上传方数据一致。
+ */
+export declare function readSnapshotFromDir(dir: string, fsx?: SnapshotFs, opts?: {
+    missingFileDir?: 'throw' | 'empty';
+}): Promise<SyncSnapshot>;

package/lib/sync/layout.js

@@ -0,0 +1,203 @@
+/**
+ * m-sync-transport：散文件目录布局。
+ * 快照根目录 = manifest.json + 按 SECTION_JSON_PATHS 平铺的 JSON 分区
+ *            + 按 SECTION_FILE_PREFIXES 的文件类分区目录（skills 等真实文件）。
+ * 复用 src/schema/config.ts 的路径表；核心逻辑经 SnapshotFs 注入（默认 node:fs/promises）。
+ */
+import path from 'node:path';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
+import { sha256Hex } from '../utils/hashing.js';
+import { SECTION_FILE_PREFIXES, SECTION_JSON_PATHS } from '../schema/config.js';
+import { createSnapshotFs, joinFs } from './fs.js';
+import { hashSection } from './sync-state.js';
+import { isEncryptedSections } from './transport.js';
+export const SNAPSHOT_MANIFEST_FILE = 'manifest.json';
+/**
+ * 空文件类分区的 git 占位文件（git 不跟踪空目录）：
+ * 上传方（GitTransport.upload）给 files 为空的文件类分区目录写入本占位文件，
+ * 保证远端仓库保留该目录；读回时仅当「文件名 + 内容」同时匹配才过滤，
+ * 避免吞掉用户真实同名文件。占位文件不参与 sectionHashes（基于传入数据计算）。
+ * 注意：占位内容不得含换行 —— Windows core.autocrlf 会把 LF 转 CRLF，内容校验会失败。
+ */
+export const SNAPSHOT_KEEP_FILE = '.gitkeep';
+export const SNAPSHOT_KEEP_CONTENT = 'DSH Config Manager sync placeholder (keep empty section dir)';
+const SNAPSHOT_KEEP_BYTES = new TextEncoder().encode(SNAPSHOT_KEEP_CONTENT);
+function isKeepFile(rel, data) {
+    if (rel !== SNAPSHOT_KEEP_FILE)
+        return false;
+    if (data.length !== SNAPSHOT_KEEP_BYTES.length)
+        return false;
+    for (let i = 0; i < data.length; i++) {
+        if (data[i] !== SNAPSHOT_KEEP_BYTES[i])
+            return false;
+    }
+    return true;
+}
+/** 布局支持的分区 = SECTION_JSON_PATHS ∪ SECTION_FILE_PREFIXES（secrets 等不在内） */
+const LAYOUT_SECTION_IDS = [
+    ...Object.keys(SECTION_JSON_PATHS),
+    ...Object.keys(SECTION_FILE_PREFIXES),
+];
+/**
+ * 文件相对路径安全检查：拒绝空/'.'/'..'、绝对路径、Windows 盘符、反斜杠、
+ * 含 '..' 或 '.' 片段（防穿越快照根目录）。
+ */
+export function isSafeRelPath(rel) {
+    if (rel === '' || rel === '.' || rel === '..')
+        return false;
+    if (rel.startsWith('/') || /^[A-Za-z]:[\\/]/.test(rel))
+        return false;
+    if (rel.includes('\\'))
+        return false;
+    const parts = rel.split('/');
+    if (parts.some((p) => p === '' || p === '.' || p === '..'))
+        return false;
+    return true;
+}
+/** 递归列出 dir 下的全部文件（相对 dir 的正斜杠路径，字典序）；目录不存在 → [] */
+export async function listSnapshotFiles(fsx, dir) {
+    const out = [];
+    const walk = async (abs, rel) => {
+        const names = await fsx.readdir(abs);
+        for (const name of names) {
+            if (name === '' || name === '.' || name === '..')
+                continue; // 防御异常/恶意 fs
+            const childAbs = joinFs(abs, name);
+            const childRel = rel === '' ? name : `${rel}/${name}`;
+            if (await fsx.isDir(childAbs)) {
+                await walk(childAbs, childRel);
+            }
+            else {
+                out.push(childRel);
+            }
+        }
+    };
+    await walk(dir, '');
+    return out.sort();
+}
+/**
+ * 将快照写入散文件目录。
+ * 非法输入（不支持的子分区 / 穿越路径）在任何写入发生前抛错，不留半成品目录。
+ */
+export async function writeSnapshotToDir(snapshot, dir, fsx = createSnapshotFs()) {
+    // 加密快照不写散文件目录（本地不落盘：密文/明文都不落；远端已存密文）
+    if (isEncryptedSections(snapshot.sections)) {
+        throw new Error('加密快照不写散文件目录（本地不落盘；请直接使用密文传输）');
+    }
+    const sectionHashes = {};
+    for (const [id, data] of Object.entries(snapshot.sections)) {
+        const sid = id;
+        if (!LAYOUT_SECTION_IDS.includes(sid)) {
+            throw new Error(`分区 ${sid} 不在散文件布局支持范围（SECTION_JSON_PATHS / SECTION_FILE_PREFIXES）`);
+        }
+        sectionHashes[sid] = hashSection(data);
+    }
+    // 预校验全部文件相对路径（不合法 → 抛错且零写入）
+    for (const [sid, data] of Object.entries(snapshot.sections)) {
+        if (!(sid in SECTION_FILE_PREFIXES))
+            continue;
+        for (const file of data.files) {
+            if (!isSafeRelPath(file.relativePath)) {
+                throw new Error(`非法文件相对路径: ${file.relativePath}（分区 ${sid}）`);
+            }
+        }
+    }
+    await fsx.mkdir(dir);
+    const manifest = {
+        id: snapshot.id,
+        createdAt: snapshot.createdAt,
+        manifest: snapshot.manifest,
+        sectionHashes,
+    };
+    await fsx.writeFile(joinFs(dir, SNAPSHOT_MANIFEST_FILE), new TextEncoder().encode(stringifyJsonSafe(manifest, { space: 2 })));
+    // JSON 分区：按 SECTION_JSON_PATHS 平铺
+    for (const [sid, rel] of Object.entries(SECTION_JSON_PATHS)) {
+        const data = snapshot.sections[sid];
+        if (data === undefined)
+            continue;
+        const abs = joinFs(dir, rel);
+        await fsx.mkdir(path.dirname(abs));
+        await fsx.writeFile(abs, new TextEncoder().encode(stringifyJsonSafe(data, { space: 2 })));
+    }
+    // 文件类分区：目录前缀 + 真实文件
+    for (const [sid, prefix] of Object.entries(SECTION_FILE_PREFIXES)) {
+        const data = snapshot.sections[sid];
+        if (data === undefined)
+            continue;
+        const baseAbs = joinFs(dir, prefix);
+        await fsx.mkdir(baseAbs); // 空文件类分区也保留目录（读回可还原空 files）
+        for (const file of data.files) {
+            const abs = joinFs(baseAbs, file.relativePath);
+            await fsx.mkdir(path.dirname(abs));
+            await fsx.writeFile(abs, file.data);
+        }
+    }
+    return manifest;
+}
+/**
+ * 从散文件目录读回快照。
+ * manifest 声明的分区必须可解析：JSON 分区文件缺失 / 文件分区目录缺失 → 抛错（不静默降级），
+ * 但 opts.missingFileDir='empty' 时文件分区目录缺失降级为空分区
+ * （git 通道专用：git 不跟踪空目录，目录缺失 = 空文件分区；提交原子性保证非空目录不会缺失）。
+ * 读回时过滤 git 占位文件（SNAPSHOT_KEEP_FILE），使 files 与上传方数据一致。
+ */
+export async function readSnapshotFromDir(dir, fsx = createSnapshotFs(), opts = {}) {
+    const manifestAbs = joinFs(dir, SNAPSHOT_MANIFEST_FILE);
+    if (!(await fsx.exists(manifestAbs))) {
+        throw new Error(`快照目录缺少 ${SNAPSHOT_MANIFEST_FILE}: ${dir}`);
+    }
+    const parsed = parseJsonSafe(Buffer.from(await fsx.readFile(manifestAbs)).toString('utf8'));
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('manifest.json 损坏：必须是对象');
+    }
+    const m = parsed;
+    if (typeof m['id'] !== 'string' || typeof m['createdAt'] !== 'string'
+        || m['manifest'] === null || typeof m['manifest'] !== 'object'
+        || m['sectionHashes'] === null || typeof m['sectionHashes'] !== 'object') {
+        throw new Error('manifest.json 损坏：缺少 id/createdAt/manifest/sectionHashes');
+    }
+    const manifest = parsed;
+    const sections = {};
+    const declared = Object.keys(manifest.sectionHashes);
+    for (const sid of declared) {
+        if (!LAYOUT_SECTION_IDS.includes(sid)) {
+            throw new Error(`manifest 声明了布局不支持的分区 ${sid}`);
+        }
+    }
+    // JSON 分区
+    for (const [sid, rel] of Object.entries(SECTION_JSON_PATHS)) {
+        if (!(sid in manifest.sectionHashes))
+            continue;
+        const abs = joinFs(dir, rel);
+        if (!(await fsx.exists(abs))) {
+            throw new Error(`快照缺少 JSON 分区文件 ${rel}（${sid}）`);
+        }
+        sections[sid] = parseJsonSafe(Buffer.from(await fsx.readFile(abs)).toString('utf8'));
+    }
+    // 文件类分区
+    for (const [sid, prefix] of Object.entries(SECTION_FILE_PREFIXES)) {
+        if (!(sid in manifest.sectionHashes))
+            continue;
+        const baseAbs = joinFs(dir, prefix);
+        if (!(await fsx.isDir(baseAbs))) {
+            if (opts.missingFileDir === 'empty') {
+                // git 通道降级：目录缺失 = 空文件分区（git 不跟踪空目录，详见函数注释）
+                sections[sid] = { version: 1, files: [] };
+                continue;
+            }
+            throw new Error(`快照缺少文件分区目录 ${prefix}（${sid}）`);
+        }
+        const rels = await listSnapshotFiles(fsx, baseAbs);
+        const files = [];
+        for (const rel of rels) {
+            const data = await fsx.readFile(joinFs(baseAbs, rel));
+            // 过滤 git 占位文件（名 + 内容同时匹配才过滤，避免吞用户真实同名文件）
+            if (isKeepFile(rel, data))
+                continue;
+            files.push({ relativePath: rel, data, contentHash: sha256Hex(data) });
+        }
+        sections[sid] = { version: 1, files };
+    }
+    return { id: manifest.id, createdAt: manifest.createdAt, manifest: manifest.manifest, sections };
+}
+//# sourceMappingURL=layout.js.map

package/lib/sync/snapshot-json.d.ts

@@ -0,0 +1,9 @@
+import type { SyncSnapshot } from './transport.ts';
+/** sections 整体 JSON 化（加密密文载荷原样透传）。 */
+export declare function sectionsToJsonSafe(sections: SyncSnapshot['sections']): SyncSnapshot['sections'];
+/** sections 从 JSON 还原（加密密文载荷原样透传）。 */
+export declare function sectionsFromJsonSafe(sections: unknown): SyncSnapshot['sections'];
+/** 整份快照序列化为 JSON 字符串（本地不落盘，仅用于传输/加密载荷）。 */
+export declare function serializeSnapshot(snapshot: SyncSnapshot): string;
+/** 从 JSON 字符串还原快照（形状非法抛错；调用方负责包装成通道错误）。 */
+export declare function deserializeSnapshot(raw: string): SyncSnapshot;

package/lib/sync/snapshot-json.js

@@ -0,0 +1,107 @@
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
+import { isEncryptedSections } from './transport.js';
+/** 二进制数据在 JSON 中的标记对象键（base64 载荷）。 */
+const BIN_KEY = '$bin';
+/** duck-typing：文件类分区（version===1 + files 数组） */
+function isFilesSectionLike(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    const o = v;
+    return o.version === 1 && Array.isArray(o.files);
+}
+/** 单个文件分区：Uint8Array → { $bin: base64 }（非二进制原样保留）。 */
+function encodeFileData(data) {
+    if (data instanceof Uint8Array) {
+        return { [BIN_KEY]: Buffer.from(data).toString('base64') };
+    }
+    return data;
+}
+/** 单个文件分区：{ $bin: base64 } → Uint8Array（非标记对象原样保留）。 */
+function decodeFileData(data) {
+    if (data !== null && typeof data === 'object') {
+        const bin = data[BIN_KEY];
+        if (typeof bin === 'string') {
+            // 普通 Uint8Array（非 Buffer 子类）：与内存中文件分区形态一致，深比较等价
+            return new Uint8Array(Buffer.from(bin, 'base64'));
+        }
+    }
+    return data;
+}
+/** 单个分区 JSON 化：文件类分区逐文件转 base64；JSON 分区原样。 */
+function sectionToJsonSafe(section) {
+    if (!isFilesSectionLike(section))
+        return section;
+    return {
+        version: 1,
+        files: section.files.map((f) => ({
+            relativePath: f.relativePath,
+            data: encodeFileData(f.data),
+            ...(f.contentHash !== undefined ? { contentHash: f.contentHash } : {}),
+        })),
+    };
+}
+/** 单个分区从 JSON 还原：文件类分区逐文件还原 Uint8Array。 */
+function sectionFromJsonSafe(section) {
+    if (!isFilesSectionLike(section))
+        return section;
+    return {
+        version: 1,
+        files: section.files.map((f) => ({
+            relativePath: f.relativePath,
+            data: decodeFileData(f.data),
+            ...(f.contentHash !== undefined ? { contentHash: f.contentHash } : {}),
+        })),
+    };
+}
+/** sections 整体 JSON 化（加密密文载荷原样透传）。 */
+export function sectionsToJsonSafe(sections) {
+    if (isEncryptedSections(sections))
+        return sections;
+    const out = {};
+    for (const [id, data] of Object.entries(sections)) {
+        out[id] = sectionToJsonSafe(data);
+    }
+    return out;
+}
+/** sections 从 JSON 还原（加密密文载荷原样透传）。 */
+export function sectionsFromJsonSafe(sections) {
+    if (isEncryptedSections(sections))
+        return sections;
+    if (sections === null || typeof sections !== 'object' || Array.isArray(sections)) {
+        throw new Error('快照 sections 必须是对象');
+    }
+    const out = {};
+    for (const [id, data] of Object.entries(sections)) {
+        out[id] = sectionFromJsonSafe(data);
+    }
+    return out;
+}
+/** 整份快照序列化为 JSON 字符串（本地不落盘，仅用于传输/加密载荷）。 */
+export function serializeSnapshot(snapshot) {
+    return stringifyJsonSafe({
+        id: snapshot.id,
+        createdAt: snapshot.createdAt,
+        manifest: snapshot.manifest,
+        sections: sectionsToJsonSafe(snapshot.sections),
+    });
+}
+/** 从 JSON 字符串还原快照（形状非法抛错；调用方负责包装成通道错误）。 */
+export function deserializeSnapshot(raw) {
+    const parsed = parseJsonSafe(raw);
+    const snap = parsed;
+    const okShape = snap !== null && typeof snap === 'object' && !Array.isArray(snap)
+        && typeof snap.id === 'string'
+        && typeof snap.createdAt === 'string'
+        && typeof snap.manifest === 'object' && snap.manifest !== null
+        && typeof snap.sections === 'object' && snap.sections !== null;
+    if (!okShape) {
+        throw new Error('快照 JSON 形状非法（缺少 id/createdAt/manifest/sections）');
+    }
+    return {
+        id: snap.id,
+        createdAt: snap.createdAt,
+        manifest: snap.manifest,
+        sections: sectionsFromJsonSafe(snap.sections),
+    };
+}
+//# sourceMappingURL=snapshot-json.js.map