mellos-mapping 0.26.1 → 0.27.0

package/README.md

@@ -5,6 +5,7 @@
 [![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)
+[![LINUX DO](https://img.shields.io/badge/LINUX%20DO-community-ffb400?logo=discourse&logoColor=white)](https://linux.do)
 
 English | [简体中文](README.zh-CN.md)
 
@@ -120,6 +121,22 @@ 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).
 
+**pi** reads none of that layout: it loads an extension and has no MCP of its
+own, by design. So the plugin speaks MCP to itself — the extension declared in
+`package.json#pi.extensions` (`dist/pi-extension.mjs`) starts the same
+`dist/server.mjs` in the session's directory, which makes the eight `mmap_*`
+tools the same eight, under the same names, and builds the session paragraph
+from the same store and the same policy text the Claude hook prints:
+
+```
+pi install npm:mellos-mapping
+```
+
+Add `-l` to install it for the current project instead of every one, then start
+a new session: pi discovers packages at session start. The package's `skills/`
+and `commands/` travel with it — the same map discipline, and `/mmap` for the
+same slash command. See [pi installation and behaviour](docs/distributions/pi.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
@@ -188,6 +205,18 @@ 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).
 
+pi updates the package it installed, with no marketplace in between:
+
+```
+pi update npm:mellos-mapping
+```
+
+That is the npm source; a git source is reconciled to the ref your settings name
+by pi's own update, and a versioned spec (`npm:mellos-mapping@0.27.0`) is pinned
+and skipped. Restart the session afterwards: a session owns the map server
+process it started, so one still running keeps the copy it began with until it
+ends.
+
 ### Upgrading from 0.19
 
 0.20 moved the store out of `.claude/` — the map belongs to this tool, not to
@@ -751,6 +780,11 @@ are stored in `~/.mellos/support/star-reminder.json`; nothing is uploaded and
 GitHub is contacted only when the user follows the link. Unreadable settings
 or a busy store silently skip the reminder.
 
+## Community
+
+This project takes part in and endorses the
+[LINUX DO](https://linux.do) community.
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -5,6 +5,7 @@
 [![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)
+[![LINUX DO](https://img.shields.io/badge/LINUX%20DO-community-ffb400?logo=discourse&logoColor=white)](https://linux.do)
 
 [English](README.md) | 简体中文
 
@@ -108,6 +109,21 @@ omp 不读 `hooks/hooks.json`，所以那段会话说明由插件的 omp 宿主
 件，用它们装会只剩适配器、没有工具。见
 [omp 安装与限制](docs/distributions/omp.md)。
 
+**pi** 则完全不读那套目录：它加载的是扩展，而且出于设计考虑自己没有 MCP。
+所以这个插件自己跟自己讲 MCP——在 `package.json#pi.extensions` 里声明的扩
+展（`dist/pi-extension.mjs`）会在会话所在目录启动同一个 `dist/server.mjs`，
+八个 `mmap_*` 工具因此就是同样的八个、同名可用，会话说明也来自同一个存储、
+同一段策略文字，与 Claude 钩子打印的一样：
+
+```
+pi install npm:mellos-mapping
+```
+
+加 `-l` 只装到当前项目而不是所有项目，之后开一个新会话：pi 在会话开始时才
+发现包。包里的 `skills/` 与 `commands/` 随之一并生效——同一套建图纪律，
+`/mmap` 也还是同一个斜杠命令。见
+[pi 安装与行为](docs/distributions/pi.md)。
+
 装完之后的第一个会话只会问你**一个**问题——建图要多积极——并把答案记成
 你以后打开的每一个项目的默认。此后钩子会自己把它带进每个新会话；再也没有
 "每个项目设置一遍"这回事。见
@@ -166,6 +182,16 @@ omp plugin marketplace update mellos-mapping && omp plugin upgrade mellos-mappin
 因此版本号提升是给发行**贴标签**，而不是送达的门槛。之后重启 omp，并把仍显示旧
 运行文件的面板关掉重开（面板里按 `q`，再 `mmap_open`）。
 
+pi 更新的则是它装下的那个包，中间没有市场目录：
+
+```
+pi update npm:mellos-mapping
+```
+
+这是 npm 来源；git 来源由 pi 自己的更新流程校准到你 settings 里写的 ref，带版本的
+写法（`npm:mellos-mapping@0.27.0`）会被跳过。之后重启会话：每个会话各自拥有它启动
+的地图服务器进程，仍在运行的会话会一直用开始时的那份副本，直到会话结束。
+
 ### 从 0.19 升级
 
 0.20 把地图存储从 `.claude/` 挪到了 `.mellos/`——地图属于这个工具，不属于
@@ -671,6 +697,10 @@ Star 按钮会调用系统默认浏览器打开 GitHub，方便沿用已有登
 UTC 日期、最多 3 天的计数和已提醒标记，不上传数据，不查询是否点过 Star；
 只有用户主动点击链接时才访问 GitHub。设置损坏、不可写或锁忙时静默跳过。
 
+## 社区
+
+本项目积极参与并认可 [LINUX DO 社区](https://linux.do)。
+
 ## 许可证
 
 MIT

package/commands/mmap.md

@@ -0,0 +1,124 @@
+---
+description: Open the live Mellos map in a terminal split pane beside this session
+argument-hint: "[setup] [--page <slug>] [--window] [--ascii]"
+allowed-tools: Bash(wt *), Bash(node *), Bash(tmux *)
+---
+
+If `$ARGUMENTS` contains `setup`, do NOT open the pane. Run the setup
+questionnaire instead: call `mmap_setup` (no arguments) to read the current
+policy — the reply names the USER-level choice, this project's override if it
+has one, and which of them is in effect. Then ask the user which mode they
+want — `always` (map every structured task: workflows, designs, architecture,
+technical dependencies), `complex` (only medium or complex tasks),
+`on-request` (only when explicitly asked) — using AskUserQuestion where
+available, mentioning whatever is already set.
+
+Persist with `mmap_setup {policy, scope}`. `scope` defaults to `user`, which
+is almost always right: the question is about how this person works, so it is
+answered once and applies to every project they open. Use
+`scope: "project"` only when they say they want THIS project to differ from
+that — ask which they mean if `$ARGUMENTS` does not make it obvious. Confirm
+what was saved, at which scope, and where. Then stop.
+
+Otherwise: open the live Mellos map watcher for this project in a separate terminal pane.
+
+The `mmap_open` tool does exactly this and is the shorter route — pass the page
+this conversation is working on (`mmap_open {page: "<slug>"}`, or `window: true`
+for the dedicated window). It resolves the runtime's own absolute paths and
+reports back whether a pane actually came up, which is also why it is the one
+route that needs no placeholder expanded: this command's text is plain text, and
+`${CLAUDE_PLUGIN_ROOT}` inside it is substituted by Claude Code, NOT by omp
+(omp expands that placeholder inside a plugin's MCP config, not in command
+bodies) nor by a bare MCP client.
+Use the platform routes below when the mmap tools are not available in this
+session, or when the tool reports it could not open one. (You do not need this
+command to keep the map visible day to day: every write answers with a `pane:`
+line, and a `pane: CLOSED` is the assistant's cue to call `mmap_open` itself.)
+The watcher is at `${CLAUDE_PLUGIN_ROOT}/dist/watch.mjs`. The store is
+MULTI-PAGE: the default page lives at `.mellos/map.json` and named
+pages at `.mellos/pages/<slug>.json` — the watcher takes the
+default path as its base, polls ALL of these files, and redraws on change.
+The default file is optional; a project whose work lives on named pages has
+no `.mellos/map.json` at all. So never probe that single file to
+decide whether a map exists — call `mmap_view`, which reads the real store
+and ends every response with a `pages:` line naming the pages that exist
+(marking the default page absent when it is) and the one it just rendered.
+
+Follow the platform-appropriate route:
+
+1. **Windows with Windows Terminal** (`wt` available — the usual case, in
+   Claude Code and in omp alike; omp's plugin also ships this same launcher): run
+
+   ```
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/open-pane.mjs" "<PROJECT_DIR>" --page <PAGE_SLUG>
+   ```
+
+   replacing `<PROJECT_DIR>` with the absolute project directory and
+   `<PAGE_SLUG>` with the page THIS conversation's effort lives on — the same
+   slug you pass to the mmap tools. Care about what the pane actually shows:
+   without `--page` it opens on the most recently written page, which after a
+   gap or in a multi-effort project may not be the one under discussion. Omit
+   `--page` only when no particular page is the subject (the user just wants
+   the map open), or for the default page. The
+   launcher identifies the Windows Terminal window hosting THIS session
+   (console-title nonce probe), brings it to the foreground, and splits it
+   vertically, then returns keyboard focus to the conversation. If the session
+   window cannot be identified or focused, report that failure and ask the user
+   to activate this conversation's PowerShell tab before retrying. Do not open
+   a separate window unless the user explicitly asks for one.
+
+   Flags: `--page <slug>` names the page to show first. Once open, the pane
+   AUTO-FOLLOWS the page being written (the map the agent is operating on),
+   so it tracks the work by itself; the user can toggle that with the `f`
+   key, and `--no-follow` starts it off. When a watcher bound to this console is
+   ALREADY running, the launcher does not open another pane — it retargets
+   the existing one (output says `refocused=<slug>`, picked up within a
+   poll tick); rerun with `--page` when the user asks to see a specific
+   page. `--window` skips the split
+   and opens the map in the dedicated window on purpose — use it when the
+   user prefers the map separate from the chat (second monitor, small
+   screens). `--ascii` for fonts without box-drawing characters. `--force`
+   opens another pane even though a watcher for this project is already
+   running (default is to skip). The remaining watcher flags are forwarded
+   verbatim: `--no-color`, `--no-mouse`, `--interval <ms>` (default 250,
+   floored at 50). An unknown flag is a usage error, never dropped in
+   silence — relay the message rather than retrying blind.
+
+   A page the user is done with they can close from the pane itself: `x`, or
+   the `×` on the active tab, asks, and a second press within the window
+   deletes that page's file. `mmap_remove {pages: [...]}` does the same from
+   a tool call — with the user behind it, never on your own initiative.
+
+   The user also has the pane on a toggle of their own: `mmap` typed in the
+   current console opens its pane, and `mmap` again closes that pane. So a pane
+   that disappears mid-session is a decision, not a crash — say so rather
+   than reopening it uninvited.
+
+2. **Linux/macOS with tmux**: use the same `mmap_open` tool or launcher command
+   as route 1. It targets the inherited session/pane, or discovers the single
+   attached session even when the tool shell has no `TMUX`. It creates a right
+   split without moving input focus; `--window` requests a new tmux window.
+   Repeated opens reuse and retarget this session's watcher. If several sessions
+   are attached, set `MELLOS_MAPPING_TMUX_TARGET` in the MCP server environment
+   to a session or pane (for example `work:2.1`). For a custom server socket,
+   also set `MELLOS_MAPPING_TMUX_SOCKET` to its absolute path, then restart the
+   MCP server. Do not guess a session or open a detached window.
+
+3. **Neither**: print the watcher command and tell the user to run it in any
+   second terminal themselves (add `--ascii` if their font lacks box-drawing
+   characters). The launcher's own failure message quotes it in full, with
+   absolute paths — relay that one verbatim. Written by hand it is
+   `node "<plugin root>/dist/watch.mjs" --file "<PROJECT_DIR>/.mellos/map.json" --page <PAGE_SLUG>`,
+   where `<plugin root>` is `${CLAUDE_PLUGIN_ROOT}` inside Claude Code and the
+   installed runtime's own directory everywhere else (omp and bare MCP
+   clients: take the path from the tool's message rather than inventing one).
+
+If launching fails, relay its reason and the complete quoted fallback command.
+Do not repeatedly call `mmap_open` on later writes; retry only after the terminal
+environment changes or the user asks. `mmap_view` remains available inline. After
+the pane is up, confirm briefly; only when neither the default file nor any
+page file exists does the pane sit on its standby screen ("waiting for the
+first mmap_declare ...", or "waiting for &lt;file&gt; ..." when `--page` named a
+page that does not exist yet), until the first `mmap_declare`.
+
+$ARGUMENTS

package/dist/omp-extension.mjs

@@ -1,6 +1,5 @@
 // src/host/omp/extension.ts
-import { homedir as homedir2 } from "node:os";
-import { dirname as dirname5, join as join5 } from "node:path";
+import { dirname as dirname5 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/hook/session-start.ts
@@ -288,7 +287,9 @@ if (launchedAsEntry(process.argv[1], import.meta.url)) {
   main().catch(() => process.exit(0));
 }
 
-// src/host/omp/extension.ts
+// src/host/session-context.ts
+import { homedir as homedir2 } from "node:os";
+import { join as join5 } from "node:path";
 var SESSION_CONTEXT_TYPE = "mellos-mapping.session-context";
 function sessionParagraph(projectDir) {
   const stateFile = join5(projectDir, STATE_FILE_RELATIVE_PATH);
@@ -296,6 +297,12 @@ function sessionParagraph(projectDir) {
   if (!scopes.ok) return void 0;
   return sessionStartContext({ policy: scopes.value.effective, hasStore: hasMap(stateFile) });
 }
+function storeIsReadable(projectDir) {
+  const stateFile = join5(projectDir, STATE_FILE_RELATIVE_PATH);
+  return effectiveMappingPolicy(configFilePath(stateFile), userConfigFilePath(homedir2())).ok;
+}
+
+// src/host/omp/extension.ts
 function mellosMappingOmp(pi) {
   const pluginRoot = dirname5(dirname5(fileURLToPath2(import.meta.url)));
   let armed = true;
@@ -348,12 +355,6 @@ function mellosMappingOmp(pi) {
     return { message };
   });
 }
-function storeIsReadable(projectDir) {
-  const stateFile = join5(projectDir, STATE_FILE_RELATIVE_PATH);
-  return effectiveMappingPolicy(configFilePath(stateFile), userConfigFilePath(homedir2())).ok;
-}
 export {
-  SESSION_CONTEXT_TYPE,
-  mellosMappingOmp as default,
-  sessionParagraph
+  mellosMappingOmp as default
 };