@tensorix/metahub 0.3.2 → 0.4.0

package/README.md

@@ -78,15 +78,19 @@ mh --server --port 7777
 mh sync http://a-host:7777
 ```
 
-Pair two devices once and they sync both ways on a timer — no need to run `mh sync` each time. The same `sync` command also moves a single document or table to/from a local file (document ↔ Markdown, table ↔ CSV). See the [system-design docs](./docs/system-design/) for how it works.
+Pair two devices once (`mh config device code` / `mh config device add`) and they sync both ways on a timer — no need to run `mh sync` each time. `mh status` answers "where does my data live and how fresh is each copy" from local state alone, so it works offline. The same `sync` command also moves a single document or table to/from a local file (document ↔ Markdown, table ↔ CSV). See the [system-design docs](./docs/system-design/) for how it works.
 
 ## WebUI, API, and agent-hosted sites
 
-`mh --server` serves a browser **WebUI** at `/` (browse and inline-edit tables, block-level WYSIWYG document editing, full-text search, manage agent sites). The same server also exposes:
+`mh --server` serves a browser **WebUI** at `/` (browse and inline-edit tables, a **CodeMirror 6** WYSIWYG Markdown editor — slash menu, doc tables, media embeds, `[[…]]` internal links, one-click code-block formatting, source/blocks toggle, find, TOC — full-text search, manage agent sites). The same server also exposes:
 
 - `/api/*` — REST endpoints over your tables and documents (read **and** write; hosted site pages call them same-origin).
 - `/docs` — auto-generated OpenAPI documentation.
-- `/sites/<name>/` — `mh site publish` hosts the HTML/CSS/JS an agent generates; pages call `/api/*` same-origin, or import the optional typed client at `/metahub-sdk.js` (a local mini-Supabase). Note the trust model: hosted pages are same-origin, so any published site effectively holds full hub access — publish only sites you or your agent authored.
+- `/sites/<name>/` — `mh site upload` hosts the HTML/CSS/JS an agent generates; pages call `/api/*` same-origin, or import the optional typed client at `/metahub-sdk.js` (a local mini-Supabase). Note the trust model: hosted pages are same-origin, so any published site effectively holds full hub access — publish only sites you or your agent authored.
+- `/sites/<name>/api/*` — the **guest** data surface of a *public* site: anonymous visitors get exactly the table×operation access you granted with `mh site grant` (`read`/`create`/`update` — never delete), optionally behind a password or Turnstile.
+- `/share/<slug>` — `mh share` publishes a doc/database/site as a public link (view = read-only SSR, edit = accepts guest writes; optional password + expiry), over a server, an S3 bucket, or an always-on room on your own Cloudflare edge.
+
+**Publishing when your device is offline** is optional and runs entirely in *your* Cloudflare account: `mh edge deploy` (sign in with Cloudflare, or paste an API token) puts up one Worker with two namespaces — a **write inbox** that accepts sealed, encrypted visitor submissions your device ingests on its next sync round, and **rooms** (Durable Objects) that keep a shared site live and realtime while every device of yours is asleep. metahub itself operates no backend: the edge only ever holds ciphertext envelopes, or the partition you explicitly shared.
 
 Requests are guarded by a single token (persisted in `~/.metahub`). The server binds `127.0.0.1` by default; only `--host 0.0.0.0` exposes it, and credentials travel as plaintext Bearer — put it behind a trusted network or TLS (a reverse proxy like Caddy / Tailscale Serve, or `--tls-cert`/`--tls-key` to terminate TLS directly). Details in the [system-design docs](./docs/system-design/).
 
@@ -105,7 +109,7 @@ The WebUI is an installable PWA. Open **Settings → 离线副本** and this bro
 
 | Command | Description |
 | --- | --- |
-| `mh init` | Create `~/.metahub` |
+| `mh init` | Create `~/.metahub` (`--claude` / `--codex` install this guide as a Claude Code `/mh` / Codex `$mh` skill instead) |
 | `mh db create\|list\|get\|delete` | Manage databases (tables) |
 | `mh use [<db>] [--clear]` | Set/show the "current db" (record/prop default to it) |
 | `mh get <ref>` | Universal lookup: resolve by id/prefix/name, auto-detect type |
@@ -113,7 +117,7 @@ The WebUI is an installable PWA. Open **Settings → 离线副本** and this bro
 | `mh record create\|list\|get\|update\|delete` | Manage records (rows) |
 | `mh doc create\|list\|get\|update\|delete` | Manage Markdown documents |
 | `mh doc read <id>` | Read body + version token (AI reads before editing) |
-| `mh doc edit <id> --old --new` | Anchored find-and-replace (`--replace-all` / `--if-match`) |
+| `mh doc edit <id> --old --new` | Anchored find-and-replace (`--replace-all` / `--if-match`); `--edits '<json array>'` applies N pairs atomically in one pass |
 | `mh doc append\|prepend <id> --body` | Append a block at the document head/tail |
 | `mh doc history <id>` / `mh doc revert <id> --to <version>` | List a document's revisions / restore a past version (a new forward revision; `doc get --at <version>` previews; revert resurrects a deleted doc) |
 | `mh record history <id> [--field <name>]` / `mh record revert <id> --to <version>` | Record edit history (per-revision field diffs, or one cell's value trail) / restore past cells (resurrects a deleted record) |
@@ -124,14 +128,23 @@ The WebUI is an installable PWA. Open **Settings → 离线副本** and this bro
 | `mh doctor` | Read-only health check: list integrity issues (orphan refs/cells, duplicate paths, doc cycles, name clashes) + oplog/disk stats |
 | `mh repair [--dry-run]` | Deterministic, idempotent repair of auto-fixable issues (changes replicate via oplog); `--dry-run` previews (same as doctor) |
 | `mh compact [--keep <days>] [--dry-run]` | Prune oplog history older than the retention window (default 90d) + GC blobs + VACUUM. Local-only; current data untouched, older history collapses to a baseline |
-| `mh site create\|put\|publish\|list\|files\|rm\|delete` | Host static sites (HTML/CSS/JS) an agent generates, served by `--server` at `/sites/<name>/` |
+| `mh site create\|scaffold\|put\|upload\|list\|files\|rm\|delete` | Host static sites (HTML/CSS/JS) an agent generates, served by `--server` at `/sites/<name>/`. `scaffold` writes a starter page; `upload <dir>` mirrors a directory (`--create` on first upload, `--prune` to delete what's gone) |
+| `mh site access <site> [public\|private]` | Show or change who can reach a site. Public = token-free; private answers exactly like a nonexistent site. `--show-links` prints capability URLs (they *are* the secret) |
+| `mh site grant <site> <db>:<ops>` / `mh site grants <site>` | Anonymous data access for a public site's `api/` (`read,create,update` — no delete), optionally gated by `--password` / `--turnstile`; `--revoke <db>` / `--clear` to take it back |
+| `mh share create\|list\|servers\|link\|renew\|revoke` | Publish a doc/database/site as a public link (`/share/<slug>`): server SSR, S3 export, or `--room` on your own edge; view/edit permission, optional password + expiry, optional `--grant <db>:<ops>` data surface |
+| `mh edge deploy\|status\|pull\|rotate\|connect` | Your own Cloudflare Worker + D1 (+ Durable Objects): deploy it (sign in with Cloudflare or an API token), check health, pull the write inbox by hand, rotate recipient keys, or attach a second device to an existing edge |
+| `mh blob add <file>` / `mh blob get <hash>` | Store a local file as a content-addressed `/blob/<hash>` URL (embed in a doc) / resolve its bytes (local cache → peers → bucket) |
+| `mh cache [status\|clear\|gc\|full-device\|redundancy\|pin\|unpin]` | Inspect/manage the local blob cache; designate "full blob devices" (durable anchors) so images are safely clearable |
 | `mh token [show\|refresh]` | Show/rotate the persisted server auth token (stored in `~/.metahub`, rotates at 30-day expiry by default) |
 | `mh completion <bash\|zsh\|fish>` | Print a completion script: `eval "$(mh completion zsh)"` |
-| `mh sync <url>` | Sync one round with a server (CRDT push/pull); uses a stored credential when `/sync` is protected, otherwise prompts for a token in an interactive terminal and remembers it (`--token` for non-interactive) |
+| `mh sync` | Sync now: one round against every configured device and bucket |
+| `mh sync <url>` | Sync one round with a specific server (CRDT push/pull); uses a stored credential when `/sync` is protected, otherwise prompts for a token in an interactive terminal and remembers it (`--token` for non-interactive) |
 | `mh sync <src> <dst>` | Move a single document/table to/from a file: document ↔ Markdown, table ↔ CSV; direction inferred from which side is an in-repo entity |
-| `mh config` | Configure the server and sync devices: no args opens an interactive wizard, `--flag` sets directly (`--host/--port/--sync-interval/--auto-sync`) |
-| `mh config peer code\|add\|list\|sync\|enable\|disable\|rm` | Multi-device pairing and management: generate a one-time code / pair / list / sync now / enable-disable / remove (also revokes the credential issued to the peer) |
-| `mh config grant list\|revoke` | List/revoke inbound sync credentials this machine issued (`revoke --token` accepts an exact value or prefix) |
+| `mh status` | Where your data lives and how fresh each copy is: every device/bucket, its freshness, the one issue that matters most, and what to do about it. Purely local — it answers offline |
+| `mh config` | Interactive wizard over everything below (`server` / `device` / `backup` / `edge`). Daily *tools* stay top-level; anything that changes long-lived state lives under `config` |
+| `mh config server --port … --host … --sync-interval …` | Server settings persisted in `~/.metahub` (CLI flags still win at startup) |
+| `mh config device code\|add\|list\|revoke` | Pair devices with a one-time code, inspect the roster (how each joined, last activity, whether it can be cut off — `--refresh` adds bucket presence), or cut one off |
+| `mh config backup connect\|list\|rotate\|recovery\|anchors` | Attach a cloud bucket (S3/R2) for offline store-and-forward — direct keys, an `--enroll` code/QR, or `--provision-r2` to create the bucket first. `rotate` re-keys after losing a device; `recovery` prints a hand-copyable recovery card; `anchors` sets blob redundancy |
 | `mh --server [--port] [--host] [--debug] [--token] [--sync-interval] [--no-auto-sync] [--tls-cert --tls-key]` | Start the server: `/sync` (master token or pairing credential) + WebUI/PWA at `/` + `/api/*` REST + `/docs` (OpenAPI) + static sites `/sites/<name>/` + token exchange `/auth/token` + pairing `/api/pair`; a built-in timer auto-syncs paired peers; `--tls-*` serves https directly (PEM paths) |
 
 </details>

package/README.zh-CN.md

@@ -71,15 +71,19 @@ mh --server --port 7777
 mh sync http://a-host:7777
 ```
 
-配对一次后即可后台**周期性自动双向同步**，不必每次手敲 `mh sync`。同一条 `sync` 命令也能在「单个文档 / 数据表」与本地文件之间导入导出（文档 ↔ markdown、数据表 ↔ CSV）。原理详见[系统设计文档](./docs/system-design/)。
+配对一次（`mh config device code` / `mh config device add`）后即可后台**周期性自动双向同步**，不必每次手敲 `mh sync`。`mh status` 只凭本地状态就能回答「我的数据存在哪几处、每处有多新」，因此离线也答得出。同一条 `sync` 命令也能在「单个文档 / 数据表」与本地文件之间导入导出（文档 ↔ markdown、数据表 ↔ CSV）。原理详见[系统设计文档](./docs/system-design/)。
 
 ## WebUI、API 与 Agent 站点
 
-`mh --server` 在根路径 `/` 内置浏览器 **WebUI**（浏览 / 行内编辑数据表、块级所见即所得编辑文档、全文搜索、管理 agent 站点）。同一服务端还暴露：
+`mh --server` 在根路径 `/` 内置浏览器 **WebUI**（浏览 / 行内编辑数据表、**CodeMirror 6** 所见即所得 Markdown 编辑器——斜杠菜单、文档表格、媒体嵌入、`[[…]]` 文档内链、代码块一键格式化、源码/块模式切换、查找、TOC、全文搜索、管理 agent 站点）。同一服务端还暴露：
 
 - `/api/*` —— REST 接口，读写本库的数据表与文档。
 - `/docs` —— 自动生成的 OpenAPI 文档。
-- `/sites/<name>/` —— `mh site publish` 托管 agent 生成的 HTML/CSS/JS；页面同源调用 `/api/*` 即可读本库数据（一个本地 mini-Supabase）。
+- `/sites/<name>/` —— `mh site upload` 托管 agent 生成的 HTML/CSS/JS；页面同源调用 `/api/*` 即可读本库数据（一个本地 mini-Supabase）。
+- `/sites/<name>/api/*` —— **公开**站点的访客数据面：匿名访客只拿到你用 `mh site grant` 明确开出的「表 × 操作」权限（`read`/`create`/`update`，**没有 delete**），可再加密码或 Turnstile。
+- `/share/<slug>` —— `mh share` 把文档/数据库/站点发布成公开链接（view = 只读 SSR，edit = 接受 guest 写入；可加密码 + 过期），经 server、S3 桶，或你自己 Cloudflare 边缘上的常在线房间。
+
+**设备离线时也想让别人访问**是可选能力，且完全跑在**你自己的** Cloudflare 账号里：`mh edge deploy`（用 Cloudflare 登录，或粘贴 API token）部署一个 Worker、两个命名空间——**写信箱**收下访客的密文投稿，你的设备下次同步时再解密入库；**房间**（Durable Object）让分享出去的站点在你所有设备都休眠时依然实时可用。metahub 自己不运营任何后端：边缘上要么只有密文信封，要么只有你明确分享出去的那一小块分区。
 
 每个请求由单 token 守护（持久化在 `~/.metahub`）。服务端默认只绑 `127.0.0.1`；`--host 0.0.0.0` 才对外，此时凭据以明文 Bearer 传输，请置于可信网络或前置 TLS。细节见[系统设计文档](./docs/system-design/)。
 
@@ -90,7 +94,7 @@ mh sync http://a-host:7777
 
 | 命令 | 说明 |
 | --- | --- |
-| `mh init` | 创建 `~/.metahub` |
+| `mh init` | 创建 `~/.metahub`（`--claude` / `--codex` 改为把本指南装成 Claude Code `/mh` / Codex `$mh` skill） |
 | `mh db create\|list\|get\|delete` | 管理数据库（表） |
 | `mh use [<db>] [--clear]` | 设置/显示「当前库」（record/prop 默认作用于它） |
 | `mh get <ref>` | 通用查找：按 id/前缀/名字解析，自动判别类型 |
@@ -98,7 +102,7 @@ mh sync http://a-host:7777
 | `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 edit <id> --old --new` | 锚定查找替换（`--replace-all` / `--if-match`）；`--edits '<json 数组>'` 一次原子应用 N 对 |
 | `mh doc append\|prepend <id> --body` | 在文档首/尾追加块 |
 | `mh doc history <id>` / `mh doc revert <id> --to <version>` | 列出文档修订历史 / 恢复到某版本（回滚是一次新的正向修订；`doc get --at <version>` 预览；revert 可复活已删文档） |
 | `mh record history <id> [--field <名>]` / `mh record revert <id> --to <version>` | 记录修改历史（逐修订字段 diff，或单字段值变迁）/ 恢复历史值（可复活已删记录） |
@@ -109,14 +113,23 @@ mh sync http://a-host:7777
 | `mh doctor` | 只读体检：列出逻辑完整性问题（孤儿引用/单元格、重复路径、文档环、重名等）+ oplog/磁盘统计 |
 | `mh repair [--dry-run]` | 确定性、幂等修复可自动修的问题（改动随 oplog 复制）；`--dry-run` 仅预览（等价 doctor） |
 | `mh compact [--keep <天数>] [--dry-run]` | 清理保留窗口（默认 90 天）之外的 oplog 历史 + 回收无引用 blob + VACUUM。纯本地操作；当前数据不变，窗口外历史坍缩为基线（无法再回滚到更早版本） |
-| `mh site create\|put\|publish\|list\|files\|rm\|delete` | 托管 agent 生成的静态站点（HTML/CSS/JS），由 `--server` 在 `/sites/<name>/` serve 出去 |
+| `mh site create\|scaffold\|put\|upload\|list\|files\|rm\|delete` | 托管 agent 生成的静态站点（HTML/CSS/JS），由 `--server` 在 `/sites/<name>/` serve 出去。`scaffold` 写一份起步页；`upload <目录>` 镜像整个目录（首次加 `--create`，`--prune` 连带删除本地已不存在的文件） |
+| `mh site access <site> [public\|private]` | 查看 / 修改「谁可以访问这个站点」。public = 免 token；private 的响应与「不存在」完全一致。`--show-links` 才打印能力 URL（链接本身即密钥） |
+| `mh site grant <site> <db>:<ops>` / `mh site grants <site>` | 给公开站点的 `api/` 开匿名数据授权（`read,create,update`，无 delete），可用 `--password` / `--turnstile` 加门；`--revoke <db>` / `--clear` 收回 |
+| `mh share create\|list\|servers\|link\|renew\|revoke` | 把文档/数据库/站点发布成公开链接（`/share/<slug>`）：server SSR、S3 导出，或 `--room` 上你自己的边缘；view/edit 权限、可选密码 + 过期、可选 `--grant <db>:<ops>` 数据面 |
+| `mh edge deploy\|status\|pull\|rotate\|connect` | 你自己的 Cloudflare Worker + D1（+ Durable Object）：部署（用 Cloudflare 登录或 API token）、查健康、手动拉一轮写信箱、轮换收件密钥、把第二台设备接到既有 edge |
+| `mh blob add <file>` / `mh blob get <hash>` | 把本地文件存成内容寻址 `/blob/<hash>` URL（嵌入文档）/ 取回字节（本地 cache → peer → 桶） |
+| `mh cache [status\|clear\|gc\|full-device\|redundancy\|pin\|unpin]` | 查看/管理本地 blob 缓存；指定「全量设备」（durable 锚）使图片可安全清理 |
 | `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` | 立即同步：对每一台已配置的设备与每一个桶各跑一轮 |
+| `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 status` | 数据在哪几处、每处有多新、当前最要紧的问题是什么、该怎么办。纯本地派生，离线可答 |
+| `mh config` | 交互向导，覆盖下面全部（`server` / `device` / `backup` / `edge`）。日常**工具**留在顶层，凡改**长期状态**的都收在 `config` 下 |
+| `mh config server --port … --host … --sync-interval …` | 持久化服务器设置到 `~/.metahub`（启动时 CLI flag 仍优先） |
+| `mh config device code\|add\|list\|revoke` | 用一次性码配对设备、查看设备名册（怎么加入的、最后活跃、能否吊销；`--refresh` 追加桶在场性）、断开某台设备 |
+| `mh config backup connect\|list\|rotate\|recovery\|anchors` | 挂云端桶（S3/R2）做离线 store-and-forward——直填凭据、`--enroll` 码/二维码，或 `--provision-r2` 先替你建桶。`rotate` 丢设备后换钥换短语；`recovery` 打印可手抄的恢复码卡；`anchors` 设 blob 冗余判定 |
 | `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>

package/dist/cli/edge-worker-script.d.ts

@@ -0,0 +1,4 @@
+/** Called by compiled-entry.ts before the CLI runs. */
+export declare function setEdgeWorkerScript(script: string): void;
+export declare function getEdgeWorkerScript(): Promise<string>;
+//# sourceMappingURL=edge-worker-script.d.ts.map

package/dist/cli/edge-worker-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-worker-script.d.ts","sourceRoot":"","sources":["../../src/cli/edge-worker-script.ts"],"names":[],"mappings":"AAeA,uDAAuD;AACvD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAExD;AAED,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAmB3D"}