dsh-config-manager 0.1.67 → 0.1.68

package/icon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="DSH Config Manager">
+  <defs>
+    <linearGradient id="tile" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#5B7CFA"/>
+      <stop offset="1" stop-color="#3B3AD1"/>
+    </linearGradient>
+  </defs>
+  <rect width="512" height="512" rx="112" fill="url(#tile)"/>
+  <path fill="#FFFFFF" d="M196 142 254 226H224V364H168V226H138Z"/>
+  <path fill="#FFFFFF" d="M316 370 258 286H288V148H344V286H374Z"/>
+</svg>

package/lib/adapters/file-collection.d.ts

@@ -1,6 +1,6 @@
 import type { MsgFunc } from '../core/messages.ts';
 import type { FilesSection, SectionId } from '../schema/types.ts';
-import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext, ImportContext, PlanItem, Portability, ValidationResult } from '../core/types.ts';
+import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext, ImportContext, PlanItem, Portability, SectionPreview, ValidationResult } from '../core/types.ts';
 /**
  * 文件类分区导出的**单分区累计字节闸门**：分区内文件内容合计放不下的单元整块剔除（见 export()）。
  *
@@ -66,6 +66,36 @@ export declare abstract class FileCollectionAdapter implements ConfigAdapter<Fil
         warnings: string[];
     } | null>;
     export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<FilesSection>>;
+    /**
+     * 只读预览（`/export-preview`）：与 `export()` **共用同一个内核**（`collect`），
+     * 只把「读文件内容 + SHA-256」换成 `ctx.fs.statSize`。
+     *
+     * 为什么必须共用：预览说的「会带哪些单元、各多大」就是用户勾选的依据，一旦与真实导出
+     * 分叉，用户会按预览勾选却拿到不同的包（`file-collection.test.ts` 逐项断言两者相等）。
+     */
+    preview(ctx: HostContext, options: ExportOptions): Promise<SectionPreview<FilesSection>>;
+    /**
+     * 分区收集内核（`export` / `preview` 共用）。
+     *
+     * - `mode === 'content'`：读文件内容 + 算 SHA-256（真实导出）；
+     * - `mode === 'size'`：只取字节数（`ctx.fs.statSize`），不解码、不哈希（预览）。
+     *
+     * 两种模式共用**同一套**单元分组、条目级白名单、单分区字节闸门与告警生成 ——
+     * 因此「预览的单元 / 体积 / 告警」与「导出的单元 / 体积 / 告警」逐项相等。
+     *
+     * 返回值里的 `entries` **只含** `relativePath`/`data`/`contentHash` 三个字段：
+     * `FilesSection` 是备份格式的一部分，多带内部字段会被序列化出去；体积走旁路 `sizes`。
+     */
+    private collect;
+    /**
+     * 读一个成员文件。
+     *
+     * - `content`：读内容并按需算 SHA-256（真实导出）；
+     * - `size`：优先 `ctx.fs.statSize`（只 stat，不读内容）；门面未实现或返回 null（文件消失 /
+     *   读不到）时**退回 readFile** —— 与改造前把「读不到」暴露成同一个错误，绝不把未知体积
+     *   当成 0（0 会让字节闸门少算，把本该剔除的单元放进预览，预览与导出就分叉了）。
+     */
+    private readMember;
     /** 单元清单（零 I/O：直接由 export 产物归并）。 */
     listUnits(section: ExportSection<FilesSection>): ExportUnit[];
     analyzeImport(data: FilesSection, ctx: ImportContext): Promise<PlanItem[]>;

package/lib/adapters/file-collection.js

@@ -16,7 +16,7 @@ import { sha256Hex } from '../utils/hashing.js';
 import { isReservedInternalRel, normalizePath } from '../utils/paths.js';
 import { msgOf, zhMsg } from '../core/messages.js';
 import { linkWarnings, listFilesDetailed } from './link-report.js';
