mellos-mapping 0.20.0 → 0.20.2

package/scripts/codex-register.mjs

@@ -12,37 +12,106 @@
  * directory, which is exactly the contract dist/server.mjs already expects.
  * The registered path is absolute and version-specific, so re-run after
  * every plugin update.
+ *
+ * Two Windows facts shape the process handling below:
+ *   - A missing `codex` is NOT a spawn error there. The call goes through
+ *     cmd.exe (only a shell resolves both codex.exe and an npm .cmd shim), so
+ *     "not recognized as an internal or external command" arrives as an
+ *     ordinary non-zero exit, and a check for spawnSync's `error` field can
+ *     never fire. PATH is probed up front instead.
+ *   - The child writes its diagnostics in the console's OEM code page.
+ *     Decoding those bytes as UTF-8 turns every non-English message into
+ *     mojibake, so they are passed through as bytes and the terminal decodes
+ *     them as it decodes everything else it prints.
+ *
+ * Pure helpers are exported for the spec; registration runs only as an entry
+ * point, so importing this file is inert.
  */
 import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const serverPath = join(pluginRoot, 'dist', 'server.mjs');
+/** cmd.exe's exit code for a command it cannot resolve on PATH. */
+export const COMMAND_NOT_FOUND_EXIT_CODE = 9009;
+
+/** Quote one argument for a cmd.exe command line. */
+export function quoteForShell(arg) {
+  return /[\s"]/.test(arg) ? `"${arg}"` : arg;
+}
+
+/**
+ * What went wrong, in the user's terms.
+ * @param status - the child's exit code (null = it never ran).
+ * @returns the line to print; a missing CLI is named as such on every
+ *   platform, because that is the failure a first-time reader actually hits.
+ */
+export function describeFailure(status) {
+  return status === COMMAND_NOT_FOUND_EXIT_CODE || status === null
+    ? 'codex CLI not found on PATH — install Codex first, then re-run this script.'
+    : `codex mcp add failed (exit ${status}).`;
+}
+
+/** Whether `codex` resolves on PATH. */
+function codexOnPath() {
+  const probe =
+    process.platform === 'win32'
+      ? spawnSync('where', ['codex'], { stdio: 'ignore', windowsHide: true })
+      : spawnSync('command', ['-v', 'codex'], { shell: true, stdio: 'ignore' });
+  return probe.error === undefined && probe.status === 0;
+}
 
+/**
+ * Run the codex CLI. Output is captured as BYTES (no `encoding`), so the
+ * child's console-code-page diagnostics reach the terminal unaltered.
+ */
 function codex(args) {
   if (process.platform !== 'win32') {
-    return spawnSync('codex', args, { stdio: 'pipe', encoding: 'utf8' });
+    return spawnSync('codex', args, { stdio: 'pipe' });
   }
   // Windows: codex may be an .exe or an npm .cmd shim; only a shell resolves
   // both. The shell needs explicit quoting for paths with spaces.
-  const line = ['codex', ...args].map((a) => (/[\s"]/.test(a) ? `"${a}"` : a)).join(' ');
-  return spawnSync(line, { shell: true, stdio: 'pipe', encoding: 'utf8' });
+  const line = ['codex', ...args].map(quoteForShell).join(' ');
+  return spawnSync(line, { shell: true, stdio: 'pipe', windowsHide: true });
 }
 
-// Idempotent: drop any previous (possibly stale, version-specific) entry.
-codex(['mcp', 'remove', 'mellos-mapping']);
-
-const added = codex(['mcp', 'add', 'mellos-mapping', '--', 'node', serverPath]);
-if (added.error !== undefined || added.status !== 0) {
-  process.stderr.write(added.stderr ?? '');
-  console.error(
-    added.error !== undefined
-      ? 'codex CLI not found on PATH — install Codex first, then re-run this script.'
-      : `codex mcp add failed (exit ${added.status}).`,
-  );
-  process.exit(1);
+function main() {
+  const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+  const serverPath = join(pluginRoot, 'dist', 'server.mjs');
+
+  if (!codexOnPath()) {
+    console.error(describeFailure(COMMAND_NOT_FOUND_EXIT_CODE));
+    process.exit(1);
+  }
+
+  // Idempotent: drop any previous (possibly stale, version-specific) entry.
+  codex(['mcp', 'remove', 'mellos-mapping']);
+
+  const added = codex(['mcp', 'add', 'mellos-mapping', '--', 'node', serverPath]);
+  if (added.status !== 0) {
+    if (added.stderr) process.stderr.write(added.stderr);
+    console.error(describeFailure(added.status));
+    process.exit(1);
+  }
+  if (added.stdout) process.stdout.write(added.stdout);
+  console.log(`mellos-mapping MCP registered with Codex: node ${serverPath}`);
+  console.log('State files resolve to each session’s working directory (.mellos/map.json).');
 }
-process.stdout.write(added.stdout ?? '');
-console.log(`mellos-mapping MCP registered with Codex: node ${serverPath}`);
-console.log('State files resolve to each session’s working directory (.mellos/map.json).');
+
+/**
+ * Run only as an entry point, so the spec can import the helpers above
+ * without registering anything. Each script in this directory carries its own
+ * copy: package.json ships them file-by-file, so a shared scripts/ module
+ * would simply be missing from an npm install.
+ */
+function launchedAsEntry() {
+  const entry = process.argv[1];
+  if (entry === undefined) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (launchedAsEntry()) main();

package/scripts/install-mmap-command.mjs

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/**
+ * Put `mmap` on the PATH of a plugin install.
+ *
+ *   node scripts/install-mmap-command.mjs [--uninstall] [--json]
+ *
+ * npm users get `mmap` for free — package.json declares it in `bin`. Claude
+ * Code installs this plugin by CLONING the repo, with no npm install and no
+ * bin shims, so the one command a human is meant to type has nowhere to be
+ * typed from. This script is that missing step, and nothing more: it writes
+ * two tiny shims into `%LOCALAPPDATA%\mellos-mapping\bin` — `mmap.cmd` for
+ * cmd/PowerShell, `mmap` for git-bash — and adds that one directory to the
+ * USER PATH.
+ *
+ * Nobody has to run it by hand: the SessionStart hook
+ * (src/hook/session-start.ts) notices a missing or stale shim when a session
+ * starts and runs this script with `--json`, which prints the outcome as one
+ * JSON line instead of prose — that outcome object is the contract between
+ * the two files. The script stays a standalone command for the cases the
+ * hook does not cover: `--uninstall`, and re-adding a PATH entry the user
+ * removed while the shims still exist (the hook checks only the shims).
+ *
+ * What it will NEVER do, and says so instead:
+ *
+ *   - Touch the SYSTEM PATH. This is a per-user tool.
+ *   - Rewrite a user PATH that `setx` cannot carry safely. `setx` writes a
+ *     plain string and truncates past SETX_VALUE_MAX, so a PATH holding
+ *     `%USERPROFILE%`-style references would come back with the references
+ *     flattened, and a long one would come back SHORTER. Both are damage that
+ *     outlives this tool, so in either case the shims are still installed and
+ *     the exact line to add by hand is printed.
+ *
+ * Windows-first, deliberately: this plugin's pane is Windows Terminal. On
+ * other platforms `mmap` is `npm i -g mellos-mapping`, or a shell alias.
+ *
+ * Pure helpers are exported for the spec; the installer runs only as an entry
+ * point, so importing this file is inert.
+ */
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { launchedAsEntry, pluginRootOf } from './pane-core.mjs';
+
+export const USAGE = 'usage: node scripts/install-mmap-command.mjs [--uninstall] [--json]';
+
+/**
+ * Longest value `setx` stores without truncating it, in characters. Documented
+ * by the tool itself ("the maximum size is 1024 characters") and the reason
+ * this script would rather refuse than shorten someone's PATH.
+ */
+export const SETX_VALUE_MAX = 1024;
+
+/** The one directory this installer owns, given a `%LOCALAPPDATA%`. */
+export function binDirIn(localAppData) {
+  return join(localAppData, 'mellos-mapping', 'bin');
+}
+
+/** The cmd/PowerShell shim: forwards every argument, prints nothing of its own. */
+export function cmdShim(mmapPath) {
+  return ['@echo off', `node "${mmapPath}" %*`, ''].join('\r\n');
+}
+
+/**
+ * The git-bash shim. The target is written with forward slashes: a Windows
+ * path inside sh double quotes keeps its backslashes verbatim, and `\U` in
+ * `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');
+}
+
+/** PATH entries as written, empties dropped — the unit every rule below works on. */
+function entriesOf(rawPath) {
+  return rawPath.split(';').filter((e) => e.trim() !== '');
+}
+
+/** Two PATH entries naming the same directory: case and a trailing slash do not count. */
+function samePathEntry(a, b) {
+  const norm = (s) => s.trim().replace(/^"|"$/g, '').replace(/[\\/]+$/, '').toLowerCase();
+  return norm(a) === norm(b);
+}
+
+/** Is `dir` already on this PATH? Then installing it again must change nothing. */
+export function pathContains(rawPath, dir) {
+  return entriesOf(rawPath).some((e) => samePathEntry(e, dir));
+}
+
+/** `rawPath` with `dir` appended — unchanged when it is already there. */
+export function pathWith(rawPath, dir) {
+  return pathContains(rawPath, dir) ? rawPath : [...entriesOf(rawPath), dir].join(';');
+}
+
+/** `rawPath` with every mention of `dir` removed. */
+export function pathWithout(rawPath, dir) {
+  return entriesOf(rawPath)
+    .filter((e) => !samePathEntry(e, dir))
+    .join(';');
+}
+
+/**
+ * Why `setx` must not be used to write `nextValue`, or undefined when it can.
+ *
+ * @param rawValue - the USER PATH exactly as the registry holds it.
+ * @param nextValue - what this script would write.
+ * @returns a sentence naming the damage that would be done, for the caller to
+ *   print beside the manual instructions.
+ */
+export function setxRefusal(rawValue, nextValue) {
+  if (rawValue.includes('%')) {
+    return 'your user PATH contains %VARIABLE% references, and setx would store them flattened to whatever they mean right now';
+  }
+  if (nextValue.length > SETX_VALUE_MAX) {
+    return `your user PATH would be ${nextValue.length} characters and setx truncates past ${SETX_VALUE_MAX}`;
+  }
+  return undefined;
+}
+
+/**
+ * What bringing the PATH from `raw` to `wanted` takes — decided, not done.
+ * The single place the write/refuse/no-op judgment lives; both the prose
+ * path and the `--json` path execute exactly this plan.
+ * @returns {{action: 'unchanged'} | {action: 'write'} | {action: 'refused', reason: string}}
+ */
+export function planPath(raw, wanted) {
+  if (wanted === raw) return { action: 'unchanged' };
+  const reason = setxRefusal(raw, wanted);
+  return reason === undefined ? { action: 'write' } : { action: 'refused', reason };
+}
+
+/**
+ * The USER PATH exactly as the registry holds it — unexpanded, so a
+ * `%USERPROFILE%` in it is still a `%USERPROFILE%` here.
+ *
+ * node's own `process.env.Path` is the merged, expanded, per-process value and
+ * writing THAT back would fold the machine's PATH into the user's.
+ * @returns the raw value, or '' when the user has no PATH of their own.
+ */
+function readUserPath() {
+  const r = spawnSync('reg', ['query', 'HKCU\\Environment', '/v', 'Path'], { encoding: 'utf8', windowsHide: true });
+  const m = (r.stdout ?? '').match(/^\s*Path\s+REG_(?:EXPAND_)?SZ\s+(.*)$/m);
+  return m === null ? '' : m[1].trimEnd();
+}
+
+/** Ask Windows to store the user's PATH, and to tell running shells about it. */
+function writeUserPath(value) {
+  const r = spawnSync('setx', ['PATH', value], { encoding: 'utf8', windowsHide: true });
+  return r.status === 0 ? { ok: true, value: undefined } : { ok: false, error: (r.stderr || r.stdout || '').trim() };
+}
+
+/**
+ * Bring the USER PATH to where it should be, saying out loud what changes
+ * before anything does.
+ * @param wanted - the PATH value this run wants.
+ * @param raw - the PATH value as it stands.
+ */
+function applyPath(raw, wanted) {
+  const plan = planPath(raw, wanted);
+  if (plan.action === 'unchanged') {
+    console.log('Your user PATH already says what it should — leaving it alone.');
+    return;
+  }
+  if (plan.action === 'refused') {
+    console.log(`NOT touching your user PATH: ${plan.reason}.`);
+    console.log('Add (or remove) this entry yourself, in Settings > "Edit environment variables for your account":');
+    console.log(`  ${wanted}`);
+    return;
+  }
+  console.log('Changing ONE thing in your Windows user environment — your user PATH becomes:');
+  console.log(`  ${wanted}`);
+  const written = writeUserPath(wanted);
+  if (!written.ok) {
+    console.error(`setx refused: ${written.error}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * 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
+ * `--json` output and the contract the SessionStart hook reads — change a
+ * field here and src/hook/session-start.ts must follow.
+ *
+ * @returns one of
+ *   {kind: 'not-built', missing}  — dist/mmap.mjs absent, nothing written;
+ *   {kind: 'installed', binDir, cmdPath, shPath, path, wanted, reason?} —
+ *     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).
+ */
+export function install(localAppData, pluginRoot) {
+  const mmapPath = join(pluginRoot, 'dist', 'mmap.mjs');
+  if (!existsSync(mmapPath)) return { kind: 'not-built', missing: mmapPath };
+
+  const binDir = binDirIn(localAppData);
+  const cmdPath = join(binDir, 'mmap.cmd');
+  const shPath = join(binDir, 'mmap');
+  mkdirSync(binDir, { recursive: true });
+  writeFileSync(cmdPath, cmdShim(mmapPath));
+  writeFileSync(shPath, shShim(mmapPath));
+  try {
+    chmodSync(shPath, 0o755); // git-bash honors the execute bit it can see
+  } catch {
+    // A filesystem without POSIX modes still runs the shim through `sh`;
+    // refusing to install over a chmod would be theatre.
+  }
+
+  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 };
+  if (plan.action === 'refused') {
+    return { kind: 'installed', binDir, cmdPath, shPath, path: 'refused', wanted, reason: plan.reason };
+  }
+  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 };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const uninstall = argv.includes('--uninstall');
+  const json = argv.includes('--json');
+  const unknown = argv.find((a) => a !== '--uninstall' && a !== '--json');
+  if (unknown !== undefined) {
+    console.error(`unknown argument "${unknown}"\n${USAGE}`);
+    process.exit(1);
+  }
+  if (uninstall && json) {
+    console.error(`--uninstall talks to a human; it has no --json mode\n${USAGE}`);
+    process.exit(1);
+  }
+  if (process.platform !== 'win32') {
+    console.error('This installer is for Windows. Elsewhere, `npm i -g mellos-mapping` provides the same `mmap` command.');
+    process.exit(1);
+  }
+  const localAppData = process.env['LOCALAPPDATA'];
+  if (localAppData === undefined || localAppData === '') {
+    console.error('LOCALAPPDATA is not set — there is no per-user place to install into.');
+    process.exit(1);
+  }
+
+  if (uninstall) {
+    const binDir = binDirIn(localAppData);
+    const raw = readUserPath();
+    for (const path of [join(binDir, 'mmap.cmd'), join(binDir, 'mmap')]) {
+      rmSync(path, { force: true });
+      console.log(`removed ${path}`);
+    }
+    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;
+  }
+
+  const outcome = install(localAppData, pluginRootOf(import.meta.url));
+  if (json) {
+    console.log(JSON.stringify(outcome));
+    return;
+  }
+  if (outcome.kind === 'not-built') {
+    console.error(`the plugin is not built — run "npm run build" (missing ${outcome.missing})`);
+    process.exit(1);
+  }
+  console.log(`wrote ${outcome.cmdPath}`);
+  console.log(`wrote ${outcome.shPath}`);
+  switch (outcome.path) {
+    case 'unchanged':
+      console.log('Your user PATH already says what it should — leaving it alone.');
+      break;
+    case 'updated':
+      console.log('Changed ONE thing in your Windows user environment — your user PATH is now:');
+      console.log(`  ${outcome.wanted}`);
+      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}`);
+      break;
+    case 'error':
+      console.error(`setx refused: ${outcome.reason}`);
+      process.exit(1);
+  }
+  console.log(
+    'Close Windows Terminal entirely and reopen it — a running terminal, new tabs included, keeps the old PATH.',
+  );
+  console.log('Then type `mmap` in any project: it opens the map pane, or closes the open one.');
+}
+
+if (launchedAsEntry(process.argv[1], import.meta.url)) main();

package/scripts/mmap.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * `mmap` — the human's entrance to the map pane. A TOGGLE.
+ *
+ *   mmap                      open the pane for this project, or close the one
+ *                             that is already open
+ *   mmap <slug>               open the pane ON that page, or retarget the pane
+ *                             that is already open. Never closes anything:
+ *                             naming a page is asking to SEE it
+ *   mmap [--window] [--ascii] [--no-color] [--no-mouse] [--no-follow]
+ *        [--interval <ms>] [--force]
+ *
+ * Two things make this a different command from scripts/open-pane.mjs rather
+ * than a flag on it:
+ *
+ *   1. It has no project argument. A human types `mmap` wherever they happen
+ *      to be standing, so the project is DISCOVERED — walk up from the cwd to
+ *      the nearest directory holding the store, the way git finds its root.
+ *   2. It closes. `mmap` with a pane open writes the store's one-shot quit
+ *      request and the pane exits within a poll tick. The agent's launcher
+ *      deliberately cannot do that.
+ *
+ * Everything else — the window probe, the already-running check, the `wt`
+ * payload — is ./pane-core.mjs, shared verbatim with open-pane.mjs.
+ *
+ * Pure helpers are exported for the spec; the command runs only as an entry
+ * point, so importing this file is inert.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import {
+  DEDICATED_WINDOW_NAME,
+  PANE_MODE,
+  launchedAsEntry,
+  loadPluginPaths,
+  placePane,
+  pluginRootOf,
+  takeWatcherFlag,
+  paneIsOpen,
+  writeFocusRequest,
+  writeQuitRequest,
+} from './pane-core.mjs';
+
+export const USAGE =
+  'usage: mmap [<page-slug>] [--window] [--force] [--ascii] [--no-color] [--no-mouse]' +
+  ' [--no-follow] [--interval <ms>]\n' +
+  '       bare `mmap` toggles: it opens the map pane for this project, or closes the open one.';
+
+/**
+ * Parse the toggle's command line.
+ *
+ * @param argv - arguments after the script path.
+ * @param idRule - the store's page-slug grammar (ID_RULE), passed in rather
+ *   than restated, so this parser cannot drift from the ids the store accepts.
+ * @returns ok(config) or err(message). One positional argument at most, and it
+ *   is a PAGE SLUG — not a directory: `mmap` is typed inside the project it
+ *   means. An unknown flag is refused rather than dropped, exactly as the
+ *   watcher and the agent launcher refuse one.
+ */
+export function parseMmapArgs(argv, idRule) {
+  const positional = [];
+  const watcherFlags = [];
+  let mode = PANE_MODE.split;
+  let force = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const watcher = takeWatcherFlag(argv, i);
+    if (watcher.kind === 'bad-value') return { ok: false, error: `${watcher.message}\n${USAGE}` };
+    if (watcher.kind === 'taken') {
+      watcherFlags.push(...watcher.flags);
+      i = watcher.next;
+    } else if (a === '--window') {
+      mode = PANE_MODE.window;
+    } else if (a === '--force') {
+      force = true;
+    } else if (a === '--page') {
+      // The slug is the positional here; accepting both spellings would make
+      // `mmap api --page other` a question with no answer.
+      return { ok: false, error: `mmap takes the page slug as its argument, not --page\n${USAGE}` };
+    } else if (a.startsWith('--')) {
+      return { ok: false, error: `unknown flag "${a}"\n${USAGE}` };
+    } else {
+      positional.push(a);
+    }
+  }
+  if (positional.length > 1) return { ok: false, error: `mmap takes at most one page slug\n${USAGE}` };
+  const pageSlug = positional[0];
+  if (pageSlug !== undefined && !idRule.test(pageSlug)) {
+    return { ok: false, error: `a page is a kebab-case slug (got "${pageSlug}")\n${USAGE}` };
+  }
+  return { ok: true, value: { pageSlug, mode, force, watcherFlags } };
+}
+
+/**
+ * The directories to look in for a project's store, nearest first: the
+ * starting directory, then every ancestor up to and including the filesystem
+ * root.
+ *
+ * Pure on purpose — the caller asks the filesystem which of these actually
+ * holds a store — so the walk itself is specifiable without a project tree.
+ */
+export function storeSearchPath(startDir) {
+  const dirs = [];
+  let dir = resolve(startDir);
+  for (;;) {
+    dirs.push(dir);
+    const parent = dirname(dir);
+    if (parent === dir) return dirs; // the filesystem root is its own parent
+    dir = parent;
+  }
+}
+
+/**
+ * The directory whose presence marks a project, taken from the store's own
+ * default-page path (its first segment). Derived rather than restated: this
+ * script must not carry a second copy of the store's layout.
+ */
+export function storeMarkerOf(storeRelativePath) {
+  return storeRelativePath.split(/[\\/]/)[0];
+}
+
+/**
+ * Which project `mmap` was typed in: the NEAREST candidate that holds a store,
+ * the way git discovers its root.
+ *
+ * @param candidates - storeSearchPath's answer, nearest first.
+ * @param holdsStore - whether each candidate holds the store directory, in the
+ *   same order. A parallel array of answers rather than a predicate to call:
+ *   the filesystem question belongs to the entry point, and this rule is then
+ *   a fold over values that a spec can state in full.
+ * @returns the project root, and whether a store was actually found —
+ *   `found: false` means the starting directory is being used because nothing
+ *   above it has a map yet, which is a legitimate first open, not an error.
+ */
+export function nearestProject(candidates, holdsStore) {
+  const at = holdsStore.indexOf(true);
+  return at >= 0 ? { root: candidates[at], found: true } : { root: candidates[0], found: false };
+}
+
+/**
+ * What a `mmap` invocation means, given whether a pane is already up.
+ *
+ * The toggle rule in one place: a BARE `mmap` against a running pane closes
+ * it; naming a page never does — asking to see something is not asking to
+ * lose it — and retargets the running pane instead. With no pane running,
+ * every form opens one.
+ *
+ * @param running - a watcher for this project's map file is alive.
+ * @param pageSlug - the page named on the command line, if any.
+ * @param force - `--force`: open another pane regardless.
+ */
+export function toggleAction(running, pageSlug, force = false) {
+  if (!running || force) return { kind: 'open' };
+  return pageSlug === undefined ? { kind: 'quit' } : { kind: 'focus', page: pageSlug };
+}
+
+async function main() {
+  const loaded = await loadPluginPaths(pluginRootOf(import.meta.url));
+  if (!loaded.ok) {
+    console.error(loaded.error);
+    process.exit(1);
+  }
+  const { store, watchPath } = loaded.value;
+
+  const parsed = parseMmapArgs(process.argv.slice(2), store.ID_RULE);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    process.exit(1);
+  }
+  if (process.platform !== 'win32') {
+    console.error('mmap opens the pane through Windows Terminal — on other platforms run the watcher yourself:');
+    console.error(`  node "${watchPath}" --file "<project>/${store.STATE_FILE_RELATIVE_PATH}"`);
+    process.exit(1);
+  }
+
+  const candidates = storeSearchPath(process.cwd());
+  const marker = storeMarkerOf(store.STATE_FILE_RELATIVE_PATH);
+  const project = nearestProject(candidates, candidates.map((dir) => existsSync(join(dir, marker))));
+  const cfg = { ...parsed.value, projectDir: project.root };
+  const mapFile = join(project.root, store.STATE_FILE_RELATIVE_PATH);
+  const action = toggleAction(paneIsOpen(store, mapFile), cfg.pageSlug, cfg.force);
+
+  if (action.kind === 'quit') {
+    writeQuitRequest(store.quitFilePath(mapFile));
+    console.log(`Closing the map pane for ${project.root}.`);
+    return;
+  }
+  if (action.kind === 'focus') {
+    writeFocusRequest(store.focusFilePath(mapFile), action.page);
+    console.log(`The map pane for ${project.root} is already open — showing page "${action.page}".`);
+    return;
+  }
+
+  const placed = placePane(cfg, watchPath, mapFile);
+  if (!placed.ok) {
+    console.error(placed.error);
+    process.exit(1);
+  }
+  const where =
+    placed.value.mode === PANE_MODE.window
+      ? `in the dedicated "${DEDICATED_WINDOW_NAME}" window (${placed.value.reason})`
+      : 'beside this terminal (vertical split)';
+  console.log(`Map opened for ${project.root} ${where}.`);
+  if (!project.found) {
+    console.log(
+      'This project has no map yet, so the pane will sit on its standby screen ' +
+        'until the assistant declares one.',
+    );
+  }
+}
+
+if (launchedAsEntry(process.argv[1], import.meta.url)) await main();