@logictan/dsh-config-manager 0.1.60

package/lib/core/consult-source.d.ts

@@ -0,0 +1,58 @@
+import type { SectionId } from '../schema/types.ts';
+import type { ConsultSourceData, ConsultSourceRef, MigratabilityResult } from './migration-consult.ts';
+export interface ConsultSourceReaderOptions {
+    /** 计算可迁移性（宿主注入；缺省 null = 不评估） */
+    computeMigratability?: (zipPath: string) => Promise<MigratabilityResult>;
+    /** 高熵扫描开关（固定 true 保证确定性；缺省 true） */
+    highEntropy?: boolean;
+}
+/** 从导出 ZIP 读取并归一化源数据（只读） */
+export declare function readExportZipSource(ref: ConsultSourceRef, zipPath: string, opts?: ConsultSourceReaderOptions): Promise<ConsultSourceData>;
+export interface LocalSnapshotSourceInput {
+    /** 快照捕获的分区数据（按 adapter 分组；best-effort） */
+    sections: Map<SectionId, unknown>;
+    /** 快照完整性校验结果（verifySnapshot） */
+    verify: {
+        ok: boolean;
+        reason?: string;
+    };
+    /** 恢复计划（planRestore）→ 可迁移性 */
+    restorePlan: {
+        itemCount: number;
+        conflicts: number;
+        warnings: number;
+        sections: SectionId[];
+        errors: string[];
+    };
+    /** 合成 manifest 的源信息（宿主 dshVersion/platform） */
+    sourceDsh: string;
+    sourcePlatform: string;
+}
+/**
+ * 从本地快照（rollback 点）构建 ConsultSourceData。
+ * 快照无导出 manifest → 用合成 manifest（schemaVersion=1，sections 来自捕获分区），
+ * 避免「无导出 manifest」被误判为 compatibility/integrity critical。
+ * 完整性 = verifySnapshot（blob hashes / metadataHash）；可迁移性 = planRestore。
+ */
+export declare function buildLocalSnapshotSource(ref: ConsultSourceRef, input: LocalSnapshotSourceInput): ConsultSourceData;
+export interface ProfileSourceInput {
+    /** profile 的分区数据（decodeSections） */
+    sections: Map<SectionId, unknown>;
+    /** 切换预览（analyzeSwitch）→ 可迁移性 */
+    switchPreview: {
+        itemCount: number;
+        conflicts: number;
+        warnings: number;
+        sections: SectionId[];
+        errors: string[];
+    };
+    /** 合成 manifest 的源信息（宿主 dshVersion/platform） */
+    sourceDsh: string;
+    sourcePlatform: string;
+}
+/**
+ * 从配置档案（profile.json）构建 ConsultSourceData。
+ * profile 无导出 manifest → 用合成 manifest（sections 来自 profile 分区）。
+ * 可迁移性 = analyzeSwitch（切换预览计划项）。
+ */
+export declare function buildProfileSource(ref: ConsultSourceRef, input: ProfileSourceInput): ConsultSourceData;

package/lib/core/consult-source.js