-import { defaultUnitId, unitAllowed, unitsFromFiles } from './units.js';
+import { defaultUnitId, unitAllowed, unitsFromEntries, unitsFromFiles } from './units.js';
 import { validateJsonSection } from './json-section.js';
 /**
  * 文件类分区导出的**单分区累计字节闸门**：分区内文件内容合计放不下的单元整块剔除（见 export()）。
@@ -40,6 +40,14 @@ import { validateJsonSection } from './json-section.js';
 export const MAX_FILE_SECTION_BYTES = 256 * 1024 * 1024;
 /** 字节闸门告警里最多列出的单元数（其余折叠成 "(+ N)"，避免大分区把报告撑爆；与 link-report 同口径） */
 const MAX_UNITS_PER_GATE_WARNING = 5;
+/**
+ * 只读预览下文件条目的占位内容（长度 0）。
+ *
+ * 为什么可用空内容：预览产出的 `FilesSection` 只在内存里流转（选择器只需要 `relativePath`
+ * 与体积），**绝不**进 ZIP / 快照 / 导入路径 —— 空内容一旦被误当导出产物，写出去的会是空文件。
+ * 因此 `preview()` 的返回值在类型注释里明确标注「不是格式的一部分」（见 types.ts 的 SectionPreview）。
+ */
+const EMPTY_DATA = new Uint8Array(0);
 /** 告警文案里的体积（人类可读；纯数值格式化，不含用户可见散文） */
 function formatBytes(bytes) {
     if (bytes < 1024)
@@ -95,7 +103,49 @@ export class FileCollectionAdapter {
         return null;
     }
     async export(ctx, options) {
+        const collected = await this.collect(ctx, options, 'content');
+        return {
+            sectionId: this.id,
+            data: { version: 1, files: collected.entries },
+            counts: { files: collected.entries.length },
+            warnings: collected.warnings,
+        };
+    }
+    /**
+     * 只读预览（`/export-preview`）：与 `export()` **共用同一个内核**（`collect`），
+     * 只把「读文件内容 + SHA-256」换成 `ctx.fs.statSize`。
+     *
+     * 为什么必须共用：预览说的「会带哪些单元、各多大」就是用户勾选的依据，一旦与真实导出
+     * 分叉，用户会按预览勾选却拿到不同的包（`file-collection.test.ts` 逐项断言两者相等）。
+     */
+    async preview(ctx, options) {
+        const collected = await this.collect(ctx, options, 'size');
+        return {
+            section: {
+                sectionId: this.id,
+                data: { version: 1, files: collected.entries },
+                counts: { files: collected.entries.length },
+                warnings: collected.warnings,
+            },
+            sizeBytes: collected.totalBytes,
+            items: unitsFromEntries(this.id, collected.sizes, (rel) => this.unitIdOf(rel)),
+        };
+    }
+    /**
+     * 分区收集内核（`export` / `preview` 共用）。
+     *
+     * - `mode === 'content'`：读文件内容 + 算 SHA-256（真实导出）；
+     * - `mode === 'size'`：只取字节数（`ctx.fs.statSize`），不解码、不哈希（预览）。
+     *
+     * 两种模式共用**同一套**单元分组、条目级白名单、单分区字节闸门与告警生成 ——
+     * 因此「预览的单元 / 体积 / 告警」与「导出的单元 / 体积 / 告警」逐项相等。
+     *
+     * 返回值里的 `entries` **只含** `relativePath`/`data`/`contentHash` 三个字段：
+     * `FilesSection` 是备份格式的一部分，多带内部字段会被序列化出去；体积走旁路 `sizes`。
+     */
+    async collect(ctx, options, mode) {
         const files = [];
+        const sizes = [];
         const warnings = [];
         const allow = options.includeItems?.[this.id];
         // issue #37：用「跟随 junction/符号链接」的遍历，并把跟随/跳过的链接写进告警——
@@ -148,11 +198,15 @@ export class FileCollectionAdapter {
             const pending = [];
             let unitBytes = 0;
             for (const member of unitEntries.get(unitId) ?? []) {
-                const data = await ctx.fs.readFile(member.rel);
-                unitBytes += data.byteLength;
+                const read = await this.readMember(ctx, member.rel, mode);
+                unitBytes += read.sizeBytes;
                 if (unitBytes > room)
                     break;
-                pending.push({ rel: member.rel, file: { relativePath: member.relPath, data, contentHash: sha256Hex(data) } });
+                pending.push({
+                    rel: member.rel,
+                    sizeBytes: read.sizeBytes,
+                    entry: { relativePath: member.relPath, data: read.data, contentHash: read.contentHash },
+                });
             }
             if (unitBytes > room) {
                 droppedUnits.push(unitId);
@@ -160,13 +214,15 @@ export class FileCollectionAdapter {
             }
             usedBytes += unitBytes;
             for (const p of pending)
-                keptByRel.set(p.rel, p.file);
+                keptByRel.set(p.rel, { entry: p.entry, sizeBytes: p.sizeBytes });
         }
         // ③ 按 ① 的顺序落盘（未触发闸门时与改造前的文件顺序逐项一致）
         for (const rel of considered) {
-            const file = keptByRel.get(rel);
-            if (file !== undefined)
-                files.push(file);
+            const kept = keptByRel.get(rel);
+            if (kept === undefined)
+                continue;
+            files.push(kept.entry);
+            sizes.push({ relativePath: kept.entry.relativePath, sizeBytes: kept.sizeBytes });
         }
         // 绝不静默：被整块剔除的单元写进告警（导出报告可见），并给出上限与实际保留量
         if (droppedUnits.length > 0) {
@@ -183,12 +239,24 @@ export class FileCollectionAdapter {
         if (rels.length === 0)
             warnings.push(msgOf(ctx)('adapter.dirEmpty', { type: this.displayName }));
         warnings.push(...linkWarnings(msgOf(ctx), this.displayName, listing));
-        return {
-            sectionId: this.id,
-            data: { version: 1, files },
-            counts: { files: files.length },
-            warnings,
-        };
+        return { entries: files, sizes, totalBytes: usedBytes, warnings };
+    }
+    /**
+     * 读一个成员文件。
+     *
+     * - `content`：读内容并按需算 SHA-256（真实导出）；
+     * - `size`：优先 `ctx.fs.statSize`（只 stat，不读内容）；门面未实现或返回 null（文件消失 /
+     *   读不到）时**退回 readFile** —— 与改造前把「读不到」暴露成同一个错误，绝不把未知体积
+     *   当成 0（0 会让字节闸门少算，把本该剔除的单元放进预览，预览与导出就分叉了）。
+     */
+    async readMember(ctx, rel, mode) {
+        if (mode === 'size') {
+            const size = (await ctx.fs.statSize?.(rel)) ?? null;
+            if (size !== null)
+                return { data: EMPTY_DATA, sizeBytes: size, contentHash: '' };
+        }
+        const data = await ctx.fs.readFile(rel);
+        return { data, sizeBytes: data.byteLength, contentHash: mode === 'content' ? sha256Hex(data) : '' };
     }
     /** 单元清单（零 I/O：直接由 export 产物归并）。 */
     listUnits(section) {

package/lib/adapters/test-helpers.d.ts

@@ -26,6 +26,13 @@ export declare class MemFs implements FileSystemFacade {
     /** 测试助手：登记某文件的 mtime（null = 恢复为「读不到」） */
     setMtime(relPath: string, ms: number | null): void;
     mtimeMs(relPath: string): Promise<number | null>;
+    /**
+     * 文件字节数（只读预览用）。
+     *
+     * 语义与真实门面一致：**读不到 → null**（不返回 0）—— 0 会让字节闸门少算，
+     * 让预览把本该剔除的单元也列出来，与真实导出分叉。
+     */
+    statSize(relPath: string): Promise<number | null>;
     listRecursive(dir: string): Promise<string[]>;
     mkdir(): Promise<void>;
 }

package/lib/adapters/test-helpers.js

@@ -57,6 +57,16 @@ export class MemFs {
     async mtimeMs(relPath) {
         return this.mtimes.get(this.key(relPath)) ?? null;
     }
+    /**
+     * 文件字节数（只读预览用）。
+     *
+     * 语义与真实门面一致：**读不到 → null**（不返回 0）—— 0 会让字节闸门少算，
+     * 让预览把本该剔除的单元也列出来，与真实导出分叉。
+     */
+    async statSize(relPath) {
+        const v = this.files.get(this.key(relPath));
+        return v === undefined ? null : v.byteLength;
+    }
     async listRecursive(dir) {
         const base = normalizePath(this.homeDir);
         const prefix = normalizePath(dir) === '' ? base : `${base}/${normalizePath(dir)}`;

package/lib/adapters/units.d.ts

@@ -23,10 +23,20 @@ export declare function defaultUnitId(rel: string): string;
  * 空数组 = 什么都不允许（调用方应把该分区整体视为未勾选，见 Exporter.export）。
  */
 export declare function unitAllowed(allow: readonly string[] | undefined, id: string): boolean;
-/** 白名单是否让该分区整体为空（= 用户取消了整个分区，不是「导出空分区」）。 */
-export declare function allowListEmptiesSection(allow: readonly string[] | undefined): boolean;
 /** 由「成员文件」归并出单元清单（体积 = 成员文件字节合计；零 I/O）。 */
 export declare function unitsFromFiles(sectionId: string, files: readonly {
     relativePath: string;
     data: Uint8Array;
 }[], unitIdOf: (rel: string) => string): ExportUnit[];
+/**
+ * 由「路径 + 已知体积」归并出单元清单（零 I/O）。
+ *
+ * 为什么要有这一份：只读预览（`/export-preview`）拿不到文件内容（也不该读），体积来自
+ * `ctx.fs.statSize`。若预览改用「data 为空的 FilesSection」喂 `unitsFromFiles`，
+ * 每个单元的体积会变成 0，选择器显示的体积全错。两份实现必须**同一套聚合规则**，
+ * 否则预览与导出会算出不同的单元体积（`file-collection.test.ts` 钉住两者逐项相等）。
+ */
+export declare function unitsFromEntries(sectionId: string, entries: readonly {
+    relativePath: string;
+    sizeBytes: number;
+}[], unitIdOf: (rel: string) => string): ExportUnit[];

package/lib/adapters/units.js

@@ -15,18 +15,25 @@ export function defaultUnitId(rel) {
 export function unitAllowed(allow, id) {
     return allow === undefined || allow.includes(id);
 }
-/** 白名单是否让该分区整体为空（= 用户取消了整个分区，不是「导出空分区」）。 */
-export function allowListEmptiesSection(allow) {
-    return allow !== undefined && allow.length === 0;
-}
 /** 由「成员文件」归并出单元清单（体积 = 成员文件字节合计；零 I/O）。 */
 export function unitsFromFiles(sectionId, files, unitIdOf) {
+    return unitsFromEntries(sectionId, files.map((f) => ({ relativePath: f.relativePath, sizeBytes: f.data.byteLength })), unitIdOf);
+}
+/**
+ * 由「路径 + 已知体积」归并出单元清单（零 I/O）。
+ *
+ * 为什么要有这一份：只读预览（`/export-preview`）拿不到文件内容（也不该读），体积来自
+ * `ctx.fs.statSize`。若预览改用「data 为空的 FilesSection」喂 `unitsFromFiles`，
+ * 每个单元的体积会变成 0，选择器显示的体积全错。两份实现必须**同一套聚合规则**，
+ * 否则预览与导出会算出不同的单元体积（`file-collection.test.ts` 钉住两者逐项相等）。
+ */
+export function unitsFromEntries(sectionId, entries, unitIdOf) {
     const byUnit = new Map();
-    for (const f of files) {
+    for (const f of entries) {
         const unit = unitIdOf(f.relativePath);
         const cur = byUnit.get(unit) ?? { count: 0, size: 0 };
         cur.count += 1;
-        cur.size += f.data.length;
+        cur.size += f.sizeBytes;
         byUnit.set(unit, cur);
     }
     return [...byUnit.entries()].map(([unit, agg]) => ({