@logictan/dsh-config-manager 0.1.60

package/src/sync/transport.ts

@@ -0,0 +1,118 @@
+/**
+ * m-sync-transport：SyncTransport 抽象层。
+ * 纯类型 + 纯 helper，零副作用、零 fs —— 传输通道实现（git 等）由后续波次提供。
+ * 与核心引擎同原则：只依赖 src/schema/types.ts 的纯类型，不 import 任何 DSH 运行时包。
+ */
+import type { EncryptionInfo, Manifest, SectionData, SectionId } from '../schema/types.ts';
+import { hashSection } from './sync-state.ts';
+
+/** manifest 摘要：快照列表展示 / 变更判断所需的轻量来源信息 */
+export interface ManifestSummary {
+  schemaVersion: number;
+  dshVersion: string;
+  platform: string;
+  /** 快照包含的分区（按 manifest.sections 中为 true 的键） */
+  sectionIds: SectionId[];
+  containsSecrets: boolean;
+  /** 快照是否加密（sections 为 EncryptedSections 密文载荷）；缺省 false（旧快照兼容） */
+  encrypted?: boolean;
+  /** 产生该快照的同步通道（git / webdav；供同步历史展示触发来源；旧快照缺省 undefined） */
+  transport?: string;
+}
+
+/** 快照元信息：list() 条目 / upload() 返回值 */
+export interface SyncSnapshotMeta {
+  id: string;
+  createdAt: string; // ISO-8601 UTC
+  /** 各分区内容 hash（sectionId → hashSection 结果），用于变更检测。
+   *  加密快照的 sections 为密文载荷，不参与明文 hash 比较 → 空对象。 */
+  sections: Partial<Record<SectionId, string>>;
+  manifest: ManifestSummary;
+}
+
+/** 加密快照的 sections 载荷：整个明文 sections 对象序列化后整体加密（AES-256-GCM）。 */
+export interface EncryptedSections {
+  encrypted: {
+    /** 加密参数（salt/iv/authTag base64；与 security/encryption.ts 的 EncryptionInfo 对齐） */
+    info: EncryptionInfo;
+    /** base64：带 DSC1 头的密文（明文 = 序列化的 sections Record） */
+    data: string;
+  };
+}
+
+/** 快照载荷：upload() 入参 / download() 返回 */
+export interface SyncSnapshot {
+  id: string;
+  createdAt: string; // ISO-8601 UTC
+  manifest: ManifestSummary;
+  /** JSON 分区数据 + 文件类分区（FilesSection）；加密快照为 EncryptedSections 密文载荷 */
+  sections: Partial<Record<SectionId, SectionData>> | EncryptedSections;
+}
+
+/**
+ * 远端快照传输通道契约。
+ * 实现约定：同 id 重复 upload 视为覆盖（幂等友好）；download 对不存在的 id 必须抛错。
+ */
+export interface SyncTransport {
+  readonly type: string;
+  /** 列出远端已有快照（按 createdAt 升序） */
+  list(): Promise<SyncSnapshotMeta[]>;
+  /** 上传快照，返回其元信息（含各分区 hash） */
+  upload(snapshot: SyncSnapshot): Promise<SyncSnapshotMeta>;
+  /** 下载快照完整载荷 */
+  download(id: string): Promise<SyncSnapshot>;
+  /** 删除远端快照（不存在视为成功） */
+  delete(id: string): Promise<void>;
+}
+
+/** 由快照计算元信息：sections hash 记录 + manifest 摘要透传。
+ *  加密快照（sections 为密文载荷）→ sections hash 记录为空（密文无法与本地明文比较）。 */
+export function computeSnapshotMeta(snapshot: SyncSnapshot): SyncSnapshotMeta {
+  const sections: SyncSnapshotMeta['sections'] = {};
+  if (!isEncryptedSections(snapshot.sections)) {
+    for (const [id, data] of Object.entries(snapshot.sections)) {
+      sections[id as SectionId] = hashSection(data as SectionData);
+    }
+  }
+  return { id: snapshot.id, createdAt: snapshot.createdAt, sections, manifest: snapshot.manifest };
+}
+
+/** 判定远端索引条目与本地快照「内容相同」（快照级跳过判定，供 webdav 通道增量上传用）：
+ *  仅比较各分区内容 hash（sections 全等），不比较 createdAt / manifest 摘要
+ *  （同 id 重复上传但内容未变 → 视为幂等覆盖，无需重新 PUT 载荷）。
+ *  - 本地 sections 为空对象（加密快照：密文无法与远端明文 hash 比较）→ 返回 false，
+ *    「无法比较」必须照常上传，绝不跳过；
+ *  - 键集合与每个键的 hash 值全部相等 → true；否则 false。
+ */
+export function sectionsEqual(remote: SyncSnapshotMeta, local: SyncSnapshotMeta): boolean {
+  const r = remote.sections;
+  const l = local.sections;
+  if (Object.keys(l).length === 0) return false; // 本地为空（加密快照）→ 无法比较
+  if (Object.keys(r).length !== Object.keys(l).length) return false;
+  for (const key of Object.keys(r)) {
+    if (r[key as SectionId] !== l[key as SectionId]) return false;
+  }
+  return true;
+}
+
+/** 判定 sections 是否为加密密文载荷（duck-typing：含 encrypted.info + encrypted.data 字符串）。 */
+export function isEncryptedSections(sections: unknown): sections is EncryptedSections {
+  if (sections === null || typeof sections !== 'object') return false;
+  const enc = (sections as { encrypted?: unknown }).encrypted;
+  if (enc === null || typeof enc !== 'object') return false;
+  const e = enc as { info?: unknown; data?: unknown };
+  return typeof e.data === 'string' && e.data !== '' && e.info !== null && typeof e.info === 'object';
+}
+
+/** 从导出 Manifest 提取摘要 */
+export function manifestSummaryFrom(manifest: Manifest): ManifestSummary {
+  return {
+    schemaVersion: manifest.schemaVersion,
+    dshVersion: manifest.source.dshVersion,
+    platform: manifest.source.platform,
+    sectionIds: Object.entries(manifest.sections)
+      .filter(([, included]) => included)
+      .map(([id]) => id) as SectionId[],
+    containsSecrets: manifest.security.containsSecrets,
+  };
+}

