mellos-mapping 0.24.0 → 0.26.0

package/README.md

@@ -61,7 +61,11 @@ Clone the branch for your host, then run one command. No build is required.
 | `claude` | Claude Code | `node install.mjs` |
 | `chatgpt-app` | ChatGPT desktop, Codex mode | `node install.mjs` |
 
-Requires Node.js 18+ and the corresponding host CLI on PATH. The installer checks
+Requires Node.js 18.17+ on the 18.x line, or 20.3+, and the corresponding host CLI
+on PATH. Supported platforms are Windows 10+, macOS 13.0+ and Linux with glibc
+2.28+, each on x64 or arm64. The OS must also meet the selected Node.js version's
+requirements. Native lock bindings ship with the release; no local compilation
+is needed. The installer checks
 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).
@@ -81,13 +85,41 @@ Or one line in a terminal:
 claude plugin marketplace add GuangminJu/mellos-mapping && claude plugin install mellos-mapping@mellos-mapping
 ```
 
-Requires Node.js 18+ on PATH (install Node separately when using native Claude Code). No build step: `dist/` is committed, so a clone runs as-is —
+Requires the same [Node.js and platform versions](#install) on PATH (install
+Node separately when using native Claude Code). No build step: `dist/` is
+committed, so a clone runs as-is —
 `dist/server.mjs` (the MCP server), `dist/watch.mjs` (the pane),
 `dist/mmap.mjs` (the `mmap` toggle), `dist/hook-session-start.mjs` (the
 `SessionStart` hook that `hooks/hooks.json` registers) and
 `dist/store-paths.mjs` (the store's path vocabulary, which the plain-node pane
 launcher imports instead of restating filenames).
 
+**omp (Oh My Pi)** reads the same plugin layout the Claude Code edition ships —
+the same marketplace catalog, `.mcp.json`, skill and slash command — so one
+release serves both hosts:
+
+```
+omp plugin marketplace add GuangminJu/mellos-mapping
+omp plugin install mellos-mapping@mellos-mapping
+```
+
+That install follows `main`, where a release is a version bump. To freeze a
+version instead, add a checkout of one — the Claude Code edition ZIP from the
+GitHub Release, or a clone at the release tag:
+
+```
+omp plugin marketplace add "<checkout or extracted release directory>"
+omp plugin install mellos-mapping@mellos-mapping
+```
+
+omp never reads `hooks/hooks.json`, so the session paragraph arrives through the
+plugin's omp host adapter (`dist/omp-extension.mjs`, declared in
+`package.json#omp.extensions`): the same store, the same policy text, and the
+same `mmap` shim install as the Claude hook. The pane is the same terminal
+split beside the session. Install it *as a plugin*: neither `omp plugin link`
+nor the npm package is a plugin, and both would leave the tools behind. See
+[omp installation and limitations](docs/distributions/omp.md).
+
 The first session after installing asks you **one** question — how eager
 mapping should be — and records the answer for every project you will ever
 open. From then on the hook carries it into each new session by itself; there
@@ -104,8 +136,14 @@ Terminal inherits the old environment, so close the terminal app entirely and
 reopen it before the first `mmap`. The PATH edit keeps the
 installer's guarantees: nothing happens when the entry is already there, and
 a PATH that `setx` would damage (flattened `%VARIABLE%` references, truncation
-past its limit) is refused outright, with the entry to add by hand named
-instead.
+past its limit) is refused outright.
+
+A refused PATH is not a dead end: the same two shims are then written into
+`%LOCALAPPDATA%\Microsoft\WindowsApps` (or `~/.local/bin`) — a directory your
+PATH already names — so `mmap` is runnable in a new terminal with no PATH
+change at all. Machines with a long PATH are exactly where that happens, and
+where it matters most. The command takes the page to open as an argument
+(`mmap omp-host-support`), and closes the pane when it is already open.
 
 The step behind it is still a command of its own, for the cases the hook does
 not cover — `--uninstall`, or re-adding a PATH entry you removed while the
