dsh-config-manager 0.1.78 → 0.1.80

package/src/client/sync/sync-api.ts

@@ -31,7 +31,7 @@ import type { SyncTransportType as HostSyncTransportType } from '../../sync/sync
 // 云端点通道的**回传视图**（只带 secretStored 布尔，绝无密钥值）：类型直接取宿主声明处，
 // type-only 引用打包时被擦除，不会把 sync-config.ts 的 node:fs 带进浏览器产物。
 import type { CloudGistChannelView, CloudS3ChannelView } from '../../sync/sync-config.ts';
-import type { PlanItemKind, SessionFormatDisposition } from '../../core/types.ts';
+import type { PathMapping, PlanItemKind, SessionFormatDisposition } from '../../core/types.ts';
 import type { SectionId } from '../../schema/types.ts';
 import type { ConsultReport } from '../../core/migration-consult.ts';
 import { getJson, LONG_REQUEST_TIMEOUT_MS, postJson, type RequestOptions } from '../common/http.ts';
@@ -59,6 +59,11 @@ export type SyncTransportType = HostSyncTransportType;
 /** GET /sync/status 响应：配置/凭据/上次同步的只读事实（无任何 secret 值） */
 export interface SyncStatusResponse {
   ok: boolean;
+  /**
+   * 方案 A：是否存在同步基线（本地祖先指针；宿主只回布尔，绝不回快照 id）。
+   * **缺省 undefined = 未知 → 一律按「无基准」处理**，走老导入确认路径（fail-safe）。
+   */
+  hasBaseline?: boolean;
   /** 是否已保存过仓库/通道配置（sync-config.json；任一通道配置过即为 true） */
   configured: boolean;
   /** git 通道：已配置的仓库地址（不含 token，可回显；与当前通道无关，配置过即返回） */
@@ -121,6 +126,8 @@ export interface SyncWorkDirFacts {
   ahead: number | null;
   /** 工作树是否有未提交改动（仅 detail 自检时给出，否则 null） */
   dirty: boolean | null;
+  /** 远端分支上的快照数（仅 detail 自检时给出，否则 null；issue #104 建议 3） */
+  remoteSnapshots: number | null;
 }
 
 /** 同步密码的保存状态（只回布尔；密码值永不回传浏览器）。 */
@@ -286,6 +293,42 @@ export interface SyncPullPayload extends SyncPushPayload {
   decryptPassword?: string;
 }
 
+/* ---------------------------------------------------------------- 连通性自检（cloud-sync 借鉴项 ②） */
+
+/**
+ * POST /sync/probe 结果。
+ *
+ * **失败也是正常返回**（HTTP 200 + \`ok:false\`）：测试连接是**预期会失败**的诊断动作，
+ * 用 5xx 表达会被界面当成基础设施崩溃。\`message\` / \`hint\` 由通道层本地化并脱敏后原样带回。
+ */
+export interface SyncProbeSuccess {
+  ok: true
+  transport: string
+  /** 结论（可直接展示的成功文案） */
+  message: string
+  /** 附加提醒（例如「该 S3 兼容端点应把 region 填成 xxx」），有值时界面按 warn 级展示 */
+  hint?: string
+  /** 远端已有快照数（取得时回传） */
+  snapshotCount?: number
+  /** 自检过程中**自动创建**的远端目录（webdav 幂等 MKCOL；界面须逐条说明，绝不静默写远端） */
+  createdCollections?: string[]
+}
+
+/** 自检失败（诊断动作的预期结果，不是异常） */
+export interface SyncProbeFailure {
+  ok: false
+  error: string
+  /**
+   * **能力边界标记**：该通道不提供连通性自检（传输层未实现 probe）。
+   *
+   * 与故障**严格区分**：true = 这个通道没有这项能力（中性提示，同步功能不受影响）；
+   * 缺省/undefined = 真的没连通（按故障展示）。界面据此选 info 而不是「操作失败」。
+   */
+  unsupported?: boolean
+}
+
+export type SyncProbeResult = SyncProbeSuccess | SyncProbeFailure
+
 /* ---------------------------------------------------------------- 一键同步（方案 A） */
 
 /** GET /sync/snapshots-list 响应：远端历史快照列表（按 createdAt 倒序）。 */
@@ -311,6 +354,14 @@ export interface SyncSnapshotLite {
   sectionCount: number;
   platform: string;
   dshVersion: string;
+  /**
+   * cloud-sync 借鉴项 ⑥：推送方设备身份（宿主从快照 manifest 读出）。
+   * **旧快照没有这两个字段** —— 界面必须据此不显示设备行，绝不把 undefined 渲染成文案、
+   * 也不显示空串占位。
+   */
+  deviceName?: string;
+  /** 稳定设备 id（换主机名/改机器名都不变；用于认出「同一台设备」）。 */
+  deviceId?: string;
 }
 
 /** POST /sync/sync 请求体（一键同步第一步：拉取 → 差异确认会话）。 */
@@ -441,6 +492,111 @@ export interface SyncRollbackFailedItem {
   manualHint?: string;
 }
 
+/* ---------------------------------------------------------------- 远程合并裁决（T-ui-merge） */
+
+/**
+ * 合并冲突成因（对齐宿主 src/sync/merge.ts 的 MergeConflictReason）。
+ * 未在本联合里的字符串照样可能从宿主回传 —— 界面侧一律经 merge-view.ts 的
+ * mergeReasonKey() 映射，未知值按 both-modified 措辞，**绝不渲染裸枚举**。
+ */
+export type MergeConflictReason =
+  | 'both-modified'
+  | 'modify-delete'
+  | 'delete-modify'
+  | 'no-ancestor'
+  | 'binary'
+  | 'format'
+  | 'array'
+  | 'section';
+
+/** 分区级合并决策（'conflict' = 双侧改动重叠，必须由用户裁决）。 */
+export type MergeSectionDecision = 'useRemote' | 'keepLocal' | 'merge' | 'skip' | 'conflict';
+
+/** 单条冲突的三列预览（已由宿主脱敏/序列化，界面负责截断）。 */
+export interface MergePreviewConflict {
+  /** 冲突位置：JSON 分区是 top-level key；FilesSection 是 relativePath。 */
+  path: string;
+  kind: 'key' | 'file';
+  reason?: MergeConflictReason;
+  localPreview: string;
+  remotePreview: string;
+  ancestorPreview: string;
+}
+
+/** 单个分区的合并预览。 */
+export interface MergePreviewSection {
+  id: SectionId;
+  decision: MergeSectionDecision;
+  /** 自动合并并入的变更点数量（仅自动合并成功时有意义） */
+  autoMerged?: number;
+  conflictCount: number;
+  conflicts: MergePreviewConflict[];
+}
+
+/** 预览摘要（可自动应用 / 待裁决 / 冲突条目 / 无变化）。 */
+export interface MergePreviewSummary {
+  auto: number;
+  review: number;
+  conflicts: number;
+  skipped: number;
+}
+
+/** POST /sync/merge-preview 请求体（只读；密码仅内存传输，绝不落盘/落日志）。 */
+export interface MergePreviewPayload {
+  /** 远端快照 id；缺省 = 最新 */
+  snapshotId?: string;
+  /** 解密密码（仅当远端快照加密时使用；缺省 = 已保存的 DECRYPT 凭据） */
+  decryptPassword?: string;
+  /** 跨机路径映射（与一键同步同一口径） */
+  pathMappings?: PathMapping[];
+}
+
+/** POST /sync/merge-preview 响应（只读三方合并结果）。 */
+export interface MergePreviewResponse {
+  ok: boolean;
+  snapshotId: string;
+  /** 是否存在共同基准快照（false = 退化为两方比较，双侧不一致一律按冲突） */
+  hasAncestor: boolean;
+  sections: MergePreviewSection[];
+  summary: MergePreviewSummary;
+  /** 失败/降级原因（仅在 ok=false 等场景出现） */
+  message?: string;
+}
+
+/** 单条裁决动作。 */
+export type MergeResolutionActionWire = 'keepLocal' | 'useRemote' | 'useMerged' | 'skip';
+
+/** 单条裁决：id = 分区 id（分区级）或 `分区id::冲突路径`（冲突级，见 merge-view.ts）。 */
+export interface MergeResolution {
+  id: string;
+  action: MergeResolutionActionWire;
+}
+
+/** POST /sync/apply-merge 请求体（写动作；过 mutation gate）。 */
+export interface MergeApplyPayload extends MergePreviewPayload {
+  resolutions: MergeResolution[];
+}
+
+/** POST /sync/apply-merge 响应（字段与 /sync/apply-items 同风格 + pendingConflicts）。 */
+export interface MergeApplyResponse {
+  ok: boolean;
+  applied: string[];
+  skipped: string[];
+  needsRestart?: boolean;
+  warnings: string[];
+  /** 执行前快照 id（界面一键回滚用） */
+  restoreId?: string;
+  /** 任一失败是否整体回滚 */
+  rolledBack?: boolean;
+  /** 整体回滚是否完整（false = 有项未恢复，见 warnings；缺省 = 旧宿主未回传） */
+  rollbackFull?: boolean;
+  /** 执行后仍待裁决的分区（下次同步仍会出现） */
+  pendingConflicts: SectionId[];
+  failed?: { itemId: string; message?: string }[];
+  ineffective?: { itemId: string; adapter: string; message?: string }[];
+  historyWriteError?: string;
+}
+
 /* ---------------------------------------------------------------- 自动同步 */
 
 /** 统一间隔类型。 */
@@ -449,10 +605,24 @@ export type AutosyncInterval = '5m' | '15m' | '30m' | '60m' | '6h' | '12h' | '24
 /** 最近一次自动同步执行状态。 */
 export type AutosyncRunStatus = 'success' | 'skipped' | 'failed' | 'partial';
 
+/** 自动应用的最高风险等级（low = 只自动落低风险分区；medium = plugins/mcp 也自动落盘）。 */
+export type AutosyncAutoApplyTier = 'low' | 'medium';
+
+/** 双侧都改（真冲突）时的策略（ask = 保留冲突待人工裁决；local = 保留本机并推上去）。 */
+export type AutosyncConflictPolicy = 'ask' | 'local';
+
 /** GET/POST /sync/autosync 响应：自动同步状态。 */
 export interface AutosyncStatusResponse {
   enabled: boolean;
   interval: AutosyncInterval;
+  /** 真·自动同步：本地改动即时触发（缺省 true；host 读取层已补缺省） */
+  realtime?: boolean;
+  /** realtime 下的远端轮询间隔（ms；缺省 60000） */
+  remoteCheckMs?: number;
+  /** 自动应用的最高风险等级（缺省 medium：plugins/mcp 也自动落盘） */
+  autoApplyTier?: AutosyncAutoApplyTier;
+  /** 双侧都改时的策略（缺省 local：保留本机并推上去） */
+  conflictPolicy?: AutosyncConflictPolicy;
   lastRunAt?: string;
   lastRunStatus?: AutosyncRunStatus;
   lastRunMessage?: string;
@@ -477,6 +647,14 @@ export interface AutosyncUpdatePayload {
   enabled: boolean;
   interval?: AutosyncInterval;
   startupMinIntervalMs?: number;
+  /** 本地改动即时触发（缺省 true） */
+  realtime?: boolean;
+  /** realtime 下的远端轮询间隔（ms；宿主 clamp 到 15s–1h） */
+  remoteCheckMs?: number;
+  /** 自动应用等级（缺省 medium） */
+  autoApplyTier?: AutosyncAutoApplyTier;
+  /** 冲突策略（缺省 local） */
+  conflictPolicy?: AutosyncConflictPolicy;
 }
 
 /* ---------------------------------------------------------------- 同步历史 */
@@ -614,14 +792,26 @@ export class SyncApi {
    * 重建 git 工作副本（issue #79 的自救入口）。
    *
    * - `relink`：只把 origin / push URL 重指向当前配置地址（非破坏性，不碰工作树与本地提交）；
+   * - `adopt`：把当前地址的远端历史合并进工作副本（issue #104：换仓库 / 远端历史被重写后两条历史
+   *   不相交，pull --ff-only 永远失败）。不改写本地提交、可 `git revert`，冲突由 host 自动 `merge --abort`；
    * - `reclone`：删除工作副本后重新 clone（**丢弃未上行的本地提交**）→ 必须带 `confirm: true`。
    *
    * 写动作：host 侧过 mutation gate（SAFE MODE / 环境锁）。
    */
-  async workdirReset(payload: { mode: 'relink' | 'reclone'; confirm?: boolean }): Promise<{ ok: boolean; mode: string; workDir: { facts: SyncWorkDirFacts } }> {
+  async workdirReset(payload: { mode: 'relink' | 'adopt' | 'reclone'; confirm?: boolean }): Promise<{ ok: boolean; mode: string; workDir: { facts: SyncWorkDirFacts } }> {
     return postJson<{ ok: boolean; mode: string; workDir: { facts: SyncWorkDirFacts } }>(SYNC_API.workdirReset, payload, this.t, SYNC_OPTS);
   }
 
+  /**
+   * cloud-sync 借鉴项 ②：连通性自检（**只读**）。
+   *
+   * 失败回 \`ok:false\` 而非抛错 —— 调用方必须按 \`result.ok\` 分流，把失败当**结论**展示，
+   * 不要落进 catch（否则「连不上」会被渲染成崩溃）。
+   */
+  async probe(payload: SyncPushPayload): Promise<SyncProbeResult> {
+    return postJson<SyncProbeResult>(SYNC_API.probe, payload, this.t, SYNC_OPTS);
+  }
+
   /**
    * 分区条目清单（复用 /export-preview；**只读**，不写任何内容）。
    *
@@ -777,6 +967,26 @@ export class SyncApi {
     return postJson<SyncRollbackResponse>(SYNC_API.rollback, payload, this.t, SYNC_OPTS);
   }
 
+  /**
+   * T-ui-merge：远程合并**只读**预览（三方合并 + 冲突清单 + 摘要），零写入。
+   *
+   * 与 /sync/sync 的区别：这里不做导入计划、不登记同步会话，只回答「远端与本地差在哪、
+   * 哪些分区需要我裁决」；密码只在请求体内传输（宿主绝不回传/落日志）。
+   */
+  async mergePreview(payload: MergePreviewPayload = {}): Promise<MergePreviewResponse> {
+    return postJson<MergePreviewResponse>(SYNC_API.mergePreview, payload, this.t, SYNC_OPTS);
+  }
+
+  /**
+   * T-ui-merge：按逐项裁决执行合并（写动作，宿主侧过 mutation gate）。
+   *
+   * 返回 pendingConflicts = 执行后**仍**待裁决的分区：界面据此告诉用户
+   * 「跳过 ≠ 已解决，下次同步仍会出现」，而不是把一次带 skip 的执行报成「已解决」。
+   */
+  async applyMerge(payload: MergeApplyPayload): Promise<MergeApplyResponse> {
+    return postJson<MergeApplyResponse>(SYNC_API.applyMerge, payload, this.t, SYNC_OPTS);
+  }
+
   /** Phase 7 迁移前咨询（只读健康评分 + 建议）：对远端快照生成咨询报告。 */
   async consult(input: { type: 'remote-snapshot'; id: string; snapshotId?: string }): Promise<ConsultReport> {
     return postJson<ConsultReport>(CONFIG_MANAGER_API.consult, input, this.t, SYNC_OPTS);

package/src/client/sync/sync-entry.test.ts

@@ -0,0 +1,78 @@
+/**
+ * 方案 A 入口编排单测（node:test，零依赖）：只发**一次**预览请求 + fail-safe 回退。
+ * 重点不是「happy path」，而是三条**绝不挡老路径**的判据：无基准、请求抛错、宿主 ok=false。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolveSmartSync } from './sync-entry.ts'
+import type { MergePreviewResponse, SyncApi } from './sync-api.ts'
+
+/** 假 api：只记录 mergePreview 的调用次数（其余成员本测试用不到）。 */
+function fakeApi(result: MergePreviewResponse | Error): { api: SyncApi; calls: () => number } {
+  let calls = 0
+  const api = {
+    mergePreview: async (): Promise<MergePreviewResponse> => {
+      calls += 1
+      if (result instanceof Error) throw result
+      return result
+    },
+  } as unknown as SyncApi
+  return { api, calls: () => calls }
+}
+
+function preview(overrides: Partial<MergePreviewResponse> = {}): MergePreviewResponse {
+  return {
+    ok: true,
+    snapshotId: 'snap-1',
+    hasAncestor: true,
+    sections: [{ id: 'settings', decision: 'conflict', conflictCount: 1, conflicts: [] }],
+    summary: { auto: 0, review: 1, conflicts: 1, skipped: 0 },
+    ...overrides,
+  }
+}
+
+const deps = (api: SyncApi, hasBaseline: unknown, decryptPassword?: string) => ({
+  api,
+  hasBaseline,
+  channelPayload: () => ({}),
+  ...(decryptPassword === undefined ? {} : { decryptPassword }),
+})
+
+test('sync-entry: 无基准（含未知/缺省）→ fallback，且**零请求**（行为与方案 A 之前逐字一致）', async () => {
+  for (const hasBaseline of [undefined, false, null, 'true', 1]) {
+    const { api, calls } = fakeApi(preview())
+    const out = await resolveSmartSync(deps(api, hasBaseline))
+    assert.deepEqual(out, { kind: 'fallback' }, 'hasBaseline=' + String(hasBaseline))
+    assert.equal(calls(), 0, '无基准时不得发预览请求')
+  }
+})
+
+test('sync-entry: 有基准 + 有变更 → merge，且**只请求一次**并原样复用该 preview', async () => {
+  const seeded = preview()
+  const { api, calls } = fakeApi(seeded)
+  const out = await resolveSmartSync(deps(api, true))
+  assert.equal(out.kind, 'merge')
+  assert.equal(calls(), 1, '预览只取一次（视图不得二次请求）')
+  assert.equal(out.kind === 'merge' ? out.preview : null, seeded, '复用同一次结果（同一引用）')
+})
+
+test('sync-entry: 有基准 + 全 skip → upToDate（提示已是最新，不写任何东西）', async () => {
+  const { api, calls } = fakeApi(preview({ sections: [{ id: 'settings', decision: 'skip', conflictCount: 0, conflicts: [] }] }))
+  assert.deepEqual(await resolveSmartSync(deps(api, true)), { kind: 'upToDate' })
+  assert.equal(calls(), 1)
+})
+
+test('sync-entry: 预览请求抛错 → fallback + 错误文本（新入口绝不挡住老路径）', async () => {
+  const { api, calls } = fakeApi(new Error('network down'))
+  const out = await resolveSmartSync(deps(api, true))
+  assert.equal(out.kind, 'fallback')
+  assert.equal(out.kind === 'fallback' ? out.error : null, 'network down')
+  assert.equal(calls(), 1)
+})
+
+test('sync-entry: 宿主 ok=false → fallback + 宿主 message（如实带出原因，不回退成静默）', async () => {
+  const { api } = fakeApi(preview({ ok: false, sections: [], message: '远端没有快照' }))
+  const out = await resolveSmartSync(deps(api, true))
+  assert.deepEqual(out, { kind: 'fallback', error: '远端没有快照' })
+})

package/src/client/sync/sync-entry.ts

@@ -0,0 +1,53 @@
+/**
+ * 方案 A 的「一键同步」入口编排（宿主调用 + 结果归类）。
+ *
+ * 分工：**决策**是纯函数（merge-view.ts 的 `decideSyncEntry()`，判据在那里冻结）；
+ * 本文件只负责「按需发**一次** /sync/merge-preview + 把结果归成三类」，让 SyncPanel 保持装配层。
+ * 单独成文件的第二个理由：fail-safe 回退（无基准 / 请求失败 / ok=false 一律回老导入确认路径）
+ * 是最需要单测的地方，而组件层在本仓库没有测试框架（见 AGENTS.md）。
+ */
+import { decideSyncEntry, hasMergeBaseline } from './merge-view.ts'
+import type { MergePreviewResponse, SyncApi, SyncPushPayload } from './sync-api.ts'
+
+export interface SmartSyncDeps {
+  api: SyncApi
+  /** /sync/status 的 hasBaseline；unknown = 缺省/旧宿主（一律按无基准走老路径） */
+  hasBaseline: unknown
+  /** 通道请求体（含 transport / 地址 / 凭据引用；与 push/pull 同源） */
+  channelPayload: () => SyncPushPayload
+  /** 解密密码（可选，仅内存） */
+  decryptPassword?: string
+}
+
+/**
+ * 分派结果：
+ *  - 'fallback'：走老路径（`runSync()` 导入确认）。可能带 error（预览请求失败或宿主 ok=false）；
+ *  - 'merge'   ：打开裁决视图，**复用本次 preview**（调用方不得再请求一次）；
+ *  - 'upToDate'：全部 skip / 无分区 → 提示「已是最新」，零写入。
+ */
+export type SmartSyncOutcome =
+  | { kind: 'merge'; preview: MergePreviewResponse }
+  | { kind: 'upToDate' }
+  | { kind: 'fallback'; error?: string }
+
+/**
+ * 解析本次一键同步该走哪条路。**无基准时不发任何请求**（行为与方案 A 之前逐字一致）。
+ * 预览请求失败绝不抛：转成 'fallback' + error 文本，由调用方 toast 后继续走老路径。
+ */
+export async function resolveSmartSync(deps: SmartSyncDeps): Promise<SmartSyncOutcome> {
+  // 判据与 decideSyncEntry 的第一条**同源**（hasMergeBaseline）；这里提前返回只是为了不发请求
+  if (!hasMergeBaseline(deps.hasBaseline)) return { kind: 'fallback' }
+  const password = deps.decryptPassword !== undefined && deps.decryptPassword !== ''
+    ? { decryptPassword: deps.decryptPassword }
+    : {}
+  try {
+    const preview = await deps.api.mergePreview({ ...deps.channelPayload(), ...password })
+    const decision = decideSyncEntry(deps.hasBaseline, preview)
+    if (decision === 'merge') return { kind: 'merge', preview }
+    if (decision === 'upToDate') return { kind: 'upToDate' }
+    // ok === false：宿主明确说预览没产出（例如远端没有快照）→ 老路径 + 如实带出原因
+    return { kind: 'fallback', ...(preview.message !== undefined ? { error: preview.message } : {}) }
+  } catch (err) {
+    return { kind: 'fallback', error: err instanceof Error ? err.message : String(err) }
+  }
+}