mellos-mapping 0.22.1 → 0.23.0

package/README.md

@@ -62,7 +62,7 @@ Clone the branch for your host, then run one command. No build is required.
 | `chatgpt-app` | ChatGPT desktop, Codex mode | `node install.mjs` |
 
 Requires Node.js 18+ and the corresponding host CLI on PATH. The installer checks
-release integrity and all six MCP tools, retains the runtime outside the clone,
+release integrity and all eight MCP tools, retains the runtime outside the clone,
 and configures the host. Start a new conversation after installation.
 See [release and branch instructions](docs/releasing.md).
 
@@ -158,7 +158,7 @@ directory they resolved at startup.
 
 This is Codex mode in the ChatGPT desktop app (also called Codex App).
 From the source branch run the following command; on `chatgpt-app`, omit the
-host argument. It configures the desktop skill, marketplace and six MCP tools.
+host argument. It configures the desktop skill, marketplace and eight MCP tools.
 
 ```
 node install.mjs chatgpt-app
@@ -239,7 +239,7 @@ servers), then the server process's own working directory. Set
 somewhere other than the project you are working in.
 
 The skill/discipline layer is Claude Code + Codex specific; other clients
-get the six `mmap_*` tools and the pane, and bring their own prompting.
+get the eight `mmap_*` tools and the pane, and bring their own prompting.
 
 ## Use
 
@@ -494,12 +494,19 @@ When a hidden sub-map changes in the background, the footer says so.
 
 ## MCP tools
 
+Start with `mmap_read` to resume an existing page; a new conversation is not a
+new effort. Use stable IDs, filtered reads and revision-checked writes. The
+[persistent-map API guide](docs/map-api.md) covers complete CRUD, atomic mixed
+batches, context checkpoints, source hashes and worktree boundaries.
+
 | Tool | Purpose |
 | --- | --- |
 | `mmap_declare` | Grow the map: title (`null` removes it), diagram kind, layer bands, lanes, groups (subsystems), nodes — with `status`, `evidence`, `detail`, `kind`, `group`, `lane`, `submap` — and edges, optionally labeled (all-or-nothing batch) |
 | `mmap_update` | Record progress **and revise**: status (`planned → in-progress → done` +evidence, `regressed`), relabel a node, move it to another band (`layer`), join/leave a group or lane, set a node kind or a `submap`; rename and re-rank bands (`layers`), relabel groups (`groups`) and lanes (`lanes`); `null` clears any clearable field |
 | `mmap_remove` | Revise: drop edges, nodes, groups, lanes, empty bands — and, with `pages`, whole pages, file and all (permanent; applied after this call's map edits) |
 | `mmap_view` | Render the current map as text inline (optional `zoom`, `-4`…`2`), ending with a `pages:` line naming every page the project has and which one you are looking at |
+| `mmap_read` | Structured page discovery, precise IDs, filtered/paginated reads, context and source changes |
+| `mmap_batch` | One-page mixed create/update/remove transaction with a revision check |
 | `mmap_setup` | Get/set the project's mapping policy — when maps open |
 | `mmap_open` | Put the map on your screen: open the pane, or retarget an open one to a `page` (`window: true` for the dedicated window). It answers with whether a pane actually reported in afterwards, not merely that a command ran — and it can never close one |
 
@@ -624,7 +631,7 @@ The repo is itself layered bottom-up, and each layer has its spec:
 | 1 store | `src/store/store.ts` | `store.test.ts`, `atomic-save.test.ts` | atomic state-file persistence on Node |
 | 1 semantics | `src/semantics/` | `semantics.test.ts` | medium-neutral view semantics: zoom ladder, group aggregation, page-set rules, sequence flip, the shared glyph vocabulary |
 | 2 apply | `src/server/apply.ts` | `apply.test.ts` | tool inputs → transactional op sequences |
-| 3 server | `src/server/server.ts` | `server.test.ts`, `save-failure.test.ts` | the six MCP tools over stdio |
+| 3 server | `src/server/server.ts` | `server.test.ts`, `save-failure.test.ts` | the eight MCP tools over stdio |
 | 4 render | `src/render/` | `render.test.ts`, `routing.test.ts` | the ASCII renderer and its wire routing |
 | 4 pane | `src/watch/` | `watch.test.ts`, `pane-state.test.ts`, `input.test.ts` | the polling pane: page set, input parsing, panel and chrome |
 | — launchers | `scripts/` | `open-pane.test.mjs`, `codex-register.test.mjs` | plain-node entry points |

package/README.zh-CN.md

@@ -55,7 +55,7 @@ Claude 为你构建系统时，对话旁边的分屏实时显示这个系统的*
 | `chatgpt-app` | ChatGPT 桌面 App 的 Codex 模式 | `node install.mjs` |
 
 前置要求为 Node.js 18+ 和对应宿主的 CLI，并确保命令在 PATH 中。安装器检查
-发行文件和六个 MCP 工具，将运行时保留到克隆目录之外，完成宿主配置。
+发行文件和八个 MCP 工具，将运行时保留到克隆目录之外，完成宿主配置。
 安装后开启新对话。详见[发布与分支说明](docs/releasing.md)。
 
 Claude Code 也可以通过插件市场安装：
@@ -141,7 +141,7 @@ the move.`）：
 
 本版用于 ChatGPT 桌面 App 的 Codex 模式（也称 Codex App）。在源码分支运行
 以下命令；在 `chatgpt-app` 分支运行时省略宿主参数。它会一次配置桌面专用技能、
