dsh-config-manager 0.1.12 → 0.1.13

package/lib/client.d.ts

@@ -147,6 +147,8 @@ interface ImportResult {
   rollback: RollbackReport | null;
   snapshotId: string | null;
 }
+/** 快照生命周期状态（M1 增强；旧快照无此字段，视为未知/兼容） */
+type SnapshotStatus = 'pending' | 'done' | 'rolled-back';
 interface RollbackReport {
   full: boolean;
   restored: string[];
@@ -175,6 +177,97 @@ interface ExportReport {
   warnings: string[];
 }
 //#endregion
+//#region src/core/restore.d.ts
+type RestoreActionKind = 'hostFileRestore' | 'hostFileRemove' | 'pluginRemove' | 'fileRestore' | 'fileRemove' | 'credentialHint' | 'skip';
+interface RestoreAction {
+  kind: RestoreActionKind;
+  /** 人类可读描述 */
+  description: string;
+  /** 目标：相对 $DSH_HOME 的 relPath（hostFile/file 类）或插件名（pluginRemove） */
+  target?: string;
+  /** hostFileRestore/fileRestore：快照内 blob 相对路径（相对 snapshotDir） */
+  blobPath?: string;
+  /** pluginRemove：插件包名 */
+  pluginName?: string;
+  /** credentialHint：人工提示文本 */
+  manualHint?: string;
+  /** 附加说明（旧快照缺基线 / 离线无法恢复等） */
+  detail?: string;
+  /** 该动作是否对应 settings 主文件（settingsPath 解析出的文件） */
+  isSettings?: boolean;
+}
+interface RestorePlan {
+  snapshotId: string;
+  createdAt: string;
+  sourceZip: string;
+  actions: RestoreAction[];
+  summary: {
+    hostFileRestores: number;
+    hostFileRemoves: number;
+    pluginRemoves: number;
+    fileRestores: number;
+    fileRemoves: number;
+    credentialHints: number;
+    skips: number;
+  };
+  /** beforePlugins 基线是否可用（undefined=旧快照无基线 → 不计划任何插件卸载） */
+  pluginBaselineConfirmed: boolean;
+}
+interface RestoreReport {
+  snapshotId: string;
+  /** 已还原/已删除的目标（相对 $DSH_HOME） */
+  restored: string[];
+  /** 已卸载的插件名 */
+  removedPlugins: string[];
+  /** 需人工处理的提示（凭据补录等） */
+  manualHints: string[];
+  /** 失败清单 */
+  failed: {
+    item: string;
+    reason: string;
+  }[];
+  /** 跳过项（无动作 / 离线无法处理） */
+  skipped: string[];
+}
+interface SnapshotMeta {
+  id: string;
+  createdAt: string;
+  sourceZip: string;
+  status?: SnapshotStatus;
+  entryCount: number;
+  hostFileBackupCount: number;
+  beforePluginCount: number;
+}
+//#endregion
+//#region src/core/run-registry.d.ts
+/** run 类型：导出 / 导入。 */
+type RunKind = 'export' | 'import';
+/** run 状态：进行中 / 完成 / 失败。 */
+type RunStatus = 'running' | 'done' | 'failed';
+/** 单个 run 的实时状态（/progress 返回体；纯 JSON 可序列化）。 */
+interface RunState {
+  /** 不可猜测的 run id（32 hex 字符）。 */
+  runId: string;
+  kind: RunKind;
+  status: RunStatus;
+  /** 当前分区（adapter id 或导入阶段名）；无则 null。 */
+  section: string | null;
+  /** 分区总数（导出 = 选中分区数；导入无此语义 = null）。 */
+  sectionTotal: number | null;
+  /** 已完成的内部计数（导出 = 当前分区序号；导入 = 已处理计划项数）。 */
+  item: number | null;
+  /** 内部计数总数（导出 = 分区总数；导入 = 计划项总数）。 */
+  itemTotal: number | null;
+  /** 非敏感进度摘要（当前分区 / 当前计划项 id）。 */
+  detail: string | null;
+  /** 完成时的业务结果（仅 JSON 可序列化、不含秘密值）。 */
+  result?: unknown;
+  /** 失败时的错误消息（非敏感）。 */
+  error?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+//#endregion
 //#region src/client/api.d.ts
 /** Host 半健康检查响应（plugin 版本 / DSH 版本 / 平台，用于主页横幅与兼容性说明） */
 interface ServiceStatus {
@@ -184,11 +277,13 @@ interface ServiceStatus {
   platform: string;
   arch: string;
 }
-/** export 端点响应（对齐 ExportFlow 的 ExportRunResult 前半部分） */
+/** export 端点响应（对齐 ExportFlow 的 ExportRunResult 前半部分；runId 为 m1 run 注册表标识） */
 interface ExportResponse {
   zipPath: string;
   manifest: Manifest;
   report: ExportReport;
+  /** m1：本次导出 run 的 id（可用 /progress 查询状态 / 刷新恢复） */
+  runId: string;
 }
 /** upload 端点响应：Host 把用户上传的 ZIP 存入受控临时目录，返回可被 analyze/plan/execute 引用的路径 */
 interface UploadResponse {
@@ -196,6 +291,12 @@ interface UploadResponse {
   name: string;
   sizeBytes: number;
 }
+/** restore 端点响应：dryRun=true 返回 plan；执行返回 report（与 CLI 一致的诚实报告） */
+interface RestoreResponse {
+  dryRun: boolean;
+  plan?: RestorePlan;
+  report?: RestoreReport;
+}
 /** 携带路由 JSON error 消息的错误类型 */
 declare class ConfigManagerApiError extends Error {
   constructor(message: string);
@@ -239,7 +340,17 @@ declare class ConfigManagerApi {
     confirm: boolean;
     secretInputs?: Record<string, string>;
     rollbackOnError: boolean;
-  }): Promise<ImportResult>;
+  }): Promise<ImportResult & {
+    runId: string;
+  }>;
+  /** m1：查询单个 run 的实时状态（执行中轮询 / 刷新恢复用；404 = 已过保留期或不存在） */
+  progress(runId: string): Promise<RunState>;
+  /** m1：列出当前活跃（running）的 run（刷新后重新订阅进行中任务的入口） */
+  runs(): Promise<RunState[]>;
+  /** 列出全部快照元信息（createdAt 倒序；含 status/条目数/宿主文件数/插件数） */
+  snapshots(): Promise<SnapshotMeta[]>;
+  /** 快照恢复：dryRun=true 只取动作计划（零写入）；false 执行并返回诚实报告 */
+  restoreSnapshot(snapshotId: string, dryRun: boolean): Promise<RestoreResponse>;
 }
 //#endregion
 //#region src/client/client-types.d.ts
@@ -254,11 +365,12 @@ interface ConfigManagerSectionInjected {
  * 字典 namespace 由 client/index.ts 注册（declare module 合并进 LocaleNamespaceMap）。
  * 键集合通过 `ConfigManagerKey` 类型在注册处做编译期校验（缺键/多键即编译错误）。
  */
-declare const zh: {
+declare const zh$1: {
   readonly 'section.label': "备份与迁移";
   readonly 'section.description': "导出 / 导入 / 迁移 DSH 配置（备份不含密钥，加密备份可选）";
   readonly 'view.export': "导出备份";
   readonly 'view.import': "导入恢复";
+  readonly 'view.snapshots': "快照恢复";
   readonly 'common.close': "关闭";
   readonly 'common.cancel': "取消";
   readonly 'common.back': "上一步";
@@ -326,6 +438,31 @@ declare const zh: {
   readonly 'import.paths.old': "原路径";
   readonly 'import.paths.new': "新路径";
   readonly 'import.paths.unresolved': "还有 {count} 条路径未映射";
+  readonly 'snapshots.title': "快照恢复";
+  readonly 'snapshots.hint': "恢复到导入前状态：整文件还原 settings/patch、卸载导入期间新增插件、补偿被修改文件。执行前会把当前文件备份到快照的 pre-restore 目录。";
+  readonly 'snapshots.empty': "暂无快照。执行导入时会自动创建安全快照。";
+  readonly 'snapshots.loading': "加载快照中…";
+  readonly 'snapshots.selectHint': "选择快照以预览恢复计划（dry-run，零写入）：";
+  readonly 'snapshots.createdAt': "创建时间";
+  readonly 'snapshots.sourceZip': "来源备份";
+  readonly 'snapshots.status': "状态";
+  readonly 'snapshots.entries': "条目";
+  readonly 'snapshots.plugins': "插件";
+  readonly 'snapshots.status.pending': "进行中";
+  readonly 'snapshots.status.done': "已完成";
+  readonly 'snapshots.status.rolled-back': "已回滚";
+  readonly 'snapshots.status.unknown': "未知";
+  readonly 'snapshots.planTitle': "恢复计划预览";
+  readonly 'snapshots.noActions': "该快照无可用恢复动作（或全部跳过）。";
+  readonly 'snapshots.execute': "执行恢复";
+  readonly 'snapshots.executing': "恢复执行中…";
+  readonly 'snapshots.confirmRestore': "确认执行恢复？当前文件会先备份到快照的 pre-restore 目录，插件通过官方 dsh plugin remove 卸载。";
+  readonly 'snapshots.reportTitle': "恢复报告";
+  readonly 'snapshots.restored': "已还原";
+  readonly 'snapshots.removedPlugins': "已卸载插件";
+  readonly 'snapshots.manualHints': "需人工处理";
+  readonly 'snapshots.failed': "失败";
+  readonly 'snapshots.skipped': "跳过";
   readonly 'report.export.title': "导出完成";
   readonly 'report.import.title': "导入结果";
   readonly 'report.rollback.title': "回滚报告";
@@ -337,7 +474,46 @@ declare const zh: {
   readonly 'error.hint': "错误消息已自动脱敏，不会泄露任何密钥信息。";
 };
 /** 字典键联合（注册处 compile-time 校验） */
-type ConfigManagerKey = keyof typeof zh;
+type ConfigManagerKey = keyof typeof zh$1;
+//#endregion
+//#region src/client/sync/sync-locales.d.ts
+/**
+ * 远程同步设置区块（config-manager-sync）表面文案：zh 为源语言，en 镜像每个键。
+ * 独立命名空间、独立文件：不触碰共享的 locales.ts（并行会话已改），零冲突。
+ * 键集合经 `SyncKey` 类型在 client/index.ts 注册处做编译期校验。
+ */
+declare const zh: {
+  readonly 'section.label': "远程同步";
+  readonly 'section.description': "通过 Git 私有仓库在设备间同步可移植配置（secret 永不参与同步）";
+  readonly privateRepoHint: "安全要求：同步仓库必须为私有仓库（public 仓库会公开你的配置内容）。认证 token 仅用于仓库访问，绝不写入同步文件、提交内容或日志。";
+  readonly 'config.title': "仓库配置";
+  readonly 'config.repoUrl': "仓库地址";
+  readonly 'config.repoUrlHint': "Git 私有仓库地址（https / ssh / 本地路径）。认证 token 请使用下方凭据字段，不要拼入地址。";
+  readonly 'config.token': "认证 token";
+  readonly 'config.tokenHint': "将安全写入 DSH credentials（引用名 {ref}），不会写入同步文件或日志。留空表示沿用已保存的凭据。";
+  readonly 'config.tokenSaved': "凭据已配置";
+  readonly 'config.gitBin': "git 可执行文件（可选）";
+  readonly 'config.gitBinHint': "缺省使用 PATH 中的 git。";
+  readonly 'status.title': "同步状态";
+  readonly 'status.never': "从未同步";
+  readonly 'action.push': "推送到远端";
+  readonly 'action.pull': "拉取差异预览";
+  readonly 'action.pushing': "正在推送…";
+  readonly 'action.pulling': "正在拉取…";
+  readonly 'push.title': "推送结果";
+  readonly 'pull.title': "拉取差异预览";
+  readonly 'pull.previewHint': "以上为只读差异预览，不会执行导入。v1 暂不提供一键导入接线；如需应用远端配置，请使用「导入恢复」向导手动导入导出的备份。";
+  readonly 'pull.needsReview': "包含需要人工决策的项（冲突 / 密钥 / 依赖 / 安装）";
+  readonly 'pull.empty': "远端快照与本地一致（无变更）";
+  readonly 'change.total': "共 {total} 项变更";
+  readonly 'sections.title': "同步分区";
+  readonly 'warnings.title': "分区告警";
+  readonly 'common.close': "关闭";
+  readonly 'common.retry': "重试";
+  readonly 'common.loading': "加载中…";
+};
+/** 字典键联合（注册处 compile-time 校验） */
+type SyncKey = keyof typeof zh;
 //#endregion
 //#region src/client/ConfigManagerSection.d.ts
 type ConfigManagerSectionProps = PropsRuntime<'settings.section'> & ConfigManagerSectionInjected & {
@@ -356,11 +532,90 @@ interface ImportWizardViewProps {
   t: TranslateNS<'config-manager'>;
 }
 //#endregion
+//#region src/sync/sync-engine.d.ts
+interface SyncPushReport {
+  ok: boolean;
+  snapshotId: string;
+  /** 实际进入同步的 portable 分区 */
+  sections: SectionId[];
+  /** 分区级告警（单项失败不拖垮整体，§34.17 语义） */
+  warnings: string[];
+  message?: string;
+}
+/** 差异报告中的单个变更项（PlanItem 摘要，不含敏感细节） */
+interface PullChange {
+  id: string;
+  adapter: SectionId;
+  kind: PlanItemKind;
+  description: string;
+  severity: PlanItem['severity'];
+}
+interface SyncPullReport {
+  ok: boolean;
+  snapshotId: string;
+  changes: PullChange[];
+  /** 是否存在需要人工决策的项（Conflict / MissingSecret / MissingDependency / Install / 路径问题） */
+  needsReview: boolean;
+  message?: string;
+}
+//#endregion
+//#region src/client/sync/sync-api.d.ts
+/** GET /sync/status 响应：配置/凭据/上次同步的只读事实（无任何 secret 值） */
+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 再使用） */
+interface SyncPushPayload {
+  repoUrl: string;
+  gitBin?: string;
+  token?: string;
+}
+/** pull 请求体（strategy 缺省 merge：冲突保留待决策；snapshotId 缺省 = 最新） */
+interface SyncPullPayload extends SyncPushPayload {
+  strategy?: 'merge' | 'replace' | 'skipExisting';
+  snapshotId?: string;
+}
+/** 远程同步浏览器半数据入口（settings.section: config-manager-sync 的注入业务面） */
+declare class SyncApi {
+  /** 读取同步状态（配置 / 凭据 / 上次同步时间 / 分区数） */
+  status(): Promise<SyncStatusResponse>;
+  /** 推送：导出 portable 分区 → 提交到私有 Git 仓库 → 更新 sync-state */
+  push(payload: SyncPushPayload): Promise<SyncPushReport>;
+  /** 拉取差异预览：拉取远端最新快照 → 只读分析（绝不执行导入） */
+  pull(payload: SyncPullPayload): Promise<SyncPullReport>;
+}
+//#endregion
+//#region src/client/sync/SyncSettingsView.d.ts
+interface SyncSettingsSectionInjected {
+  api: SyncApi;
+}
+type SyncSettingsViewProps = PropsRuntime<'settings.section'> & SyncSettingsSectionInjected & {
+  t: TranslateNS<'config-manager-sync'>;
+};
+//#endregion
 //#region src/client/index.d.ts
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
     /** Config Manager 表面文案。 */
     'config-manager': ConfigManagerKey;
+    /** 远程同步设置区块文案（m-sync-ui）。 */
+    'config-manager-sync': SyncKey;
   }
 }
 /** 必需服务（fiber inject 等待 —— slots/locale 必须先就绪）。 */
@@ -371,7 +626,7 @@ declare const inject: string[];
  */
 declare function apply(ctx: ClientContext): void;
 //#endregion
-export { type ConfigManagerApiError, type ConfigManagerKey, type ConfigManagerSectionProps, type DownloadResult, type ExportViewProps, type ImportWizardViewProps, type ServiceStatus, type UploadResponse, apply, inject };
+export { type ConfigManagerApiError, type ConfigManagerKey, type ConfigManagerSectionProps, type DownloadResult, type ExportViewProps, type ImportWizardViewProps, type ServiceStatus, type SyncKey, type SyncSettingsViewProps, type UploadResponse, apply, inject };
 
 		return module.exports;
 	}