@tensorix/metahub 0.1.4 → 0.1.7

package/README.zh-CN.md

@@ -0,0 +1,127 @@
+# metahub
+
+**给你的 AI 一个本地知识库。**
+
+[English](./README.md) · 简体中文
+
+metahub 是基于 Bun + SQLite 的本地优先知识库 CLI，给 AI agent 一份持久、可同步的工作记忆：用 notion 风格的**类型化数据表**装结构化数据，用 **markdown 文档**装长文本知识，再配一套像 `Read / Edit / Write` 的编辑接口。数据全部存在你本机的 `~/.metahub/`，单机离线可用，多机之间保持一致。
+
+> 运行时依赖 [Bun](https://bun.sh)。用 `bunx`、全局安装后的 `mh`，或下载独立二进制都行。
+
+## 为什么用它
+
+- **为 AI 读写而设计** —— `doc read` 先返回正文 + 版本号，`doc edit --old/--new` 做锚定查找替换、只传增量；引用一律支持 id 前缀 / 名字，不必粘完整 id。
+- **结构化 + 非结构化一处管** —— 类型化数据表（行 / 列，8 种属性类型）放任务、流水、联系人；markdown 文档放设计稿、笔记。
+- **本地优先、可同步** —— 数据在你自己的磁盘上，离线可用；多台机器干净合并，改不同段落互不覆盖。
+- **自带 GUI 与 API** —— `mh --server` 一条命令起浏览器 WebUI（浏览 / 行内编辑 / 全文搜索）+ `/api/*` REST 接口 + 自动生成的 OpenAPI 文档。
+
+<!-- TODO 截图：docs/assets/webui.png（WebUI）、docs/assets/desktop.png（桌面端） -->
+> 想看界面？装上[桌面 App](#获取--安装)，或运行 `mh --server` 后打开 `http://localhost:7777/`。
+
+## 快速开始
+
+```bash
+bunx @tensorix/metahub init                       # 创建 ~/.metahub
+mh db create "Tasks"                              # 建一张表 → 返回 id，如 db_tasks-k3f9c1
+mh use tasks                                      # 设为「当前库」，之后 record/prop 免带库参数
+mh prop add Title  --type text
+mh prop add Status --type select --options "todo,doing,done"
+mh record create --data '{"Title":"写设计稿","Status":"todo"}'
+mh doc create --title "架构说明" --body @arch.md  # @file / @- / 直接字符串
+mh search "架构"                                   # 全文检索文档 + 记录
+```
+
+引用不必粘完整 id：凡接受 id 的地方都接受**完整 id / 唯一前缀 / 名字**，歧义时报错列候选。
+
+**给 AI 用的非交互增量编辑**（对标 `Read / Edit / Write`）：
+
+```bash
+mh doc read <ref>                                 # 读正文 + version（改前先读）
+mh doc edit <ref> --old "旧文本" --new "新文本"   # 锚定查找替换，只传增量
+mh doc append <ref> --body "追加段落"             # 也有 prepend
+```
+
+输出按受众自动切换：终端（人）显示表格 / markdown，被管道或子进程调用（AI）输出 **JSON**；`--json` / `--pretty` 可强制。
+
+## 获取 / 安装
+
+| 形态 | 安装 | 适合 |
+| --- | --- | --- |
+| **桌面 App**（GUI） | `brew install --cask tensorix/tap/metahub-app` | 想要图形界面、像 notion 那样用 |
+| **CLI** | `brew install tensorix/tap/metahub-cli`，或 `npm i -g @tensorix/metahub`，或免安装 `bunx @tensorix/metahub <cmd>` | AI agent / 命令行 |
+| **库**（Bun） | `bun add @tensorix/metahub` | 在自己的 Bun 程序里直接调用 |
+| **独立二进制** | 下载对应平台文件，`chmod +x` 后直接运行 | 无运行时环境 |
+
+```ts
+// 作为库使用：所有 core 能力从包根导出
+import { openMetahub, createDatabase, createRecord, search } from "@tensorix/metahub";
+```
+
+支持平台：`darwin-arm64` / `darwin-x64` / `linux-x64` / `linux-arm64` / `windows-x64`。库 API 详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
+
+## 多机同步
+
+在一台机器起服务端，另一台与它同步。文档按段落级合并，所以并发改同一篇文档的不同部分能干净合并。
+
+```bash
+# A 机：启动同步服务端（它本身也是一个 metahub 节点）
+mh --server --port 7777
+
+# B 机：与服务端推 / 拉一轮
+mh sync http://a-host:7777
+```
+
+配对一次后即可后台**周期性自动双向同步**，不必每次手敲 `mh sync`。同一条 `sync` 命令也能在「单个文档 / 数据表」与本地文件之间导入导出（文档 ↔ markdown、数据表 ↔ CSV）。原理详见[系统设计文档](./docs/system-design/)。
+
+## WebUI、API 与 Agent 站点
+
+`mh --server` 在根路径 `/` 内置浏览器 **WebUI**（浏览 / 行内编辑数据表、块级所见即所得编辑文档、全文搜索）。同一服务端还暴露：
+
+- `/api/*` —— REST 接口，读写本库的数据表与文档。
+- `/docs` —— 自动生成的 OpenAPI 文档。
+- `/sites/<name>/` —— `mh site publish` 托管 agent 生成的 HTML/CSS/JS；页面同源调用 `/api/*` 即可读本库数据（一个本地 mini-Supabase）。
+
+每个请求由单 token 守护（持久化在 `~/.metahub`）。服务端默认只绑 `127.0.0.1`；`--host 0.0.0.0` 才对外，此时凭据以明文 Bearer 传输，请置于可信网络或前置 TLS。细节见[系统设计文档](./docs/system-design/)。
+
+## 命令参考
+
+<details>
+<summary>展开完整命令表</summary>
+
+| 命令 | 说明 |
+| --- | --- |
+| `mh init` | 创建 `~/.metahub` |
+| `mh db create\|list\|get\|delete` | 管理数据库（表） |
+| `mh use [<db>] [--clear]` | 设置/显示「当前库」（record/prop 默认作用于它） |
+| `mh get <ref>` | 通用查找：按 id/前缀/名字解析，自动判别类型 |
+| `mh prop add\|list\|update\|remove` | 管理属性（列）；`add` 用 `--db` 指定库（默认当前库） |
+| `mh record create\|list\|get\|update\|delete` | 管理记录（行） |
+| `mh doc create\|list\|get\|update\|delete` | 管理 markdown 文档 |
+| `mh doc read <id>` | 读正文 + version token（AI 改前先读） |
+| `mh doc edit <id> --old --new` | 锚定查找替换（`--replace-all` / `--if-match`） |
+| `mh doc append\|prepend <id> --body` | 在文档首/尾追加块 |
+| `mh edit <id>` | 在 `$EDITOR` 中交互式编辑文档/记录（给人用） |
+| `mh search <query>` | 全文检索（文档 + 记录） |
+| `mh doctor` | 只读体检：列出逻辑完整性问题（孤儿引用/单元格、重复路径、文档环、重名等） |
+| `mh repair [--dry-run]` | 确定性、幂等修复可自动修的问题（改动随 oplog 复制）；`--dry-run` 仅预览（等价 doctor） |
+| `mh site create\|put\|publish\|list\|files\|rm\|delete` | 托管 agent 生成的静态站点（HTML/CSS/JS），由 `--server` 在 `/sites/<name>/` serve 出去 |
+| `mh token [show\|refresh]` | 查看 / 轮换持久化的服务器鉴权 token（存于 `~/.metahub`，默认 30 天到期轮换） |
+| `mh completion <bash\|zsh\|fish>` | 打印补全脚本：`eval "$(mh completion zsh)"` |
+| `mh sync <url>` | 与服务端同步一轮（CRDT 推/拉）；`/sync` 受保护时按已存凭据直连，否则在交互终端提示输入 token 并记住（`--token` 非交互） |
+| `mh sync <src> <dst>` | 单个文档/数据表与文件互导：文档↔markdown、数据表↔CSV；方向按参数判别（哪侧是库内实体） |
+| `mh config` | 配置服务器与同步设备：无参进交互向导，`--flag` 直配（`--host/--port/--sync-interval/--auto-sync`） |
+| `mh config peer code\|add\|list\|sync\|enable\|disable\|rm` | 多设备配对与管理：生成一次性配对码 / 配对 / 列出 / 立即同步 / 启停 / 移除（连带吊销签发给对方的凭据） |
+| `mh config grant list\|revoke` | 列出 / 吊销本机签发的入站同步凭据（`revoke --token` 支持精确或前缀） |
+| `mh --server [--port] [--host] [--debug] [--token] [--sync-interval] [--no-auto-sync]` | 启动服务端：`/sync`（主 token 或配对凭据）+ 根路径 WebUI + `/api/*` REST + `/docs`（OpenAPI）+ 静态站点 `/sites/<name>/` + token 交换 `/auth/token` + 配对 `/api/pair`；内置定时器自动同步已配对 peer |
+
+</details>
+
+## 文档
+
+- [系统设计](./docs/system-design/) —— 架构、数据模型、能力清单、使用流程。
+- [贡献指南](./CONTRIBUTING.md) —— 本地开发、构建、发布、目录结构、库 API。
+- [桌面 App](./apps/desktop/README.md) —— Electron 壳 + Bun sidecar。
+
+## 许可证
+
+[AGPL-3.0-only](./LICENSE)。

package/dist/cli.js

@@ -5,25 +5,43 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -667,7 +685,7 @@ var init_prompt = __esm(() => {
   Object.keys(r.modifier);
   tD = Object.keys(r.color);
   eD = Object.keys(r.bgColor);
-  [...tD];
+  [...tD, ...eD];
   iD = sD();
   v = new Set(["\x1B", "\x9B"]);
   y = `${rD}8;;`;
@@ -891,7 +909,7 @@ function observeHlc(db, node, remote, now = Date.now()) {
 }
 
 // src/core/blocks.ts
-function parseBlocks(md) {
+function parseDocBlocks(md) {
   if (!md)
     return [];
   const lines = md.replace(/\r\n?/g, `
@@ -901,24 +919,24 @@ function parseBlocks(md) {
   let cur = [];
   let fenceChar = null;
   let fenceLen = 0;
-  const flushPara = () => {
-    while (cur.length && cur[cur.length - 1].trim() === "")
-      cur.pop();
-    while (cur.length && cur[0].trim() === "")
-      cur.shift();
-    if (cur.length)
-      blocks.push(cur.join(`
-`));
-    cur = [];
+  const closeBlock = () => {
+    if (cur.length) {
+      blocks.push({ text: cur.join(`
+`), blankAfter: 0 });
+      cur = [];
+    }
+  };
+  const onBlank = () => {
+    closeBlock();
+    if (blocks.length)
+      blocks[blocks.length - 1].blankAfter++;
   };
   for (const raw of lines) {
     if (fenceChar) {
       cur.push(raw);
       const m2 = raw.match(/^\s*(`{3,}|~{3,})\s*$/);
       if (m2 && m2[1][0] === fenceChar && m2[1].length >= fenceLen) {
-        blocks.push(cur.join(`
-`));
-        cur = [];
+        closeBlock();
         fenceChar = null;
         fenceLen = 0;
       }
@@ -926,28 +944,34 @@ function parseBlocks(md) {
     }
     const open = raw.match(/^\s*(`{3,}|~{3,})/);
     if (open) {
-      flushPara();
+      closeBlock();
       fenceChar = open[1][0];
       fenceLen = open[1].length;
       cur.push(raw);
     } else if (raw.trim() === "") {
-      flushPara();
+      onBlank();
     } else {
       cur.push(raw);
     }
   }
-  if (fenceChar) {
-    if (cur.length)
-      blocks.push(cur.join(`
-`));
-  } else {
-    flushPara();
-  }
+  closeBlock();
+  for (let i2 = 0;i2 < blocks.length - 1; i2++)
+    blocks[i2].blankAfter = Math.max(0, blocks[i2].blankAfter - 1);
   return blocks;
 }
-function serializeBlocks(texts) {
-  return texts.filter((t2) => !!t2 && t2.length > 0).join(`
-
+function serializeDocBlocks(blocks) {
+  const live = blocks.filter((b2) => !!b2.text && b2.text.length > 0);
+  const out = [];
+  live.forEach((b2, i2) => {
+    out.push(...b2.text.split(`
+`));
+    const extra = Math.max(0, b2.blankAfter ?? 0);
+    if (i2 < live.length - 1)
+      out.push("");
+    for (let k2 = 0;k2 < extra; k2++)
+      out.push("");
+  });
+  return out.join(`
 `);
 }
 function reconcile(oldTexts, newTexts) {
@@ -1004,9 +1028,9 @@ function isBlockManaged(db, docId) {
   return db.query("SELECT 1 AS x FROM doc_blocks WHERE doc_id = ? LIMIT 1").get(docId) != null;
 }
 function recomputeDocBody(db, docId) {
-  const rows = db.query("SELECT text FROM doc_blocks WHERE doc_id = ? AND __deleted = 0 ORDER BY order_key, id").all(docId);
+  const rows = db.query("SELECT text, blank_after FROM doc_blocks WHERE doc_id = ? AND __deleted = 0 ORDER BY order_key, id").all(docId);
   ensureRow(db, "documents", docId);
-  db.query("UPDATE documents SET body = ? WHERE id = ?").run(serializeBlocks(rows.map((r3) => r3.text)), docId);
+  db.query("UPDATE documents SET body = ? WHERE id = ?").run(serializeDocBlocks(rows.map((r3) => ({ text: r3.text, blankAfter: r3.blank_after ?? 0 }))), docId);
 }
 function materialize(db, dataset, rowId, col, valueJson) {
   if (dataset === "records") {
@@ -1096,7 +1120,7 @@ var init_crdt = __esm(() => {
     },
     doc_blocks: {
       table: "doc_blocks",
-      cols: new Set(["doc_id", "text", "order_key", "__deleted"])
+      cols: new Set(["doc_id", "text", "order_key", "blank_after", "__deleted"])
     },
     sites: {
       table: "sites",
@@ -1390,6 +1414,7 @@ async function serveWebui(req) {
         headers: { "content-type": "text/javascript; charset=utf-8" }
       });
     } catch (e3) {
+      console.error("[webui] failed to serve /webui.js \u2014", e3);
       return new Response(`webui build failed: ${e3}`, { status: 500 });
     }
   }
@@ -1423,6 +1448,7 @@ var HTML = `<!doctype html>
     --radius:8px; --radius-sm:6px;
     --ui:"Hanken Grotesk",-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;
     --mono:"JetBrains Mono",ui-monospace,SFMono-Regular,monospace;
+    --note-lh:1.6;
     --code-bg:#f8f8f6;
     --hl-cmt:#9a9aa2; --hl-key:#a626a4; --hl-str:#28823f; --hl-num:#b76a00;
     --hl-fn:#3f51d6; --hl-type:#0a7ea4; --hl-var:#c2410c;
@@ -1455,7 +1481,7 @@ var HTML = `<!doctype html>
   * { box-sizing: border-box; }
   html, body { margin: 0; height: 100%; }
   body { font-family: var(--ui); font-size: 14px; line-height: 1.55; color: var(--fg); background: var(--bg);
-    overflow: hidden; -webkit-font-smoothing: antialiased; text-rendering: optimizeLegibility; }
+    overflow: hidden; text-rendering: auto; }
   button { font: inherit; color: inherit; cursor: pointer; background: none; border: 0; padding: 0; }
   input, textarea { font: inherit; color: inherit; }
   .muted { color: var(--muted); }
@@ -1511,6 +1537,8 @@ var HTML = `<!doctype html>
   .dragging { opacity:.35; }
   .sb-footer { flex:none; padding:6px 8px; border-top:1px solid var(--line); }
   .sb-footer .navitem { font-size:13.5px; }
+  .nav-dot { flex:none; width:7px; height:7px; border-radius:50%; background:var(--danger);
+    box-shadow:0 0 0 2px var(--surface); margin-right:2px; }
 
   /* settings page */
   .set-page { max-width:680px; margin:0 auto; padding:40px 28px 64px; }
@@ -1520,8 +1548,19 @@ var HTML = `<!doctype html>
   .set-section-head { font-size:12px; font-weight:600; text-transform:uppercase; letter-spacing:.07em; color:var(--muted); margin-bottom:4px; }
   .set-section-desc { color:var(--fg-soft); margin-bottom:16px; }
   .set-footer { margin-top:40px; padding-top:20px; border-top:1px solid var(--line); display:flex;
-    justify-content:center; gap:8px; color:var(--muted); font-size:12px; }
-  .set-footer-sep { opacity:.5; }
+    flex-wrap:wrap; justify-content:center; align-items:center; gap:7px; color:var(--muted); font-size:12px; }
+  .set-footer-sep { opacity:.45; }
+  .ver-num { font-family:var(--mono); font-size:11px; color:var(--fg-soft); letter-spacing:-.01em; }
+  .ver-up { display:inline-flex; align-items:center; gap:6px; }
+  .ver-up.err .ver-msg { color:var(--danger); }
+  .ver-act { background:none; border:0; padding:0; margin:0; font:inherit; font-size:12px; line-height:1;
+    color:var(--muted); cursor:pointer; transition:color .12s; }
+  .ver-act:hover { color:var(--accent); }
+  .ver-act.accent { color:var(--accent); font-weight:600; }
+  .ver-act[aria-disabled="true"] { opacity:.6; cursor:default; pointer-events:none; }
+  .ver-dot { width:6px; height:6px; border-radius:50%; background:var(--accent); flex:none; }
+  .ver-dot.pulse { animation:verpulse 1.8s ease-in-out infinite; }
+  @keyframes verpulse { 0%,100% { opacity:1; } 50% { opacity:.4; } }
   .theme-grid { display:grid; grid-template-columns:repeat(3,1fr); gap:12px; }
   .theme-card { position:relative; display:flex; flex-direction:column; align-items:flex-start; gap:10px;
     text-align:left; padding:16px; border:1px solid var(--line-strong); border-radius:var(--radius);
@@ -1614,8 +1653,10 @@ var HTML = `<!doctype html>
   /* The list item's host gutter controls the whole unit, so suppress the nested
      code block's own gutter (it would overlap the list marker on the same row). */
   .block.list-code-host + .block-wrap.nested .gutter { display:none; }
-  .editable { outline:none; flex:1; min-width:0; padding:3px 2px; line-height:1.6; }
+  .editable { outline:none; flex:1; min-width:0; padding:3px 2px; line-height:var(--note-lh); }
   .editable:empty::before { content:attr(data-ph); color:var(--muted); pointer-events:none; }
+  /* The generic "/" prompt only shows on the focused line; idle blank lines (paragraphs and list items, any depth) stay blank. */
+  .editable[data-ph-hint="slash"]:empty:not(:focus)::before { content:""; }
   .b-h1 .editable { font-size:28px; font-weight:700; letter-spacing:-.02em; padding-top:12px; }
   .b-h2 .editable { font-size:22px; font-weight:650; letter-spacing:-.01em; padding-top:8px; }
   .b-h3 .editable { font-size:18px; font-weight:600; padding-top:4px; }
@@ -1667,7 +1708,8 @@ var HTML = `<!doctype html>
   .hljs-emphasis { font-style:italic; }
   .hljs-strong { font-weight:700; }
   .marker { width:24px; flex:none; text-align:center; color:var(--fg-soft); user-select:none; padding-top:4px; }
-  .b-todo .marker { padding-top:5px; }
+  .b-todo .marker { box-sizing:content-box; padding-top:3px; height:calc(1em * var(--note-lh));
+    display:flex; align-items:center; justify-content:center; }
   .b-todo .marker input { width:15px; height:15px; accent-color:var(--accent); cursor:pointer; }
   .b-divider { padding:10px 0; }
   .b-divider hr { border:0; border-top:1px solid var(--line-strong); margin:0; width:100%; }
@@ -1854,14 +1896,14 @@ var HTML = `<!doctype html>
   .optrow .x:hover { background:var(--hover-2); color:var(--danger); }
 
   /* modal */
-  .modal-scrim { position:fixed; inset:0; background:rgba(15,15,25,.4); z-index:100; display:grid; place-items:center;
+  .modal-scrim { position:fixed; inset:0; background:rgba(15,15,25,.4); z-index:100; display:flex; align-items:center; justify-content:center;
     opacity:0; pointer-events:none; transition:opacity .15s; padding:20px; }
   .modal-scrim.open { opacity:1; pointer-events:auto; }
-  .modal { background:var(--bg); border-radius:16px; box-shadow:var(--shadow-lg); width:440px; max-width:100%; overflow:hidden; }
+  .modal { background:var(--bg); border-radius:16px; box-shadow:var(--shadow-lg); width:440px; max-width:100%; max-height:100%; display:flex; flex-direction:column; overflow:hidden; }
   .modal-head { padding:20px 22px 0; }
   .modal-head h3 { margin:0; font-size:18px; font-weight:700; letter-spacing:-.01em; }
   .modal-head p { margin:6px 0 0; color:var(--muted); font-size:13.5px; }
-  .modal-body { padding:18px 22px; }
+  .modal-body { padding:18px 22px; overflow-y:auto; }
   .modal-foot { display:flex; justify-content:flex-end; gap:8px; padding:14px 22px; background:var(--surface); border-top:1px solid var(--line); }
   .field-label { font-size:12px; font-weight:600; color:var(--fg-soft); margin:12px 0 5px; }
   .field-label:first-child { margin-top:0; }
@@ -2080,6 +2122,17 @@ var HTML = `<!doctype html>
   .qn-body .doc { max-width:none; margin:0; padding:14px 22px 30vh; }
   .qn-body .doc-title { font-size:24px; margin-bottom:2px; }
   .qn-body .doc-meta { display:none; }
+  /* A native checkbox paints an opaque white box when unchecked, which breaks
+     the window's vibrancy blur. Draw a custom box so the unchecked background
+     stays transparent; checked falls back to the accent fill + checkmark. */
+  body.quicknote .b-todo .marker input {
+    appearance:none; -webkit-appearance:none; box-sizing:border-box;
+    border:1.5px solid color-mix(in srgb, var(--fg-soft) 55%, transparent);
+    border-radius:4px; background:transparent; }
+  body.quicknote .b-todo .marker input:checked {
+    border-color:var(--accent);
+    background:var(--accent) center/10px no-repeat
+      url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='white' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12l5 5L20 7'/%3E%3C/svg%3E"); }
   /* Compact menus inside the quick-note window only (dropdown + slash command
      share .pop/.item/.lico with the main app; scope under body.quicknote so the
      main app keeps its roomier density). */
@@ -3540,8 +3593,9 @@ async function runMain(cmd, opts = {}) {
 // package.json
 var package_default = {
   name: "@tensorix/metahub",
-  version: "0.1.4",
+  version: "0.1.7",
   description: "Metahub core library and CLI",
+  license: "AGPL-3.0-only",
   type: "module",
   main: "./dist/index.js",
   module: "./dist/index.js",
@@ -3559,7 +3613,9 @@ var package_default = {
   },
   files: [
     "dist",
-    "README.md"
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
   ],
   scripts: {
     dev: "bun --hot src/cli/index.ts",
@@ -3692,11 +3748,12 @@ CREATE TABLE IF NOT EXISTS documents (
 -- independent CRDT register so concurrent edits to different blocks merge.
 -- order_key is a fractional index (ties broken by id) giving display order.
 CREATE TABLE IF NOT EXISTS doc_blocks (
-  id        TEXT PRIMARY KEY,
-  doc_id    TEXT,
-  text      TEXT,
-  order_key TEXT,
-  __deleted INTEGER NOT NULL DEFAULT 0
+  id          TEXT PRIMARY KEY,
+  doc_id      TEXT,
+  text        TEXT,
+  order_key   TEXT,
+  blank_after INTEGER NOT NULL DEFAULT 0,  -- extra blank lines kept after this block (user spacing)
+  __deleted   INTEGER NOT NULL DEFAULT 0
 );
 CREATE INDEX IF NOT EXISTS idx_doc_blocks_doc ON doc_blocks(doc_id);
 
@@ -4384,6 +4441,10 @@ function migratePeers(db) {
       db.exec(`ALTER TABLE peers ADD COLUMN ${col} ${decl}`);
   }
 }
+function migrateDocBlocks(db) {
+  if (!hasColumn(db, "doc_blocks", "blank_after"))
+    db.exec("ALTER TABLE doc_blocks ADD COLUMN blank_after INTEGER NOT NULL DEFAULT 0");
+}
 function openMetahub() {
   ensureDirs();
   const db = new Database(dbPath(), { create: true });
@@ -4391,6 +4452,7 @@ function openMetahub() {
   runSchema(db);
   migrateRecords(db);
   migratePeers(db);
+  migrateDocBlocks(db);
   return db;
 }
 
@@ -4562,7 +4624,7 @@ var use_default = defineCommand({
 init_ids();
 init_crdt();
 function liveBlocks(db, docId) {
-  return db.query("SELECT id, text, order_key FROM doc_blocks WHERE doc_id = ? AND __deleted = 0 ORDER BY order_key, id").all(docId);
+  return db.query("SELECT id, text, order_key, blank_after FROM doc_blocks WHERE doc_id = ? AND __deleted = 0 ORDER BY order_key, id").all(docId);
 }
 function makeBlockId(text) {
   return newId("blk", text.split(`
@@ -4572,29 +4634,37 @@ function emitBlock(db, docId, fields) {
   const id = makeBlockId(fields.text);
   emit(db, "doc_blocks", id, "doc_id", docId);
   emit(db, "doc_blocks", id, "order_key", fields.order_key);
+  if (fields.blankAfter)
+    emit(db, "doc_blocks", id, "blank_after", fields.blankAfter);
   emit(db, "doc_blocks", id, "text", fields.text);
 }
-function insertBlocks(db, docId, texts, after, before) {
-  const keys = keysBetween(after, before, texts.length);
-  texts.forEach((text, i2) => emitBlock(db, docId, { text, order_key: keys[i2] }));
+function insertBlocks(db, docId, blocks, after, before) {
+  const keys = keysBetween(after, before, blocks.length);
+  blocks.forEach((b2, i2) => emitBlock(db, docId, { text: b2.text, order_key: keys[i2], blankAfter: b2.blankAfter }));
 }
 function ensureBlocks(db, docId) {
   if (db.query("SELECT 1 AS x FROM doc_blocks WHERE doc_id = ? LIMIT 1").get(docId))
     return;
   const row = db.query("SELECT body FROM documents WHERE id = ?").get(docId);
-  const texts = parseBlocks(row?.body ?? "");
-  if (texts.length)
-    insertBlocks(db, docId, texts, null, null);
+  const blocks = parseDocBlocks(row?.body ?? "");
+  if (blocks.length)
+    insertBlocks(db, docId, blocks, null, null);
 }
 function reconcileBody(db, docId, body) {
   const old = liveBlocks(db, docId);
-  const plan = reconcile(old.map((b2) => b2.text), parseBlocks(body));
+  const next = parseDocBlocks(body);
+  const plan = reconcile(old.map((b2) => b2.text), next.map((b2) => b2.text));
   for (const oi of plan.deleted)
     emit(db, "doc_blocks", old[oi].id, "__deleted", 1);
   const { items } = plan;
   let i2 = 0;
   while (i2 < items.length) {
-    if ("keep" in items[i2]) {
+    const it = items[i2];
+    if ("keep" in it) {
+      const oldB = old[it.keep];
+      const want = next[i2].blankAfter;
+      if ((oldB.blank_after ?? 0) !== want)
+        emit(db, "doc_blocks", oldB.id, "blank_after", want);
       i2++;
       continue;
     }
@@ -4603,8 +4673,7 @@ function reconcileBody(db, docId, body) {
       j++;
     const left = i2 > 0 ? old[items[i2 - 1].keep].order_key : null;
     const right = j < items.length ? old[items[j].keep].order_key : null;
-    const texts = items.slice(i2, j).map((it) => it.insert);
-    insertBlocks(db, docId, texts, left, right);
+    insertBlocks(db, docId, next.slice(i2, j), left, right);
     i2 = j;
   }
 }
@@ -4623,9 +4692,9 @@ function createDocument(db, opts) {
   if (opts.parent_id !== undefined)
     emit(db, "documents", id, "parent_id", opts.parent_id);
   if (opts.body !== undefined) {
-    const texts = parseBlocks(opts.body);
-    if (texts.length)
-      insertBlocks(db, id, texts, null, null);
+    const blocks = parseDocBlocks(opts.body);
+    if (blocks.length)
+      insertBlocks(db, id, blocks, null, null);
   }
   return getDocument(db, id);
 }
@@ -4671,7 +4740,7 @@ function editDocument(db, id, opts) {
     throw new Error("--old must not be empty");
   ensureBlocks(db, id);
   const blocks = liveBlocks(db, id);
-  const body = serializeBlocks(blocks.map((b2) => b2.text));
+  const body = serializeDocBlocks(blocks.map((b2) => ({ text: b2.text, blankAfter: b2.blank_after })));
   const count = countOccurrences(body, opts.old);
   if (count === 0)
     throw new Error(`anchor not found: no match for --old`);
@@ -4698,25 +4767,25 @@ function appendDocument(db, id, body) {
   if (!getDocument(db, id))
     throw new Error(`no such document: ${id}`);
   ensureBlocks(db, id);
-  const texts = parseBlocks(body);
-  if (texts.length) {
+  const next = parseDocBlocks(body);
+  if (next.length) {
     const blocks = liveBlocks(db, id);
     const last = blocks.length ? blocks[blocks.length - 1].order_key : null;
-    insertBlocks(db, id, texts, last, null);
+    insertBlocks(db, id, next, last, null);
   }
-  return { id, changed: texts.length > 0, replaced: texts.length, version: documentVersion(db, id) };
+  return { id, changed: next.length > 0, replaced: next.length, version: documentVersion(db, id) };
 }
 function prependDocument(db, id, body) {
   if (!getDocument(db, id))
     throw new Error(`no such document: ${id}`);
   ensureBlocks(db, id);
-  const texts = parseBlocks(body);
-  if (texts.length) {
+  const next = parseDocBlocks(body);
+  if (next.length) {
     const blocks = liveBlocks(db, id);
     const first = blocks.length ? blocks[0].order_key : null;
-    insertBlocks(db, id, texts, null, first);
+    insertBlocks(db, id, next, null, first);
   }
-  return { id, changed: texts.length > 0, replaced: texts.length, version: documentVersion(db, id) };
+  return { id, changed: next.length > 0, replaced: next.length, version: documentVersion(db, id) };
 }
 function deleteDocument(db, id) {
   if (!getDocument(db, id))
@@ -17211,7 +17280,7 @@ function finalize(ctx, schema) {
     result.$schema = "http://json-schema.org/draft-07/schema#";
   } else if (ctx.target === "draft-04") {
     result.$schema = "http://json-schema.org/draft-04/schema#";
-  } else if (ctx.target === "openapi-3.0") {} else {}
+  } else if (ctx.target === "openapi-3.0") {}
   if (ctx.external?.uri) {
     const id = ctx.external.registry.get(schema)?.id;
     if (!id)
@@ -17455,7 +17524,7 @@ var literalProcessor = (schema, ctx, json, _params) => {
     if (val === undefined) {
       if (ctx.unrepresentable === "throw") {
         throw new Error("Literal `undefined` cannot be represented in JSON Schema");
-      } else {}
+      }
     } else if (typeof val === "bigint") {
       if (ctx.unrepresentable === "throw") {
         throw new Error("BigInt literals cannot be represented in JSON Schema");
@@ -23482,7 +23551,7 @@ function startServer(opts = {}) {
   let timer = null;
   if (autoSync && syncIntervalMs > 0) {
     timer = setInterval(() => {
-      syncAllPeers(db).catch(() => {});
+      syncAllPeers(db).catch((e3) => console.error("[sync] auto-sync tick failed \u2014", e3));
     }, syncIntervalMs);
     timer.unref?.();
   }
@@ -23922,4 +23991,4 @@ if (argv2.includes("--server")) {
   runMain(main, { showUsage: showUsage2 });
 }
 
-//# debugId=74D4BFCB8CE1AB2064756E2164756E21
+//# debugId=6697905C98729D8364756E2164756E21