mellos-mapping 0.19.0 → 0.20.2

package/dist/hook-session-start.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
+
+// src/hook/session-start.ts
+import { spawnSync } from "node:child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname as dirname2, join as join2 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// src/store/store.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+// src/domain/types.ts
+var ok = (value) => ({ ok: true, value });
+var err = (error) => ({ ok: false, error });
+var RANK_MIN = 0;
+var RANK_MAX = 99;
+var RANK_RULE_TEXT = `an integer in ${RANK_MIN}..${RANK_MAX}, 0 = bottom / most primitive`;
+
+// src/store/store.ts
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function stripBom(text) {
+  return text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+}
+var STORE_DIR_NAME = ".mellos";
+var STATE_FILE_RELATIVE_PATH = join(STORE_DIR_NAME, "map.json");
+var PAGES_DIR_NAME = "pages";
+var CONFIG_FILE_NAME = "config.json";
+var CONFIG_FILE_VERSION = 1;
+function configFilePath(defaultFile) {
+  return join(dirname(defaultFile), CONFIG_FILE_NAME);
+}
+function userConfigFilePath(userBase) {
+  return join(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 });
+}
+var LEGACY_STATE_FILE_RELATIVE_PATH = join(".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. Declare the whole ghost design with mmap_declare BEFORE writing code.",
+    "  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.",
+    "An explicit request from the user always outranks this."
+  ].join("\n");
+}
+function hasMap(stateFile) {
+  return existsSync2(stateFile) || existsSync2(join2(dirname2(stateFile), PAGES_DIR_NAME));
+}
+function mmapShimFilePath(localAppData) {
+  return join2(localAppData, "mellos-mapping", "bin", "mmap.cmd");
+}
+function mmapShimCurrent(shimContent, mmapPath) {
+  return shimContent !== void 0 && shimContent.includes(`"${mmapPath}"`);
+}
+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";
+    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").'
+    ].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 = join2(pluginRoot, "dist", "mmap.mjs");
+  let shim;
+  try {
+    shim = readFileSync2(mmapShimFilePath(localAppData), "utf8");
+  } catch {
+    shim = void 0;
+  }
+  if (mmapShimCurrent(shim, mmapPath)) return void 0;
+  const run = spawnSync(
+    process.execPath,
+    [join2(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 = join2(projectDir, STATE_FILE_RELATIVE_PATH);
+  const scopes = effectiveMappingPolicy(configFilePath(stateFile), userConfigFilePath(homedir()));
+  if (!scopes.ok) return;
+  const pluginRoot = dirname2(dirname2(fileURLToPath(import.meta.url)));
+  const 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));
+}
+export {
+  hasMap,
+  hookOutput,
+  installContextLine,
+  launchedAsEntry,
+  mmapShimCurrent,
+  mmapShimFilePath,
+  parseHookInput,
+  sessionStartContext
+};