package/src/sync/ui-prefs.test.ts

@@ -0,0 +1,152 @@
+/**
+ * ui-prefs 测试：ui-prefs.json 读写往返、缺省值、损坏 JSON 回退缺省、非法通道值忽略、
+ * Star 引导弹窗状态字段往返与非法值忽略、updateUiPrefs 局部原子更新不互相覆盖。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  defaultUiPrefs, readUiPrefs, writeUiPrefs, updateUiPrefs,
+  UI_PREFS_FILE, UI_PREFS_SCHEMA_VERSION,
+} from './ui-prefs.ts';
+
+test('writeUiPrefs + readUiPrefs：写入通道 → 读回一致 + 原始文件校验', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ui-prefs-rt-'));
+  try {
+    await writeUiPrefs(dir, { schemaVersion: 1, lastSyncChannel: 'webdav' });
+    const prefs = await readUiPrefs(dir);
+    assert.equal(prefs.lastSyncChannel, 'webdav');
+    const raw = JSON.parse(await fs.readFile(path.join(dir, UI_PREFS_FILE), 'utf8'));
+    assert.equal(raw.schemaVersion, UI_PREFS_SCHEMA_VERSION);
+    assert.equal(raw.lastSyncChannel, 'webdav');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('writeUiPrefs：无通道 → 文件不写 lastSyncChannel 字段', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ui-prefs-none-'));
+  try {
+    await writeUiPrefs(dir, defaultUiPrefs());
+    const raw = JSON.parse(await fs.readFile(path.join(dir, UI_PREFS_FILE), 'utf8'));
+    assert.equal(raw.schemaVersion, UI_PREFS_SCHEMA_VERSION);
+    assert.equal('lastSyncChannel' in raw, false, '未配置通道不落字段');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readUiPrefs：文件不存在 → 缺省（无通道）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ui-prefs-default-'));
+  try {
+    const prefs = await readUiPrefs(dir);
+    assert.equal(prefs.lastSyncChannel, undefined);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readUiPrefs：损坏 JSON → 回退缺省', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ui-prefs-corrupt-'));
+  try {
+    await fs.writeFile(path.join(dir, UI_PREFS_FILE), '{not-json', 'utf8');
+    const prefs = await readUiPrefs(dir);
+    assert.equal(prefs.lastSyncChannel, undefined);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readUiPrefs：不支持的 schemaVersion → 回退缺省', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ui-prefs-schema-'));
+  try {
+    await fs.writeFile(
+      path.join(dir, UI_PREFS_FILE),
+      JSON.stringify({ schemaVersion: 99, lastSyncChannel: 'git' }),
+      'utf8',
+    );
+    const prefs = await readUiPrefs(dir);
+    assert.equal(prefs.lastSyncChannel, undefined);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readUiPrefs：非法通道值 → 忽略（回退缺省）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ui-prefs-bad-'));
+  try {
+    await fs.writeFile(
+      path.join(dir, UI_PREFS_FILE),
+      JSON.stringify({ schemaVersion: 1, lastSyncChannel: 'ftp' }),
+      'utf8',
+    );
+    const prefs = await readUiPrefs(dir);
+    assert.equal(prefs.lastSyncChannel, undefined, '非 git/webdav 值被忽略');
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('Star 引导状态：写入三字段 → 读回一致 + 原始文件校验', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ui-prefs-star-'));
+  try {
+    await writeUiPrefs(dir, {
+      schemaVersion: 1,
+      starPromptFirstSeenAt: 1700000000000,
+      starPromptDismissed: false,
+      starPromptClicked: true,
+    });
+    const prefs = await readUiPrefs(dir);
+    assert.equal(prefs.starPromptFirstSeenAt, 1700000000000);
+    assert.equal(prefs.starPromptDismissed, undefined, 'false 不落字段');
+    assert.equal(prefs.starPromptClicked, true);
+    const raw = JSON.parse(await fs.readFile(path.join(dir, UI_PREFS_FILE), 'utf8'));
+    assert.equal(raw.starPromptFirstSeenAt, 1700000000000);
+    assert.equal('starPromptDismissed' in raw, false, 'false 不写字段');
+    assert.equal(raw.starPromptClicked, true);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('readUiPrefs：Star 字段非法值（字符串时间戳 / 非布尔）→ 忽略', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ui-prefs-star-bad-'));
+  try {
+    await fs.writeFile(
+      path.join(dir, UI_PREFS_FILE),
+      JSON.stringify({ schemaVersion: 1, starPromptFirstSeenAt: 'yesterday', starPromptDismissed: 'yes' }),
+      'utf8',
+    );
+    const prefs = await readUiPrefs(dir);
+    assert.equal(prefs.starPromptFirstSeenAt, undefined);
+    assert.equal(prefs.starPromptDismissed, undefined);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('updateUiPrefs：局部补丁合并，不覆盖未涉及的字段（防多端点互覆盖）', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ui-prefs-upd-'));
+  try {
+    await writeUiPrefs(dir, { schemaVersion: 1, lastSyncChannel: 'webdav' });
+    // star-prompt 端点更新：只补弹窗字段，lastSyncChannel 必须保留
+    const next = await updateUiPrefs(dir, { starPromptFirstSeenAt: 1700000000000, starPromptClicked: true });
+    assert.equal(next.lastSyncChannel, 'webdav', '未涉及的 lastSyncChannel 保留');
+    assert.equal(next.starPromptFirstSeenAt, 1700000000000);
+    assert.equal(next.starPromptClicked, true);
+    // sync/ui-prefs 端点更新：只补通道字段，弹窗字段必须保留
+    const after = await updateUiPrefs(dir, { lastSyncChannel: 'git' });
+    assert.equal(after.lastSyncChannel, 'git');
+    assert.equal(after.starPromptFirstSeenAt, 1700000000000, '未涉及的 Star 字段保留');
+    assert.equal(after.starPromptClicked, true);
+    // 磁盘最终态
+    const raw = JSON.parse(await fs.readFile(path.join(dir, UI_PREFS_FILE), 'utf8'));
+    assert.equal(raw.lastSyncChannel, 'git');
+    assert.equal(raw.starPromptFirstSeenAt, 1700000000000);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+
+test('更新内容弹窗状态：写入字段 → 读回一致 + 原始文件校验', async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-ui-prefs-rn-'));
+  try {
+    await writeUiPrefs(dir, {
+      schemaVersion: 1,
+      releaseNotesLastSeenVersion: '0.1.54',
+      releaseNotesDismissed: true,
+    });
+    const prefs = await readUiPrefs(dir);
+    assert.equal(prefs.releaseNotesLastSeenVersion, '0.1.54');
+    assert.equal(prefs.releaseNotesDismissed, true);
+    const raw = JSON.parse(await fs.readFile(path.join(dir, UI_PREFS_FILE), 'utf8'));
+    assert.equal(raw.releaseNotesLastSeenVersion, '0.1.54');
+    assert.equal(raw.releaseNotesDismissed, true);
+  } finally { await fs.rm(dir, { recursive: true, force: true }); }
+});
+

package/src/sync/ui-prefs.ts

@@ -0,0 +1,135 @@
+/**
+ * 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.ts';
+import { atomicWriteFile } from '../utils/atomic-write.ts';
+
+export const UI_PREFS_FILE = 'ui-prefs.json';
+export const UI_PREFS_SCHEMA_VERSION = 1;
+
+/** 同步通道类型（与 sync-selection / sync-config 共享语义；避免循环 import 自行声明） */
+export type UiPrefsChannel = 'git' | 'webdav';
+
+/** 插件自身 UI 偏好（持久化面）。 */
+export interface UiPrefs {
+  schemaVersion: number;
+  /** 用户上次选择的同步通道；未配置为 undefined */
+  lastSyncChannel?: UiPrefsChannel;
+  /** Star 引导弹窗：首次进入页面时间（ms 时间戳）；未配置 = 尚未进入过页面 */
+  starPromptFirstSeenAt?: number;
+  /** Star 引导弹窗：用户点过「不再提示」（永久不再弹） */
+  starPromptDismissed?: boolean;
+  /** Star 引导弹窗：用户点过「去点 Star」（方案 A：引导完成，不再弹） */
+  starPromptClicked?: boolean;
+  /** 更新内容弹窗：上次已记录/展示过的插件版本号（如 '0.1.54'） */
+  releaseNotesLastSeenVersion?: string;
+  /** 更新内容弹窗：用户点过「永不提示」（永久不再自动弹出） */
+  releaseNotesDismissed?: boolean;
+}
+
+/** 缺省配置（首次无文件 / 损坏 / 不支持 schema 时回退） */
+export function defaultUiPrefs(): UiPrefs {
+  return { schemaVersion: UI_PREFS_SCHEMA_VERSION };
+}
+
+/** 读取 UI 偏好；文件不存在 / 损坏 / 不支持 schema → 缺省值（不抛错）。 */
+export async function readUiPrefs(dir: string): Promise<UiPrefs> {
+  const file = path.join(dir, UI_PREFS_FILE);
+  let raw: string;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch {
+    return defaultUiPrefs();
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseJsonSafe(raw);
+  } catch {
+    return defaultUiPrefs();
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return defaultUiPrefs();
+  }
+  const obj = parsed as Record<string, unknown>;
+  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: string, prefs: UiPrefs): Promise<void> {
+  await fs.mkdir(dir, { recursive: true });
+  const payload: Record<string, unknown> = {
+    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: string, patch: UiPrefsPatch): Promise<UiPrefs> {
+  const current = await readUiPrefs(dir);
+  const next: UiPrefs = { ...current, ...patch };
+  await writeUiPrefs(dir, next);
+  return next;
+}
+
+/** updateUiPrefs 的补丁类型（UiPrefs 全部可选字段，schemaVersion 不可补丁）。 */
+export type UiPrefsPatch = Partial<Omit<UiPrefs, 'schemaVersion'>>;