@logictan/dsh-config-manager 0.1.60

package/lib/sync/ui-prefs.js

@@ -0,0 +1,109 @@
+/**
+ * m-self：插件自身 UI 偏好持久化（ui-prefs.json）。
+ *
+ * 与 sync-config.json / sync-selection.json 并列独立文件：语义清楚、schema 演进独立。
+ * 当前存 lastSyncChannel（用户上次选择的同步通道 git/webdav）+ Star 引导弹窗状态
+ * （starPromptFirstSeenAt / starPromptDismissed / starPromptClicked，见 src/ui/star-prompt.ts）。
+ *
+ * 背景（self 分区设计）：此前该偏好只存浏览器 localStorage（键
+ * dsh.configManager.syncChannel），换浏览器/换机器即丢失，且 Host 进程读不到
+ * （自动同步在浏览器关闭时也运行）。迁移到磁盘后：
+ *  - Host 侧可读可写（status 响应回填、POST /sync/ui-prefs 保存）；
+ *  - 随 self 分区进入导出备份，迁移到新机器时恢复；
+ *  - localStorage 仅保留为前端同步读取的降级通道（status 未带回填时的兜底）。
+ *
+ * 字段 { schemaVersion, lastSyncChannel?: 'git' | 'webdav',
+ *         starPromptFirstSeenAt?: number, starPromptDismissed?: boolean,
+ *         starPromptClicked?: boolean }：
+ * - 缺省/未配置 = undefined（UI 回退到 sync-config.transport / 首次进入页面）；
+ * - 原子写（临时文件 + rename），损坏/不支持 schema 回退缺省；
+ * - 多端点共写同一文件：一律经 updateUiPrefs（read → merge → write）原子更新，
+ *   避免「sync/ui-prefs 写 lastSyncChannel」与「star-prompt 写弹窗状态」互相覆盖。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
+import { atomicWriteFile } from '../utils/atomic-write.js';
+export const UI_PREFS_FILE = 'ui-prefs.json';
+export const UI_PREFS_SCHEMA_VERSION = 1;
+/** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
+export function defaultUiPrefs() {
+    return { schemaVersion: UI_PREFS_SCHEMA_VERSION };
+}
+/** 读取 UI 偏好；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export async function readUiPrefs(dir) {
+    const file = path.join(dir, UI_PREFS_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(file, 'utf8');
+    }
+    catch {
+        return defaultUiPrefs();
+    }
+    let parsed;
+    try {
+        parsed = parseJsonSafe(raw);
+    }
+    catch {
+        return defaultUiPrefs();
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return defaultUiPrefs();
+    }
+    const obj = parsed;
+    if (obj['schemaVersion'] !== undefined && obj['schemaVersion'] !== UI_PREFS_SCHEMA_VERSION) {
+        return defaultUiPrefs();
+    }
+    if (obj['schemaVersion'] === undefined) {
+        return defaultUiPrefs();
+    }
+    const prefs = defaultUiPrefs();
+    if (obj['lastSyncChannel'] === 'git' || obj['lastSyncChannel'] === 'webdav') {
+        prefs.lastSyncChannel = obj['lastSyncChannel'];
+    }
+    if (typeof obj['starPromptFirstSeenAt'] === 'number' && Number.isFinite(obj['starPromptFirstSeenAt'])) {
+        prefs.starPromptFirstSeenAt = obj['starPromptFirstSeenAt'];
+    }
+    if (obj['starPromptDismissed'] === true) {
+        prefs.starPromptDismissed = true;
+    }
+    if (obj['starPromptClicked'] === true) {
+        prefs.starPromptClicked = true;
+    }
+    if (typeof obj['releaseNotesLastSeenVersion'] === 'string' && obj['releaseNotesLastSeenVersion'].trim().length > 0) {
+        prefs.releaseNotesLastSeenVersion = obj['releaseNotesLastSeenVersion'].trim();
+    }
+    if (obj['releaseNotesDismissed'] === true) {
+        prefs.releaseNotesDismissed = true;
+    }
+    return prefs;
+}
+/** 写入 UI 偏好（原子写：临时文件 + rename；自动创建目录）。 */
+export async function writeUiPrefs(dir, prefs) {
+    await fs.mkdir(dir, { recursive: true });
+    const payload = {
+        schemaVersion: UI_PREFS_SCHEMA_VERSION,
+        ...(prefs.lastSyncChannel !== undefined ? { lastSyncChannel: prefs.lastSyncChannel } : {}),
+        ...(prefs.starPromptFirstSeenAt !== undefined ? { starPromptFirstSeenAt: prefs.starPromptFirstSeenAt } : {}),
+        ...(prefs.starPromptDismissed === true ? { starPromptDismissed: true } : {}),
+        ...(prefs.starPromptClicked === true ? { starPromptClicked: true } : {}),
+        ...(prefs.releaseNotesLastSeenVersion !== undefined ? { releaseNotesLastSeenVersion: prefs.releaseNotesLastSeenVersion } : {}),
+        ...(prefs.releaseNotesDismissed === true ? { releaseNotesDismissed: true } : {}),
+    };
+    const target = path.join(dir, UI_PREFS_FILE);
+    const data = stringifyJsonSafe(payload, { space: 2 });
+    await atomicWriteFile(target, data, { mode: 0o600 });
+}
+/**
+ * 局部原子更新：read → merge → write。
+ * 多端点共写 ui-prefs.json 时（sync/ui-prefs 与 star-prompt），任一端点写全量对象
+ * 都会丢掉另一端点刚写入的字段；统一走本函数按补丁合并，杜绝互相覆盖。
+ */
+export async function updateUiPrefs(dir, patch) {
+    const current = await readUiPrefs(dir);
+    const next = { ...current, ...patch };
+    await writeUiPrefs(dir, next);
+    return next;
+}
+//# sourceMappingURL=ui-prefs.js.map

