dsh-config-manager 0.1.0

package/src/core/types.ts

@@ -0,0 +1,343 @@
+/**
+ * 核心引擎契约类型（对齐 Docs/design/architecture.md §13.2/§13.3/§13.5）。
+ *
+ * 关键解耦原则：核心引擎只依赖这里的接口，绝不 import DSH 运行时包。
+ * HostContext 是 m3 定义、m5 实现的 DSH Service 门面（研究报告 §3.2 的叶子方法最小集），
+ * 测试用内存 mock 即可驱动完整导出→导入往返。
+ */
+import type { EncryptionInfo, Manifest, SectionId, WorkspaceRecord } from '../schema/types.ts';
+import type { Logger } from '../utils/logger.ts';
+
+/* ---------------- 导出选项与分区产出 ---------------- */
+
+export interface ExportOptions {
+  /** 是否包含真实秘密（必须配合 encryption 提供者；缺省 false = 只导状态） */
+  includeSecrets: boolean;
+  /** 仅导出指定分区（缺省 = 全部默认包含分区） */
+  only?: SectionId[];
+  /** 导出文件路径（缺省自动生成 dsh-config-<date>.zip） */
+  outPath?: string;
+}
+
+/** adapter.export() 的产出：数据 + 文件 + 报告计数 + 告警 */
+export interface ExportSection<T = unknown> {
+  sectionId: SectionId;
+  data: T;
+  /** 文件类分区（skills/agentPresets/pluginFiles/sessions）以真实文件形式进入 ZIP */
+  files?: { relativePath: string; data: Uint8Array }[];
+  counts: Record<string, number>;
+  warnings: string[];
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  issues: { path: string; message: string; severity: 'error' | 'warning' }[];
+}
+
+/* ---------------- Secret 扫描（m4 可替换实现） ---------------- */
+
+export interface SensitiveHit { path: string; field: string; }
+
+export interface SecretScanner {
+  /** 递归扫描 + 剥离敏感字段值；返回清洗后的数据与命中清单（不泄值） */
+  scanAndRedact(data: unknown): { sanitized: unknown; hits: SensitiveHit[] };
+  /** 文本级扫描（文件类分区内容），供强化版使用 */
+  scanText?(text: string): SensitiveHit[];
+}
+
+/* ---------------- DSH Service 门面（m5 对接真实 ctx） ---------------- */
+
+export interface NamespaceInfo {
+  value: unknown;
+  base?: unknown;
+  revision: number;
+  applies?: string[];
+  secrets: { path: string[]; set: boolean }[];
+}
+
+export interface SettingsFacade {
+  /** 读某 namespace（redactSecrets 剥离密钥值）；返回含乐观锁 revision */
+  describe(namespace: string, opts?: { redactSecrets?: boolean }): Promise<NamespaceInfo>;
+  /** 整体替换（导入/回滚主通道）；expectedRevision 不一致时抛 SETTINGS_CONFLICT 类错误 */
+  replace(namespace: string, value: unknown, expectedRevision?: number): Promise<void>;
+  /** 部分更新（未来 Merge 策略用） */
+  update?(namespace: string, patch: unknown, expectedRevision?: number): Promise<void>;
+}
+
+export interface CredentialsFacade {
+  /** 只返回状态，永不返回值 */
+  describe(ref: string): Promise<{ configured: boolean; source?: string; writable?: boolean }>;
+  set(ref: string, value: string): Promise<void>;
+  unset(ref: string): Promise<void>;
+}
+
+export interface PluginInfo { name: string; version: string; enabled: boolean; isBundle?: boolean; inBundles?: string[]; }
+
+export interface PluginsFacade {
+  listInstalled(): Promise<PluginInfo[]>;
+  install(pkg: string): Promise<{ needsRestart: boolean }>;
+}
+
+export interface WorkspaceFacade {
+  listRecords(): Promise<WorkspaceRecord[]>;
+  writeRecord(record: WorkspaceRecord): Promise<void>;
+  removeRecord?(id: string): Promise<void>;
+}
+
+export interface PatchChange { lineId: string; raw: unknown; action: 'insert' | 'update' | 'remove'; }
+
+export interface PatchFileFacade {
+  readPatchLines(file: string): Promise<{ lineId: string; raw: unknown }[]>;
+  applyPatchChanges(file: string, changes: PatchChange[]): Promise<void>;
+}
+
+export interface FileSystemFacade {
+  readFile(relPath: string): Promise<Uint8Array>;
+  writeFile(relPath: string, data: Uint8Array): Promise<void>;
+  exists(relPath: string): Promise<boolean>;
+  copy(from: string, to: string): Promise<void>;
+  remove(relPath: string): Promise<void>;
+  listRecursive(dir: string): Promise<string[]>;
+  mkdir(dir: string): Promise<void>;
+}
+
+/** DSH 运行时门面：m3 只依赖此接口；m5 用真实 ctx.settings/credentials/… 实现 */
+export interface HostContext {
+  platform: string;
+  arch: string;
+  homeDir: string;
+  dshVersion: string;
+  log: Logger;
+  settings: SettingsFacade;
+  credentials: CredentialsFacade;
+  plugins: PluginsFacade;
+  workspace: WorkspaceFacade;
+  patchFile: PatchFileFacade;
+  fs: FileSystemFacade;
+}
+
+/* ---------------- 导入计划（§13.3 十类 + 决策） ---------------- */
+
+export type PlanItemKind =
+  | 'Create' | 'Update' | 'Skip' | 'Conflict' | 'Install'
+  | 'MissingSecret' | 'MissingDependency' | 'PathMapping' | 'Warning' | 'Error';
+
+export type ItemResolution = 'keepCurrent' | 'useImported' | 'review';
+export type GlobalConflictStrategy = 'merge' | 'replace' | 'skipExisting';
+
+export interface ConflictDecision { itemId: string; resolution: ItemResolution; }
+
+export interface PathMapping {
+  oldPrefix: string;
+  newPrefix: string;
+  appliesTo: ('workspaces' | 'mcp' | 'pluginConfig' | 'skills')[];
+}
+
+export interface PathIssue {
+  kind: 'missing' | 'platformMismatch' | 'homeMismatch';
+  value: string;
+  mappedTo?: string;
+}
+
+export interface SnapshotTarget { adapter: SectionId; ref: string; }
+
+export interface PlanItem {
+  id: string;                 // 稳定项 id（plugin:pkg / prompt:name / workspace:<id> …）
+  kind: PlanItemKind;
+  adapter: SectionId;
+  description: string;
+  detail?: string;
+  severity: 'info' | 'warning' | 'error';
+  conflict?: ConflictDecision;
+  pathMapping?: PathMapping;
+  missingDependency?: string;
+  target?: SnapshotTarget;    // 该项将修改的目标（快照登记用）
+}
+
+export interface ApplyResult { ok: boolean; message?: string; needsRestart?: boolean; }
+
+/* ---------------- 三段式输入输出 ---------------- */
+
+export interface ImportAnalysis {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  compatibility: 'excellent' | 'good' | 'partial' | 'unsupported';
+  sectionsInZip: SectionId[];
+  pluginSummary: { installed: number; toInstall: number };
+  pathIssues: PathIssue[];
+  secretCount: number;
+  dependencyIssues: { item: string; dependency: string }[];
+}
+
+export interface ImportDecisions {
+  strategy: GlobalConflictStrategy;
+  resolutions: Record<string, ItemResolution>;
+  pathMappings: PathMapping[];
+}
+
+export interface ImportPlan {
+  items: PlanItem[];
+  globalStrategy: GlobalConflictStrategy;
+  pathMappings: PathMapping[];
+  missingSecrets: { ref: string; required: boolean }[];
+  needsRestart: boolean;
+  estimatedActions: Record<SectionId, number>;
+}
+
+export interface ExecutedItem {
+  itemId: string;
+  status: 'ok' | 'skipped' | 'failed';
+  message?: string;
+}
+
+export interface ImportResult {
+  ok: boolean;
+  executed: ExecutedItem[];
+  needsRestart: boolean;
+  missingSecrets: string[];
+  warnings: string[];
+  rollback: RollbackReport | null;
+  snapshotId: string | null;
+}
+
+/* ---------------- 导入上下文（传给 adapter.analyzeImport / applyItem） ---------------- */
+
+export interface ImportContext {
+  manifest: Manifest;
+  targetPlatform: string;
+  /** 目标 DSH 门面（adapter 比较目标状态 / 写入 / 读取数据用） */
+  target: HostContext;
+  /** 已由 PathMapper 处理后的各分区最终数据（adapter.applyItem 从这取写入内容） */
+  sections: Map<SectionId, unknown>;
+  pathMappings: PathMapping[];
+  resolutions: Record<string, ItemResolution>;
+  /** 用户补录的秘密值（仅内存，永不落盘/日志） */
+  secretInputs: Record<string, string>;
+  decryptedCredentials?: Map<string, string>;
+  log: Logger;
+}
+
+/* ---------------- Snapshot / Rollback（§8） ---------------- */
+
+export type SnapshotEntryKind = 'settingsNamespace' | 'credential' | 'patchLine' | 'file' | 'workspaceRecord';
+
+export interface SnapshotEntry {
+  kind: SnapshotEntryKind;
+  adapter: SectionId;
+  ref: string;
+  /** 原值（credential 条目不含值，仅 existed 标志） */
+  before: unknown;
+  revision?: number;
+  /** file 条目：原文件副本在快照存储中的位置 */
+  copiedTo?: string;
+  /** credential/file 条目：原目标是否存在 */
+  existed?: boolean;
+  /** 所属快照 id（file 条目回滚读取 blob 时使用） */
+  snapshotId?: string;
+}
+
+export interface Snapshot {
+  id: string;
+  createdAt: string;
+  sourceZip: string;
+  entries: SnapshotEntry[];
+}
+
+/** 快照存储（默认文件实现见 core/backup.ts；测试可用内存实现） */
+export interface SnapshotStore {
+  save(snapshot: Snapshot, blobs?: Map<string, Uint8Array>): Promise<string>;
+  load(id: string): Promise<Snapshot>;
+  readBlob(id: string, blobPath: string): Promise<Uint8Array>;
+}
+
+export interface RollbackReport {
+  full: boolean;
+  restored: string[];
+  failed: { item: string; reason: string; manualHint?: string }[];
+}
+
+/* ---------------- 兼容性（§13.3 注释规则） ---------------- */
+
+export interface CompatibilityInput {
+  sourceDsh: string;
+  targetDsh: string;
+  sourcePlatform: string;
+  targetPlatform: string;
+  schemaVersion: number;
+  missingSections: SectionId[];
+}
+
+export type CompatibilityScore = 'excellent' | 'good' | 'partial' | 'unsupported';
+
+/* ---------------- 导出报告（规范 §21） ---------------- */
+
+export interface ExportReport {
+  included: { section: SectionId; counts: Record<string, number> }[];
+  excluded: SectionId[];
+  security: {
+    secretsExcluded: boolean;
+    containsSecrets: boolean;
+    encrypted: boolean;
+    redactedHits: number;
+  };
+  file: { name: string; sizeBytes: number };
+  warnings: string[];
+}
+
+/* ---------------- ConfigAdapter 契约（m5 实现；§13.2） ---------------- */
+
+export type Portability = 'portable' | 'deviceSpecific' | 'platformSpecific';
+
+export interface ConfigAdapter<TSection = unknown> {
+  readonly id: SectionId;
+  readonly displayName: string;
+  readonly defaultIncluded: boolean;
+  readonly portability: Portability;
+
+  /** 读取当前 DSH 该类别配置 → 导出数据（无秘密值） */
+  export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<TSection>>;
+
+  /** 分析导入数据与目标 DSH 的差异 → 计划项（纯计算，零写入） */
+  analyzeImport(data: TSection, ctx: ImportContext): Promise<PlanItem[]>;
+
+  /** 执行单个计划项（Importer 引擎按阶段调度） */
+  applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
+
+  /** 结构校验 */
+  validate(data: TSection): Promise<ValidationResult>;
+
+  /** 可选：导入前快照（缺省用引擎通用快照） */
+  snapshot?(targets: SnapshotTarget[], ctx: HostContext): Promise<SnapshotEntry[]>;
+
+  /** 可选：针对本 adapter 的补偿动作 */
+  rollback?(entries: SnapshotEntry[], ctx: HostContext): Promise<void>;
+}
+
+/* ---------------- 加密提供者（m4 用 node:crypto 实现） ---------------- */
+
+export interface EncryptionProvider {
+  encrypt(plaintext: string): Promise<{ blob: Uint8Array; info: EncryptionInfo }>;
+  /** authTag 校验失败必须抛错 */
+  decrypt(blob: Uint8Array, info: EncryptionInfo, password: string): Promise<string>;
+}
+
+/* ---------------- 错误类型 ---------------- */
+
+/** 导入被确认前拒绝执行（安全阀） */
+export class ImportNotConfirmedError extends Error {
+  constructor() {
+    super('导入未确认：必须显式 confirm 后才允许修改任何数据');
+    this.name = 'ImportNotConfirmedError';
+  }
+}
+
+/** 导入失败：触发回滚后抛出，携带结果供 UI 展示 */
+export class ImportFailedError extends Error {
+  readonly result: ImportResult;
+  constructor(message: string, result: ImportResult) {
+    super(message);
+    this.name = 'ImportFailedError';
+    this.result = result;
+  }
+}

