dsh-config-manager 0.1.12 → 0.1.13

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

@@ -0,0 +1,132 @@
+/**
+ * 远程同步浏览器半 —— `/api/dsh-config-manager/sync/*` 的类型化 fetch 封装。
+ *
+ * 独立于 `../api.ts`（ConfigManagerApi 为并行会话已改文件，禁碰）：本文件自持
+ * 端点常量与 readJson/postJson 小工具（与 api.ts 同款模式），只新增不修改。
+ *
+ * 端点契约（Host 半 src/index.ts 的 makeRoutes 按此实现）：
+ * ```
+ * GET  /api/dsh-config-manager/sync/status → SyncStatusResponse （配置/凭据/上次同步）
+ * POST /api/dsh-config-manager/sync/push    → SyncPushReport    （body: { repoUrl, gitBin?, token?, snapshotId? }）
+ * POST /api/dsh-config-manager/sync/pull    → SyncPullReport    （body: { repoUrl, gitBin?, token?, strategy?, snapshotId? }）
+ * ```
+ *
+ * 安全约束：
+ *  - token 只存在于请求体内（同源 loopback，与导入 secretInputs 同策略），由 Host 写入
+ *    DSH credentials（credentialRef），绝不落同步文件/日志/URL；响应永不回传 token；
+ *  - 错误消息由 Host 侧已脱敏（GitTransport 统一 [REDACTED]），UI 侧再经 ErrorBanner redact 兜底；
+ *  - 本文件不 import 任何 node 模块（纯浏览器 bundle；sync-engine 仅作 type-only 引用）。
+ */
+import type { SyncPullReport, SyncPushReport } from '../../sync/sync-engine.ts';
+import { ConfigManagerApiError } from '../api.ts';
+
+/** 同步端点常量（与 Host 半 src/index.ts API 常量保持一致） */
+export const SYNC_API = {
+  base: '/api/dsh-config-manager/sync',
+  status: '/api/dsh-config-manager/sync/status',
+  push: '/api/dsh-config-manager/sync/push',
+  pull: '/api/dsh-config-manager/sync/pull',
+} as const;
+
+/** DSH credentials 中的同步 token 引用名（Host 半同值；仅供提示文案使用，值由 Host 读写） */
+export const SYNC_CREDENTIAL_REF = 'DSH_CONFIG_MANAGER_SYNC_TOKEN';
+
+/** GET /sync/status 响应：配置/凭据/上次同步的只读事实（无任何 secret 值） */
+export interface SyncStatusResponse {
+  ok: boolean;
+  /** 是否已保存过仓库配置（sync-config.json） */
+  configured: boolean;
+  /** 上次使用的仓库地址（不含 token，可回显） */
+  repoUrl?: string;
+  gitBin?: string;
+  /** DSH credentials 中是否已存在 token（describe 只报状态，值永不返回） */
+  credentialConfigured: boolean;
+  credentialWritable: boolean;
+  /** sync-state.lastSyncAt；'' = 从未同步 */
+  lastSyncAt?: string;
+  /** sync-state.sections 条目数 */
+  sectionCount: number;
+  transport?: { type: string; ref: string };
+}
+
+/** push 请求体（token 可选：非空则 Host 先写入 DSH credentials 再使用） */
+export interface SyncPushPayload {
+  repoUrl: string;
+  gitBin?: string;
+  token?: string;
+}
+
+/** pull 请求体（strategy 缺省 merge：冲突保留待决策；snapshotId 缺省 = 最新） */
+export interface SyncPullPayload extends SyncPushPayload {
+  strategy?: 'merge' | 'replace' | 'skipExisting';
+  snapshotId?: string;
+}
+
+/** 同步请求超时（ms）：与 Host 半 ROUTE_TIMEOUT_MS 对齐（git 网络操作可能较慢） */
+const SYNC_TIMEOUT_MS = 5 * 60 * 1000;
+
+/** 解析 JSON 响应；非 2xx 时抛出带路由 error 消息的 ConfigManagerApiError（与 api.ts 同款） */
+async function readJson<T>(response: Response): Promise<T> {
+  const notMountedMessage =
+    'config-manager 服务未挂载（插件未加载）：请确认 profile 中已安装 dsh-config-manager 并重启 DSH';
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch {
+    if (response.status === 404) throw new ConfigManagerApiError(notMountedMessage);
+    throw new ConfigManagerApiError(`HTTP ${response.status}: invalid JSON response`);
+  }
+  if (!response.ok) {
+    const message =
+      typeof body === 'object' && body !== null && typeof (body as { error?: unknown }).error === 'string'
+        ? (body as { error: string }).error
+        : response.status === 404
+          ? notMountedMessage
+          : `HTTP ${response.status}`;
+    throw new ConfigManagerApiError(message);
+  }
+  return body as T;
+}
+
+/** POST JSON 请求（带超时：宿主卡死时 UI 拿到明确错误而不是永远转圈） */
+async function postJson<T>(path: string, body: unknown): Promise<T> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), SYNC_TIMEOUT_MS);
+  try {
+    const response = await fetch(path, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    return await readJson<T>(response);
+  } catch (err) {
+    if (controller.signal.aborted) {
+      throw new ConfigManagerApiError(
+        `同步请求超时（${Math.round(SYNC_TIMEOUT_MS / 60000)} 分钟）：请检查网络与仓库可达性后重试`,
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** 远程同步浏览器半数据入口（settings.section: config-manager-sync 的注入业务面） */
+export class SyncApi {
+  /** 读取同步状态（配置 / 凭据 / 上次同步时间 / 分区数） */
+  async status(): Promise<SyncStatusResponse> {
+    const response = await fetch(SYNC_API.status);
+    return readJson<SyncStatusResponse>(response);
+  }
+
+  /** 推送：导出 portable 分区 → 提交到私有 Git 仓库 → 更新 sync-state */
+  async push(payload: SyncPushPayload): Promise<SyncPushReport> {
+    return postJson<SyncPushReport>(SYNC_API.push, payload);
+  }
+
+  /** 拉取差异预览：拉取远端最新快照 → 只读分析（绝不执行导入） */
+  async pull(payload: SyncPullPayload): Promise<SyncPullReport> {
+    return postJson<SyncPullReport>(SYNC_API.pull, payload);
+  }
+}

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

@@ -0,0 +1,77 @@
+/**
+ * 远程同步设置区块（config-manager-sync）表面文案：zh 为源语言，en 镜像每个键。
+ * 独立命名空间、独立文件：不触碰共享的 locales.ts（并行会话已改），零冲突。
+ * 键集合经 `SyncKey` 类型在 client/index.ts 注册处做编译期校验。
+ */
+
+export const zh = {
+  // 入口
+  'section.label': '远程同步',
+  'section.description': '通过 Git 私有仓库在设备间同步可移植配置（secret 永不参与同步）',
+  // 私有仓库强制提示（常驻警示横幅）
+  'privateRepoHint': '安全要求：同步仓库必须为私有仓库（public 仓库会公开你的配置内容）。认证 token 仅用于仓库访问，绝不写入同步文件、提交内容或日志。',
+  // 仓库配置表单
+  'config.title': '仓库配置',
+  'config.repoUrl': '仓库地址',
+  'config.repoUrlHint': 'Git 私有仓库地址（https / ssh / 本地路径）。认证 token 请使用下方凭据字段，不要拼入地址。',
+  'config.token': '认证 token',
+  'config.tokenHint': '将安全写入 DSH credentials（引用名 {ref}），不会写入同步文件或日志。留空表示沿用已保存的凭据。',
+  'config.tokenSaved': '凭据已配置',
+  'config.gitBin': 'git 可执行文件（可选）',
+  'config.gitBinHint': '缺省使用 PATH 中的 git。',
+  // 状态
+  'status.title': '同步状态',
+  'status.never': '从未同步',
+  // 操作
+  'action.push': '推送到远端',
+  'action.pull': '拉取差异预览',
+  'action.pushing': '正在推送…',
+  'action.pulling': '正在拉取…',
+  // 报告
+  'push.title': '推送结果',
+  'pull.title': '拉取差异预览',
+  'pull.previewHint': '以上为只读差异预览，不会执行导入。v1 暂不提供一键导入接线；如需应用远端配置，请使用「导入恢复」向导手动导入导出的备份。',
+  'pull.needsReview': '包含需要人工决策的项（冲突 / 密钥 / 依赖 / 安装）',
+  'pull.empty': '远端快照与本地一致（无变更）',
+  'change.total': '共 {total} 项变更',
+  'sections.title': '同步分区',
+  'warnings.title': '分区告警',
+  // 公共
+  'common.close': '关闭',
+  'common.retry': '重试',
+  'common.loading': '加载中…',
+} as const;
+
+export const en: Record<keyof typeof zh, string> = {
+  'section.label': 'Remote Sync',
+  'section.description': 'Sync portable configuration across devices via a private Git repository (secrets never sync)',
+  'privateRepoHint': 'Security requirement: the sync repository MUST be private (a public repo would expose your configuration). The auth token is only used for repository access and is never written into sync files, commit content, or logs.',
+  'config.title': 'Repository',
+  'config.repoUrl': 'Repository URL',
+  'config.repoUrlHint': 'Private Git repository URL (https / ssh / local path). Use the credential field below for the auth token; never embed it in the URL.',
+  'config.token': 'Auth token',
+  'config.tokenHint': 'Securely written into DSH credentials (ref {ref}); never written into sync files or logs. Leave blank to reuse the saved credential.',
+  'config.tokenSaved': 'Credential configured',
+  'config.gitBin': 'git executable (optional)',
+  'config.gitBinHint': 'Defaults to git on PATH.',
+  'status.title': 'Sync Status',
+  'status.never': 'Never synced',
+  'action.push': 'Push to remote',
+  'action.pull': 'Pull diff preview',
+  'action.pushing': 'Pushing…',
+  'action.pulling': 'Pulling…',
+  'push.title': 'Push Result',
+  'pull.title': 'Pull Diff Preview',
+  'pull.previewHint': 'Read-only diff preview above; nothing is imported. v1 does not wire one-click import yet — use the Import wizard to apply a downloaded backup if needed.',
+  'pull.needsReview': 'Contains items that need human decisions (conflicts / secrets / dependencies / installs)',
+  'pull.empty': 'Remote snapshot matches local (no changes)',
+  'change.total': '{total} change(s)',
+  'sections.title': 'Synced Sections',
+  'warnings.title': 'Section Warnings',
+  'common.close': 'Close',
+  'common.retry': 'Retry',
+  'common.loading': 'Loading…',
+};
+
+/** 字典键联合（注册处 compile-time 校验） */
+export type SyncKey = keyof typeof zh;

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

@@ -0,0 +1,211 @@
+/**
+ * m-sync-ui：远程同步区块渲染模型单测（纯函数，node 可测，无需 DOM）。
+ * 覆盖验收：报告渲染（push/pull）、按钮状态、私有仓库提示、状态行。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import type { PullChange, SyncPullReport, SyncPushReport } from '../../sync/sync-engine.ts'
+import type { SyncStatusResponse } from './sync-api.ts'
+import {
+  PRIVATE_REPO_HINT, computeSyncButtons, computeSyncStatus, formatDateTime, formatLastSync,
+  kindLabel, pullReportView, pushReportView, severityLabel, summarizePullChanges,
+} from './sync-view.ts'
+
+/* ---------------------------------------------------------------- 私有仓库提示 */
+
+test('sync-view: 私有仓库强制提示文案存在且强调私有', () => {
+  assert.match(PRIVATE_REPO_HINT, /私有/)
+  assert.match(PRIVATE_REPO_HINT, /public/)
+  assert.match(PRIVATE_REPO_HINT, /token/)
+})
+
+/* ---------------------------------------------------------------- 按钮状态 */
+
+test('sync-view: 空闲 + 仓库地址为空 → 两个按钮都禁用', () => {
+  const b = computeSyncButtons(null, '')
+  assert.equal(b.canPush, false)
+  assert.equal(b.canPull, false)
+  assert.equal(b.pushLabel, '推送到远端')
+  assert.equal(b.pullLabel, '拉取差异预览')
+})
+
+test('sync-view: 空闲 + 有效仓库地址 → 两个按钮可用', () => {
+  const b = computeSyncButtons(null, ' https://github.com/u/r.git ')
+  assert.equal(b.canPush, true)
+  assert.equal(b.canPull, true)
+})
+
+test('sync-view: push 进行中 → 按钮禁用且文案切换为正在推送（防并发）', () => {
+  const b = computeSyncButtons('push', 'https://github.com/u/r.git')
+  assert.equal(b.canPush, false)
+  assert.equal(b.canPull, false)
+  assert.equal(b.pushLabel, '正在推送…')
+  assert.equal(b.pullLabel, '拉取差异预览')
+})
+
+test('sync-view: pull 进行中 → 两个按钮都禁用，pull 文案切换', () => {
+  const b = computeSyncButtons('pull', 'https://github.com/u/r.git')
+  assert.equal(b.canPush, false)
+  assert.equal(b.canPull, false)
+  assert.equal(b.pullLabel, '正在拉取…')
+})
+
+/* ---------------------------------------------------------------- 变更摘要 */
+
+function change(overrides: Partial<PullChange>): PullChange {
+  return { id: 'x', adapter: 'settings', kind: 'Update', description: 'd', severity: 'info', ...overrides }
+}
+
+test('sync-view: summarizePullChanges 按 severity 计数', () => {
+  const summary = summarizePullChanges([
+    change({ severity: 'info' }),
+    change({ severity: 'info' }),
+    change({ severity: 'warning' }),
+    change({ severity: 'error' }),
+  ])
+  assert.equal(summary.total, 4)
+  assert.equal(summary.info, 2)
+  assert.equal(summary.warning, 1)
+  assert.equal(summary.error, 1)
+  assert.equal(summary.needsReview, false)
+})
+
+test('sync-view: summarizePullChanges 对冲突/安装/密钥/依赖项标记 needsReview', () => {
+  const summary = summarizePullChanges([
+    change({ kind: 'Conflict' }),
+    change({ kind: 'Install' }),
+  ])
+  assert.equal(summary.needsReview, true)
+})
+
+test('sync-view: summarizePullChanges 空数组 → total 0 且不需决策', () => {
+  const summary = summarizePullChanges([])
+  assert.equal(summary.total, 0)
+  assert.equal(summary.needsReview, false)
+})
+
+test('sync-view: kindLabel / severityLabel 覆盖关键类型', () => {
+  assert.equal(kindLabel('Conflict'), '冲突')
+  assert.equal(kindLabel('Install'), '安装')
+  assert.equal(kindLabel('MissingSecret'), '缺密钥')
+  assert.equal(severityLabel('error'), '错误')
+  assert.equal(severityLabel('warning'), '警告')
+  assert.equal(severityLabel('info'), '信息')
+})
+
+/* ---------------------------------------------------------------- push 报告渲染 */
+
+test('sync-view: push 成功报告 → ok 头部含快照 id + 分区透传', () => {
+  const report: SyncPushReport = { ok: true, snapshotId: 'sync-1', sections: ['settings', 'plugins'], warnings: [] }
+  const view = pushReportView(report)
+  assert.notEqual(view, null)
+  assert.equal(view?.kind, 'ok')
+  assert.match(view?.headline ?? '', /sync-1/)
+  assert.deepEqual(view?.sections, ['settings', 'plugins'])
+})
+
+test('sync-view: push 失败报告 → error 显示引擎 message', () => {
+  const report: SyncPushReport = { ok: false, snapshotId: '', sections: [], warnings: [], message: '全部导出失败' }
+  const view = pushReportView(report)
+  assert.equal(view?.kind, 'error')
+  assert.equal(view?.headline, '全部导出失败')
+})
+
+test('sync-view: null 报告 → null（不渲染卡片）', () => {
+  assert.equal(pushReportView(null), null)
+  assert.equal(pullReportView(null), null)
+})
+
+/* ---------------------------------------------------------------- pull 报告渲染 */
+
+test('sync-view: pull 无变更 → empty 渲染（无差异列表）', () => {
+  const report: SyncPullReport = { ok: true, snapshotId: 'sync-1', changes: [], needsReview: false }
+  const view = pullReportView(report)
+  assert.equal(view?.kind, 'empty')
+  assert.equal(view?.summary, null)
+})
+
+test('sync-view: pull 差异报告 → ok + 摘要计数 + needsReview + 只读预览提示', () => {
+  const report: SyncPullReport = {
+    ok: true,
+    snapshotId: 'sync-9',
+    changes: [
+      change({ id: 'settings:a', kind: 'Update', description: '更新设置 a', severity: 'info' }),
+      change({ id: 'plugin:x', kind: 'Conflict', adapter: 'plugins', description: '插件 x 冲突', severity: 'warning' }),
+    ],
+    needsReview: true,
+  }
+  const view = pullReportView(report)
+  assert.equal(view?.kind, 'ok')
+  assert.match(view?.headline ?? '', /sync-9/)
+  assert.equal(view?.summary?.total, 2)
+  assert.equal(view?.summary?.needsReview, true)
+  assert.equal(view?.summary?.items[0]?.description, '更新设置 a')
+  assert.equal(view?.summary?.items[1]?.kind, 'Conflict')
+  assert.notEqual(view?.previewHint, '')
+  assert.match(view?.previewHint, /不会执行导入/)
+})
+
+test('sync-view: pull 失败 → error 渲染', () => {
+  const report: SyncPullReport = { ok: false, snapshotId: '', changes: [], needsReview: false, message: '认证失败' }
+  const view = pullReportView(report)
+  assert.equal(view?.kind, 'error')
+  assert.equal(view?.headline, '认证失败')
+})
+
+/* ---------------------------------------------------------------- 状态行 */
+
+test('sync-view: 加载中 → loading 状态', () => {
+  const s = computeSyncStatus(null, true, null)
+  assert.equal(s.kind, 'loading')
+})
+
+test('sync-view: 加载失败 → error 状态带消息', () => {
+  const s = computeSyncStatus(null, false, '网络错误')
+  assert.equal(s.kind, 'error')
+  assert.equal(s.text, '网络错误')
+})
+
+test('sync-view: 未配置仓库 → unconfigured 提示', () => {
+  const s = computeSyncStatus(null, false, null)
+  assert.equal(s.kind, 'unconfigured')
+  assert.match(s.text, /尚未配置/)
+})
+
+test('sync-view: 已配置但缺凭据 → ready 文案提示未配置凭据', () => {
+  const info: SyncStatusResponse = {
+    ok: true, configured: true, repoUrl: 'https://github.com/u/r.git',
+    credentialConfigured: false, credentialWritable: true, lastSyncAt: undefined, sectionCount: 0,
+  }
+  const s = computeSyncStatus(info, false, null)
+  assert.equal(s.kind, 'ready')
+  assert.match(s.text, /未配置凭据/)
+})
+
+test('sync-view: 已配置 + 凭据就绪 + 上次同步 → ready 文案含日期与通道', () => {
+  const info: SyncStatusResponse = {
+    ok: true, configured: true, repoUrl: 'https://github.com/u/r.git',
+    credentialConfigured: true, credentialWritable: true,
+    lastSyncAt: '2026-08-16T10:30:00.000Z', sectionCount: 3,
+    transport: { type: 'git', ref: 'main' },
+  }
+  const s = computeSyncStatus(info, false, null)
+  assert.equal(s.kind, 'ready')
+  assert.match(s.text, /凭据已配置/)
+  assert.match(s.text, /上次同步/)
+  assert.match(s.text, /git\/main/)
+})
+
+/* ---------------------------------------------------------------- 时间格式化 */
+
+test('sync-view: formatLastSync 空值 → 从未同步', () => {
+  assert.equal(formatLastSync(undefined), '从未同步')
+  assert.equal(formatLastSync(''), '从未同步')
+})
+
+test('sync-view: formatLastSync / formatDateTime 合法 ISO → 本地可读格式', () => {
+  const text = formatLastSync('2026-08-16T10:30:00.000Z')
+  assert.match(text, /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/)
+  assert.equal(formatDateTime('not-a-date'), 'not-a-date')
+})

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

@@ -0,0 +1,202 @@
+/**
+ * 远程同步区块的纯渲染模型（m-sync-ui）。
+ *
+ * 与 src/ui/progress.ts → progress-view.ts 同模式：把「报告怎么渲染 / 按钮什么状态 /
+ * 状态行写什么 / 私有仓库提示怎么展示」做成无副作用纯函数，node --test 直接测，
+ * React 组件只做装配。文案直接用中文（项目源语言），组件不重复造。
+ */
+import type { PlanItem, PlanItemKind } from '../../core/types.ts';
+import type { PullChange, SyncPullReport, SyncPushReport } from '../../sync/sync-engine.ts';
+import type { SyncStatusResponse } from './sync-api.ts';
+
+/* ---------------------------------------------------------------- 私有仓库提示 */
+
+/**
+ * 私有仓库强制提示文案（Settings 区块常驻警示横幅）。
+ * 安全约束：同步内容为可移植配置，public 仓库会公开配置 → 必须私有；
+ * token 仅用于认证，绝不写入同步文件/提交内容/日志。
+ */
+export const PRIVATE_REPO_HINT =
+  '安全要求：同步仓库必须为私有仓库（public 仓库会公开你的配置内容）。认证 token 仅用于仓库访问，绝不写入同步文件、提交内容或日志。';
+
+/* ---------------------------------------------------------------- 变更摘要 */
+
+/** 需要人工决策的 PlanItem 类型（与 SyncEngine.pull 的 needsReview 判定一致） */
+const REVIEW_KINDS: ReadonlySet<PlanItemKind> = new Set([
+  'Conflict', 'MissingSecret', 'MissingDependency', 'Install', 'Error',
+]);
+
+export interface PullChangeSummary {
+  total: number;
+  info: number;
+  warning: number;
+  error: number;
+  /** 是否包含需要人工决策的项（冲突/密钥/依赖/安装/错误） */
+  needsReview: boolean;
+  items: PullChange[];
+}
+
+/** 差异摘要：按 severity 计数 + 需人工决策标记（UI 统计徽章与警示横幅的数据源） */
+export function summarizePullChanges(changes: readonly PullChange[]): PullChangeSummary {
+  let info = 0;
+  let warning = 0;
+  let error = 0;
+  let needsReview = false;
+  for (const c of changes) {
+    if (c.severity === 'error') error += 1;
+    else if (c.severity === 'warning') warning += 1;
+    else info += 1;
+    if (REVIEW_KINDS.has(c.kind)) needsReview = true;
+  }
+  return { total: changes.length, info, warning, error, needsReview, items: [...changes] };
+}
+
+/** PlanItemKind → 短标签（列表徽章） */
+export function kindLabel(kind: PlanItemKind): string {
+  switch (kind) {
+    case 'Create': return '新增';
+    case 'Update': return '更新';
+    case 'Skip': return '跳过';
+    case 'Conflict': return '冲突';
+    case 'Install': return '安装';
+    case 'MissingSecret': return '缺密钥';
+    case 'MissingDependency': return '缺依赖';
+    case 'PathMapping': return '路径映射';
+    case 'Warning': return '警告';
+    case 'Error': return '错误';
+    default: return kind;
+  }
+}
+
+/** severity → 短标签 */
+export function severityLabel(severity: PlanItem['severity']): string {
+  switch (severity) {
+    case 'error': return '错误';
+    case 'warning': return '警告';
+    default: return '信息';
+  }
+}
+
+/* ---------------------------------------------------------------- 按钮状态 */
+
+export interface SyncButtons {
+  canPush: boolean;
+  canPull: boolean;
+  pushLabel: string;
+  pullLabel: string;
+}
+
+/**
+ * 按钮可用性与文案：
+ * - 任一操作进行中（busy）→ 两个按钮都禁用（防并发 push/pull）；
+ * - 仓库地址为空 → 禁用（无仓库无从同步）；
+ * - busy 时按钮文案切换为「正在推送/拉取…」（配 Spinner）。
+ */
+export function computeSyncButtons(busy: 'push' | 'pull' | null, repoUrl: string): SyncButtons {
+  const idle = busy === null;
+  const repoOk = repoUrl.trim() !== '';
+  const enabled = idle && repoOk;
+  return {
+    canPush: enabled,
+    canPull: enabled,
+    pushLabel: busy === 'push' ? '正在推送…' : '推送到远端',
+    pullLabel: busy === 'pull' ? '正在拉取…' : '拉取差异预览',
+  };
+}
+
+/* ---------------------------------------------------------------- 状态行 */
+
+export type SyncStatusKind = 'loading' | 'unconfigured' | 'ready' | 'error';
+
+export interface SyncStatusSummary {
+  kind: SyncStatusKind;
+  text: string;
+}
+
+/** 状态行渲染模型：加载 / 未配置 / 就绪（凭据 + 上次同步 + 通道）/ 错误 */
+export function computeSyncStatus(
+  statusInfo: SyncStatusResponse | null,
+  loading: boolean,
+  error: string | null,
+): SyncStatusSummary {
+  if (loading) return { kind: 'loading', text: '正在读取同步状态…' };
+  if (error !== null) return { kind: 'error', text: error };
+  if (statusInfo === null || !statusInfo.configured) {
+    return { kind: 'unconfigured', text: '尚未配置同步仓库（请填写仓库地址并推送一次以保存配置）' };
+  }
+  const cred = statusInfo.credentialConfigured
+    ? '凭据已配置'
+    : '未配置凭据（token 将在首次推送/拉取时写入 DSH credentials）';
+  const last =
+    statusInfo.lastSyncAt !== undefined && statusInfo.lastSyncAt !== ''
+      ? `上次同步：${formatDateTime(statusInfo.lastSyncAt)}`
+      : '尚未同步过';
+  const transport =
+    statusInfo.transport !== undefined
+      ? ` · ${statusInfo.transport.type}${statusInfo.transport.ref !== '' ? `/${statusInfo.transport.ref}` : ''}`
+      : '';
+  return { kind: 'ready', text: `${cred} · ${last}${transport}` };
+}
+
+/** ISO-8601 → 本地可读时间（YYYY-MM-DD HH:mm；非法输入原样返回） */
+export function formatDateTime(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  const pad = (n: number): string => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/** 上次同步时间的展示文本（'' / undefined = 从未同步） */
+export function formatLastSync(iso: string | undefined): string {
+  if (iso === undefined || iso === '') return '从未同步';
+  return formatDateTime(iso);
+}
+
+/* ---------------------------------------------------------------- 报告渲染模型 */
+
+export interface PushReportView {
+  kind: 'ok' | 'error';
+  headline: string;
+  sections: string[];
+  warnings: string[];
+}
+
+/** push 报告 → 渲染模型（ok 头部带快照 id；失败显示引擎 message；分区与告警透传） */
+export function pushReportView(report: SyncPushReport | null): PushReportView | null {
+  if (report === null) return null;
+  if (!report.ok) {
+    return { kind: 'error', headline: report.message ?? '推送失败', sections: report.sections, warnings: report.warnings };
+  }
+  return {
+    kind: 'ok',
+    headline: `推送成功（快照 ${report.snapshotId}）`,
+    sections: report.sections,
+    warnings: report.warnings,
+  };
+}
+
+export interface PullReportView {
+  kind: 'ok' | 'empty' | 'error';
+  headline: string;
+  summary: PullChangeSummary | null;
+  /** 只读预览提示（ok 时非空：明确「预览不执行导入」） */
+  previewHint: string;
+}
+
+/** pull 报告 → 渲染模型（差异预览；empty = 无变更；error = 拉取失败） */
+export function pullReportView(report: SyncPullReport | null): PullReportView | null {
+  if (report === null) return null;
+  if (!report.ok) {
+    return { kind: 'error', headline: report.message ?? '拉取失败', summary: null, previewHint: '' };
+  }
+  if (report.changes.length === 0) {
+    return { kind: 'empty', headline: report.message ?? '远端快照与本地一致（无变更）', summary: null, previewHint: '' };
+  }
+  return {
+    kind: 'ok',
+    headline: `远端快照 ${report.snapshotId} 差异预览：共 ${report.changes.length} 项变更`,
+    summary: summarizePullChanges(report.changes),
+    previewHint:
+      '以上为只读差异预览，不会执行导入。v1 暂不提供一键导入接线；如需应用远端配置，请使用「导入恢复」向导手动导入导出的备份。',
+  };
+}