mellos-mapping 0.15.0 → 0.16.0

package/README.md

@@ -128,9 +128,11 @@ the script after updating the plugin.
 To watch the live pane beside a Codex session on Windows, run
 `node <plugin root>/scripts/open-pane.mjs <project dir>` — it splits the
 terminal window hosting the session (or falls back to a dedicated
-"mellos-mapping" window; `--window` picks that on purpose). Elsewhere run
-`node <plugin root>/dist/watch.mjs` from the project directory in a second
-terminal (or any terminal split).
+"mellos-mapping" window; `--window` picks that on purpose). Add
+`--page <slug>` to open on a particular page — and with a pane already open,
+rerunning with `--page` retargets it instead of opening another. Elsewhere
+run `node <plugin root>/dist/watch.mjs` (same `--page` flag) from the
+project directory in a second terminal (or any terminal split).
 
 ## Any MCP client
 

package/README.zh-CN.md

@@ -118,8 +118,10 @@ node ~/.codex/plugins/cache/mellos-mapping/mellos-mapping/<版本>/scripts/codex
 要在 Codex 会话旁边看实况面板，Windows 上运行
 `node <插件根>/scripts/open-pane.mjs <项目目录>`——它会在承载本会话的
 终端窗口里分屏（识别不到就确定性地开到专属的 "mellos-mapping" 窗口；
-`--window` 则是主动选择专属窗口）。其他环境在项目目录下的第二个终端
-（或任意分屏）运行 `node <插件根>/dist/watch.mjs`。
+`--window` 则是主动选择专属窗口）。加 `--page <slug>` 指定打开哪一页；
+面板已经开着时，带 `--page` 重跑一次不会再开新面板，而是让现有面板
+切到那一页。其他环境在项目目录下的第二个终端（或任意分屏）运行
+`node <插件根>/dist/watch.mjs`（同样支持 `--page`）。
 
 ## 任意 MCP 客户端
 

package/dist/server.mjs

@@ -22133,7 +22133,7 @@ function drawBox(canvas, box, opts, neutral, focused = false) {
 }
 
 // src/store/store.ts
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 var STATE_FILE_VERSION = 1;
 var STATE_FILE_RELATIVE_PATH = join(".claude", "mellos-mapping.json");
@@ -22515,7 +22515,7 @@ function summarize(map) {
 
 // src/server/server.ts
 var SERVER_NAME = "mellos-mapping";
-var SERVER_VERSION = "0.15.0";
+var SERVER_VERSION = "0.16.0";
 var ID = external_exports.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/, "lowercase letters, digits and dashes, 1-64 chars").describe("stable kebab-case identifier");
 var PAGE = ID.optional().describe(
   "page (parallel map) this call targets; omit for the default page. One effort = one page: start a NEW effort on its own page named after the effort, so concurrent sessions never write over each other and the pane can switch between pages."

package/dist/watch.mjs

@@ -967,11 +967,14 @@ function drawBox(canvas, box, opts, neutral, focused = false) {
 }
 
 // src/store/store.ts
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 var STATE_FILE_VERSION = 1;
 var STATE_FILE_RELATIVE_PATH = join(".claude", "mellos-mapping.json");
 var PAGES_DIR_NAME = "mellos-mapping.pages";
+function makePageId(raw) {
+  return ID_RULE.test(raw) ? ok(raw) : err({ kind: "invalid-id", raw, rule: ID_RULE_TEXT });
+}
 function pageFilePath(defaultFile, page) {
   return page === void 0 ? defaultFile : join(dirname(defaultFile), PAGES_DIR_NAME, `${page}.json`);
 }
@@ -993,6 +996,35 @@ function listPageFiles(defaultFile) {
   }
   return out;
 }