@@ -0,0 +1,260 @@
+/**
+ * 迁移前咨询的源读取（Phase 7，只读分析层）。
+ *
+ * 把 4 种可迁移源（export-zip / local-snapshot / remote-snapshot / profile）归一化为
+ * `ConsultSourceData`，供 `computeConsultReport` 评分。本模块**只读**：
+ *  - 读 ZIP / 快照 / profile 文件；
+ *  - 复用安全/schema 工具（parseZipHardened / parseManifest / verifyChecksumsJson /
+ *    validateSectionData / scanAndRedact / scanText）；
+ *  - 可迁移性经宿主注入的 `computeMigratability`（analyzeImport / createImportPlan，零写入）。
+ *
+ * READ-ONLY 磁盘边界：临时 ZIP 可写但必须净空（调用方负责 try/finally 清理）；
+ * 配置 / 快照存储 / journal 零写。
+ */
+import fs from 'node:fs/promises';
+import { parseZipHardened } from '../security/zip-security.js';
+import { MANIFEST_FILE, CHECKSUMS_FILE, parseManifest, validateManifest } from '../schema/manifest.js';
+import { verifyChecksumsJson } from '../security/integrity.js';
+import { SECTION_JSON_PATHS, SECTION_FILE_PREFIXES, isFileSection } from '../schema/config.js';
+import { scanAndRedact, scanText } from '../security/secret-scanner.js';
+/** 从导出 ZIP 读取并归一化源数据（只读） */
+export async function readExportZipSource(ref, zipPath, opts = {}) {
+    const highEntropy = opts.highEntropy ?? true;
+    const raw = await fs.readFile(zipPath);
+    // 1. 安全解析 ZIP（捕获 Zip Slip / 结构问题）
+    const zipSlipIssues = [];
+    let archive;
+    try {
+        archive = parseZipHardened(raw);
+    }
+    catch (err) {
+        zipSlipIssues.push(err instanceof Error ? err.message : String(err));
+        return {
+            source: ref,
+            manifest: null,
+            manifestIssues: [],
+            sections: new Map(),
+            sectionFiles: new Map(),
+            checksums: null,
+            checksumIssues: [],
+            zipSlipIssues,
+            encrypted: false,
+            containsSecrets: false,
+            sourceDsh: '',
+            sourcePlatform: '',
+            schemaVersion: 0,
+            missingSections: [],
+            sensitiveHits: [],
+            migratability: null,
+        };
+    }
+    // 2. manifest（捕获结构问题，不抛错）
+    let manifest = null;
+    let manifestIssues = [];
+    if (archive.has(MANIFEST_FILE)) {
+        try {
+            manifest = parseManifest(archive.readEntryText(MANIFEST_FILE));
+        }
+        catch {
+            // parseManifest 抛错 → 用 validateManifest 捕获具体问题
+            try {
+                const parsed = JSON.parse(archive.readEntryText(MANIFEST_FILE));
+                manifestIssues = validateManifest(parsed);
+            }
+            catch {
+                manifestIssues = [{ path: '$', message: 'manifest 无法解析', severity: 'error' }];
+            }
+        }
+    }
+    else {
+        manifestIssues = [{ path: '$', message: 'manifest 缺失', severity: 'error' }];
+    }
+    // 3. checksums（捕获不匹配，不抛错）
+    const checksumIssues = [];
+    let checksums = null;
+    if (archive.has(CHECKSUMS_FILE)) {
+        try {
+            const entries = new Map();
+            for (const name of archive.names()) {
+                if (name === MANIFEST_FILE || name === CHECKSUMS_FILE)
+                    continue;
+                try {
+                    entries.set(name, archive.readEntry(name));
+                }
+                catch { /* 损坏条目计入 checksumIssues */ }
+            }
+            const result = verifyChecksumsJson(entries, archive.readEntryText(CHECKSUMS_FILE));
+            checksums = result.ok ? {} : null;
+            for (const m of result.mismatches)
+                checksumIssues.push(`"${m}" (hash 不符)`);
+            for (const m of result.missing)
+                checksumIssues.push(`"${m}" (缺失)`);
+        }
+        catch (err) {
+            checksumIssues.push(err instanceof Error ? err.message : String(err));
+        }
+    }
+    // 4. 提取分区（捕获缺失/不可解析）
+    const sections = new Map();
+    const sectionFiles = new Map();
+    const missingSections = [];
+    if (manifest !== null) {
+        for (const [sid, enabled] of Object.entries(manifest.sections)) {
+            if (!enabled)
+                continue;
+            if (isFileSection(sid)) {
+                const prefix = SECTION_FILE_PREFIXES[sid];
+                for (const name of archive.names()) {
+                    if (!name.startsWith(prefix) || name === prefix)
+                        continue;
+                    const rel = name.slice(prefix.length);
+                    if (rel === '' || rel.endsWith('/'))
+                        continue;
+                    sectionFiles.set(`${sid}/${rel}`, archive.readEntry(name));
+                }
+                sections.set(sid, { version: 1, files: [] });
+                continue;
+            }
+            const jsonPath = SECTION_JSON_PATHS[sid];
+            if (jsonPath === undefined)
+                continue;
+            if (!archive.has(jsonPath)) {
+                missingSections.push(sid);
+                continue;
+            }
+            try {
+                sections.set(sid, archive.readEntryJson(jsonPath));
+            }
+            catch {
+                missingSections.push(sid);
+            }
+        }
+    }
+    // 5. 敏感暴露面（scanAndRedact 结构化 + scanText 文件类）
+    const sensitiveHits = [];
+    for (const [sid, data] of sections) {
+        const { hits } = scanAndRedact(data, { highEntropy });
+        for (const h of hits)
+            sensitiveHits.push({ path: `${sid}:${h.path}`, field: h.field });
+    }
+    for (const [key, bytes] of sectionFiles) {
+        const text = Buffer.from(bytes).toString('utf8');
+        for (const h of scanText(text, { highEntropy })) {
+            sensitiveHits.push({ path: `${key}:${h.path}`, field: h.field });
+        }
+    }
+    // 6. 可迁移性（宿主注入；零写入）
+    const migratability = opts.computeMigratability !== undefined
+        ? await opts.computeMigratability(zipPath)
+        : null;
+    return {
+        source: ref,
+        manifest,
+        manifestIssues,
+        sections,
+        sectionFiles,
+        checksums,
+        checksumIssues,
+        zipSlipIssues,
+        encrypted: manifest?.security.encrypted ?? false,
+        containsSecrets: manifest?.security.containsSecrets ?? false,
+        sourceDsh: manifest?.source.dshVersion ?? '',
+        sourcePlatform: manifest?.source.platform ?? '',
+        schemaVersion: manifest?.schemaVersion ?? 0,
+        missingSections,
+        sensitiveHits,
+        migratability,
+    };
+}
+/**
+ * 从本地快照（rollback 点）构建 ConsultSourceData。
+ * 快照无导出 manifest → 用合成 manifest（schemaVersion=1，sections 来自捕获分区），
+ * 避免「无导出 manifest」被误判为 compatibility/integrity critical。
+ * 完整性 = verifySnapshot（blob hashes / metadataHash）；可迁移性 = planRestore。
+ */
+export function buildLocalSnapshotSource(ref, input) {
+    const sectionFlags = {};
+    for (const sid of input.sections.keys())
+        sectionFlags[sid] = true;
+    const manifest = {
+        schemaVersion: 1,
+        exporter: { name: 'DSH Config Manager', version: 'snapshot' },
+        source: { dshVersion: input.sourceDsh, platform: input.sourcePlatform, arch: 'unknown' },
+        exportedAt: new Date().toISOString(),
+        sections: sectionFlags,
+        security: { containsSecrets: false, encrypted: false, encryption: null },
+    };
+    const manifestIssues = input.verify.ok ? [] : [{ path: '$', message: input.verify.reason ?? '快照完整性校验失败', severity: 'error' }];
+    const checksumIssues = input.verify.ok ? [] : [input.verify.reason ?? '快照完整性校验失败'];
+    const migratability = {
+        ok: input.restorePlan.errors.length === 0,
+        itemCount: input.restorePlan.itemCount,
+        fatalConflicts: input.restorePlan.conflicts,
+        warnings: input.restorePlan.warnings,
+        sections: input.restorePlan.sections,
+        errors: input.restorePlan.errors,
+    };
+    return {
+        source: ref,
+        manifest,
+        manifestIssues,
+        sections: input.sections,
+        sectionFiles: new Map(),
+        checksums: input.verify.ok ? {} : null,
+        checksumIssues,
+        zipSlipIssues: [],
+        encrypted: false,
+        containsSecrets: false,
+        sourceDsh: input.sourceDsh,
+        sourcePlatform: input.sourcePlatform,
+        schemaVersion: 1,
+        missingSections: [],
+        sensitiveHits: [],
+        migratability,
+    };
+}
+/**
+ * 从配置档案（profile.json）构建 ConsultSourceData。
+ * profile 无导出 manifest → 用合成 manifest（sections 来自 profile 分区）。
+ * 可迁移性 = analyzeSwitch（切换预览计划项）。
+ */
+export function buildProfileSource(ref, input) {
+    const sectionFlags = {};
+    for (const sid of input.sections.keys())
+        sectionFlags[sid] = true;
+    const manifest = {
+        schemaVersion: 1,
+        exporter: { name: 'DSH Config Manager', version: 'profile' },
+        source: { dshVersion: input.sourceDsh, platform: input.sourcePlatform, arch: 'unknown' },
+        exportedAt: new Date().toISOString(),
+        sections: sectionFlags,
+        security: { containsSecrets: false, encrypted: false, encryption: null },
+    };
+    const migratability = {
+        ok: input.switchPreview.errors.length === 0,
+        itemCount: input.switchPreview.itemCount,
+        fatalConflicts: input.switchPreview.conflicts,
+        warnings: input.switchPreview.warnings,
+        sections: input.switchPreview.sections,
+        errors: input.switchPreview.errors,
+    };
+    return {
+        source: ref,
+        manifest,
+        manifestIssues: [],
+        sections: input.sections,
+        sectionFiles: new Map(),
+        checksums: {},
+        checksumIssues: [],
+        zipSlipIssues: [],
+        encrypted: false,
+        containsSecrets: false,
+        sourceDsh: input.sourceDsh,
+        sourcePlatform: input.sourcePlatform,
+        schemaVersion: 1,
+        missingSections: [],
+        sensitiveHits: [],
+        migratability,
+    };
+}
+//# sourceMappingURL=consult-source.js.map