package/lib/sync/webdav/webdav-transport.d.ts

@@ -0,0 +1,77 @@
+import type { MsgFunc } from '../../core/messages.ts';
+import type { SyncSnapshot, SyncSnapshotMeta, SyncTransport } from '../transport.ts';
+/** 请求选项：headers / body / 覆盖默认超时（ms；0 = 不超时） */
+export interface WebDavRequestOptions {
+    headers?: Record<string, string>;
+    body?: string;
+    timeoutMs?: number;
+}
+/** 请求响应最小形状（兼容 fetch Response 的 status/ok/text()；headers 供重定向读 Location） */
+export interface WebDavResponse {
+    readonly status: number;
+    readonly ok: boolean;
+    /** 响应头（可选：注入的 mock 可省略，默认 request 总会带上，重定向跟随需要 location） */
+    readonly headers?: Record<string, string>;
+    text(): Promise<string>;
+}
+/** 可注入的请求函数（测试 mock 用）；method/url/options */
+export type WebDavRequestFn = (method: string, url: string, options?: WebDavRequestOptions) => Promise<WebDavResponse>;
+/** 凭据提供者：password 只从这里读取，绝不落盘/进日志 */
+export interface WebDavCredentialProvider {
+    getPassword(): Promise<string>;
+}
+export interface WebDavTransportOptions {
+    /** WebDAV 远端根 URL（http/https），如 https://dav.example.com/dav/config */
+    baseUrl: string;
+    /** HTTP Basic 认证用户名 */
+    username: string;
+    /** 密码提供者（HTTP Basic 密码） */
+    credentials: WebDavCredentialProvider;
+    /** 可注入 request（测试 mock 用）；缺省 = 全局 fetch + AbortController 超时 */
+    request?: WebDavRequestFn;
+    /** 单请求超时 ms，默认 120000（慢速 WebDAV 上传大快照需要宽裕窗口；0 = 不超时） */
+    timeoutMs?: number;
+    /** 消息翻译器（缺省 zh） */
+    msg?: MsgFunc;
+}
+export declare class WebDavTransportError extends Error {
+    constructor(message: string);
+}
+/** 实现 SyncTransport 的 WebDAV 通道。所有网络操作经 request 注入（缺省 defaultRequest，自动跟随重定向）。 */
+export declare class WebDavTransport implements SyncTransport {
+    readonly type = "webdav";
+    private readonly o;
+    constructor(options: WebDavTransportOptions);
+    /** 列出远端已有快照（按 createdAt 升序）。index.json 缺失视为空。 */
+    list(): Promise<SyncSnapshotMeta[]>;
+    /** 上传快照：幂等 MKCOL → 快照级跳过判定（同 id 且内容全等则免上传）→ PUT <id>.json
+     *  → 合并写回 index.json；返回远端 meta（跳过时）或 computeSnapshotMeta。
+     *  序列化经 snapshot-json：文件类分区字节以 base64 传输（JSON 无法直传 Uint8Array）。 */
+    upload(snapshot: SyncSnapshot): Promise<SyncSnapshotMeta>;
+    /** 下载快照完整载荷。不存在的 id 必须抛错（契约）。 */
+    download(id: string): Promise<SyncSnapshot>;
+    /** 删除远端快照并从 index 摘除（写回合并后的 index）；文件不存在视为成功。 */
+    delete(id: string): Promise<void>;
+    private validateOptions;
+    private assertSafeId;
+    private snapshotsBase;
+    private snapshotsColUrl;
+    private snapshotUrl;
+    private indexUrl;
+    /** 读取一次 password（错误脱敏用） */
+    private passwordOnce;
+    /** 幂等创建 snapshots 集合：MKCOL；已存在（405/2xx/3xx）视为成功。 */
+    private ensureCollection;
+    /** 读 index（缺失 → []；非法 → 抛错）。 */
+    private readIndex;
+    private parseIndex;
+    private parseSnapshot;
+    /** 发送请求：注入 Basic 认证头 + 调用 request；网络错误/超时归一 */
+    private send;
+    /** 构造 HTTP 非 2xx 失败消息：附上脱敏后的响应体片段（截断） */
+    private failText;
+    /** 识别超时错误（AbortController 抛出的 AbortError / DOMException timeout / TimeoutError） */
+    private isTimeout;
+    /** 错误消息脱敏：password（原文与 URL 编码形态）一律替换 */
+    private mask;
+}