-插件市场与六个 MCP 工具。
+插件市场与八个 MCP 工具。
 
 ```
 node install.mjs chatgpt-app
@@ -223,7 +223,7 @@ npx -y -p mellos-mapping mellos-mapping-watch
 插件 MCP 服务器设置的约定），最后才是服务器进程自己的工作目录。如果你的
 客户端会在你实际工作的项目之外启动服务器，就设 `MELLOS_MAPPING_CWD`。
 
-技能/纪律层是 Claude Code 与 Codex 专属的；其他客户端获得六个 `mmap_*`
+技能/纪律层是 Claude Code 与 Codex 专属的；其他客户端获得八个 `mmap_*`
 工具和面板，提示词自备。
 
 ## 使用
@@ -448,12 +448,18 @@ Claude 会话的正确姿势。
 
 ## MCP 工具
 
+先用 `mmap_read` 查找并恢复已有页面；新对话不等于新任务。通过稳定 ID、过滤查询
+和版本检查做增量修改。[持久化地图接口说明](docs/map-api.md)包含完整增删改查、
+混合事务、恢复摘要、源码哈希和 worktree 边界。
+
 | 工具 | 用途 |
 | --- | --- |
 | `mmap_declare` | 生长地图：标题（传 `null` 删掉）、图种、层级横条、泳道、分组（子系统）、节点（可带 `status`、`evidence`、`detail`、`kind`、`group`、`lane`、`submap`）、边（可带标签）；批量，全有或全无 |
 | `mmap_update` | 记录进度**并修订**：状态（`planned → in-progress → done` 附证据、`regressed`）、改节点标签、把节点搬到另一层（`layer`）、加入/退出分组或泳道、设节点 kind 或 `submap`；给层改名和改 rank（`layers`）、给分组改标签（`groups`）、给泳道改标签（`lanes`）；任何可清空的字段传 `null` 即清空 |
 | `mmap_remove` | 修订：删除边、节点、分组、泳道、空层——以及用 `pages` 删掉整页，连文件一起（永久；在本次调用的地图修改之后执行） |
 | `mmap_view` | 把当前地图渲染成文本，直接在对话里看（可选 `zoom`，`-4`…`2`）；每次响应结尾都有一行 `pages:`，列出本项目有哪些页、以及你正在看哪一页 |
+| `mmap_read` | 结构化页面发现、稳定 ID、过滤分页查询、恢复摘要与源码变化检查 |
+| `mmap_batch` | 单页增删改混合事务与版本冲突检查 |
 | `mmap_setup` | 查/设本项目的建图策略——什么时候开地图 |
 | `mmap_open` | 把地图放到你屏幕上：开面板，或把已开的面板切到某一 `page`（`window: true` 用独立窗口）。它回答的是"事后有没有面板真的报到"，而不只是"命令跑过了"——而且它永远关不掉面板 |
 
@@ -561,7 +567,7 @@ npm run verify
 | 1 store | `src/store/store.ts` | `store.test.ts`、`atomic-save.test.ts` | Node 上的原子化状态文件持久化 |
 | 1 semantics | `src/semantics/` | `semantics.test.ts` | 媒介无关的视图语义：缩放阶梯、分组聚合、页集规则、时序翻转、共享字形词汇表 |
 | 2 apply | `src/server/apply.ts` | `apply.test.ts` | 工具输入 → 事务性操作序列 |
-| 3 server | `src/server/server.ts` | `server.test.ts`、`save-failure.test.ts` | stdio 上的六个 MCP 工具 |
+| 3 server | `src/server/server.ts` | `server.test.ts`、`save-failure.test.ts` | stdio 上的八个 MCP 工具 |
 | 4 render | `src/render/` | `render.test.ts`、`routing.test.ts` | ASCII 渲染器与它的走线 |
 | 4 pane | `src/watch/` | `watch.test.ts`、`pane-state.test.ts`、`input.test.ts` | 轮询面板：页集、输入解析、详情面板与外框 |
 | — 启动脚本 | `scripts/` | `open-pane.test.mjs`、`codex-register.test.mjs` | 纯 node 的入口 |

package/dist/hook-session-start.mjs

@@ -113,7 +113,8 @@ function sessionStartContext(input) {
     `mellos-mapping policy: ${policy} \u2014 ${describeMappingPolicy(policy)}.`,
     scope,
     "  1. Load the mellos-mapping skill and follow it.",
-    "  2. Declare the whole ghost design with mmap_declare BEFORE writing code.",
+    "  2. Read existing pages and context with mmap_read; a new conversation is not a new effort.",
+    "     Reuse the matching page and verified nodes. Use mmap_declare only for missing structure.",
     "  3. Open the map pane WITHOUT asking \u2014 the recorded policy is the user's standing consent:",
     '       mmap_open {page: "<the page this effort lives on>"}',
     "     It opens the pane beside this conversation, or retargets one that is already open.",
@@ -121,6 +122,7 @@ function sessionStartContext(input) {
     "     looking. `pane: CLOSED` means the user cannot see this map \u2014 call mmap_open then too.",
     "  5. Keep the map current as the work proceeds: in-progress when a node is started,",
     "     done WITH EVIDENCE when its verification passes, regressed when something breaks.",
+    "     Save a concise context.next checkpoint and use expectedRevision for incremental writes.",
     "An explicit request from the user always outranks this."
   ].join("\n");
 }

package/dist/mmap.mjs

@@ -418,7 +418,7 @@ async function main() {
     console.error(parsed.error);
     process.exit(1);
   }
-  const candidates = storeSearchPath(process.cwd());
+  const candidates = [store.resolveProjectDirectory(process.cwd())];
   const marker = storeMarkerOf(store.STATE_FILE_RELATIVE_PATH);
   const project = nearestProject(candidates, candidates.map((dir) => existsSync2(join2(dir, marker))));
   const cfg = { ...parsed.value, projectDir: project.root };

package/dist/preview.mjs

@@ -222,12 +222,37 @@ function updateNode(map, input) {
   return ok({ ...map, nodes: map.nodes.map((n) => n.id === input.id ? updated : n) });
 }
 
+// src/domain/context.ts
+function sourceError(raw) {
+  if (!Array.isArray(raw) || raw.length > 100) return "sources must be an array of at most 100 file references";
+  for (const item of raw) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return "source must be an object";
+    const s = item;
+    if (Object.keys(s).some((k) => k !== "path" && k !== "sha256")) return "unknown source field";
+    if (typeof s.path !== "string" || s.path.length > 1024 || !s.path || /[\u0000-\u001f\u007f-\u009f\\:]/.test(s.path) || s.path.startsWith("/") || s.path.split("/").some((p) => !p || p === "." || p === "..")) return "source path must be relative to the project, with forward slashes and no traversal";
+    if (s.sha256 !== void 0 && (typeof s.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(s.sha256))) return "source sha256 must be a lowercase SHA256 hash";
+  }
+  return void 0;
+}
+function contextError(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return "context must be an object";
+  for (const [key, value] of Object.entries(raw)) {
+    if (key !== "summary" && key !== "next") return "unknown context field";
+    if (typeof value !== "string" || value.length > 2e3 || /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/.test(value)) return "context fields must be text of at most 2000 characters";
+  }
+  return void 0;
+}
+
 // src/domain/text.ts
 var NO_CONTROLS = /^[^\u0000-\u001f\u007f-\u009f]*$/;
 var NO_CONTROLS_TEXT = "one line of text; control characters (ESC, newline, tab) are not allowed";
 var NO_CONTROLS_BUT_BREAKS = /^[^\u0000-\u0008\u000b-\u001f\u007f-\u009f]*$/;
 var NO_CONTROLS_BUT_BREAKS_TEXT = "text with optional newlines (\\n) and tabs; other control characters (ESC, BEL, CR) are not allowed";
 function mapTextError(map) {
+  if (map.context !== void 0) {
+    const error2 = contextError(map.context);
+    if (error2) return error2;
+  }
   const check = (field, value, multiline = false) => value === void 0 || (multiline ? NO_CONTROLS_BUT_BREAKS : NO_CONTROLS).test(value) ? void 0 : `${field}: ${multiline ? NO_CONTROLS_BUT_BREAKS_TEXT : NO_CONTROLS_TEXT}`;
   let error = check("title", map.title);
   if (error) return error;
@@ -242,6 +267,10 @@ function mapTextError(map) {
     }
   }
   for (const [i, node] of map.nodes.entries()) {
+    if (node.sources !== void 0) {
+      const error2 = sourceError(node.sources);
+      if (error2) return `nodes[${i}]: ${error2}`;
+    }
     for (const name of ["label", "evidence", "detail"]) {
       error = check(`nodes[${i}].${name}`, node[name], name !== "label");
       if (error) return error;
@@ -307,8 +336,8 @@ function optionalString(rec, key, where, path) {
 }
 function parseMap(raw, path) {
   if (!isRecord(raw)) return err({ kind: "bad-shape", path, detail: "root is not an object" });
-  if (raw["version"] !== STATE_FILE_VERSION) {
-    return err({ kind: "bad-shape", path, detail: `version is ${String(raw["version"])}, expected ${STATE_FILE_VERSION}` });
+  if (raw["version"] !== STATE_FILE_VERSION && raw["version"] !== 2) {
+    return err({ kind: "bad-shape", path, detail: `version is ${String(raw["version"])}, expected ${STATE_FILE_VERSION} or 2` });
   }
   const layers = arrayField(raw, "layers", path, "required");
   if (!layers.ok) return layers;
@@ -321,6 +350,11 @@ function parseMap(raw, path) {
   const groups = arrayField(raw, "groups", path, "optional");
   if (!groups.ok) return groups;
   let map = EMPTY_MAP;
+  if (raw["context"] !== void 0) {
+    const error = contextError(raw["context"]);
+    if (error) return err({ kind: "bad-shape", path, detail: error });
+    map = { ...map, context: raw["context"] };
+  }
   const title = optionalString(raw, "title", "map", path);
   if (!title.ok) return title;
   if (title.value !== void 0) map = setTitle(map, title.value);
@@ -449,6 +483,11 @@ function parseMap(raw, path) {
       if (!updated.ok) return err({ kind: "invariant-violation", path, violation: updated.error });
       map = updated.value;
     }
+    if (rawNode["sources"] !== void 0) {
+      const error = sourceError(rawNode["sources"]);
+      if (error) return err({ kind: "bad-shape", path, detail: `${where}: ${error}` });
+      map = { ...map, nodes: map.nodes.map((n) => n.id === id.value ? { ...n, sources: rawNode["sources"] } : n) };
+    }
   }
   for (const [i, rawEdge] of edges.value.entries()) {
     const where = `edges[${i}]`;