mellos-mapping 0.25.0 → 0.26.0

package/README.md

@@ -94,6 +94,32 @@ committed, so a clone runs as-is —
 `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
@@ -110,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
@@ -136,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

package/README.zh-CN.md

@@ -84,6 +84,30 @@ claude plugin marketplace add GuangminJu/mellos-mapping && claude plugin install
 钩子），以及 `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)。
+
 装完之后的第一个会话只会问你**一个**问题——建图要多积极——并把答案记成
 你以后打开的每一个项目的默认。此后钩子会自己把它带进每个新会话；再也没有
 "每个项目设置一遍"这回事。见
@@ -97,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 条目却被你删掉之后重新加回去：
@@ -120,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/`——地图属于这个工具，不属于

package/dist/hook-session-start.mjs

@@ -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
 };

package/dist/omp-extension.mjs

@@ -0,0 +1,359 @@
+// src/host/omp/extension.ts
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname5, join as join5 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/hook/session-start.ts
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname as dirname4, join as join4 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// src/domain/types.ts
+var ok = (value) => ({ ok: true, value });
+var err = (error) => ({ ok: false, error });
+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/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;
+}
+
+// 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 join2(dirname2(defaultFile), CONFIG_FILE_NAME);
+}
+function userConfigFilePath(userBase) {
+  return join2(userBase, STORE_DIR_NAME, CONFIG_FILE_NAME);
+}
+var MAPPING_POLICIES = ["always", "complex", "on-request"];
+function makeMappingPolicy(raw) {
+  return MAPPING_POLICIES.includes(raw) ? ok(raw) : err({ kind: "invalid-policy", raw, allowed: MAPPING_POLICIES });
+}
+function describeMappingPolicy(policy) {
+  switch (policy) {
+    case "always":
+      return "map every structured task \u2014 workflows, designs, architecture, technical dependencies";
+    case "complex":
+      return "map only medium or complex tasks \u2014 several modules, a new subsystem, roughly an hour or more";
+    case "on-request":
+      return "map only when the user explicitly asks";
+  }
+}
+function loadMappingPolicy(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return ok(void 0);
+    throw e;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(stripBom(text));
+  } catch (e) {
+    return err({ kind: "malformed-json", path, detail: e.message });
+  }
+  if (!isRecord(raw)) return err({ kind: "bad-shape", path, detail: "root is not an object" });
+  if (raw["version"] !== CONFIG_FILE_VERSION) {
+    return err({ kind: "bad-shape", path, detail: `version is ${String(raw["version"])}, expected ${CONFIG_FILE_VERSION}` });
+  }
+  const rawPolicy = raw["policy"];
+  if (rawPolicy === void 0) return ok(void 0);
+  if (typeof rawPolicy !== "string") return err({ kind: "bad-shape", path, detail: "policy is not a string" });
+  const policy = makeMappingPolicy(rawPolicy);
+  return policy.ok ? ok(policy.value) : err({ kind: "bad-shape", path, detail: `policy is "${rawPolicy}", expected one of: ${MAPPING_POLICIES.join(" | ")}` });
+}
+function effectiveMappingPolicy(projectConfigFile, userConfigFile) {
+  const project = loadMappingPolicy(projectConfigFile);
+  if (!project.ok) return project;
+  const user = loadMappingPolicy(userConfigFile);
+  if (!user.ok) return user;
+  const effective = project.value ?? user.value;
+  const source = project.value !== void 0 ? "project" : user.value !== void 0 ? "user" : void 0;
+  return ok({ project: project.value, user: user.value, effective, source });
+}
+
+// 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) {
+  const { policy, hasStore } = input;
+  if (policy === void 0) {
+    return [
+      "mellos-mapping \u2014 first-run setup. This question is asked ONCE EVER, not once per project.",
+      "Before starting structured work here, ask the user how eager mapping should be:",
+      ...MAPPING_POLICIES.map((p) => `  ${p} \u2014 ${describeMappingPolicy(p)}`),
+      'Record their answer with mmap_setup {policy: "<their choice>", scope: "user"} \u2014 it then applies',
+      'to every project they open, and a single project can still override it with scope: "project".',
+      "Do not choose for them, and do not ask again once it is recorded."
+    ].join("\n");
+  }
+  if (policy === "on-request") {
+    return hasStore ? "mellos-mapping: this project has a Mellos map. The user's policy is on-request \u2014 use the mmap tools only when they ask." : void 0;
+  }
+  const scope = policy === "always" ? "For ANY structured task in this project \u2014 workflows, designs, architecture, technical dependencies:" : "For any MEDIUM OR COMPLEX task in this project \u2014 several modules, a new subsystem, roughly an hour of work or more (skip trivial edits):";
+  return [
+    `mellos-mapping policy: ${policy} \u2014 ${describeMappingPolicy(policy)}.`,
+    scope,
+    "  1. Load the mellos-mapping skill and follow it.",
+    "  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.",
+    "  4. Watch the `pane:` line every write answers with: it says whether anybody is actually",
+    "     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");
+}
+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(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) {
+  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;
+  const o = outcome;
+  if (o.kind !== "installed" || typeof o.binDir !== "string") return void 0;
+  if (o.path === "updated") {
+    return [
+      "mellos-mapping: the `mmap` terminal command was just installed for the user",
+      `(${o.binDir} was added to their user PATH). Typed in any project terminal, \`mmap\``,
+      "toggles the map pane. The PATH change reaches only NEW processes \u2014 and a new tab of",
+      "a running Windows Terminal inherits the old environment, so if the user says `mmap`",
+      "is not recognized, tell them to close Windows Terminal entirely and reopen it."
+    ].join("\n");
+  }
+  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 their account").'
+    ].join("\n");
+  }
+  return void 0;
+}
+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 = join4(pluginRoot, "dist", "mmap.mjs");
+  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(
+    runtime,
+    [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;
+  let outcome;
+  try {
+    outcome = JSON.parse(run.stdout);
+  } catch {
+    return void 0;
+  }
+  return installContextLine(outcome);
+}
+function parseHookInput(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { cwd: void 0 };
+  }
+  if (typeof parsed !== "object" || parsed === null) return { cwd: void 0 };
+  const cwd = parsed.cwd;
+  return { cwd: typeof cwd === "string" && cwd !== "" ? cwd : void 0 };
+}
+function hookOutput(additionalContext) {
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext } });
+}
+async function readAll(stream) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function main() {
+  const raw = process.stdin.isTTY === true ? "" : await readAll(process.stdin);
+  const projectDir = parseHookInput(raw).cwd ?? process.cwd();
+  const stateFile = join4(projectDir, STATE_FILE_RELATIVE_PATH);
+  const scopes = effectiveMappingPolicy(configFilePath(stateFile), userConfigFilePath(homedir()));
+  if (!scopes.ok) return;
+  const pluginRoot = dirname4(dirname4(fileURLToPath(import.meta.url)));
+  const context = sessionStartContext({
+    policy: scopes.value.effective,
+    hasStore: hasMap(stateFile)
+  });
+  let installNote;
+  try {
+    installNote = ensureMmapCommand(pluginRoot);
+  } catch {
+    installNote = void 0;
+  }
+  const parts = [context, installNote].filter((p) => p !== void 0);
+  if (parts.length > 0) process.stdout.write(hookOutput(parts.join("\n\n")));
+}
+function launchedAsEntry(argv1, moduleUrl) {
+  if (argv1 === void 0) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return pathToFileURL(argv1).href === moduleUrl;
+  }
+}
+if (launchedAsEntry(process.argv[1], import.meta.url)) {
+  main().catch(() => process.exit(0));
+}
+
+// src/host/omp/extension.ts
+var SESSION_CONTEXT_TYPE = "mellos-mapping.session-context";
+function sessionParagraph(projectDir) {
+  const stateFile = join5(projectDir, STATE_FILE_RELATIVE_PATH);
+  const scopes = effectiveMappingPolicy(configFilePath(stateFile), userConfigFilePath(homedir2()));
+  if (!scopes.ok) return void 0;
+  return sessionStartContext({ policy: scopes.value.effective, hasStore: hasMap(stateFile) });
+}
+function mellosMappingOmp(pi) {
+  const pluginRoot = dirname5(dirname5(fileURLToPath2(import.meta.url)));
+  let armed = true;
+  let installNote;
+  let told;
+  const rearm = async () => {
+    armed = true;
+  };
+  pi.setLabel?.("Mellos Mapping");
+  pi.on("session_start", async () => {
+    armed = true;
+    try {
+      installNote = ensureMmapCommand(pluginRoot);
+    } catch {
+      installNote = void 0;
+    }
+  });
+  pi.on("session_switch", rearm);
+  pi.on("session_branch", rearm);
+  pi.on("session_compact", rearm);
+  pi.on("before_agent_start", async (_event, ctx) => {
+    const cwd = ctx !== null && typeof ctx === "object" && "cwd" in ctx ? ctx.cwd : void 0;
+    const projectDir = typeof cwd === "string" && cwd !== "" ? cwd : process.cwd();
+    let paragraph;
+    let broken = false;
+    try {
+      paragraph = sessionParagraph(projectDir);
+    } catch {
+      paragraph = void 0;
+    }
+    if (paragraph === void 0) {
+      broken = !storeIsReadable(projectDir);
+    }
+    const content = [paragraph, installNote].filter((part) => part !== void 0).join("\n\n");
+    const owed = armed || paragraph !== void 0 && paragraph !== told;
+    if (!owed || broken || content === "") {
+      if (!broken) armed = false;
+      return void 0;
+    }
+    armed = false;
+    told = paragraph;
+    const message = {
+      customType: SESSION_CONTEXT_TYPE,
+      content,
+      // Standing instruction, not conversation: the model reads it, and the
+      // transcript does not grow a message the user never sent.
+      display: false,
+      attribution: "agent"
+    };
+    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
+};

package/dist/server.mjs

@@ -24383,7 +24383,7 @@ function viewTool() {
 function openTool() {
   return {
     title: "Open the map pane",
-    description: 'For automatic display beside the current ChatGPT desktop conversation in Codex mode, use surface: "web-terminal", then call open_in_codex with the returned browser hostOpen object. No paste or Computer Use is needed. For the native host terminal, use surface: "codex-terminal": prepare absolute watcher commands for the current project, then ask the host to open its right terminal. This does not launch the watcher or type into that terminal. Agent exec PTYs cannot be attached using their numeric session ids. For a document panel, use surface: "markdown": generate MD + SVG files, enable automatic preview updates after successful map writes, then use the HOST file-opening tool to display the returned absolute Markdown path on the right of the current conversation. Generated does not mean visible: this server cannot open or observe the desktop side panel. For interactive maps, choose surface: "web": start or reuse a project-local web viewer and pass the returned URL to the host browser-opening tool. Markdown and terminal remain available. The default surface is "terminal", preserving the terminal workflow. Put the live map on the user\'s screen: a terminal pane beside this conversation that redraws on every write. Call it whenever a result says `pane: CLOSED` \u2014 and do NOT ask permission first, because a user who has set a mapping policy has already said they want to see the map. With a pane already open this RETARGETS it to `page` instead of opening a second one, so it is also how you show the user a particular page when they ask for one. It never closes a pane: taking the map off the screen belongs to the user (the `q` key in the pane, or typing `mmap` in a terminal). The reply says whether a pane actually reported itself in afterwards, not merely that a command was run. Automatic terminal opening supports Windows Terminal and tmux on Linux/macOS. If opening fails, relay the reason and copyable command; retry only after the environment changes or the user asks.',
+    description: 'For automatic display beside the current ChatGPT desktop conversation in Codex mode, use surface: "web-terminal", then call open_in_codex with the returned browser hostOpen object. No paste or Computer Use is needed. For the native host terminal, use surface: "codex-terminal": prepare absolute watcher commands for the current project, then ask the host to open its right terminal. This does not launch the watcher or type into that terminal. Agent exec PTYs cannot be attached using their numeric session ids. For a document panel, use surface: "markdown": generate MD + SVG files, enable automatic preview updates after successful map writes, then use the HOST file-opening tool to display the returned absolute Markdown path on the right of the current conversation. Generated does not mean visible: this server cannot open or observe the desktop side panel. For interactive maps, choose surface: "web": start or reuse a project-local web viewer and pass the returned URL to the host browser-opening tool. Markdown and terminal remain available. The default surface is "terminal", preserving the terminal workflow. Put the live map on the user\'s screen: a terminal pane beside this conversation that redraws on every write. Call it whenever a result says `pane: CLOSED` \u2014 and do NOT ask permission first, because a user who has set a mapping policy has already said they want to see the map. With a pane already open this RETARGETS it to `page` instead of opening a second one, so it is also how you show the user a particular page when they ask for one. It never closes a pane: taking the map off the screen belongs to the user (the `q` key in the pane, or typing `mmap` in a terminal). The reply says whether a pane actually reported itself in afterwards, not merely that a command was run. Automatic terminal opening supports Windows Terminal and tmux on Linux/macOS. omp (Oh My Pi) has no side panel of its own: there the routes are this same terminal pane (a Windows Terminal split, or a tmux split on Linux/macOS) and the web viewer, whose URL the session opens with its own browser tool. If opening fails, relay the reason and copyable command; retry only after the environment changes or the user asks.',
     inputSchema: closed({
       surface: external_exports.enum(["terminal", "codex-terminal", "markdown", "web", "web-terminal"]).optional().describe("web-terminal = automatically started mmap terminal in a local browser page; codex-terminal = prepare a command for the desktop host terminal; web = local browser viewer; markdown = MD/SVG; terminal = Windows Terminal or tmux launcher (default)"),
       page: id(
@@ -24650,7 +24650,7 @@ function launcherViewerPid(run) {
 
 // src/server/server.ts
 var SERVER_NAME = "mellos-mapping";
-var SERVER_VERSION = "0.25.0";
+var SERVER_VERSION = "0.26.0";
 function text(s, isError = false) {
   return { content: [{ type: "text", text: s }], ...isError ? { isError: true } : {} };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "mcpName": "io.github.GuangminJu/mellos-mapping",
   "description": "A live layered dependency map for bottom-up development — MCP server + terminal pane. Ghost the design first, then light nodes up from the bottom as they are built and verified.",
   "type": "module",
@@ -65,6 +65,11 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
+  "omp": {
+    "extensions": [
+      "./dist/omp-extension.mjs"
+    ]
+  },
   "files": [
     "dist",
     "lib",

package/scripts/install-mmap-command.mjs

@@ -37,7 +37,7 @@
  * point, so importing this file is inert.
  */
 import { spawnSync } from 'node:child_process';
-import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { launchedAsEntry, pluginRootOf } from './pane-core.mjs';
@@ -56,9 +56,36 @@ export function binDirIn(localAppData) {
   return join(localAppData, 'mellos-mapping', 'bin');
 }
 
+/**
+ * Per-user command directories that are USUALLY already on the PATH, in the
+ * order they should be tried, given a `%LOCALAPPDATA%` and a home directory.
+ *
+ * These exist for one case: `setx` refuses to write a user PATH this script
+ * will not carry safely (see setxRefusal), and the canonical `bin` directory is
+ * therefore unreachable for good. A machine with a long PATH — conda, five
+ * Pythons, several toolchains — then has no way to run `mmap` at all, which is
+ * the opposite of what the command is for. Dropping the same two shims into a
+ * directory the PATH already names fixes that without editing anything:
+ *
+ *   - `WindowsApps` is Windows' own per-user command directory (the one App
+ *     Execution Aliases live in) and is on the PATH of every interactive user;
+ *   - `~/.local/bin` is the same idea as the rest of the world spells it.
+ *
+ * Only ever consulted when the PATH route is refused, and only if the directory
+ * exists, is reachable on the CURRENT PATH, and accepts a write.
+ */
+export function linkDirCandidates(localAppData, home) {
+  return [join(localAppData, 'Microsoft', 'WindowsApps'), join(home, '.local', 'bin')];
+}
+
+/** The candidates this PATH can already reach, in the order they were given. */
+export function reachableDirs(candidates, rawPath, exists) {
+  return candidates.filter((dir) => exists(dir) && pathContains(rawPath, dir));
+}
+
 /** The cmd/PowerShell shim: forwards every argument, prints nothing of its own. */
 export function cmdShim(mmapPath) {
-  return ['@echo off', `node "${mmapPath}" %*`, ''].join('\r\n');
+  return ['@echo off', `rem ${SHIM_MARKER}`, `node "${mmapPath}" %*`, ''].join('\r\n');
 }
 
 /**
@@ -67,7 +94,7 @@ export function cmdShim(mmapPath) {
  * `C:\Users` is one escape away from being someone else's bug.
  */
 export function shShim(mmapPath) {
-  return ['#!/bin/sh', `exec node "${mmapPath.replaceAll('\\', '/')}" "$@"`, ''].join('\n');
+  return ['#!/bin/sh', `# ${SHIM_MARKER}`, `exec node "${mmapPath.replaceAll('\\', '/')}" "$@"`, ''].join('\n');
 }
 
 /** PATH entries as written, empties dropped — the unit every rule below works on. */
@@ -175,6 +202,68 @@ function applyPath(raw, wanted) {
   }
 }
 
+/** The command name this plugin installs, and the script it must point at. */
+export const SHIM_COMMAND = 'mmap';
+export const SHIM_SCRIPT = 'mmap.mjs';
+
+/**
+ * Written into both shim shapes. The path alone says nothing reliable about
+ * who wrote a file in a shared directory — the same plugin may be installed
+ * under any checkout name — so ownership gets its own line, and old shims are
+ * still recognized by their target.
+ */
+export const SHIM_MARKER = 'mellos-mapping mmap shim';
+
+/**
+ * The `mmap.mjs` bundle a shim launches, normalized to forward slashes, or
+ * undefined when the text quotes no such path. One reader for every question
+ * about ownership: the cmd shape writes the Windows path, the git-bash shape
+ * the forward-slash one, and a rule that knew only one form would answer
+ * differently about a shim's two files.
+ */
+export function shimTarget(content) {
+  const quoted = /"([^"]*mmap\.mjs)"/.exec(content)?.[1];
+  return quoted === undefined ? undefined : quoted.replaceAll('\\', '/');
+}
+
+/**
+ * Is this shim file one of ours — a `mmap` command that launches a
+ * `dist/mmap.mjs` of this plugin family?
+ *
+ * The fallback directory is SHARED (`WindowsApps`, `~/.local/bin`): a file
+ * called `mmap` there may belong to somebody else, and a plugin that overwrites
+ * a stranger's command on its way in has no standing to be careful on the way
+ * out. Ownership is read from the file's own text. Every shim written since the
+ * marker exists carries it — an install under ANY directory name owns its
+ * copies — and shims written before it are recognized by their target, whose
+ * path named the plugin.
+ */
+export function shimIsOurs(content) {
+  if (content.includes(SHIM_MARKER)) return true;
+  const target = shimTarget(content);
+  return target !== undefined && /mellos-mapping/i.test(target);
+}
+
+/**
+ * Does this shim launch exactly `mmapPath`? Both shapes write the path their
+ * own way, so the comparison happens on the normalized form — the rule every
+ * removal in this file uses, or a git-bash copy would outlive the uninstall
+ * that removed its cmd sibling.
+ */
+export function shimLaunches(content, mmapPath) {
+  const target = shimTarget(content);
+  return target !== undefined && target === mmapPath.replaceAll('\\', '/');
+}
+
+/** Read a file's text, or undefined when it is absent or unreadable. */
+function readIfPresent(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * The install itself, with the narration stripped out: write the shims, bring
  * the PATH in line, report what happened as data. This outcome object IS the
@@ -183,13 +272,16 @@ function applyPath(raw, wanted) {
  *
  * @returns one of
  *   {kind: 'not-built', missing}  — dist/mmap.mjs absent, nothing written;
- *   {kind: 'installed', binDir, cmdPath, shPath, path, wanted, reason?} —
+ *   {kind: 'installed', binDir, cmdPath, shPath, path, wanted, reason?, alias?} —
  *     shims written; `path` says what happened to the USER PATH:
  *       'unchanged' — the entry was already there,
  *       'updated'   — the entry was appended,
  *       'refused'   — setx would damage this PATH (`reason` says how); the
  *                     entry in `wanted` must be added by hand,
  *       'error'     — setx itself failed (`reason` is its message).
+ *     `alias` is the second copy in a directory the PATH already names, written
+ *     only when the PATH route came up short OR when one is already there and
+ *     needs to keep pointing at this install.
  */
 export function install(localAppData, pluginRoot) {
   const mmapPath = join(pluginRoot, 'dist', 'mmap.mjs');
@@ -211,14 +303,56 @@ export function install(localAppData, pluginRoot) {
   const raw = readUserPath();
   const wanted = pathWith(raw, binDir);
   const plan = planPath(raw, wanted);
-  if (plan.action === 'unchanged') return { kind: 'installed', binDir, cmdPath, shPath, path: 'unchanged', wanted };
+  /**
+   * When the PATH cannot be brought to the shim, bring the shim to the PATH:
+   * same two files, dropped into a directory this machine already searches.
+   *
+   * Two rules keep that from becoming a second install nobody owns. A
+   * candidate is skipped when its `mmap` belongs to somebody else — a shared
+   * directory is not ours to overwrite. And a copy that IS ours is refreshed
+   * on every install, not only when the PATH route fails: the shim embeds the
+   * absolute path of one plugin copy, and an untouched copy from an earlier
+   * install would keep launching a directory the next upgrade deletes.
+   *
+   * @param force - create the copy even when none exists yet (the PATH route
+   *   came up short, so this is the only runnable command).
+   * @returns `{dir, cmdPath, shPath, refreshed}` for the copy, or undefined.
+   */
+  const alias = (force) => {
+    const home = process.env['USERPROFILE'] ?? process.env['HOME'];
+    if (home === undefined || home === '') return undefined;
+    // every candidate gets its own try: a directory that exists and is on the
+    // PATH can still refuse the write, and that is a reason to try the next
+    // one, not to give up on having a runnable command
+    for (const dir of reachableDirs(linkDirCandidates(localAppData, home), process.env['PATH'] ?? '', existsSync)) {
+      const linkedCmd = join(dir, 'mmap.cmd');
+      const linkedSh = join(dir, 'mmap');
+      const existing = [readIfPresent(linkedCmd), readIfPresent(linkedSh)].filter((text) => text !== undefined);
+      const foreign = existing.some((text) => !shimIsOurs(text));
+      if (foreign) continue; // somebody else's command: not ours to touch
+      const refreshed = existing.length > 0;
+      if (!refreshed && !force) continue; // nothing there and nothing to fix
+      try {
+        writeFileSync(linkedCmd, cmdShim(mmapPath));
+        writeFileSync(linkedSh, shShim(mmapPath));
+        return { dir, cmdPath: linkedCmd, shPath: linkedSh, refreshed };
+      } catch {
+        continue;
+      }
+    }
+    return undefined;
+  };
   if (plan.action === 'refused') {
-    return { kind: 'installed', binDir, cmdPath, shPath, path: 'refused', wanted, reason: plan.reason };
+    // refused means setx would damage this PATH: the alias is the whole answer
+    return { kind: 'installed', binDir, cmdPath, shPath, path: 'refused', wanted, reason: plan.reason, alias: alias(true) };
+  }
+  if (plan.action === 'unchanged') {
+    return { kind: 'installed', binDir, cmdPath, shPath, path: 'unchanged', wanted, alias: alias(false) };
   }
   const written = writeUserPath(wanted);
   return written.ok
-    ? { kind: 'installed', binDir, cmdPath, shPath, path: 'updated', wanted }
-    : { kind: 'installed', binDir, cmdPath, shPath, path: 'error', wanted, reason: written.error };
+    ? { kind: 'installed', binDir, cmdPath, shPath, path: 'updated', wanted, alias: alias(false) }
+    : { kind: 'installed', binDir, cmdPath, shPath, path: 'error', wanted, reason: written.error, alias: alias(true) };
 }
 
 function main() {
@@ -247,11 +381,37 @@ function main() {
   if (uninstall) {
     const binDir = binDirIn(localAppData);
     const raw = readUserPath();
+    const mine = join(pluginRootOf(import.meta.url), 'dist', 'mmap.mjs');
+    // Remove only what launches THIS install. The canonical pair is shared
+    // with every other host running this plugin (one file per shape, last
+    // installer wins), so when a file belongs to another install — or to a
+    // stranger — it stays, and with it the directory and its PATH entry: the
+    // command those files leave behind is theirs, not this uninstall's to take.
+    let stillInUse = false;
     for (const path of [join(binDir, 'mmap.cmd'), join(binDir, 'mmap')]) {
-      rmSync(path, { force: true });
-      console.log(`removed ${path}`);
+      const content = readIfPresent(path);
+      if (content === undefined) continue;
+      if (shimLaunches(content, mine)) {
+        rmSync(path, { force: true });
+        console.log(`removed ${path}`);
+      } else stillInUse = true;
+    }
+    // The fallback copies — the route a refused PATH leaves — obey the same
+    // rule, per file, in every candidate directory.
+    const home = process.env['USERPROFILE'] ?? process.env['HOME'] ?? '';
+    for (const dir of home === '' ? [] : linkDirCandidates(localAppData, home)) {
+      for (const candidate of [join(dir, 'mmap.cmd'), join(dir, 'mmap')]) {
+        const content = readIfPresent(candidate);
+        if (content === undefined || !shimLaunches(content, mine)) continue;
+        rmSync(candidate, { force: true });
+        console.log(`removed ${candidate}`);
+      }
+    }
+    if (stillInUse) {
+      console.log(`kept ${binDir} and its PATH entry: another install of this plugin still launches from there.`);
+    } else {
+      applyPath(raw, pathWithout(raw, binDir));
     }
-    applyPath(raw, pathWithout(raw, binDir));
     console.log('Close your terminal app entirely and reopen it for the change to take effect — a new tab keeps the old PATH.');
     return;
   }
@@ -277,8 +437,14 @@ function main() {
       break;
     case 'refused':
       console.log(`NOT touching your user PATH: ${outcome.reason}.`);
-      console.log('Add this entry yourself, in Settings > "Edit environment variables for your account":');
-      console.log(`  ${outcome.binDir}`);
+      if (outcome.alias !== undefined) {
+        console.log(`The command works anyway: both shims were also written to ${outcome.alias.dir},`);
+        console.log('which is already on your PATH — open a new terminal and type `mmap`.');
+        console.log(`(${outcome.binDir} stays the canonical home; add it in Settings if you prefer one place.)`);
+      } else {
+        console.log('Add this entry yourself, in Settings > "Edit environment variables for your account":');
+        console.log(`  ${outcome.binDir}`);
+      }
       break;
     case 'error':
       console.error(`setx refused: ${outcome.reason}`);