mellos-mapping 0.20.2 → 0.22.1

package/README.zh-CN.md

@@ -1,16 +1,20 @@
 # Mellos Mapping · 梅勒斯地图
 
-[![CI](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml/badge.svg)](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/mellos-mapping?logo=npm&logoColor=white&label=npm&color=cb3837)](https://www.npmjs.com/package/mellos-mapping)
+[![downloads](https://img.shields.io/npm/dm/mellos-mapping?label=downloads&color=cb3837)](https://www.npmjs.com/package/mellos-mapping)
+[![MCP registry](https://img.shields.io/badge/MCP_registry-listed-2f6feb)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.GuangminJu/mellos-mapping)
+[![CI](https://img.shields.io/github/actions/workflow/status/GuangminJu/mellos-mapping/ci.yml?branch=main&label=CI)](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-444)](LICENSE)
 
 [English](README.md) | 简体中文
 
-给 [Claude Code](https://claude.com/claude-code) 与 Codex CLI 的自下而上
+给 [Claude Code](https://claude.com/claude-code) 、ChatGPT 桌面 Codex 模式与 Codex CLI 的自下而上
 开发实况地图，原生运行在终端里。
 
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: light)" srcset="docs/demo-light.svg">
-    <img alt="一张梅勒斯地图的自我构建：幽灵设计先行，spinner 逐层攀升，地基开裂向上传染，诚实修复" src="docs/demo.svg" width="620">
+    <img alt="一次 declare 铺开整张幽灵设计，节点自下而上逐个点亮 —— 地基开裂向上传染，绿色再被挣回来" src="docs/demo.svg" width="620">
   </picture>
 </p>
 
@@ -18,41 +22,11 @@ Claude 为你构建系统时，对话旁边的分屏实时显示这个系统的*
 最底层是原语，依赖边只允许向下指；虚线幽灵节点是已设计未实现的部分，
 转圈的是此刻正在构建的模块，实心绿色代表已构建**且已验证**。
 
-```
-  梅勒斯地图 · mellos-mapping 插件
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 编排层
-
-  ╭╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮
-  ╎ · MCP Server ╎
-  ╰╌╌╌┬┬╌╌╌╌┬╌╌╌╌╯
-      ││    │
-      └┼────┼───────────┐
-       │    └───┐       │
-       │        │       │
-━━━━━━━┿━━━━━━━━┿━━━━━━━┿━━━ 契约层
-       │        │       │
-  ┏━━━━┷━━━━━━━┓│ ╭╌╌╌╌╌┴╌╌╌╌╌╮
-  ┃ ■ 状态存储 ┃│ ╎ · Watcher ╎
-  ┗━━━━━┯━━━━━━┛│ ╰╌╌╌╌╌╌┬╌╌╌╌╯
-        │       │        │
-        │ ┌─────┘        │
-        │ │              │
-━━━━━━━━┿━┿━━━━━━━━━━━━━━┿━━ 原语层
-        │ │              │
-  ┏━━━━━┷━┷━━━━━━┓  ╭────┴────────╮
-  ┃ ■ 图领域模型 ┃  │ ⠋ ASCII渲染 │
-  ┗━━━━━━━━━━━━━━┛  ╰─────────────╯
-
-  · planned   ⠋ in-progress   ■ done   ✗ regressed
-```
-
-在真实终端里，连线和层级横条以暗色渲染，节点盒子按状态发光、标签加粗——
-像一块黑色电路板，元件是亮的。跨层的边会从中间层的盒子缝隙里穿过去
-（看上图 状态存储 和 Watcher 之间下潜的那根线）；互不重叠的走线段共享
-轨道行，让层与层贴得更近。
+<p align="center">
+  <img alt="Claude Code 会话旁边的梅勒斯地图面板：六层游戏引擎设计，L0 与 L1 节点实心绿色，上面几层仍是虚线幽灵节点" src="docs/session-claude-code.png">
+</p>
 
-*（这就是本插件自己的地图，开发中途的样子。转圈的 spinner 是真的在转。）*
+*真实会话：左边 Claude Code，右边地图面板。L0 已验证，L1 刚点亮，上面还是幽灵节点。*
 
 ## 为什么
 
@@ -72,6 +46,20 @@ Claude 为你构建系统时，对话旁边的分屏实时显示这个系统的*
 
 ## 安装
 
+克隆适合自己宿主的分支，运行一个安装命令即可；无需构建。
+
+| 分支 | 使用对象 | 在克隆目录运行 |
+| --- | --- | --- |
+| `main` | 共用源码／任一宿主 | `node install.mjs chatgpt-app` 或 `node install.mjs claude` |
+| `claude` | Claude Code | `node install.mjs` |
+| `chatgpt-app` | ChatGPT 桌面 App 的 Codex 模式 | `node install.mjs` |
+
+前置要求为 Node.js 18+ 和对应宿主的 CLI，并确保命令在 PATH 中。安装器检查
+发行文件和六个 MCP 工具，将运行时保留到克隆目录之外，完成宿主配置。
+安装后开启新对话。详见[发布与分支说明](docs/releasing.md)。
+
+Claude Code 也可以通过插件市场安装：
+
 在 Claude Code 对话里输入两行：
 
 ```
@@ -125,7 +113,7 @@ claude plugin marketplace update mellos-mapping && claude plugin update mellos-m
 ```
 
 要两步是因为 `plugin update` 只对比本地缓存的 marketplace 克隆——真正
-拉取本仓库的是第一条命令。重启 Claude Code 生效。发布即 `master` 分支
+拉取本仓库的是第一条命令。重启 Claude Code 生效。发布即 `main` 分支
 上的版本号提升。（在对话里输入 `/plugin` 也能打开同一个管理界面。）
 
 ### 从 0.19 升级
@@ -149,34 +137,71 @@ the move.`）：
 这一次搬迁是两个进程唯一会碰 `.claude/` 的时刻。此后工具只往 `.mellos/`
 里写，也绝不会写到启动时解析出的项目目录之外。
 
-## Codex CLI
+## ChatGPT App · Codex 模式
 
-同一个仓库也是 Codex 插件（codex-cli 0.147+）。三行装完：
+本版用于 ChatGPT 桌面 App 的 Codex 模式（也称 Codex App）。在源码分支运行
+以下命令；在 `chatgpt-app` 分支运行时省略宿主参数。它会一次配置桌面专用技能、
+插件市场与六个 MCP 工具。
 
 ```
-codex plugin marketplace add GuangminJu/mellos-mapping
-codex plugin add mellos-mapping@mellos-mapping
-node ~/.codex/plugins/cache/mellos-mapping/mellos-mapping/<版本>/scripts/codex-register.mjs
+node install.mjs chatgpt-app
 ```
 
-前两行把技能（地图纪律）装成 Codex 插件。第三行在用户级注册 MCP
-服务器——必须这么做，因为 Codex 把插件自带的 MCP 服务器拉起在插件缓存里，
-且不给它任何感知工作区的途径，捆绑的服务器会把地图写进缓存。脚本写入的
-用户级 `codex mcp add` 条目会继承每个会话的工作目录：状态文件落在你的
-项目里，与 Claude Code 下行为一致。注册的是版本相关的绝对路径——插件
-更新后重跑一次脚本即可。
+安装完成后开启新对话。技能默认使用 **web-terminal 网页终端**：
+`mmap_open {surface: "web-terminal", page: "<slug>"}` 启动本地服务后，
+AI 自动把 URL 打开到当前对话右侧浏览器，直接显示 mmap 终端地图。
+不需要粘贴命令或 Computer Use；网页有独立字号调节。
+图形 SVG 网页、原生终端和 Markdown 仍然保留。旧 MCP 对话可使用
+`node "<插件根>/dist/web.mjs" "<项目>" --terminal --page <slug>`。
+面板排队打开不等于地图已经可见。
+详见[桌面安装与限制](docs/codex.md)。
 
-要在 Codex 会话旁边看实况面板，Windows 上运行
+在 Windows Terminal 使用 Codex CLI 时（不指桌面 App 内置终端），运行
 `node <插件根>/scripts/open-pane.mjs <项目目录>`——它会在承载本会话的
-终端窗口里分屏（识别不到就确定性地开到专属的 "mellos-mapping" 窗口；
-`--window` 则是主动选择专属窗口）。加 `--page <slug>` 指定打开哪一页；
-面板已经开着时，带 `--page` 重跑一次不会再开新面板，而是让现有面板
-切到那一页。面板默认**自动跟随**正在被写入的页——AI 此刻操作哪张图，
+终端窗口右侧分屏，并保留左侧对话的键盘焦点。识别或聚焦失败时会明确报错，
+不会改开其他窗口；`--window` 用于明确选择独立窗口。加 `--page <slug>` 指定打开哪一页；
+当前会话的面板已经开着时，带 `--page` 重跑会让它切到那一页。其他会话
+或独立窗口中的面板不算当前会话已分屏。面板默认**自动跟随**正在被写入的页——AI 此刻操作哪张图，
 就看哪张图；按 `f` 开关（手动切页也会关掉），或用 `--no-follow` 启动。
 其他环境在项目目录下的第二个终端（或任意分屏）运行
 `node <插件根>/dist/watch.mjs`。两者接受同一套参数，见
 [面板参数](#面板参数)。
 
+### 桌面对话右侧：Markdown 地图
+
+用户选择文档方式时，技能会使用 `mmap_open` 的
+`surface: "markdown"`，生成地图文档后交给宿主在当前对话右侧打开。
+文档包含彩色 SVG 分层依赖图、模块状态、设计说明、验证记录和子图链接。
+不需要网页服务或 Mermaid 支持，图像放大仍保持清晰。
+
+首次打开后，本项目中成功的地图工具写入会自动重新生成预览。JSON 仍是
+唯一数据源，`.mellos/previews/` 是可重新生成的输出。图片里的节点没有
+拖拽、悬停、双击下潜和动画；用文档链接打开子图。侧栏是否自动刷新由
+桌面应用决定，生成成功不代表已显示。手动刷新或旧会话可以运行：
+
+```sh
+node "<插件根>/dist/preview.mjs" "<项目目录>" --page <页名>
+```
+
+完整说明见 [Codex 桌面地图](docs/codex.md#desktop-right-side-map)。
+
+### 可选：交互网页版
+
+现有 Markdown/SVG 用法继续保留。需要缩放拖动、悬停/固定节点详情、依赖
+高亮、搜索、状态筛选、分组概览、页面和子地图切换时，使用新增的
+`mmap_open {surface: "web", page: "<页名>"}`，将返回的网址交给宿主在右侧
+浏览器打开。网页直接读取项目地图并自动更新，也支持明暗主题和确认后删页。
+
+```sh
+node "<插件根>/dist/web.mjs" "<项目目录>" --page <页名>
+# 关闭该项目的网页服务：
+node "<插件根>/dist/web.mjs" "<项目目录>" --stop
+```
+
+服务仅在本机运行，不需要部署或下载网页依赖。Markdown 和网页共用原来的
+JSON 数据，能够同时使用；手动切页会固定当前页面。详见
+[网页版功能与运行方式](docs/codex.md#optional-interactive-web-viewer)。
+
 ## 任意 MCP 客户端
 
 服务器已发布到 npm，任何 MCP 客户端（Cursor、Windsurf、Zed、Gemini
@@ -198,7 +223,7 @@ npx -y -p mellos-mapping mellos-mapping-watch
 插件 MCP 服务器设置的约定），最后才是服务器进程自己的工作目录。如果你的
 客户端会在你实际工作的项目之外启动服务器，就设 `MELLOS_MAPPING_CWD`。
 
-技能/纪律层是 Claude Code 与 Codex 专属的；其他客户端获得五个 `mmap_*`
+技能/纪律层是 Claude Code 与 Codex 专属的；其他客户端获得六个 `mmap_*`
 工具和面板，提示词自备。
 
 ## 使用
@@ -216,6 +241,23 @@ npx -y -p mellos-mapping mellos-mapping-watch
 3. 看着节点从底部一路亮起。图让你不安的时候就打断它——这正是它存在的
    意义。
 
+在 Linux 和 macOS 上，`mmap_open` 与 `mmap` 会自动使用 tmux。启动器优先
+定位继承的 `TMUX`/`TMUX_PANE`；工具进程丢失这些变量时，会自动发现默认
+tmux 服务中唯一已连接的会话。默认在右侧分屏并保留输入焦点；`--window`
+创建一个新的 tmux 窗口。再次打开会复用属于该源面板或会话窗口的 watcher。
+
+如果有多个已连接的会话，或使用自定义 tmux socket，在 MCP 服务进程的
+环境中设置以下变量（修改后重启该进程）：
+
+| 环境变量 | 含义 |
+| --- | --- |
+| `MELLOS_MAPPING_TMUX_TARGET` | 指定 tmux 会话或面板，例如 `work:2.1` 或 `%7` |
+| `MELLOS_MAPPING_TMUX_SOCKET` | socket 的绝对路径，例如 `/tmp/my-tmux/socket` |
+
+目标不明确、会话未连接或没有安装 tmux 时，启动器会返回具体原因，以及
+包含项目、页面和正确引号的一条完整 watcher 命令，可以粘贴到可见终端。
+地图仍可正常写入；打开失败后，助手只在环境变化或你要求重试时再次打开。
+
 分屏支持鼠标（xterm SGR any-event 协议——htop 和 tmux 说的同一种话）：
 
 | 输入 | 动作 |
@@ -301,14 +343,19 @@ used by ← …`，每个邻居各带自己的状态字形），以及自动折
 watcher 的：`--file <path>` 指定默认页的状态文件（启动脚本会从项目目录
 自己推导出来）。
 
+内部 watcher 参数 `--owner <token>` 和面板报告的可选 `owner` 字段承载会话绑定。
+启动器用源控制台进程及创建时间生成身份；手动运行 watcher 可省略。切页和关闭
+请求按面板 PID 定向投递，同项目其他窗口不会抢走请求。普通 `mmap` 只切换当前
+会话的面板；`mmap --window` 切换本项目的独立窗口。
+
 ### mmap 命令
 
-在任何终端里敲 `mmap`，它是一个**开关**：本项目还没有面板就开一个，已经
-有面板就把它关掉。
+在终端里敲 `mmap`，它是当前会话地图的**开关**：本会话还没有面板就开一个，
+已经有面板就把它关掉。
 
 | 你敲的 | 发生什么 |
 | --- | --- |
-| `mmap` | 本项目没有面板在跑 → 开一个；有 → 关掉它 |
+| `mmap` | 当前会话没有面板在跑 → 开一个；有 → 关掉它 |
 | `mmap <页 slug>` | 打开时定位到这一页，或者让已开的面板切过去——永远不关 |
 | `mmap --window` | 开到专属的 "mellos-mapping" 窗口，而不是把当前窗口分屏 |
 | `mmap --force` | 即使已经有面板在跑也再开一个 |
@@ -420,7 +467,9 @@ Claude 会话的正确姿势。
   丢掉的字段；任何嵌套深度都一样；
 - 文本字段里的**控制字符**——藏在标签里的 ESC 序列，会让这张图重绘每一个
   打开它的人的终端。`detail` 是例外：换行和制表符本来就是写笔记的方式，
-  其余（ESC、BEL、单独的 CR）照样拒绝；
+  其余（ESC、BEL、单独的 CR）照样拒绝。文件加载和公共库保存也校验控制字符，
+  同时兼容旧文件中的多行证据。直接通过公共库构造地图时，终端渲染仍会消除
+  控制字符的执行效果；
 - 可选字段上的**空字符串**——清空字段用 `null`，而不是一个渲染出来跟真盒子
   分不清的空白；
 - **`submap` 指向本次调用所针对的那一页的节点**——那是个没有底的环，不是
@@ -445,7 +494,7 @@ Claude 会话的正确姿势。
 | 这一行 | 意思 |
 | --- | --- |
 | `pane: CLOSED` | 没人在看这张图；助手会用 `mmap_open` 自己开，而不是回过头来要求你开 |
-| `pane: open on this page` | 你正看着它落地 |
+| `pane: running on this page` | 活跃进程报告正在显示这一页，但终端可能被隐藏 |
 | `pane: open on <其他页>, auto-follow on` | 面板跟随最后被写入的那一页，它自己会过来 |
 | `pane: open on <其他页>, auto-follow OFF` | 那一页是你亲手钉住的：这次改动是真的，但**不在**你屏幕上。助手被要求把这件事说出来，而不是把你的视图搬走 |
 
@@ -454,6 +503,10 @@ Claude 会话的正确姿势。
 超过五秒没被刷新的报告不再算数，超过一分钟就被读到它的人删掉，所以被强杀
 的面板不会一直冒领观众。
 
+心跳不等于屏幕可见。显式调用 tmux 打开操作时，启动器还会切回已有地图所在的
+窗口，解除遮挡地图的面板缩放，并检查已连接会话的活动窗口后再报告可见。
+缺少 `TMUX` 环境变量、焦点又落在地图面板上时，会沿用原来的归属，避免重复打开。
+
 ### Setup：选择什么时候建图
 
 建图要多积极，是一个人的工作习惯，不是某个仓库的属性——所以它**只为你选
@@ -488,16 +541,16 @@ AI。从此再也不需要按项目设置什么。
 
 ## 开发
 
+先阅读[贡献说明](CONTRIBUTING.md)和[项目结构、分支与恢复指南](docs/project-maintenance.md)。
+
 ```
-npm install
+npm ci
 npm run verify
 ```
 
-`verify` 是按顺序的五步：`typecheck`（本仓库自己的源码）、
-`typecheck:packages`（dsh 插件包里不依赖框架的模块，且把 `mellos-mapping/*`
-指向本仓库源码）、`test`、`build`（打包 `dist/`、产出带声明的 `lib/`，两个
-目录都先清空），以及 `check:package`——它按真实的 `prepack` 生命周期打出
-tarball，只要 `exports` 或 `bin` 里有任何目标没被打进去就失败。
+开发环境使用 Node.js 22.12+。`verify` 依次运行 `typecheck`、`test`、`build`
+（打包 `dist/`、产出带声明的 `lib/`）、`check:package`、`check:codex` 和
+`check:release`，检查 npm 入口、Codex 包和两个可安装发行包，包括 MCP 握手。
 
 这个仓库本身就是自下而上分层的，每一层都有自己的规格测试：
 
@@ -508,30 +561,16 @@ tarball，只要 `exports` 或 `bin` 里有任何目标没被打进去就失败
 | 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.json`、`packages/` | `tests/lockfile.test.ts`、`tests/packages.test.ts`、`browser-safe.test.ts` | 发出去的是什么、发给谁 |
+| — 打包 | `package.json` | `tests/lockfile.test.ts`、`browser-safe.test.ts` | 发出去的是什么、发给谁 |
 
 `dist/` 是刻意提交的：插件安装就是克隆本仓库、不运行任何东西，所以入口
 文件以打包形式随仓库分发。CI 会把提交的 `dist/` 和一次全新构建做 diff，
 所以改了源码却忘了重新构建会直接失败。
 
-### dsh 插件包
-
-`packages/dsh` 与 `packages/dsh-client` 是 DeepSeek Harness 的那一面：一个
-读取并监视工作区 `.mellos/` 存储的宿主插件，加上用同一套语义作画的浏览器
-地图面板。它们在 dsh workspace 检出里*开发*（由那边的工具链构建），从这里
-*发布*——源码、规格测试和 `lib/` 都提交在这儿，用
-`node scripts/sync-dsh-plugin.mjs <deepseek-harness 检出路径>` 刷新，该脚本
-会把 dsh 内部包名改写成发布用的名字。本仓库构建不了它们，所以只证明它能
-证明的：`typecheck:packages` 和不依赖框架的规格测试在 CI 里跑，
-`tests/packages.test.ts` 守住 src↔lib 的结构、共享版本线和 MCP 行的拉起
-方式。需要 `@deepseek-ai` 框架或 DOM 的规格测试连同理由一起写在
-`vitest.config.ts` 里。详见
-[`packages/dsh/README.md`](packages/dsh/README.md)。
-
 ### 库
 
 底部各层同时是一个库（`npm run build` 产出带类型声明的 `lib/`，npm 打包
@@ -549,8 +588,7 @@ tarball，只要 `exports` 或 `bin` 里有任何目标没被打进去就失败
 
 **浏览器安全**的意思是 import 闭包里没有任何 Node 内建模块，由测试门禁
 守护——图形客户端（web 面板、编辑器视图）可以直接解析状态文件，并复用与
-终端面板完全一致的聚合、缩放与字形语义。`packages/dsh-client` 就是这样一个
-客户端。
+终端面板完全一致的聚合、缩放与字形语义。
 
 ## 许可证
 

package/dist/hook-session-start.mjs

@@ -3,15 +3,11 @@ import { createRequire } from 'node:module'; const require = createRequire(impor
 
 // src/hook/session-start.ts
 import { spawnSync } from "node:child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { existsSync, readFileSync as readFileSync2, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname as dirname2, join as join2 } from "node:path";
+import { dirname as dirname4, join as join4 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-// src/store/store.ts
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
-
 // src/domain/types.ts
 var ok = (value) => ({ ok: true, value });
 var err = (error) => ({ ok: false, error });
@@ -19,23 +15,30 @@ var RANK_MIN = 0;
 var RANK_MAX = 99;
 var RANK_RULE_TEXT = `an integer in ${RANK_MIN}..${RANK_MAX}, 0 = bottom / most primitive`;
 
-// src/store/store.ts
+// src/store/pages.ts
+import { basename, dirname, join } from "node:path";
+var STORE_DIR_NAME = ".mellos";
+var STATE_FILE_RELATIVE_PATH = join(STORE_DIR_NAME, "map.json");
+var PAGES_DIR_NAME = "pages";
+
+// src/store/json-text.ts
 function isRecord(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 function stripBom(text) {
   return text.charCodeAt(0) === 65279 ? text.slice(1) : text;
 }
-var STORE_DIR_NAME = ".mellos";
-var STATE_FILE_RELATIVE_PATH = join(STORE_DIR_NAME, "map.json");
-var PAGES_DIR_NAME = "pages";
+
+// src/store/policy.ts
+import { readFileSync } from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
 var CONFIG_FILE_NAME = "config.json";
 var CONFIG_FILE_VERSION = 1;
 function configFilePath(defaultFile) {
-  return join(dirname(defaultFile), CONFIG_FILE_NAME);
+  return join2(dirname2(defaultFile), CONFIG_FILE_NAME);
 }
 function userConfigFilePath(userBase) {
-  return join(userBase, STORE_DIR_NAME, CONFIG_FILE_NAME);
+  return join2(userBase, STORE_DIR_NAME, CONFIG_FILE_NAME);
 }
 var MAPPING_POLICIES = ["always", "complex", "on-request"];
 function makeMappingPolicy(raw) {
@@ -84,7 +87,10 @@ function effectiveMappingPolicy(projectConfigFile, userConfigFile) {
   const source = project.value !== void 0 ? "project" : user.value !== void 0 ? "user" : void 0;
   return ok({ project: project.value, user: user.value, effective, source });
 }
-var LEGACY_STATE_FILE_RELATIVE_PATH = join(".claude", "mellos-mapping.json");
+
+// src/store/migration.ts
+import { dirname as dirname3, join as join3 } from "node:path";
+var LEGACY_STATE_FILE_RELATIVE_PATH = join3(".claude", "mellos-mapping.json");
 
 // src/hook/session-start.ts
 function sessionStartContext(input) {
@@ -119,10 +125,10 @@ function sessionStartContext(input) {
   ].join("\n");
 }
 function hasMap(stateFile) {
-  return existsSync2(stateFile) || existsSync2(join2(dirname2(stateFile), PAGES_DIR_NAME));
+  return existsSync(stateFile) || existsSync(join4(dirname4(stateFile), PAGES_DIR_NAME));
 }
 function mmapShimFilePath(localAppData) {
-  return join2(localAppData, "mellos-mapping", "bin", "mmap.cmd");
+  return join4(localAppData, "mellos-mapping", "bin", "mmap.cmd");
 }
 function mmapShimCurrent(shimContent, mmapPath) {
   return shimContent !== void 0 && shimContent.includes(`"${mmapPath}"`);
@@ -155,7 +161,7 @@ function ensureMmapCommand(pluginRoot) {
   if (process.platform !== "win32") return void 0;
   const localAppData = process.env["LOCALAPPDATA"];
   if (localAppData === void 0 || localAppData === "") return void 0;
-  const mmapPath = join2(pluginRoot, "dist", "mmap.mjs");
+  const mmapPath = join4(pluginRoot, "dist", "mmap.mjs");
   let shim;
   try {
     shim = readFileSync2(mmapShimFilePath(localAppData), "utf8");
@@ -165,7 +171,7 @@ function ensureMmapCommand(pluginRoot) {
   if (mmapShimCurrent(shim, mmapPath)) return void 0;
   const run = spawnSync(
     process.execPath,
-    [join2(pluginRoot, "scripts", "install-mmap-command.mjs"), "--json"],
+    [join4(pluginRoot, "scripts", "install-mmap-command.mjs"), "--json"],
     { encoding: "utf8", windowsHide: true, timeout: 15e3 }
   );
   if (run.status !== 0 || typeof run.stdout !== "string") return void 0;
@@ -199,10 +205,10 @@ async function readAll(stream) {
 async function main() {
   const raw = process.stdin.isTTY === true ? "" : await readAll(process.stdin);
   const projectDir = parseHookInput(raw).cwd ?? process.cwd();
-  const stateFile = join2(projectDir, STATE_FILE_RELATIVE_PATH);
+  const stateFile = join4(projectDir, STATE_FILE_RELATIVE_PATH);
   const scopes = effectiveMappingPolicy(configFilePath(stateFile), userConfigFilePath(homedir()));
   if (!scopes.ok) return;
-  const pluginRoot = dirname2(dirname2(fileURLToPath(import.meta.url)));
+  const pluginRoot = dirname4(dirname4(fileURLToPath(import.meta.url)));
   const context = sessionStartContext({
     policy: scopes.value.effective,
     hasStore: hasMap(stateFile)