@@ -130,6 +168,26 @@ marketplace clone — the first command is what actually pulls this repo.
 Restart Claude Code to apply. Releases are version bumps on `main`.
 (In-app, `/plugin` opens the same management UI.)
 
+omp updates with its own two steps:
+
+```
+omp plugin marketplace update mellos-mapping && omp plugin upgrade mellos-mapping@mellos-mapping
+```
+
+Close the pane first (`q` in it): the watcher runs from the plugin copy, and on
+Windows an open file cannot be renamed away, so an upgrade attempted while a
+pane is open can fail with `EPERM` and leave the plugin cache empty — repaired
+by `omp plugin install mellos-mapping@mellos-mapping --force`. Then: the first
+command refreshes the catalog, the second reinstalls from it. omp also
+refreshes a catalog entry it has not updated for a day at startup, unless
+`marketplace.autoUpdate` is `off` — in the default `notify` mode that check
+writes its finding to the debug log only, so `marketplace update` is the step
+that makes an update visible. `upgrade` does not compare versions: it
+force-reinstalls whatever the catalog names, which is why a release is
+identified by its version bump rather than gated by it. Restart omp afterwards,
+and reopen a pane still showing the old bundle (`q` in it, then `mmap_open`
+again).
+
 ### Upgrading from 0.19
 
 0.20 moved the store out of `.claude/` — the map belongs to this tool, not to