package/lib/core/crash-report.d.ts

@@ -0,0 +1,84 @@
+/** 上次启动结果（持久化到 <dir>/boot-state.json）。 */
+export interface BootState {
+    /** 本次启动开始时刻（ISO 字符串）。 */
+    startedAt: string;
+    /** 启动进程 pid。 */
+    pid: number;
+    /** 本次启动是否已判定成功。 */
+    ok: boolean;
+    /** 判定成功的时刻；未成功为 null。 */
+    okAt: string | null;
+    /** 最近一次「确认正常」的时刻（成功启动时推进）。 */
+    lastGoodAt: string | null;
+    /** 崩溃原因归因；无归因为 null。 */
+    crashReason: CrashKind | null;
+}
+/** 崩溃原因分类（日志尾部签名 → 枚举；无匹配为 unknown）。 */
+export type CrashKind = 'session-corrupt' | 'bundle-check' | 'patch-tree' | 'unknown';
+/** 本次启动的 boot alert（结构化判定结果，无用户文案）。 */
+export interface BootAlert {
+    /** 是否判定为「上次启动崩溃」。 */
+    crashed: boolean;
+    /** 最近一次确认正常的时刻（供「恢复最后正常快照」使用）。 */
+    lastGoodAt: string | null;
+    /** 崩溃原因；未崩溃或无证据为 null。 */
+    crashReason: CrashKind | null;
+    /** 建议用户采取的动作，枚举而非文案。 */
+    advice: CrashAdvice;
+}
+/** 建议动作（枚举码；文案由宿主 i18n 决定）。 */
+export type CrashAdvice = 'none' | 'restore-last-good' | 'repair-session' | 'check-bundles' | 'check-patch-tree';
+/** 按日志尾部签名分类崩溃原因；无匹配返回 'unknown'。 */
+export declare function classifyCrashLog(text: string): CrashKind;
+/**
+ * advice 由 crashReason 决定：session-corrupt→repair-session, bundle-check→check-bundles,
+ * patch-tree→check-patch-tree, unknown→restore-last-good（crashReason 为 null 时同样
+ * 回退 restore-last-good：崩溃但无归因证据，只有「回到最后正常」这一条稳妥动作）。
+ * crashed=false 时 advice='none'。
+ */
+export declare function adviceFor(kind: CrashKind | null, crashed: boolean): CrashAdvice;
+/** 只读读取 boot-state；缺失/损坏/非法一律返回 null（绝不抛）。 */
+export declare function readBootState(dir: string): Promise<BootState | null>;
+/**
+ * 原子写入 boot-state（用 ../utils/atomic-write.ts 的 atomicWriteFile）。失败不抛。
+ * 只落盘 BootState 的六个已知字段（避免调用方对象上的额外字段进入持久化文件）。
+ */
+export declare function writeBootState(dir: string, state: BootState): Promise<void>;
+/**
+ * 计算本次启动的 boot alert。
+ * - prev 为 null（首次启动）→ crashed=false，lastGoodAt=null，crashReason=null，advice='none'；
+ * - prev.ok !== true → crashed=true（上次没走到「确认成功」）；
+ * - crashReason 优先沿用 prev.crashReason（上次已算过），否则若给了 logTail 就用 classifyCrashLog；
+ * - crashed=false 时 crashReason 恒为 null（健康启动不做归因，见文件头「语义决策」）。
+ */
+export declare function computeBootAlert(prev: BootState | null, logTail: string | null): BootAlert;
+/**
+ * 从候选日志文件里读尾部（最多 maxBytes，默认 262144），返回第一个非空日志的文本；
+ * 无则 null。单个候选不可读（不存在/无权限/是目录）不抛，直接跳到下一个。
+ */
+export declare function readCrashLogTail(candidates: readonly string[], maxBytes?: number): Promise<string | null>;
+/**
+ * 列出候选日志路径：`<homeDir>/logs/*.log`（按文件名字典序，稳定可测）与
+ * `<homeDir>/dsh.log`（存在才纳入）。`logs` 目录不存在/不可读时返回空数组
+ * —— 与「无候选日志」同义（不抛）。
+ */
+export declare function listCandidateLogs(homeDir: string): Promise<string[]>;
+/**
+ * 选「最后正常快照」：在 snapshots 中找 createdAt <= lastGoodAt 的**最新**一个，
+ * 跳过 kind==='pre-restore'（恢复前双保险快照，不代表「正常状态」）。
+ * lastGoodAt 为 null / 非法 → null；无符合项（含 createdAt 不可解析者）→ null。
+ * createdAt 相同时保留数组中靠前者。入参为最小结构类型，刻意不 import restore.ts
+ * （快照元信息 → 恢复执行 的依赖方向必须单向，避免循环依赖）。
+ */
+export declare function selectLastGoodSnapshot<T extends {
+    id: string;
+    createdAt: string;
+    kind?: string;
+}>(snapshots: readonly T[], lastGoodAt: string | null): T | null;
+/** 启动生命周期辅助：apply 时调用一次，写「正在启动」（ok:false）。 */
+export declare function beginBoot(pid: number, prev: BootState | null, now?: () => Date): BootState;
+/**
+ * 30 秒后 / dispose 时调用：标记成功并推进 lastGoodAt（ok:true、okAt=lastGoodAt=now）。
+ * 同时清空 crashReason：本次启动已确认正常，陈旧归因不得延续到下一次崩溃判定。
+ */
+export declare function markBootOk(state: BootState, now?: () => Date): BootState;