labull-framework 0.1.23 → 0.1.25

package/dist/types/magic-block-localfs.d.ts

@@ -64,9 +64,66 @@ export interface WriteFailure {
 export interface WriteResult {
     written: number;
     failed: WriteFailure[];
-    /** 一共排了几个文件（= `written + failed.length`，进度条的分母）。 */
+    /** 一共排了几个文件（= `written + skipped + trusted + failed.length`，进度条的分母）。 */
     total: number;
+    /** 读过一眼、确认盘上那份一模一样，因此没写的文件数（`verify` 打开时才有）。 */
+    skipped: number;
+    /** **账本命中**、一下都没碰的文件数（见 `WriteOptions.trust`）。 */
+    trusted: number;
+    /**
+     * 这一趟之后"哪个路径上是哪一份内容"是**确定**的（写过的 + 读过的 + 账本命中的）。
+     * 🔴 调用方把它当**下一趟的账本**存起来（见 `WriteOptions.trust`）：这就是"重复导出秒出"的来源。
+     * ⚠️ 失败的那些**不在里面**（盘上那份不是我们写的，不能算数）。
+     */
+    fingerprints: Map<string, string>;
 }
+/** `writePackage` 的开关。 */
+export interface WriteOptions {
+    /**
+     * 写之前**先读一眼**：盘上那份与要写的一模一样就**不写**（`skipped` 计数）。
+     *
+     * 🔴 这是"重复导出"那个闭环里最划算的一件事，而且**不改任何语义**：正文一字不差时
+     *    "写"与"不写"落盘的字节完全相同（只是 mtime 不动）。实测（真实开发包 136 个文件）：
+     *    全写 205 ms → 全跳过 53 ms；改 3 个文件后再导 70 ms。
+     * 🔴 **为什么值得**：`createWritable()` 不是"就地改几个字节"——浏览器要**另写一份临时文件再原子改名**，
+     *    所以一次写的代价远大于一次读。一个块的代码改一行，没必要把另外 135 个文件重写一遍。
+     * 🔴 **代价**：多一次 `getFileHandle`（+ 命中时一次 `getFile().text()`）。读不到（没这个文件）
+     *    就退回"照写"，所以**空目录上开着它也不亏**（实测 68 ms → 62 ms，在噪声里）。
+     * ⚠️ 读得到、比不了（不是文本 / 权限不对）也算"不比" ⇒ 照写：那种情况本来就该由写那一步报错。
+     * ⚠️ 刚 `clearChildren()` 过的目录可以传 `false`：那里**一个文件都不存在**，读那一趟纯属白问。
+     */
+    verify?: boolean;
+    /**
+     * **账本**：`包内相对路径 → 内容指纹`，记的是**上一趟我们亲手铺在那儿的**那一份
+     * （`WriteResult.fingerprints`）。指纹一样 + `existing` 说盘上真有这一份 ⇒ **一下都不碰**。
+     *
+     * 🔴 为什么还要它（`verify` 已经是"读一眼再决定"了）：**问题在"读一眼"这个动作本身**。
+     *    真实开发包 136 个文件，每份要 `getFileHandle` + `getFile` + `text()` 三次往返 ——
+     *    文件多起来之后（15 个块）这一趟就是几秒。而"上一趟铺的就是这一份"这件事我们**自己知道**，
+     *    不必每次去问盘。实测（用户真实项目 13 个块 / 136 个文件）：93 个块-文件那一档
+     *    "逐字节核对"要 3 次往返/文件，账本命中是 **0 次**。
+     * 🔴 **代价是一条语义上的让步（必须让用户知道）**：账本命中就**不再看盘**，所以
+     *    ① 用户在自己编辑器里改过、又没读回库的那些文件**会保留他的改动**（不会被盖掉 ——
+     *    这通常是好事，但"导出=覆盖"这句话就不再完全成立）；
+     *    ② 因此**必须**同时给 `existing`（`listExisting()` 的返回值）：少了它，用户手动删掉的
+     *    文件会被我们"跳过"成永远缺失。
+     * 🔴 账本只是**加速**，不是判据：丢了、换了目录、刷新了页面 ⇒ 自动退回"读一眼逐字节比对"，
+     *    结论一模一样，只是慢一次。
+     */
+    trust?: ReadonlyMap<string, string>;
+    /** `listExisting()` 的结果：这一包里哪些路径**盘上真有**（`trust` 命中时用它确认文件还在）。 */
+    existing?: ReadonlySet<string>;
+}
+/**
+ * 正文的**内容指纹**（同一路径上"是不是我们上次写的那一份"）。
+ *
+ * 🔴 **不是安全判据**，所以不必上 SHA-256：这里只回答"和上一趟那一份一样吗"，
+ *    撞车的后果仅仅是**少写一次**（文件停在我们上一趟写的内容上），不是写错内容。
+ *    53 位 + 长度，几百个文件的规模上撞车概率可以忽略。
+ * 🔴 **同步**：它在进写盘循环**之前**把整包算完（2 MB 上下 ≈ 20 ms），
+ *    换成 `crypto.subtle` 就得把一串 Promise 织进那个并发循环里 —— 不值得。
+ */
+export declare function contentDigest(text: string): string;
 /**
  * 把一整个开发包写进用户选的目录（`{相对路径: 正文}`）。
  *
@@ -74,11 +131,13 @@ export interface WriteResult {
  *    这个函数自己**不删任何东西**（`clearChildren()` 才是删那一步），它只管写。
  * 🔴 **并发写 + 目录句柄缓存**：原来是一个文件一个文件地等、每个文件都从根重新走一遍目录，
  *    几十个文件（含 540 KB 的主题那份）要串行好几趟目录树。
+ *    ⚠️ 实测（真实开发包 136 个文件）并发 8 / 16 / 32 **一样快**：浏览器那一侧本来就是一件件做的，
+ *       把口子开更大不解决问题 —— 真正省时间的是"**不写**"（见 `WriteOptions.verify`）。
  * 🔴 **一个文件写失败不许把整批吞掉**：失败收进 `failed` 回给调用方（这一层的判据与后端
  *    `export.write_dir` 一致 —— "一个块失败只报它自己"），调用方把它们显示出来。
  *    原来是一抛全停：排在前面的文件已经落盘了，用户却只看到一句"失败"，不知道铺了多少。
  */
-export declare function writePackage(dir: LocalDir, files: Record<string, string>, onProgress?: (done: number, total: number) => void): Promise<WriteResult>;
+export declare function writePackage(dir: LocalDir, files: Record<string, string>, onProgress?: (done: number, total: number) => void, options?: WriteOptions): Promise<WriteResult>;
 /** 选中目录里都有什么（顶层项 + 递归数出来的文件 / 目录数）—— 导出前"要不要清空"那个确认框用。 */
 export interface DirInventory {
     /** 顶层项（名字 + 是不是目录）。 */
@@ -114,6 +173,44 @@ export declare function inspectDirectory(dir: LocalDir, rules: ScanRules): Promi
  *    ⚠️ 一个删不掉就照原样抛（**与串行一样**）：已经删掉的那些留在那儿，"删了几项"由调用方自己看到。
  */
 export declare function clearChildren(dir: LocalDir): Promise<number>;
+/**
+ * **只删"这一包不要的东西"**（导出时那个「清空」用的扫帚）。
+ *
+ * 🔴 它与 `clearChildren()` 的**结果一样**：铺完之后目录里正好只剩这一包。但过程省得多 ——
+ *    包里那些**盘上已有**的文件原地留着（读一眼、一样就不动，见 `WriteOptions.verify`），
+ *    只删包里**没有**的东西（上一趟留下的垃圾、用户自己放进去的文件）。
+ * 🔴 **为什么值得**：`createWritable()` 不是就地改几个字节（浏览器要另写一份临时文件再原子改名），
+ *    所以"全删再全铺"里的每一次写都是白花；实测（真实开发包 136 个文件）：
+ *    全删重铺 228 ms → 只删多余 + 复用没变的 79 ms。
+ * 🔴 **只删 `dir` 里面的东西**（与 `clearChildren` 同一条边界），而"要留哪些"由**这一包自己**
+ *    算出来（`files` 的键逐级拼成集合）—— 不是从盘上读到什么再拼一次路径，所以"删到别处去"
+ *    在实现上就不可能。
+ * 🔴 **形状冲突也顺手清掉**：盘上那个位置是**目录**而包里要的是文件（或反过来）⇒ 它不在
+ *    "这一包要的文件 / 目录"集合里，于是被删掉，紧接着由写那一步按正确的形状建出来。
+ *    （这是"全删再铺"顺带保证的一件事，这里必须显式保住：否则同名目录会让那一次写直接失败。）
+ *
+ * :return: `{ removed, existing }` —— 删掉的**条目数**（每层各算一个；被整棵删掉的目录算它自己
+ *    那一个，与 `clearChildren` 报的"几项"同一个口径）+ 这一包里**盘上真有**的那些路径
+ *    （顺手数出来的，`WriteOptions.existing` 直接用，省掉再多走一遍目录树）。
+ */
+export declare function pruneTo(dir: LocalDir, files: Record<string, string>): Promise<PruneResult>;
+/** `pruneTo()` 的结果。 */
+export interface PruneResult {
+    /** 删掉的条目数（每层各算一个）。 */
+    removed: number;
+    /** 这一包里**盘上真有**的那些文件路径（顺手数出来的）。 */
+    existing: Set<string>;
+}
+/**
+ * 这一包里**哪些路径盘上真有**（只读：一个字节都不改）。
+ *
+ * 🔴 它是"账本快路"的**存在性判据**（`WriteOptions.trust` + `existing`）：账本只说"我们上一趟
+ *    把这一份铺在那儿了"，而"现在还在不在"只有盘知道 —— 少了这一步，用户手动删掉的文件会被
+ *    我们一直跳过（永远缺失）。
+ * 🔴 **只走这一包要的那些目录**（不是整棵树）：一个块文件夹有 5-10 个文件但只有 2-3 层目录，
+ *    于是"问清 136 个文件在不在"只要几十次目录遍历，而不是 136×3 次文件往返。
+ */
+export declare function listExisting(dir: LocalDir, files: Record<string, string>): Promise<Set<string>>;
 /**
  * 选中的目录**本身**就是代码那一层时当场说清（`workspace/workspace/…` 是没人想要的）。
  *

package/dist/types/magic-block-manifest.d.ts

@@ -2,8 +2,15 @@
 export declare const BLOCK_ENTRY = "index.open.html";
 /** 块包清单（必备件）。与后端 `sdk.BLOCK_MANIFEST` 逐字一致。 */
 export declare const BLOCK_MANIFEST = "magic-block.open.yaml";
-/** 清单只认这四个键，全部必填（顺序就是文档里的顺序）。 */
-export declare const MANIFEST_KEYS: readonly ["id", "module", "name", "brief"];
+/** 清单认得的键（顺序就是文档里的顺序）。🔴 `detail` 是**可选**的第五个键。 */
+export declare const MANIFEST_KEYS: readonly ["id", "module", "name", "brief", "detail"];
+/** 必须写全的那四个键（= `MANIFEST_KEYS` 去掉可选的 `detail`）。
+ *
+ *  🔴 为什么 `detail` **不进必填这一档**：它是给人读的详情介绍（一段话，比 `brief` 那句长），
+ *     存量块的清单里一个都没有 —— 判"缺少 detail"等于让库里每一个块在保存 / 体检时集体判不合格。
+ *  🔴 认得的键与必填的键**必须分开两处**：合成一处的话，报文会把可选键说成必填。
+ *     与后端 `validate.MANIFEST_REQUIRED` 逐字对齐。 */
+export declare const MANIFEST_REQUIRED: readonly ["id", "module", "name", "brief"];
 export type ManifestKey = (typeof MANIFEST_KEYS)[number];
 /** 可读名的字符上限（与后端 `NAME_MAX` 同一份）。 */
 export declare const NAME_MAX = 40;
@@ -15,7 +22,7 @@ export declare function validName(value: string): boolean;
 export type Manifest = Partial<Record<ManifestKey, string>>;
 /** 一个块包的校验结果。`files` 是提交时**原样回给后端**的那一份，这里只读不写。 */
 export interface BlockValidation {
-    /** 清单里读出来的四个键（没读全就是空对象）。 */
+    /** 清单里读出来的键（没读全就是空对象）。 */
     manifest: Manifest;
     /** 逐条问题，中文、可直接显示给用户。 */
     issues: string[];

package/dist/types/magic-block-real.d.ts

@@ -3,6 +3,6 @@ export { default as MagicBlockConsole } from './magic-block-MagicBlockConsole.vu
 export { loadBlockRender, onBlockRenderRefresh, refreshBlockRender, type BlockRender } from './magic-block-render';
 export { BLOCK_BACKEND_FILE, BLOCK_ENTRY, buildPreview } from './magic-block-preview';
 export { CLIENT_SOURCE, installBridge, type BridgeDeps } from './magic-block-bridge';
-export { BLOCK_MANIFEST, MANIFEST_KEYS, NAME_MAX, checkSelection, parseManifest, validFileName, validName, validateBlock, type BlockValidation, type Manifest, type ManifestKey, type SelectionCheck, } from './magic-block-manifest';
+export { BLOCK_MANIFEST, MANIFEST_KEYS, MANIFEST_REQUIRED, NAME_MAX, checkSelection, parseManifest, validFileName, validName, validateBlock, type BlockValidation, type Manifest, type ManifestKey, type SelectionCheck, } from './magic-block-manifest';
 export { API_BASE } from './auth-real';
 export { declaredMissing, declaredUuidOf, declaredUuidsOf, type DeclaredEntry, type DeclaredRoute, } from './magic-block-declared';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "labull-framework",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "private": false,
   "type": "module",
   "description": "Labull 前端 SDK：主题 CSS + 登录态 / 外壳组件 / magic block（四块合一，一个包）",