@@ -446,19 +504,31 @@ State lives in the tool-owned `.mellos/` directory at the project root:
 | `.mellos/quit` | one-shot "close yourself" request from the `mmap` toggle, consumed and deleted the same way |
 | `.mellos/viewers/<pid>.json` | one report per live pane — the page it is showing, whether auto-follow is on — refreshed every second while it runs (see [Who is watching](#who-is-watching)) |
 | `<any of the above>.<pid>.<random>.tmp` | a save in flight; it is renamed over its target or removed. A leftover means a write failed (and was reported) and even its cleanup could not run |
+| `.mellos/.write-lock` | permanent regular file for the OS project lock; keep it untracked and never remove, rename or replace it during normal operation |
 
 The map files are plain JSON, safe to commit if you want the maps' history in
-git. The other three are runtime chatter between a pane and whoever is talking
-to it — gitignore `focus`, `quit` and `viewers/` if you commit the store.
+git. Keep `focus`, `quit`, `viewers/` and `.write-lock` out of Git. The first
+three carry runtime messages; the lock file must remain in place, including
+when no process holds its lock.
 
 **Concurrency, stated plainly.** Every save is atomic — written to a private
 sibling temp file and renamed over the target — so a reader polling the store
-sees the previous complete map or the new one, never a torn write. There is
-no lost-update protection: two writers saving the *same* page race, and the
-last rename wins, silently discarding what the other computed from an older
-read. Pages are the isolation unit — two sessions that must not clobber each
-other belong on two pages, which is also the answer to running several Claude
-sessions in one project.
+sees the previous complete map or the new one, never a torn write. Every graph
+writer (MCP, the HTTP viewer, the watcher) uses the same non-blocking OS
+exclusive lock for the project. The lock has its own fixed file, separate from
+the map files being replaced; it stays in place after the OS releases the lock
+on completion or process exit. Contention returns a retryable `BUSY`.
+
+The lock serializes each operation's read, change and save. To protect an edit
+computed from an earlier read, pass `expectedRevision`: it is compared inside
+the lock, and a stale revision returns `CONFLICT`. Without it, a later write
+can still overwrite the same field or a whole value such as `context`. Pages
+separate unrelated efforts; sharing a page still requires revision-checked
+edits. Low-level `saveMapFile`, hand edits and older running processes do not
+participate in this contract. Stop all old MCP, viewer and watcher processes
+for the project before upgrading; an old lock directory needs a one-time
+migration. See the [persistent-map API guide](docs/map-api.md) and
+[project locking](docs/locking.md) for the boundary and upgrade steps.
 
 ### Diagram kinds
 

package/README.zh-CN.md

@@ -54,7 +54,10 @@ Claude 为你构建系统时，对话旁边的分屏实时显示这个系统的*
 | `claude` | Claude Code | `node install.mjs` |
 | `chatgpt-app` | ChatGPT 桌面 App 的 Codex 模式 | `node install.mjs` |
 
-前置要求为 Node.js 18+ 和对应宿主的 CLI，并确保命令在 PATH 中。安装器检查
+前置要求为 Node.js 18.17 及以上的 18.x，或 20.3 及以上版本，以及对应宿主的 CLI，
+并确保命令在 PATH 中。支持 Windows 10+、macOS 13.0+ 和 glibc 2.28+ 的 Linux，均支持
+x64 与 arm64；系统还须满足所选 Node.js 版本的更高要求。发行包自带原生锁绑定，
+无需用户本地编译。安装器检查
 发行文件和八个 MCP 工具，将运行时保留到克隆目录之外，完成宿主配置。
 安装后开启新对话。详见[发布与分支说明](docs/releasing.md)。
 
@@ -73,13 +76,38 @@ Claude Code 也可以通过插件市场安装：
 claude plugin marketplace add GuangminJu/mellos-mapping && claude plugin install mellos-mapping@mellos-mapping
 ```
 
-需要 PATH 上有 Node.js 18+（Claude Code 本身就依赖 Node，所以你已经有了）。
+需要 PATH 上有符合[安装要求](#安装)的 Node.js；使用原生 Claude Code 安装包时也需
+单独安装 Node.js。
 没有构建步骤：`dist/` 是提交进仓库的，克隆即用——`dist/server.mjs`（MCP
 服务器）、`dist/watch.mjs`（面板）、`dist/mmap.mjs`（`mmap` 开关）、
 `dist/hook-session-start.mjs`（由 `hooks/hooks.json` 注册的 `SessionStart`
 钩子），以及 `dist/store-paths.mjs`（存储的路径词汇；纯 node 的面板启动
 脚本从这里导入，而不是自己抄一份文件名）。
 
+**omp（Oh My Pi）** 读的是 Claude Code 版本用的同一套插件布局——同一份市场
+目录、`.mcp.json`、技能与斜杠命令——一份发行包同时服务两个宿主：
+
+```
+omp plugin marketplace add GuangminJu/mellos-mapping
+omp plugin install mellos-mapping@mellos-mapping
+```
+
+这样装跟的是 `main`，而发布就是它上面的版本号提升。要冻结版本，就改把某个
+版本的检出目录加为市场——GitHub Release 里的 Claude Code 版本 ZIP，或按
+tag 检出的克隆：
+
+```
+omp plugin marketplace add "<检出或解压出来的发行目录>"
+omp plugin install mellos-mapping@mellos-mapping
+```
+
+omp 不读 `hooks/hooks.json`，所以那段会话说明由插件的 omp 宿主适配器送达
+（`dist/omp-extension.mjs`，在 `package.json#omp.extensions` 里声明）：同一个
+存储、同一段策略文字，Windows 上的 `mmap` shim 也由它安装。面板仍旧是会话
+旁边的终端分屏。请把它**当插件**安装——`omp plugin link` 与 npm 包都不是插
+件，用它们装会只剩适配器、没有工具。见
+[omp 安装与限制](docs/distributions/omp.md)。
+
 装完之后的第一个会话只会问你**一个**问题——建图要多积极——并把答案记成
 你以后打开的每一个项目的默认。此后钩子会自己把它带进每个新会话；再也没有
 "每个项目设置一遍"这回事。见
@@ -93,7 +121,13 @@ PowerShell）和 `mmap`（git-bash）写进 `%LOCALAPPDATA%\mellos-mapping\bin`
 所以第一次敲 `mmap` 之前要把终端应用整个关掉重开。PATH 的编辑保持安装器
 原有的承诺：条目已经在里面
 就什么都不做；遇到 `setx` 会损坏的 PATH（`%VARIABLE%` 被展平、超长被截
-断），它干脆拒绝，改为把要手动添加的条目说清楚。
+断），它干脆拒绝。
+
+PATH 被拒绝不等于没命令可用：同样两个 shim 会再写一份到
+`%LOCALAPPDATA%\Microsoft\WindowsApps`（或 `~/.local/bin`）——一个你的 PATH
+本来就有名字的目录——于是**新终端里直接敲 `mmap` 就能用，完全不用改 PATH**。
+PATH 很长的机器正是这种情况，也最需要它。命令可以带要打开的页名
+（`mmap omp-host-support`）；面板已经开着时再敲一次就是关掉它。
 
 它背后的那一步仍然是个独立命令，留给钩子管不到的情形——`--uninstall`，
 或者 shim 还在、PATH 条目却被你删掉之后重新加回去：
@@ -116,6 +150,22 @@ claude plugin marketplace update mellos-mapping && claude plugin update mellos-m
 拉取本仓库的是第一条命令。重启 Claude Code 生效。发布即 `main` 分支
 上的版本号提升。（在对话里输入 `/plugin` 也能打开同一个管理界面。）
 
+omp 也有自己的两步：
+
+```
+omp plugin marketplace update mellos-mapping && omp plugin upgrade mellos-mapping@mellos-mapping
+```
+
+**先关面板**（面板里按 `q`）：watcher 跑的就是插件副本里的文件，而 Windows 不
+允许改名一个正被打开的文件——开着面板升级会以 `EPERM` 失败并把插件缓存清空
+（旧副本已删、新副本未就位），用 `omp plugin install mellos-mapping@mellos-mapping
+--force` 修回来。然后：第一条刷新市场目录，第二条按目录重装。omp 还会在启动时尽力刷新超过一天没更新过
+的目录条目——除非 `marketplace.autoUpdate` 设为 `off`；默认的 `notify` 模式只把
+"有可用更新"写进 debug 日志，所以让更新**看得见**的是 `marketplace update` 这一
+步。`upgrade` 不比较版本：它按目录里现在指的内容强制重装，同版本号也会重下——
+因此版本号提升是给发行**贴标签**，而不是送达的门槛。之后重启 omp，并把仍显示旧
+运行文件的面板关掉重开（面板里按 `q`，再 `mmap_open`）。
+
 ### 从 0.19 升级
 
 0.20 把地图存储从 `.claude/` 挪到了 `.mellos/`——地图属于这个工具，不属于
@@ -405,17 +455,26 @@ watcher 的：`--file <path>` 指定默认页的状态文件（启动脚本会
 | `.mellos/quit` | `mmap` 开关发出的一次性"自己关掉"请求，以同样的方式被消费和删除 |
 | `.mellos/viewers/<pid>.json` | 每个活着的面板一份报告——它正显示哪一页、自动跟随是否打开——运行期间每秒刷新一次（见[谁在看](#谁在看)） |
 | `<上面任一文件>.<pid>.<随机>.tmp` | 正在落盘的一次写入；它要么被改名覆盖目标，要么被删掉。留下来说明那次写入失败（并已被报告），连清理都没能跑成 |
+| `.mellos/.write-lock` | 操作系统项目锁使用的永久普通文件；不纳入 Git，正常运行时不得删除、改名或替换 |
 
-地图文件是纯 JSON，想在 git 里留下地图的历史就把它们提交进去。另外三个是
-面板和跟它说话的人之间的运行期闲聊——如果你要提交这个仓库，把 `focus`、
-`quit` 和 `viewers/` 加进 gitignore。
+地图文件是纯 JSON，想在 git 里留下地图的历史就把它们提交进去。`focus`、`quit`、
+`viewers/` 和 `.write-lock` 应加入 gitignore。前三者传递运行期消息；锁文件即使
+没有进程持锁也应保留，不要当作临时文件清理。
 
 **并发模型，直说。** 每次保存都是原子的——先写进一个私有的同级临时文件，
 再改名覆盖目标——所以轮询存储的读者要么看到上一张完整的地图，要么看到新的
-那张，绝不会读到写了一半的。但**没有丢失更新保护**：两个写者保存*同一页*
-就是在赛跑，最后那次改名赢，另一个基于旧读取算出来的东西被静默丢弃。页就是
-隔离单位——不许互相覆盖的两个会话，就该在两页上，这也是同一项目里跑多个
-Claude 会话的正确姿势。
+那张，绝不会读到写了一半的。所有写图入口（MCP、HTTP 查看器、watcher）都使用
+同一把项目级、非阻塞的操作系统排他锁。锁使用独立的固定文件，与被原子替换的
+地图文件分开；操作结束或进程退出后，操作系统释放锁，锁文件仍保留。锁被占用时
+返回可重试的 `BUSY`。
+
+这把锁串行执行每次操作的读取、修改和保存。基于先前读取计算的改动还应传入
+`expectedRevision`：它在锁内比较，版本过旧返回 `CONFLICT`。省略它时，后续写入
+仍可能覆盖同一字段或 `context` 这样的完整值。不同页面用于分开互不相关的工作；
+共用一页时仍需带版本检查。底层 `saveMapFile`、手工编辑和仍在运行的旧进程不参与
+这份约定。升级前须停掉该项目所有旧 MCP、查看器和 watcher 进程；残留的旧锁目录
+需一次性迁移。完整边界和升级步骤见[持久化地图 API 指南](docs/map-api.md)与
+[项目锁说明](docs/locking.md)。
 
 ### 图种
 

package/dist/hook-session-start.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
+import { createRequire as __mellosCreateRequire } from 'node:module'; const require = __mellosCreateRequire(import.meta.url);
 
 // src/hook/session-start.ts
 import { spawnSync } from "node:child_process";
@@ -129,11 +129,47 @@ function sessionStartContext(input) {
 function hasMap(stateFile) {
   return existsSync(stateFile) || existsSync(join4(dirname4(stateFile), PAGES_DIR_NAME));
 }
+function mmapBinDir(localAppData) {
+  return join4(localAppData, "mellos-mapping", "bin");
+}
 function mmapShimFilePath(localAppData) {
-  return join4(localAppData, "mellos-mapping", "bin", "mmap.cmd");
+  return join4(mmapBinDir(localAppData), "mmap.cmd");
+}
+function mmapFallbackDirs(localAppData, home) {
+  return [join4(localAppData, "Microsoft", "WindowsApps"), join4(home, ".local", "bin")];
+}
+function pathNames(rawPath, dir) {
+  const norm = (s) => s.trim().replace(/^"|"$/g, "").replace(/[\\/]+$/, "").toLowerCase();
+  return rawPath.split(";").some((entry) => entry.trim() !== "" && norm(entry) === norm(dir));
+}
+function readIfPresent(path) {
+  try {
+    return readFileSync2(path, "utf8");
+  } catch {
+    return void 0;
+  }
 }
 function mmapShimCurrent(shimContent, mmapPath) {
-  return shimContent !== void 0 && shimContent.includes(`"${mmapPath}"`);
+  if (shimContent === void 0) return false;
+  return shimContent.includes(`"${mmapPath}"`) || shimContent.includes(`"${mmapPath.replaceAll("\\", "/")}"`);
+}
+function shimIsOurs(content) {
+  if (content.includes("mellos-mapping mmap shim")) return true;
+  const quoted = /"([^"]*mmap\.mjs)"/.exec(content)?.[1];
+  return quoted !== void 0 && /mellos-mapping/i.test(quoted);
+}
+function mmapCommandResolves(localAppData, mmapPath, environment, read, exists) {
+  if (pathNames(environment.path, mmapBinDir(localAppData))) return true;
+  if (environment.home === void 0 || environment.home === "") return false;
+  for (const dir of mmapFallbackDirs(localAppData, environment.home)) {
+    if (!exists(dir) || !pathNames(environment.path, dir)) continue;
+    const files = ["mmap.cmd", "mmap"].map((name) => read(join4(dir, name))).filter((content) => content !== void 0);
+    if (files.length === 0) continue;
+    const ours = files.filter((content) => shimIsOurs(content));
+    if (ours.length === 0) return true;
+    return ours.every((content) => mmapShimCurrent(content, mmapPath));
+  }
+  return false;
 }
 function installContextLine(outcome) {
   if (typeof outcome !== "object" || outcome === null) return void 0;
@@ -150,11 +186,22 @@ function installContextLine(outcome) {
   }
   if (o.path === "refused" || o.path === "error") {
     const reason = typeof o.reason === "string" ? o.reason : "the PATH edit failed";
+    const aliasDir = typeof o.alias === "object" && o.alias !== null && "dir" in o.alias && typeof o.alias.dir === "string" ? o.alias.dir : void 0;
+    if (aliasDir !== void 0) {
+      return [
+        `mellos-mapping: the \`mmap\` terminal command should work: its shims live in`,
+        `${o.binDir}, and \u2014 because the user PATH could not be changed (${reason}) \u2014 a second copy`,
+        `was written to ${aliasDir}, a directory PATH already names (so \`mmap\` resolves there unless`,
+        "something earlier in PATH claims the name first).",
+        "The user can therefore type `mmap` in a new terminal right now; the command opens the map",
+        "pane for the project it is typed in, or closes the open one."
+      ].join("\n");
+    }
     return [
       `mellos-mapping: the \`mmap\` command's launcher was written to ${o.binDir},`,
       `but the user PATH was NOT changed: ${reason}.`,
       "If the user wants the `mmap` pane-toggle command, tell them to add that directory to",
-      'their user PATH (Settings > "Edit environment variables for your account").'
+      'their user PATH (Settings > "Edit environment variables for their account").'
     ].join("\n");
   }
   return void 0;
@@ -164,15 +211,18 @@ function ensureMmapCommand(pluginRoot) {
   const localAppData = process.env["LOCALAPPDATA"];
   if (localAppData === void 0 || localAppData === "") return void 0;
   const mmapPath = join4(pluginRoot, "dist", "mmap.mjs");
-  let shim;
-  try {
-    shim = readFileSync2(mmapShimFilePath(localAppData), "utf8");
-  } catch {
-    shim = void 0;
-  }
-  if (mmapShimCurrent(shim, mmapPath)) return void 0;
+  const shim = readIfPresent(mmapShimFilePath(localAppData));
+  const resolves = mmapShimCurrent(shim, mmapPath) && mmapCommandResolves(
+    localAppData,
+    mmapPath,
+    { path: process.env["PATH"] ?? "", home: process.env["USERPROFILE"] ?? process.env["HOME"] },
+    readIfPresent,
+    existsSync
+  );
+  if (resolves) return void 0;
+  const runtime = "bun" in process.versions ? "node" : process.execPath;
   const run = spawnSync(
-    process.execPath,
+    runtime,
     [join4(pluginRoot, "scripts", "install-mmap-command.mjs"), "--json"],
     { encoding: "utf8", windowsHide: true, timeout: 15e3 }
   );
@@ -236,12 +286,18 @@ if (launchedAsEntry(process.argv[1], import.meta.url)) {
   main().catch(() => process.exit(0));
 }
 export {
+  ensureMmapCommand,
   hasMap,
   hookOutput,
   installContextLine,
   launchedAsEntry,
+  mmapBinDir,
+  mmapCommandResolves,
+  mmapFallbackDirs,
   mmapShimCurrent,
   mmapShimFilePath,
   parseHookInput,
-  sessionStartContext
+  pathNames,
+  sessionStartContext,
+  shimIsOurs
 };