package/dist/mmap.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+
+// scripts/mmap.mjs
+import { existsSync as existsSync2 } from "node:fs";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
+
+// scripts/pane-core.mjs
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+var WATCHER_BOOLEAN_FLAGS = ["--ascii", "--no-color", "--no-mouse", "--no-follow"];
+var WATCHER_VALUE_FLAGS = ["--interval"];
+var PANE_MODE = { split: "split", window: "window" };
+function takeWatcherFlag(argv, i) {
+  const flag = argv[i];
+  if (WATCHER_BOOLEAN_FLAGS.includes(flag)) return { kind: "taken", next: i, flags: [flag] };
+  if (!WATCHER_VALUE_FLAGS.includes(flag)) return { kind: "other" };
+  const value = argv[i + 1];
+  if (value === void 0 || !Number.isFinite(Number(value))) return { kind: "bad-value", message: `${flag} needs a number` };
+  return { kind: "taken", next: i + 1, flags: [flag, value] };
+}
+function pluginRootOf(moduleUrl) {
+  return dirname(dirname(fileURLToPath(moduleUrl)));
+}
+async function loadPluginPaths(pluginRoot) {
+  const pathsModule = join(pluginRoot, "dist", "store-paths.mjs");
+  const watchPath = join(pluginRoot, "dist", "watch.mjs");
+  const missing = !existsSync(pathsModule) ? pathsModule : !existsSync(watchPath) ? watchPath : void 0;
+  if (missing !== void 0) {
+    return { ok: false, error: `the plugin is not built \u2014 run "npm run build" (missing ${missing})` };
+  }
+  return { ok: true, value: { store: await import(pathToFileURL(pathsModule).href), watchPath } };
+}
+function launchedAsEntry(argv1, moduleUrl) {
+  if (argv1 === void 0) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+var ORPHANED_FOCUS_FILE_NAME = "mellos-mapping.focus";
+function writeRequest(path, body) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(`${path}.tmp`, JSON.stringify(body));
+  renameSync(`${path}.tmp`, path);
+}
+function writeFocusRequest(focusFile, pageSlug) {
+  writeRequest(focusFile, { page: pageSlug });
+  try {
+    rmSync(join(dirname(focusFile), ORPHANED_FOCUS_FILE_NAME), { force: true });
+  } catch {
+  }
+}
+function writeQuitRequest(quitFile) {
+  writeRequest(quitFile, {});
+}
+function paneCommand(cfg, watchPath, mapFile) {
+  const cmd = ["--title", "mellos map", "-d", cfg.projectDir, "node", watchPath, "--file", mapFile, ...cfg.watcherFlags];
+  if (cfg.pageSlug !== void 0) cmd.push("--page", cfg.pageSlug);
+  return cmd;
+}
+function powerShellQuote(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+function watcherProbeScript(mapFile) {
+  return `$ErrorActionPreference = 'SilentlyContinue'
+$needle = ${powerShellQuote(mapFile)}
+$w = @(Get-CimInstance Win32_Process -Filter "Name='node.exe'" | Where-Object {
+  $_.CommandLine -and
+  $_.CommandLine.IndexOf('watch.mjs', [StringComparison]::OrdinalIgnoreCase) -ge 0 -and
+  $_.CommandLine.IndexOf($needle, [StringComparison]::OrdinalIgnoreCase) -ge 0
+})
+Write-Output "WATCHERS=$($w.Count)"`;
+}
+var IDENTIFY_AND_FOCUS = String.raw`
+$ErrorActionPreference = 'SilentlyContinue'
+Add-Type @"
+using System;
+using System.Text;
+using System.Runtime.InteropServices;
+public class MmapWin {
+  [DllImport("user32.dll")] public static extern bool EnumWindows(EnumWindowsProc cb, IntPtr lp);
+  public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lp);
+  [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr hWnd);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetClassName(IntPtr hWnd, StringBuilder sb, int max);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetWindowText(IntPtr hWnd, StringBuilder sb, int max);
+  [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr hWnd);
+  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] public static extern bool BringWindowToTop(IntPtr hWnd);
+  [DllImport("user32.dll")] public static extern bool AttachThreadInput(uint a, uint b, bool f);
+  [DllImport("kernel32.dll")] public static extern uint GetCurrentThreadId();
+  [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint pid);
+  [DllImport("user32.dll")] public static extern void keybd_event(byte bVk, byte bScan, uint dwFlags, IntPtr dwExtraInfo);
+  [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+  [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr hWnd);
+  [DllImport("kernel32.dll")] public static extern bool FreeConsole();
+  [DllImport("kernel32.dll")] public static extern bool AttachConsole(uint pid);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode)] public static extern bool SetConsoleTitle(string title);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode)] public static extern uint GetConsoleTitle(StringBuilder sb, uint size);
+}
+"@
+function Get-WtWindows {
+  $wins = New-Object System.Collections.ArrayList
+  $cb = {
+    param($h, $lp)
+    if ([MmapWin]::IsWindowVisible($h)) {
+      $cls = New-Object System.Text.StringBuilder 256
+      [void][MmapWin]::GetClassName($h, $cls, 256)
+      if ($cls.ToString() -eq 'CASCADIA_HOSTING_WINDOW_CLASS') {
+        $t = New-Object System.Text.StringBuilder 512
+        [void][MmapWin]::GetWindowText($h, $t, 512)
+        [void]$wins.Add(@{ hwnd = $h.ToInt64(); title = $t.ToString() })
+      }
+    }
+    return $true
+  }
+  [void][MmapWin]::EnumWindows($cb, [IntPtr]::Zero)
+  return ,$wins
+}
+
+$ancestors = @()
+$p = $PID
+for ($i = 0; $i -lt 12 -and $p; $i++) {
+  $proc = Get-CimInstance Win32_Process -Filter "ProcessId=$p"
+  if (-not $proc) { break }
+  if ($i -gt 0) { $ancestors += [uint32]$proc.ProcessId }
+  $p = $proc.ParentProcessId
+}
+
+# The agent CLI (claude/codex/...) is some ancestor holding the console that a
+# WT window renders; hidden-console ancestors just never light a window up.
+$nonce = "__NONCE__"
+$hwnd = [IntPtr]::Zero
+foreach ($apid in $ancestors) {
+  [void][MmapWin]::FreeConsole()
+  if (-not [MmapWin]::AttachConsole($apid)) { continue }
+  $sb = New-Object System.Text.StringBuilder 1024
+  [void][MmapWin]::GetConsoleTitle($sb, 1024)
+  $orig = $sb.ToString()
+  for ($i = 0; $i -lt 6 -and $hwnd -eq [IntPtr]::Zero; $i++) {
+    [void][MmapWin]::SetConsoleTitle($nonce)
+    Start-Sleep -Milliseconds 60
+    foreach ($w in (Get-WtWindows)) {
+      if ($w.title -like "*$nonce*") { $hwnd = [IntPtr]$w.hwnd; break }
+    }
+  }
+  Start-Sleep -Milliseconds 100
+  [void][MmapWin]::SetConsoleTitle($orig)
+  Start-Sleep -Milliseconds 200
+  [void][MmapWin]::FreeConsole()
+  if ($hwnd -ne [IntPtr]::Zero) { break }
+}
+
+if ($hwnd -eq [IntPtr]::Zero) { Write-Output 'IDENT=0'; exit 0 }
+Write-Output "IDENT=$($hwnd.ToInt64())"
+
+if ([MmapWin]::IsIconic($hwnd)) { [void][MmapWin]::ShowWindow($hwnd, 9) }
+$focused = $false
+[void][MmapWin]::SetForegroundWindow($hwnd)
+Start-Sleep -Milliseconds 150
+if ([MmapWin]::GetForegroundWindow() -eq $hwnd) { $focused = $true }
+if (-not $focused) {
+  [MmapWin]::keybd_event(0x12, 0, 0, [IntPtr]::Zero)
+  [void][MmapWin]::SetForegroundWindow($hwnd)
+  [MmapWin]::keybd_event(0x12, 0, 2, [IntPtr]::Zero)
+  Start-Sleep -Milliseconds 150
+  if ([MmapWin]::GetForegroundWindow() -eq $hwnd) { $focused = $true }
+}
+if (-not $focused) {
+  $fgpid = 0
+  $fgThread = [MmapWin]::GetWindowThreadProcessId([MmapWin]::GetForegroundWindow(), [ref]$fgpid)
+  $myThread = [MmapWin]::GetCurrentThreadId()
+  [void][MmapWin]::AttachThreadInput($myThread, $fgThread, $true)
+  [void][MmapWin]::BringWindowToTop($hwnd)
+  [void][MmapWin]::SetForegroundWindow($hwnd)
+  [void][MmapWin]::AttachThreadInput($myThread, $fgThread, $false)
+  Start-Sleep -Milliseconds 150
+  if ([MmapWin]::GetForegroundWindow() -eq $hwnd) { $focused = $true }
+}
+Write-Output "FOCUS=$(if ($focused) { 1 } else { 0 })"
+`;
+var PROBE_TIMEOUT_MS = 3e4;
+var WT_TIMEOUT_MS = 15e3;
+var SPLIT_SIZE = "0.42";
+var DEDICATED_WINDOW_NAME = "mellos-mapping";
+function runPowerShell(script) {
+  const encoded = Buffer.from(script, "utf16le").toString("base64");
+  const r = spawnSync(
+    "powershell.exe",
+    ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encoded],
+    { encoding: "utf8", timeout: PROBE_TIMEOUT_MS, windowsHide: true }
+  );
+  return r.stdout ?? "";
+}
+function paneIsOpen(store, mapFile) {
+  if (store.readLiveViewers(mapFile, Date.now()).length > 0) return true;
+  if (process.platform !== "win32") return false;
+  const m = runPowerShell(watcherProbeScript(mapFile)).match(/WATCHERS=(\d+)/);
+  return m !== null && Number(m[1]) > 0;
+}
+function openWt(args, what) {
+  const r = spawnSync("wt", args, { stdio: "ignore", timeout: WT_TIMEOUT_MS, windowsHide: true });
+  return r.status === 0 ? { ok: true, value: void 0 } : { ok: false, error: `wt failed to ${what} (exit ${r.status ?? "timeout"}) \u2014 is Windows Terminal installed?` };
+}
+function placePane(cfg, watchPath, mapFile) {
+  const dedicated = (reason) => {
+    const opened = openWt(["-w", DEDICATED_WINDOW_NAME, "nt", ...paneCommand(cfg, watchPath, mapFile)], "open the dedicated window");
+    return opened.ok ? { ok: true, value: { mode: PANE_MODE.window, reason } } : opened;
+  };
+  if (cfg.mode === PANE_MODE.window) return dedicated("requested");
+  const nonce = `MMAP-NONCE-${process.pid}`;
+  const out = runPowerShell(IDENTIFY_AND_FOCUS.replaceAll("__NONCE__", nonce));
+  const ident = out.match(/IDENT=(\d+)/)?.[1] ?? "0";
+  if (ident === "0") return dedicated("session-window-not-identified");
+  if (!/FOCUS=1/.test(out)) return dedicated("session-window-focus-denied");
+  const split = openWt(
+    ["-w", "0", "sp", "-V", "--size", SPLIT_SIZE, ...paneCommand(cfg, watchPath, mapFile)],
+    "split the session window"
+  );
+  return split.ok ? { ok: true, value: { mode: PANE_MODE.split, hwnd: ident } } : split;
+}
+
+// scripts/mmap.mjs
+var 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.";
+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}
+${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") {
+      return { ok: false, error: `mmap takes the page slug as its argument, not --page
+${USAGE}` };
+    } else if (a.startsWith("--")) {
+      return { ok: false, error: `unknown flag "${a}"
+${USAGE}` };
+    } else {
+      positional.push(a);
+    }
+  }
+  if (positional.length > 1) return { ok: false, error: `mmap takes at most one page slug
+${USAGE}` };
+  const pageSlug = positional[0];
+  if (pageSlug !== void 0 && !idRule.test(pageSlug)) {
+    return { ok: false, error: `a page is a kebab-case slug (got "${pageSlug}")
+${USAGE}` };
+  }
+  return { ok: true, value: { pageSlug, mode, force, watcherFlags } };
+}
+function storeSearchPath(startDir) {
+  const dirs = [];
+  let dir = resolve(startDir);
+  for (; ; ) {
+    dirs.push(dir);
+    const parent = dirname2(dir);
+    if (parent === dir) return dirs;
+    dir = parent;
+  }
+}
+function storeMarkerOf(storeRelativePath) {
+  return storeRelativePath.split(/[\\/]/)[0];
+}
+function nearestProject(candidates, holdsStore) {
+  const at = holdsStore.indexOf(true);
+  return at >= 0 ? { root: candidates[at], found: true } : { root: candidates[0], found: false };
+}
+function toggleAction(running, pageSlug, force = false) {
+  if (!running || force) return { kind: "open" };
+  return pageSlug === void 0 ? { 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 \u2014 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) => existsSync2(join2(dir, marker))));
+  const cfg = { ...parsed.value, projectDir: project.root };
+  const mapFile = join2(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 \u2014 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();
+export {
+  USAGE,
+  nearestProject,
+  parseMmapArgs,
+  storeMarkerOf,
+  storeSearchPath,
+  toggleAction
+};