package/src/core/validator.ts

@@ -0,0 +1,84 @@
+/**
+ * 整体校验与兼容性评分（规范 §18 完整性 / §30 兼容性评分 / 导入后校验）。
+ */
+import { validateManifest } from '../schema/manifest.ts';
+import { validateSectionData } from '../schema/config.ts';
+import { canImport, describeVersion } from '../schema/versions.ts';
+import type { SectionId } from '../schema/types.ts';
+import type { CompatibilityInput, CompatibilityScore, ValidationResult } from './types.ts';
+
+export { validateManifest } from '../schema/manifest.ts';
+export { validateSectionData } from '../schema/config.ts';
+
+/** 校验 ZIP 内分区数据集合（空对象=合法）；返回合并的校验结果 */
+export function validateSections(
+  sections: ReadonlyMap<SectionId, unknown>,
+): ValidationResult {
+  const issues: ValidationResult['issues'] = [];
+  for (const [sectionId, data] of sections) {
+    const sectionIssues = validateSectionData(sectionId, data);
+    for (const issue of sectionIssues) {
+      issues.push({ ...issue, path: `${sectionId}:${issue.path}` });
+    }
+  }
+  return { valid: issues.every((i) => i.severity !== 'error'), issues };
+}
+
+function parseVersion(v: string): { major: number; minor: number; patch: number; pre: number } {
+  const m = /^(\d+)\.(\d+)(?:\.(\d+))?(?:-(?:rc\.?)?(\d+))?/i.exec(v);
+  if (!m) return { major: 0, minor: 0, patch: 0, pre: 0 };
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3] ?? 0), pre: Number(m[4] ?? Infinity) };
+}
+
+/** 版本比较：-1=a<b，0=相等，1=a>b（预发布 < 正式版） */
+function compareVersions(a: ReturnType<typeof parseVersion>, b: ReturnType<typeof parseVersion>): -1 | 0 | 1 {
+  for (const k of ['major', 'minor', 'patch'] as const) {
+    if (a[k] !== b[k]) return a[k] < b[k] ? -1 : 1;
+  }
+  if (a.pre !== b.pre) return a.pre < b.pre ? -1 : 1;
+  return 0;
+}
+
+/**
+ * 兼容性评分（规则驱动，不凭感觉）：
+ *  unsupported — schema 超出本插件支持范围（过高/过低）
+ *  partial     — 跨平台、分区缺失、或备份 DSH 比目标新
+ *  good        — 备份 DSH 比目标旧（向后兼容）且其余正常
+ *  excellent   — 同平台、无缺失、schema 支持
+ */
+export function computeCompatibility(input: CompatibilityInput): CompatibilityScore {
+  if (!canImport(input.schemaVersion)) return 'unsupported';
+
+  let score: CompatibilityScore = 'excellent';
+
+  if (input.sourcePlatform !== input.targetPlatform) score = 'partial';
+  if (input.missingSections.length > 0) score = 'partial';
+
+  const src = parseVersion(input.sourceDsh);
+  const tgt = parseVersion(input.targetDsh);
+  const cmp = compareVersions(src, tgt);
+  if (cmp > 0) {
+    // 备份来自更新的 DSH → 可能有目标版本不认识的配置
+    score = 'partial';
+  } else if (cmp < 0) {
+    // 备份来自更旧的 DSH → 目标向后兼容
+    score = 'good';
+  }
+
+  return score;
+}
+
+/** 兼容性得分的可读描述（UI 报告用） */
+export function describeCompatibility(score: CompatibilityScore): string {
+  switch (score) {
+    case 'excellent': return 'Excellent — 完美兼容（同平台、无缺失、schema 支持）';
+    case 'good': return 'Good — 兼容（旧版备份导入新版 DSH）';
+    case 'partial': return 'Partial — 部分兼容（跨平台/分区缺失/版本超前，需人工确认）';
+    case 'unsupported': return 'Unsupported — 不受支持（schema 超出范围）';
+  }
+}
+
+/** 用 describeVersion 生成 schema 状态的用户可读说明 */
+export function describeSchemaStatus(schemaVersion: number): string {
+  return describeVersion(schemaVersion);
+}