package/lib/sync/webdav/webdav-transport.js

@@ -0,0 +1,451 @@
+/**
+ * m-webdav-channel：WebDAV 通道（SyncTransport 的 webdav 实现）。
+ *
+ * 远端布局（单文件 JSON 快照 + 索引）：
+ *   <base>/dsh-config-manager/<id>.json   —— 单个快照的完整载荷（SyncSnapshot 序列化）
+ *   <base>/dsh-config-manager/index.json  —— 索引（SyncSnapshotMeta 数组，每个 id 一条）
+ *
+ * 设计：
+ * - upload：先幂等 MKCOL snapshots 集合，再读 index 做「快照级跳过」判定
+ *   （同 id 条目且 sections hash 全等 → 内容未变，跳过 PUT 直接返回远端 meta）；
+ *   否则 PUT <id>.json（先快照文件）→ 合并（保留其它 id、覆盖同 id）→ PUT 写回 index
+ *   （meta 最后落盘：快照文件成功后才写索引）。
+ * - list：GET index.json，缺失（404）视为空；按 createdAt 升序返回。
+ * - download：GET <id>.json 解析成 SyncSnapshot；不存在必须抛错（契约）。
+ * - delete：DELETE <id>.json 并从 index 摘除条目（写回合并后 index）；文件不存在视为成功。
+ * - 二进制安全：快照序列化经 snapshot-json（文件分区 Uint8Array → base64 标记对象），
+ *   JSON 往返字节无损（否则 JSON.stringify 把 TypedArray 变成数字索引对象，拉取还原
+ *   成普通对象 → Buffer.from(对象) 报错）。
+ * - 认证：HTTP Basic（username 配置项 + 注入 credentials 提供者 getPassword()）。
+ *   密码绝不进 URL/日志；错误消息中的响应体统一脱敏（password → [REDACTED]）。
+ * - 重定向：默认 request 自动跟随 301/302/303/307/308（网盘 WebDAV 会把下载 GET 302 到
+ *   带时效签名的 CDN 直链，如 123pan；不自建反代返回 301 也一样）。303 且非 GET/HEAD 时
+ *   降级为 GET 并丢弃请求体；跨源跳转剥离 Authorization（CDN 直链是预签名 URL，不得把
+ *   Basic 凭据转发给第三方域）；上限 5 跳，超出抛错。无 Location / Location 非法的 3xx
+ *   按最终响应返回（上层如实报 HTTP 状态失败）。
+ * - 可注入 request 便于测试；注入实现负责自己的重定向语义（默认实现才自动跟随）。
+ */
+import { requestOnce } from '../../utils/proxy.js';
+import { zhMsg } from '../../core/messages.js';
+import { deserializeSnapshot, serializeSnapshot } from '../snapshot-json.js';
+import { computeSnapshotMeta, sectionsEqual } from '../transport.js';
+import { parseJsonSafe } from '../../utils/json.js';
+/** 快照 id 安全字符集：字母数字开头，仅 . _ -；防路径穿越与 URL 注入 */
+const SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** 保留 id：与 index.json 冲突（id 'index' 会占用索引文件路径） */
+const RESERVED_IDS = new Set(['index']);
+/**
+ * 默认单请求超时（ms）。WebDAV 上传大快照（含多个分区配置）与读写索引在慢速
+ * 服务器（如坚果云限速、自建 NAS）下较慢，30s 常不够 → 提高至 120s；
+ * 业务侧（makeSyncEngine）还会显式传 timeoutMs 覆盖默认值。
+ */
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** 错误消息里截取的响应体最大长度（防超大/二进制响应撑爆消息） */
+const ERR_BODY_MAX = 500;
+const SNAPSHOTS_SEG = 'dsh-config-manager';
+const INDEX_FILE = 'index.json';
+const REDACTED = '[REDACTED]';
+/** 自动跟随的重定向状态码（RFC 7231/9110） */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** 重定向最大跳数（RFC 7231 建议 ≤5；防 302 循环拖死请求） */
+const MAX_REDIRECTS = 5;
+export class WebDavTransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WebDavTransportError';
+    }
+}
+/** 默认请求实现：node:https/http 原生流式请求（支持全部 WebDAV 方法、准确 Content-Length 与 User-Agent）。
+ * 自动跟随 301/302/303/307/308 重定向（网盘 WebDAV 的 GET/PUT 会 302 到 CDN 预签名直链）：
+ * - 301/302/307/308 保持原方法与请求体；303 且非 GET/HEAD 降级为 GET 并丢弃请求体；
+ * - 相对 Location 用当前 URL 解析；跨源跳转剥离 Authorization（预签名 URL 不应收到 Basic 凭据）；
+ * - 上限 MAX_REDIRECTS 跳，超出抛错；无 Location / Location 非法的 3xx 按最终响应返回。 */
+const defaultRequest = async (method, url, options = {}) => {
+    let currentMethod = method;
+    let currentUrl = url;
+    let currentHeaders = { ...(options.headers ?? {}) };
+    let currentBody = options.body;
+    for (let redirects = 0;;) {
+        const res = await rawRequest(currentMethod, currentUrl, {
+            ...options,
+            headers: currentHeaders,
+            body: currentBody,
+        });
+        const status = res.status;
+        if (!REDIRECT_STATUSES.has(status))
+            return res;
+        // 3xx 但没有 Location（或 Location 非法）→ 无法跟随，作为最终响应返回（上层如实报 HTTP 状态）
+        const rawLocation = res.headers?.location;
+        const location = Array.isArray(rawLocation) ? rawLocation[0] : rawLocation;
+        if (!location)
+            return res;
+        let nextUrl;
+        try {
+            nextUrl = new URL(location, currentUrl).toString();
+        }
+        catch {
+            return res;
+        }
+        if (redirects >= MAX_REDIRECTS) {
+            const err = new Error(`Too many redirects (${MAX_REDIRECTS} max) for ${url}`);
+            err.name = 'RedirectError';
+            throw err;
+        }
+        redirects += 1;
+        // 303：非 GET/HEAD 降级 GET 并丢弃请求体（303 See Other 语义）
+        let nextMethod = currentMethod;
+        let nextHeaders = currentHeaders;
+        let nextBody = currentBody;
+        if (status === 303 && currentMethod !== 'GET' && currentMethod !== 'HEAD') {
+            nextMethod = 'GET';
+            nextBody = undefined;
+        }
+        // 跨源：剥离 Authorization（同源保留，服务器可能按 Basic 认证续用）
+        if (!sameOrigin(currentUrl, nextUrl)) {
+            nextHeaders = { ...currentHeaders };
+            delete nextHeaders.Authorization;
+        }
+        currentMethod = nextMethod;
+        currentUrl = nextUrl;
+        currentHeaders = nextHeaders;
+        currentBody = nextBody;
+    }
+};
+/** 单次裸请求（不跟随重定向）。
+ *
+ * 实现已统一到 `utils/proxy.requestOnce`（issue #30 ②级方案）：同一份实现同时服务 WebDAV 与
+ * GitHub 出站，并在此处获得**插件私有**的代理能力（HTTP 代理 absolute-form / HTTPS 代理 CONNECT
+ * 隧道 + TLS），且不改动任何全局状态。未配置代理时行为与原先的 node:http 直连完全一致。
+ */
+async function rawRequest(method, url, options) {
+    const timeoutMs = options.timeoutMs ?? 0;
+    const headers = {
+        'User-Agent': 'DSH-Config-Manager/0.1.55 (WebDAV Client)',
+        ...(options.headers ?? {}),
+    };
+    if (options.body === undefined) {
+        // 303 降级后已丢弃 body → 清除残留的 Content-Length，避免 GET 带错误长度头
+        delete headers['Content-Length'];
+        delete headers['content-length'];
+    }
+    let res;
+    try {
+        res = await requestOnce({
+            method,
+            url,
+            headers,
+            ...(options.body !== undefined ? { body: options.body } : {}),
+            ...(timeoutMs > 0 ? { timeoutMs } : {}),
+        });
+    }
+    catch (err) {
+        // 超时错误名保持 'TimeoutError'（上层 isTimeout 依赖它做文案归一）
+        if (err instanceof Error && /timed out/i.test(err.message) && err.name !== 'TimeoutError') {
+            const timeoutError = new Error(err.message);
+            timeoutError.name = 'TimeoutError';
+            throw timeoutError;
+        }
+        throw err;
+    }
+    const responseHeaders = {};
+    res.headers.forEach((value, key) => { responseHeaders[key] = value; });
+    return {
+        status: res.status,
+        ok: res.status >= 200 && res.status < 300,
+        headers: responseHeaders,
+        text: async () => res.body.toString('utf8'),
+    };
+}
+/** 同源判断（协议 + host，host 含端口；子域名不同视为跨源） */
+function sameOrigin(a, b) {
+    try {
+        const ua = new URL(a);
+        const ub = new URL(b);
+        return ua.protocol === ub.protocol && ua.host === ub.host;
+    }
+    catch {
+        return false;
+    }
+}
+/** 实现 SyncTransport 的 WebDAV 通道。所有网络操作经 request 注入（缺省 defaultRequest，自动跟随重定向）。 */
+export class WebDavTransport {
+    type = 'webdav';
+    o;
+    constructor(options) {
+        this.o = {
+            baseUrl: '',
+            username: '',
+            credentials: { getPassword: async () => '' },
+            request: defaultRequest,
+            timeoutMs: DEFAULT_TIMEOUT_MS,
+            msg: zhMsg,
+        };
+        this.validateOptions(options);
+        this.o.baseUrl = options.baseUrl;
+        this.o.username = options.username;
+        this.o.credentials = options.credentials;
+        if (options.request !== undefined)
+            this.o.request = options.request;
+        if (options.timeoutMs !== undefined)
+            this.o.timeoutMs = options.timeoutMs;
+        if (options.msg !== undefined)
+            this.o.msg = options.msg;
+    }
+    /** 列出远端已有快照（按 createdAt 升序）。index.json 缺失视为空。 */
+    async list() {
+        const pwd = await this.passwordOnce();
+        const url = this.indexUrl();
+        const res = await this.send('GET', url, pwd);
+        if (res.status === 404)
+            return []; // 缺失视为空
+        if (!res.ok) {
+            throw new WebDavTransportError(await this.failText('GET', url, res, pwd));
+        }
+        return this.parseIndex(await res.text(), url, pwd);
+    }
+    /** 上传快照：幂等 MKCOL → 快照级跳过判定（同 id 且内容全等则免上传）→ PUT <id>.json
+     *  → 合并写回 index.json；返回远端 meta（跳过时）或 computeSnapshotMeta。
+     *  序列化经 snapshot-json：文件类分区字节以 base64 传输（JSON 无法直传 Uint8Array）。 */
+    async upload(snapshot) {
+        this.assertSafeId(snapshot.id);
+        const pwd = await this.passwordOnce();
+        await this.ensureCollection(pwd);
+        // 快照级跳过（增量优化）：先读远端 index，同 id 条目与本地内容全等（sections hash 全等）
+        // → 内容未变，直接返回远端 meta，跳过 PUT 快照文件与 index 写回（幂等契约不变）。
+        // 加密快照（computeSnapshotMeta.sections 为空对象）经 sectionsEqual 判定为「无法比较」
+        // → 必须照常上传，绝不跳过。
+        const meta = computeSnapshotMeta(snapshot);
+        const idxBefore = await this.readIndex(pwd);
+        const existing = idxBefore.find((m) => m.id === snapshot.id);
+        if (existing !== undefined && sectionsEqual(existing, meta)) {
+            return existing;
+        }
+        // 先写快照文件（JSON 序列化：文件字节 base64 编码，往返无损）
+        const snapUrl = this.snapshotUrl(snapshot.id);
+        const snapRes = await this.send('PUT', snapUrl, pwd, { body: serializeSnapshot(snapshot) });
+        if (!snapRes.ok) {
+            throw new WebDavTransportError(await this.failText('PUT', snapUrl, snapRes, pwd));
+        }
+        // 再写合并后的 index（保留其它 id、覆盖同 id）—— meta 最后落盘
+        const idxUrl = this.indexUrl();
+        const merged = idxBefore.filter((m) => m.id !== snapshot.id);
+        merged.push(meta);
+        merged.sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
+        const putIdx = await this.send('PUT', idxUrl, pwd, { body: JSON.stringify(merged) });
+        if (!putIdx.ok) {
+            throw new WebDavTransportError(await this.failText('PUT', idxUrl, putIdx, pwd));
+        }
+        return meta;
+    }
+    /** 下载快照完整载荷。不存在的 id 必须抛错（契约）。 */
+    async download(id) {
+        this.assertSafeId(id);
+        const pwd = await this.passwordOnce();
+        const url = this.snapshotUrl(id);
+        const res = await this.send('GET', url, pwd);
+        if (res.status === 404) {
+            throw new WebDavTransportError(this.o.msg('sync.webdav.snapshotMissing', { id, url }));
+        }
+        if (!res.ok) {
+            throw new WebDavTransportError(await this.failText('GET', url, res, pwd));
+        }
+        return this.parseSnapshot(await res.text(), id);
+    }
+    /** 删除远端快照并从 index 摘除（写回合并后的 index）；文件不存在视为成功。 */
+    async delete(id) {
+        this.assertSafeId(id);
+        const pwd = await this.passwordOnce();
+        const idxUrl = this.indexUrl();
+        // 先读现有 index（不存在 → 空），以便摘除条目
+        let idx = [];
+        try {
+            idx = await this.readIndex(pwd);
+        }
+        catch {
+            idx = []; // index 缺失/损坏时按无条目处理（不阻塞删除）
+        }
+        // delete 快照文件：404 = 不存在，视为成功
+        const url = this.snapshotUrl(id);
+        const res = await this.send('DELETE', url, pwd);
+        if (!res.ok && res.status !== 404) {
+            throw new WebDavTransportError(await this.failText('DELETE', url, res, pwd));
+        }
+        // 若 index 中无该 id，则无需写回
+        const remaining = idx.filter((m) => m.id !== id);
+        if (remaining.length === idx.length && res.status === 404) {
+            return; // 文件与 index 都不存在 → 静默成功，无写回
+        }
+        const putIdx = await this.send('PUT', idxUrl, pwd, { body: JSON.stringify(remaining) });
+        if (!putIdx.ok) {
+            throw new WebDavTransportError(await this.failText('PUT', idxUrl, putIdx, pwd));
+        }
+    }
+    /* ---------------- 内部实现 ---------------- */
+    validateOptions(options) {
+        const msg = options.msg ?? zhMsg;
+        if (typeof options.baseUrl !== 'string' || options.baseUrl.trim() === '') {
+            throw new WebDavTransportError(msg('sync.webdav.baseUrlRequired'));
+        }
+        let parsed;
+        try {
+            parsed = new URL(options.baseUrl);
+        }
+        catch {
+            throw new WebDavTransportError(msg('sync.webdav.baseUrlInvalid', { url: options.baseUrl }));
+        }
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            throw new WebDavTransportError(msg('sync.webdav.baseUrlInvalid', { url: options.baseUrl }));
+        }
+        if (parsed.username !== '' || parsed.password !== '') {
+            throw new WebDavTransportError(msg('sync.webdav.baseUrlUserinfo'));
+        }
+        if (typeof options.username !== 'string' || options.username === '') {
+            throw new WebDavTransportError(msg('sync.webdav.usernameRequired'));
+        }
+        if (options.credentials === null || typeof options.credentials !== 'object'
+            || typeof options.credentials.getPassword !== 'function') {
+            throw new WebDavTransportError(msg('sync.webdav.credentialsRequired'));
+        }
+    }
+    assertSafeId(id) {
+        if (typeof id !== 'string' || !SAFE_ID_RE.test(id) || RESERVED_IDS.has(id)) {
+            throw new WebDavTransportError(this.o.msg('sync.webdav.invalidSnapshotId', { id: JSON.stringify(id) }));
+        }
+    }
+    snapshotsBase() {
+        return `${this.o.baseUrl.replace(/\/+$/, '')}/${SNAPSHOTS_SEG}`;
+    }
+    snapshotsColUrl() {
+        return `${this.snapshotsBase()}/`;
+    }
+    snapshotUrl(id) {
+        return `${this.snapshotsBase()}/${id}.json`;
+    }
+    indexUrl() {
+        return `${this.snapshotsBase()}/${INDEX_FILE}`;
+    }
+    /** 读取一次 password（错误脱敏用） */
+    async passwordOnce() {
+        try {
+            return await this.o.credentials.getPassword();
+        }
+        catch {
+            return '';
+        }
+    }
+    /** 幂等创建 snapshots 集合：MKCOL；已存在（405/2xx/3xx）视为成功。 */
+    async ensureCollection(pwd) {
+        const url = this.snapshotsColUrl();
+        const res = await this.send('MKCOL', url, pwd);
+        const okStatuses = new Set([200, 201, 204, 301, 302, 303, 405]);
+        if (okStatuses.has(res.status))
+            return;
+        throw new WebDavTransportError(await this.failText('MKCOL', url, res, pwd));
+    }
+    /** 读 index（缺失 → []；非法 → 抛错）。 */
+    async readIndex(pwd) {
+        const url = this.indexUrl();
+        const res = await this.send('GET', url, pwd);
+        if (res.status === 404)
+            return [];
+        if (!res.ok) {
+            throw new WebDavTransportError(await this.failText('GET', url, res, pwd));
+        }
+        return this.parseIndex(await res.text(), url, pwd);
+    }
+    parseIndex(raw, url, pwd) {
+        let parsed;
+        try {
+            parsed = parseJsonSafe(raw);
+        }
+        catch (err) {
+            throw new WebDavTransportError(this.o.msg('sync.webdav.indexInvalid', { url, err: this.mask(String(err?.message ?? ''), pwd) }));
+        }
+        if (!Array.isArray(parsed)) {
+            throw new WebDavTransportError(this.o.msg('sync.webdav.indexInvalid', { url, err: 'not an array' }));
+        }
+        const valid = (m) => typeof m === 'object' && m !== null
+            && typeof m.id === 'string'
+            && typeof m.createdAt === 'string'
+            && typeof m.manifest === 'object' && m.manifest !== null
+            && typeof m.sections === 'object' && m.sections !== null;
+        if (!parsed.every(valid)) {
+            throw new WebDavTransportError(this.o.msg('sync.webdav.indexInvalid', { url, err: 'invalid entry' }));
+        }
+        const metas = parsed;
+        metas.sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
+        return metas;
+    }
+    parseSnapshot(raw, id) {
+        try {
+            return deserializeSnapshot(raw);
+        }
+        catch (err) {
+            throw new WebDavTransportError(this.o.msg('sync.webdav.snapshotInvalid', { id, err: this.mask(String(err?.message ?? ''), '') }));
+        }
+    }
+    /** 发送请求：注入 Basic 认证头 + 调用 request；网络错误/超时归一 */
+    async send(method, url, pwd, opts = {}) {
+        const auth = 'Basic ' + Buffer.from(`${this.o.username}:${pwd}`, 'utf8').toString('base64');
+        const headers = {
+            Authorization: auth,
+            'Content-Type': 'application/json',
+            'User-Agent': 'DSH-Config-Manager/0.1.55 (WebDAV Client)',
+        };
+        if (opts.body !== undefined)
+            headers['Content-Length'] = String(Buffer.byteLength(opts.body, 'utf8'));
+        try {
+            return await this.o.request(method, url, { headers, body: opts.body, timeoutMs: this.o.timeoutMs });
+        }
+        catch (err) {
+            if (this.isTimeout(err)) {
+                throw new WebDavTransportError(this.o.msg('sync.webdav.timeout', { method, url, timeout: String(this.o.timeoutMs) }));
+            }
+            if (err instanceof Error && err.name === 'RedirectError') {
+                // 默认 request 的重定向跳数超限（如 302 循环）→ 归一为清晰消息，避免暴露内部跳转详情
+                throw new WebDavTransportError(this.o.msg('sync.webdav.tooManyRedirects', { method, url, n: String(MAX_REDIRECTS) }));
+            }
+            const rawMsg = err instanceof Error
+                ? (err.cause ? `${err.message} (${err.cause.message || err.cause})` : err.message)
+                : String(err);
+            throw new WebDavTransportError(this.o.msg('sync.webdav.requestError', { method, url, err: this.mask(rawMsg, pwd) }));
+        }
+    }
+    /** 构造 HTTP 非 2xx 失败消息：附上脱敏后的响应体片段（截断） */
+    async failText(method, url, res, pwd) {
+        let body = '';
+        try {
+            body = (await res.text()).slice(0, ERR_BODY_MAX);
+        }
+        catch {
+            body = '';
+        }
+        return this.o.msg('sync.webdav.requestFailed', {
+            method,
+            url,
+            status: String(res.status),
+            err: this.mask(body, pwd),
+        });
+    }
+    /** 识别超时错误（AbortController 抛出的 AbortError / DOMException timeout / TimeoutError） */
+    isTimeout(err) {
+        const e = err;
+        const name = e?.name ?? '';
+        if (name === 'TimeoutError')
+            return true;
+        if (name === 'AbortError')
+            return true;
+        if (typeof DOMException !== 'undefined' && err instanceof DOMException && name === 'AbortError')
+            return true;
+        return false;
+    }
+    /** 错误消息脱敏：password（原文与 URL 编码形态）一律替换 */
+    mask(text, pwd) {
+        if (!pwd)
+            return text;
+        let out = text.split(pwd).join(REDACTED);
+        out = out.split(encodeURIComponent(pwd)).join(REDACTED);
+        return out;
+    }
+}
+//# sourceMappingURL=webdav-transport.js.map

package/lib/ui/errors.d.ts

@@ -0,0 +1,19 @@
+import { type UiT } from './i18n.ts';
+/** 可操作错误（UI 渲染为 Reason / Suggested action 两段） */
+export interface ActionableError {
+    title: string;
+    reason: string;
+    suggestedAction?: string;
+    /** 相关项（如 MCP 服务器名 / 插件包名）；可空 */
+    item?: string;
+    /** 是否可重试（true 显示重试按钮） */
+    retryable: boolean;
+}
+/** 将任意错误转换为可操作错误（消息已脱敏，不泄漏 Secret） */
+export declare function toActionableError(err: unknown, opts?: {
+    item?: string;
+    fallbackTitle?: string;
+    t?: UiT;
+}): ActionableError;
+/** 格式化为用户可读的多行文本（Reason / Suggested action） */
+export declare function formatActionableError(e: ActionableError, t?: UiT): string;