+var FOCUS_FILE_NAME = "mellos-mapping.focus";
+function focusFilePath(defaultFile) {
+  return join(dirname(defaultFile), FOCUS_FILE_NAME);
+}
+function takeFocusRequest(defaultFile) {
+  const path = focusFilePath(defaultFile);
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return void 0;
+  }
+  try {
+    rmSync(path, { force: true });
+  } catch {
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null) return void 0;
+  const page = parsed.page;
+  if (page === void 0 || page === null) return { page: void 0 };
+  if (typeof page !== "string") return void 0;
+  const id = makePageId(page);
+  return id.ok ? { page: id.value } : void 0;
+}
 function describeStoreError(e) {
   switch (e.kind) {
     case "not-found":
@@ -1241,11 +1273,17 @@ function parseArgs(argv, cwd) {
   let unicode = true;
   let color = true;
   let mouse = true;
+  let page;
   for (let i = 0; i < argv.length; i++) {
     switch (argv[i]) {
       case "--file":
         file = argv[++i] ?? file;
         break;
+      case "--page": {
+        const parsed = makePageId(argv[++i] ?? "");
+        if (parsed.ok) page = parsed.value;
+        break;
+      }
       case "--interval":
         intervalMs = Math.max(50, Number(argv[++i]) || intervalMs);
         break;
@@ -1262,7 +1300,19 @@ function parseArgs(argv, cwd) {
         break;
     }
   }
-  return { file, intervalMs, unicode, color, mouse };
+  return { file, intervalMs, unicode, color, mouse, page };
+}
+function mostRecentPageFile(files, mtimeOf) {
+  let best;
+  let bestMtime = -Infinity;
+  for (const file of files) {
+    const mtime = mtimeOf(file);
+    if (mtime !== void 0 && mtime > bestMtime) {
+      best = file;
+      bestMtime = mtime;
+    }
+  }
+  return best ?? files[0];
 }
 var HIDE_CURSOR = "\x1B[?25l";
 var SHOW_CURSOR = "\x1B[?25h";
@@ -1627,6 +1677,7 @@ function main() {
   const pageViews = /* @__PURE__ */ new Map();
   let activeFile;
   let firstScan = true;
+  let pendingFocusFile = cfg.page === void 0 ? void 0 : pageFilePath(cfg.file, cfg.page);
   let lastTabSegments = [];
   let tabScroll = 0;
   let offsetX = 0;
@@ -1656,7 +1707,7 @@ function main() {
       parent = diveOrigin(cfg.file, activeFile, pageFiles, maps())?.parent;
     }
     if (parent !== void 0 && parent !== activeFile) {
-      switchPage(parent);
+      handSwitch(parent);
       return true;
     }
     return false;
@@ -1691,6 +1742,10 @@ function main() {
     const tabIndex = top.indexOf(file);
     if (tabIndex >= 0) tabScroll = tabScrollFor(pageTabsOf(top), viewWidth(), cfg.unicode, tabScroll, tabIndex);
   };
+  const handSwitch = (file) => {
+    pendingFocusFile = void 0;
+    switchPage(file);
+  };
   const hitTest = (termX, termY) => {
     const sx = termX - 1;
     const sy = termY - 1 - tabRows();
@@ -1846,8 +1901,18 @@ function main() {
         if (file === activeFile) notice = describeStoreError(loaded.error);
       }
     }
+    const request = takeFocusRequest(cfg.file);
+    if (request !== void 0 && !(firstScan && pendingFocusFile !== void 0)) {
+      pendingFocusFile = pageFilePath(cfg.file, request.page);
+    }
+    if (pendingFocusFile !== void 0 && pageFiles.includes(pendingFocusFile)) {
+      if (pendingFocusFile !== activeFile) switchPage(pendingFocusFile);
+      pendingFocusFile = void 0;
+    }
     firstScan = false;
-    if (activeFile === void 0 || !pageFiles.includes(activeFile)) switchPage(pageFiles[0]);
+    if (activeFile === void 0 || !pageFiles.includes(activeFile)) {
+      switchPage(mostRecentPageFile(pageFiles, (f) => pageData.get(f)?.mtimeMs));
+    }
     if ([...pageData.values()].some((p) => p.map?.nodes.some((n) => n.status === "in-progress"))) spinnerFrame++;
     if (flash !== void 0 && Date.now() > flash.until) flash = void 0;
     paint();
@@ -1959,7 +2024,7 @@ function main() {
                   tabScroll = Math.max(0, Math.min(tabScroll + tabHit.action.delta, lastTabFiles.length - 1));
                 } else {
                   const target = lastTabFiles[tabHit.action.index];
-                  if (target !== void 0 && target !== activeFile) switchPage(target);
+                  if (target !== void 0 && target !== activeFile) handSwitch(target);
                 }
               } else {
                 const id = hitTest(event.x, event.y);
@@ -1970,7 +2035,7 @@ function main() {
                     const target = pageFilePath(cfg.file, submap);
                     if (pageFiles.includes(target) && target !== activeFile) {
                       diveStack.push(activeFile);
-                      switchPage(target);
+                      handSwitch(target);
                     } else if (!pageFiles.includes(target)) {
                       flash = { text: `submap "${submap}" has no page yet`, until: now + 2500 };
                     }
@@ -1994,7 +2059,7 @@ function main() {
               const step = event.kind === "next-page" ? 1 : -1;
               const target = top[(current + step + top.length) % top.length];
               if (target !== activeFile) {
-                switchPage(target);
+                handSwitch(target);
                 dirty = true;
               }
             }
@@ -2003,7 +2068,7 @@ function main() {
           case "page": {
             const target = topFiles()[event.index];
             if (target !== void 0 && target !== activeFile) {
-              switchPage(target);
+              handSwitch(target);
               dirty = true;
             }
             break;
@@ -2049,6 +2114,7 @@ export {
   launchedAsEntry,
   liveRipples,
   mapPanel,
+  mostRecentPageFile,
   nearestHit,
   nodePanel,
   pageTabRow,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.15.0",
+  "version": "0.16.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",

package/scripts/open-pane.mjs

@@ -2,7 +2,7 @@
 /**
  * Open the live map pane in the RIGHT Windows Terminal window.
  *
- *   node scripts/open-pane.mjs <project-dir> [--window] [--ascii] [--force]
+ *   node scripts/open-pane.mjs <project-dir> [--page <slug>] [--window] [--ascii] [--force]
  *
  * Why this exists: the agent's shell runs on a hidden console (no WT_SESSION),
  * so a bare `wt -w 0 sp` targets the MOST RECENTLY USED terminal window — with
@@ -33,18 +33,38 @@
  * Known race, accepted: if the user focuses a DIFFERENT terminal window in
  * the ~1s between our focus-verify and wt reading its MRU state, the split
  * can still land there. The window is at least one the user is actively in.
+ *
+ * --page <slug> opens the map ON that page (the effort under discussion, not
+ * whatever page the store lists first). With a watcher already running it
+ * writes the one-shot focus file instead — the existing pane retargets within
+ * a poll tick — so re-running with --page is also how you steer an open pane.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const USAGE = 'usage: node scripts/open-pane.mjs <project-dir> [--page <slug>] [--window] [--ascii] [--force]';
+
 const argv = process.argv.slice(2);
-const flags = new Set(argv.filter((a) => a.startsWith('--')));
-const positional = argv.filter((a) => !a.startsWith('--'));
+const flags = new Set();
+const positional = [];
+let pageSlug;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--page') pageSlug = argv[++i];
+  else if (a.startsWith('--')) flags.add(a);
+  else positional.push(a);
+}
 
 if (positional.length !== 1) {
-  console.error('usage: node scripts/open-pane.mjs <project-dir> [--window] [--ascii] [--force]');
+  console.error(USAGE);
+  process.exit(1);
+}
+// Mirrors ID_RULE in src/domain/types.ts — this script runs standalone and
+// cannot import the TypeScript sources.
+if (pageSlug !== undefined && !/^[a-z0-9][a-z0-9-]{0,63}$/.test(pageSlug)) {
+  console.error(`--page needs a kebab-case slug (got "${pageSlug}")\n${USAGE}`);
   process.exit(1);
 }
 if (process.platform !== 'win32') {
@@ -203,6 +223,7 @@ Write-Output "FOCUS=$(if ($focused) { 1 } else { 0 })"
 function paneCommand() {
   const cmd = ['--title', 'mellos map', '-d', projectDir, 'node', watchPath, '--file', mapFile];
   if (flags.has('--ascii')) cmd.push('--ascii');
+  if (pageSlug !== undefined) cmd.push('--page', pageSlug);
   return cmd;
 }
 
@@ -221,8 +242,21 @@ function openDedicatedWindow(reason) {
 }
 
 if (!flags.has('--force') && watcherAlreadyRunning()) {
-  console.log('MMAP_PANE already-open');
-  console.log(`A watcher for ${mapFile} is already running — not opening another pane (use --force to override).`);
+  if (pageSlug !== undefined) {
+    // One-shot focus request (see takeFocusRequest in src/store/store.ts):
+    // the running watcher consumes and deletes it within a poll tick. Temp +
+    // rename because the watcher polls: a torn read would be swept as junk,
+    // silently losing the request.
+    mkdirSync(dirname(mapFile), { recursive: true });
+    const focusFile = join(dirname(mapFile), 'mellos-mapping.focus');
+    writeFileSync(`${focusFile}.tmp`, JSON.stringify({ page: pageSlug }));
+    renameSync(`${focusFile}.tmp`, focusFile);
+    console.log(`MMAP_PANE already-open refocused=${pageSlug}`);
+    console.log(`A watcher for ${mapFile} is already running — asked it to show page "${pageSlug}".`);
+  } else {
+    console.log('MMAP_PANE already-open');
+    console.log(`A watcher for ${mapFile} is already running — not opening another pane (use --force to override).`);
+  }
   process.exit(0);
 }