mellos-mapping 0.20.3 → 0.23.0

package/lib/store/transaction.d.ts

@@ -0,0 +1,12 @@
+import type { MellosMap } from '../domain/types.js';
+export declare class LedgerError extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export declare const revisionOf: (map: MellosMap) => string;
+export declare function assertRevision(actual: string, expected?: string): void;
+/** A named page and the default page share the same project lock. */
+export declare function storeDirectory(file: string): string;
+/** No timed polling: contention is an explicit retryable BUSY result. Never steal a live lock. */
+export declare function withStoreLock<T>(file: string, action: () => T): T;

package/lib/store/transaction.js

@@ -0,0 +1,91 @@
+/** Cooperative, cross-process transactions for MCP and HTTP writers. */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { serializeMap } from './format.js';
+export class LedgerError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+export const revisionOf = (map) => createHash('sha256').update(serializeMap(map)).digest('hex');
+export function assertRevision(actual, expected) {
+    if (expected !== undefined && expected !== actual)
+        throw new LedgerError('CONFLICT', 'Map changed; read the current revision before retrying.', { expectedRevision: expected, actualRevision: actual });
+}
+/** A named page and the default page share the same project lock. */
+export function storeDirectory(file) {
+    const dir = dirname(file);
+    return dir.endsWith('/pages') || dir.endsWith('\\pages') ? dirname(dir) : dir;
+}
+function deadOwner(lock) {
+    try {
+        const owner = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+        if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0)
+            return false;
+        try {
+            process.kill(owner.pid, 0);
+            return false;
+        }
+        catch (e) {
+            return e.code === 'ESRCH';
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/** No timed polling: contention is an explicit retryable BUSY result. Never steal a live lock. */
+export function withStoreLock(file, action) {
+    const dir = storeDirectory(file);
+    mkdirSync(dir, { recursive: true });
+    const lock = join(dir, '.write-lock');
+    const owner = join(lock, 'owner.json');
+    const token = randomUUID();
+    try {
+        mkdirSync(lock);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        // Reapers serialize inside the old directory and recheck its owner after acquiring.
+        // Missing/invalid owners are deliberately not reclaimed on an age heuristic.
+        if (!deadOwner(lock))
+            throw new LedgerError('BUSY', `Another writer owns ${lock}; retry after it completes. An orphan without owner metadata needs manual inspection.`);
+        try {
+            mkdirSync(join(lock, '.reap'));
+        }
+        catch {
+            throw new LedgerError('BUSY', 'Another process is recovering the writer lock.');
+        }
+        if (!deadOwner(lock)) {
+            rmSync(join(lock, '.reap'), { recursive: true, force: true });
+            throw new LedgerError('BUSY', 'Writer ownership changed.');
+        }
+        rmSync(lock, { recursive: true });
+        try {
+            mkdirSync(lock);
+        }
+        catch {
+            throw new LedgerError('BUSY', 'Another writer acquired the recovered lock.');
+        }
+    }
+    let initialized = false;
+    try {
+        writeFileSync(owner, JSON.stringify({ pid: process.pid, token }), { flag: 'wx' });
+        initialized = true;
+        return action();
+    }
+    finally {
+        // Only remove the directory still owned by this invocation.
+        try {
+            if (!initialized || JSON.parse(readFileSync(owner, 'utf8')).token === token)
+                rmSync(lock, { recursive: true });
+        }
+        catch { /* A cleanup error must not misreport a successfully committed map as unsaved. */ }
+    }
+}

package/lib/store/viewers.d.ts

@@ -0,0 +1,81 @@
+import { type Result } from '../domain/types.js';
+import { type StoreError } from './format.js';
+import { type PageId } from './format.js';
+/** Directory (next to the default file) holding one report per live pane. */
+export declare const VIEWERS_DIR_NAME = "viewers";
+/** On-disk report format version. Bump only with a documented migration. */
+export declare const VIEWER_FILE_VERSION = 1;
+/**
+ * How often a pane refreshes its report — the pane's timer, and the unit the
+ * two thresholds below are counted in.
+ */
+export declare const VIEWER_HEARTBEAT_MS = 1000;
+/**
+ * A report older than this is not a pane, it is a pane's remains. Five missed
+ * heartbeats: long enough to survive a garbage collection, a slow repaint or
+ * a busy disk, short enough that a closed pane is known closed before anyone
+ * asks twice.
+ */
+export declare const VIEWER_STALE_MS = 5000;
+/**
+ * A report this old is deleted on sight by whoever reads it. A pane that was
+ * killed leaves its file behind forever, and a file that outlives every pane
+ * would keep answering for one. The gap to VIEWER_STALE_MS is deliberate
+ * slack: a machine that just woke from sleep has stale reports whose panes
+ * are alive and about to beat again, and there is no reason to make them pay
+ * for the sleep with a deleted file.
+ */
+export declare const VIEWER_SWEEP_MS = 60000;
+/** Where a store's viewer reports live, given the default page's file path. */
+export declare function viewersDirPath(defaultFile: string): string;
+/** Where ONE pane's report lives. The pid in the name is the pane's identity. */
+export declare function viewerFilePath(defaultFile: string, pid: number): string;
+/** What a pane says about itself while it is up. */
+export interface ViewerReport {
+    /** The page on screen right now; undefined = the default page. */
+    readonly page: PageId | undefined;
+    /** Auto-follow: whether the pane will switch to whatever page is written next. */
+    readonly follow: boolean;
+    /** Launching console identity, or "window" for an explicitly separate pane. */
+    readonly owner?: string;
+}
+/** A report fresh enough to be a pane, with whose it is and how old. */
+export interface LiveViewer extends ViewerReport {
+    readonly pid: number;
+    /** Age of the report in ms — how long ago that pane last said anything. */
+    readonly ageMs: number;
+}
+/**
+ * Publish this pane's report, atomically (P2) — a reader polling the file
+ * sees the previous whole report or the new one, never half of one.
+ *
+ * Preconditions: none; the viewers directory is created if missing.
+ * Postcondition on ok: the pane's file holds `report` and its mtime is now,
+ * which is what says the pane is alive. On error nothing about the pane is
+ * claimed, and the next heartbeat is the whole recovery — so a caller reports
+ * a failed beat at most once and keeps beating.
+ */
+export declare function publishViewer(defaultFile: string, pid: number, report: ViewerReport): Result<void, StoreError>;
+/**
+ * Take this pane's report back — the pane is going away and says so, rather
+ * than leaving readers to wait out VIEWER_STALE_MS for the same conclusion.
+ *
+ * Best-effort by contract: an exit path is the worst place to raise, and a
+ * report nobody could delete goes stale on its own within seconds.
+ */
+export declare function retireViewer(defaultFile: string, pid: number): void;
+/**
+ * Every pane currently showing this store, youngest report first.
+ *
+ * @param nowMs - the caller's clock (Date.now()), passed in so the ageing
+ *   rules can be tested without waiting for real seconds to pass.
+ * @returns the live reports; an EMPTY array means nobody is seeing this map.
+ *
+ * Reading sweeps: a report past VIEWER_SWEEP_MS is deleted here, because the
+ * pane that would have refreshed it is provably gone and no other code runs
+ * often enough to notice. A report between stale and sweep is ignored but
+ * kept — see VIEWER_SWEEP_MS. Nothing here has an opinion about WHOSE pane a
+ * report is: a viewer started by hand counts exactly like one the launcher
+ * opened, because the user can see both.
+ */
+export declare function readLiveViewers(defaultFile: string, nowMs: number): readonly LiveViewer[];

package/lib/store/viewers.js

@@ -0,0 +1,186 @@
+import { readdirSync, readFileSync, statSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { makePageId } from './format.js';
+import { writeAtomic } from './atomic.js';
+import { isRecord, stripBom } from './json-text.js';
+// ---------------------------------------------------------------------------
+// viewers — "somebody is looking at this store" reports, from the panes
+// ---------------------------------------------------------------------------
+//
+// The first channel that runs the OTHER way. focus and quit are messages TO a
+// pane; this is a pane answering the question every other surface had to
+// guess at, and mostly guessed wrong: is anyone actually SEEING this map?
+//
+// The guess was the bug. An assistant would declare a design, light nodes up
+// as the work went, and report all of it into a store nobody had open —
+// because opening the pane took a human typing `mmap`, and nothing in the
+// system could tell that it had not happened. A map nobody can see is not a
+// map; it is a file. So a pane now says it is there, and the launcher, the
+// toggle and the MCP server read the same answer instead of inventing three.
+//
+// One file per pane, named by its pid: two panes on one store (a split and a
+// dedicated window, `--force`) never clobber each other's report, and the
+// name IS the identity, so nothing inside the payload repeats it.
+//
+// FRESHNESS IS THE FILE'S MTIME, and nothing else. A pane rewrites its report
+// every VIEWER_HEARTBEAT_MS, so a report older than VIEWER_STALE_MS belongs
+// to a pane that is gone — killed, closed with its window, or wedged. A
+// timestamp INSIDE the payload would be a second truth about the same fact,
+// free to disagree with the first; a pid checked for liveness would be worse
+// still, because Windows recycles pids and a recycled one would report a
+// phantom pane — exactly the lie this channel exists to end.
+/** Directory (next to the default file) holding one report per live pane. */
+export const VIEWERS_DIR_NAME = 'viewers';
+/** On-disk report format version. Bump only with a documented migration. */
+export const VIEWER_FILE_VERSION = 1;
+/**
+ * How often a pane refreshes its report — the pane's timer, and the unit the
+ * two thresholds below are counted in.
+ */
+export const VIEWER_HEARTBEAT_MS = 1_000;
+/**
+ * A report older than this is not a pane, it is a pane's remains. Five missed
+ * heartbeats: long enough to survive a garbage collection, a slow repaint or
+ * a busy disk, short enough that a closed pane is known closed before anyone
+ * asks twice.
+ */
+export const VIEWER_STALE_MS = 5_000;
+/**
+ * A report this old is deleted on sight by whoever reads it. A pane that was
+ * killed leaves its file behind forever, and a file that outlives every pane
+ * would keep answering for one. The gap to VIEWER_STALE_MS is deliberate
+ * slack: a machine that just woke from sleep has stale reports whose panes
+ * are alive and about to beat again, and there is no reason to make them pay
+ * for the sleep with a deleted file.
+ */
+export const VIEWER_SWEEP_MS = 60_000;
+/** Where a store's viewer reports live, given the default page's file path. */
+export function viewersDirPath(defaultFile) {
+    return join(dirname(defaultFile), VIEWERS_DIR_NAME);
+}
+/** Where ONE pane's report lives. The pid in the name is the pane's identity. */
+export function viewerFilePath(defaultFile, pid) {
+    return join(viewersDirPath(defaultFile), `${pid}.json`);
+}
+/**
+ * The pid a viewer file name denotes, or undefined when the name is not one
+ * of ours. Strict on purpose: the directory also holds the `*.tmp` files of
+ * saves in flight (writeFileAtomic), and a temp read as a report would be a
+ * pane that never existed.
+ */
+function viewerPidOf(fileName) {
+    const m = /^(\d+)\.json$/.exec(fileName);
+    return m === null ? undefined : Number(m[1]);
+}
+/** Read one report's payload; undefined for anything that is not one. */
+function parseViewerReport(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stripBom(raw));
+    }
+    catch {
+        return undefined; // a torn read from a foreign writer, or junk
+    }
+    if (!isRecord(parsed))
+        return undefined;
+    if (parsed['version'] !== VIEWER_FILE_VERSION)
+        return undefined;
+    const follow = parsed['follow'];
+    if (typeof follow !== 'boolean')
+        return undefined;
+    const owner = parsed['owner'];
+    if (owner !== undefined && (typeof owner !== 'string' || !makePageId(owner).ok))
+        return undefined;
+    const binding = owner === undefined ? {} : { owner: owner };
+    const page = parsed['page'];
+    if (page === null || page === undefined)
+        return { page: undefined, follow, ...binding };
+    if (typeof page !== 'string')
+        return undefined;
+    const id = makePageId(page);
+    return id.ok ? { page: id.value, follow, ...binding } : undefined;
+}
+/**
+ * Publish this pane's report, atomically (P2) — a reader polling the file
+ * sees the previous whole report or the new one, never half of one.
+ *
+ * Preconditions: none; the viewers directory is created if missing.
+ * Postcondition on ok: the pane's file holds `report` and its mtime is now,
+ * which is what says the pane is alive. On error nothing about the pane is
+ * claimed, and the next heartbeat is the whole recovery — so a caller reports
+ * a failed beat at most once and keeps beating.
+ */
+export function publishViewer(defaultFile, pid, report) {
+    const body = { version: VIEWER_FILE_VERSION, page: report.page ?? null, follow: report.follow, owner: report.owner };
+    // This disposable report runs on the input thread every second. A locked
+    // target keeps its previous complete report; the next heartbeat retries.
+    return writeAtomic(viewerFilePath(defaultFile, pid), `${JSON.stringify(body, null, 2)}\n`, 1);
+}
+/**
+ * Take this pane's report back — the pane is going away and says so, rather
+ * than leaving readers to wait out VIEWER_STALE_MS for the same conclusion.
+ *
+ * Best-effort by contract: an exit path is the worst place to raise, and a
+ * report nobody could delete goes stale on its own within seconds.
+ */
+export function retireViewer(defaultFile, pid) {
+    try {
+        rmSync(viewerFilePath(defaultFile, pid), { force: true });
+    }
+    catch {
+        // The file outlives us by VIEWER_STALE_MS. That is the whole cost.
+    }
+}
+/**
+ * Every pane currently showing this store, youngest report first.
+ *
+ * @param nowMs - the caller's clock (Date.now()), passed in so the ageing
+ *   rules can be tested without waiting for real seconds to pass.
+ * @returns the live reports; an EMPTY array means nobody is seeing this map.
+ *
+ * Reading sweeps: a report past VIEWER_SWEEP_MS is deleted here, because the
+ * pane that would have refreshed it is provably gone and no other code runs
+ * often enough to notice. A report between stale and sweep is ignored but
+ * kept — see VIEWER_SWEEP_MS. Nothing here has an opinion about WHOSE pane a
+ * report is: a viewer started by hand counts exactly like one the launcher
+ * opened, because the user can see both.
+ */
+export function readLiveViewers(defaultFile, nowMs) {
+    const dir = viewersDirPath(defaultFile);
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return []; // no directory — no pane has ever run here, the common case
+    }
+    const live = [];
+    for (const name of names) {
+        const pid = viewerPidOf(name);
+        if (pid === undefined)
+            continue;
+        const path = join(dir, name);
+        let raw;
+        let ageMs;
+        try {
+            // stat BEFORE the read: a report that goes stale between the two calls
+            // is merely counted a millisecond young, while the reverse order would
+            // age every report by however long its read took.
+            ageMs = Math.max(0, nowMs - statSync(path).mtimeMs);
+            if (ageMs > VIEWER_SWEEP_MS) {
+                rmSync(path, { force: true });
+                continue;
+            }
+            if (ageMs > VIEWER_STALE_MS)
+                continue;
+            raw = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue; // vanished or unreadable under us: not a pane we can speak for
+        }
+        const report = parseViewerReport(raw);
+        if (report !== undefined)
+            live.push({ ...report, pid, ageMs });
+    }
+    return live.sort((a, b) => a.ageMs - b.ageMs || a.pid - b.pid);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.20.3",
+  "version": "0.23.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",
@@ -26,6 +26,8 @@
   "bin": {
     "mellos-mapping": "dist/server.mjs",
     "mellos-mapping-watch": "dist/watch.mjs",
+    "mellos-mapping-preview": "dist/preview.mjs",
+    "mellos-mapping-web": "dist/web.mjs",
     "mmap": "dist/mmap.mjs"
   },
   "exports": {
@@ -54,6 +56,10 @@
       "default": "./lib/render/render.js"
     },
     "./server": "./dist/server.mjs",
+    "./preview": {
+      "types": "./lib/preview/index.d.ts",
+      "default": "./lib/preview/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -63,29 +69,45 @@
     "dist",
     "lib",
     "README.zh-CN.md",
+    "docs/codex.md",
+    "docs/map-api.md",
     "scripts/codex-register.mjs",
+    "scripts/codex-cli.mjs",
     "scripts/install-mmap-command.mjs",
     "scripts/mmap.mjs",
     "scripts/open-pane.mjs",
-    "scripts/pane-core.mjs"
+    "scripts/pane-core.mjs",
+    "scripts/terminal-session.mjs",
+    "scripts/tmux-session.mjs",
+    "scripts/watcher-command.mjs"
   ],
   "engines": {
     "node": ">=18"
   },
   "scripts": {
     "test": "vitest run",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.scripts.json",
     "build": "node build.mjs && tsc -p tsconfig.lib.json",
+    "package:codex": "npm run build && node scripts/package-codex.mjs",
+    "package:release": "node scripts/package-release.mjs",
+    "check:release": "node scripts/check-release.mjs",
     "check:package": "node scripts/check-package-surface.mjs",
+    "check:codex": "node scripts/check-codex-package.mjs",
+    "check:reuse": "node scripts/check-reuse.mjs",
+    "benchmark:render": "node scripts/benchmark-render.mjs",
     "prepack": "npm run build",
-    "verify": "npm run typecheck && npm run test && npm run build && npm run check:package"
+    "verify": "npm run typecheck && npm run test && npm run build && npm run check:reuse && npm run check:package && npm run check:codex && npm run check:release"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@types/node": "^24.0.0",
+    "@types/ws": "8.18.1",
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/xterm": "6.0.0",
     "esbuild": "^0.25.0",
     "typescript": "^5.8.0",
-    "vitest": "^3.1.0",
+    "vitest": "^4.1.11",
+    "ws": "8.21.3",
     "zod": "^3.24.0"
   }
 }

package/scripts/codex-cli.mjs

@@ -0,0 +1,42 @@
+/** Codex process adapter. Arguments never pass through a command shell. */
+import { spawnSync } from 'node:child_process';
+import { realpathSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function isFile(path) {
+  try { return statSync(path).isFile(); } catch { return false; }
+}
+
+/** Resolve native Codex or the official npm shim's JS entry on Windows. */
+export function resolveCodexInvocation({
+  platform = process.platform, env = process.env, nodePath = process.execPath, fileExists = isFile,
+} = {}) {
+  if (platform !== 'win32') return { command: 'codex', args: [] };
+  const path = Object.entries(env).find(([key]) => key.toUpperCase() === 'PATH')?.[1] ?? '';
+  for (const raw of path.split(';')) {
+    const dir = raw.replace(/^"|"$/g, '');
+    if (!dir) continue;
+    const executable = join(dir, 'codex.exe');
+    if (fileExists(executable)) return { command: executable, args: [] };
+    const entry = join(dir, 'node_modules', '@openai', 'codex', 'bin', 'codex.js');
+    if (fileExists(entry) && (fileExists(join(dir, 'codex.cmd')) || fileExists(join(dir, 'codex.ps1')))) {
+      return { command: nodePath, args: [entry] };
+    }
+  }
+  throw new Error('codex CLI not found on PATH — install Codex first (native executable or official npm package).');
+}
+
+export function runCodex(args) {
+  const cli = resolveCodexInvocation();
+  // Keep diagnostics as bytes; JSON callers decode their own structured output.
+  return spawnSync(cli.command, [...cli.args, ...args], {
+    stdio: 'pipe', windowsHide: true, timeout: 30_000,
+  });
+}
+
+export function launchedAsEntry(moduleUrl) {
+  try {
+    return process.argv[1] !== undefined && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(moduleUrl));
+  } catch { return false; }
+}

package/scripts/codex-register.mjs

@@ -1,117 +1,50 @@
 #!/usr/bin/env node
+// @ts-check
 /**
- * Register the bundled MCP server with Codex CLI — run once after installing
- * or updating the plugin: `node <plugin root>/scripts/codex-register.mjs`.
- *
- * Why this script exists instead of a plugin-shipped .mcp.json: Codex spawns
- * plugin-bundled MCP servers inside the plugin cache and gives them no way to
- * learn the user's workspace (no ${PLUGIN_ROOT}-style expansion in args, cwd
- * locked to the plugin root when set — verified empirically against
- * codex-cli 0.147.0). The state file would land in the cache instead of the
- * project. A user-level `codex mcp add` entry inherits the session's working
- * 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.
+ * Register the shared runtime at user scope so it inherits each session's
+ * working directory. The skill bundle and the runtime are separate host
+ * adapters over the same core; no workspace path is baked into an install.
  */
-import { spawnSync } from 'node:child_process';
-import { realpathSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isFile, launchedAsEntry, runCodex } from './codex-cli.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.
- */
+/** @param {number | null} status */
 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.
+ * Validate before changing configuration. `mcp add` replaces its named entry
+ * in one operation; removing first creates an unnecessary failure window.
+ * Dependencies are supplied here so tests cannot change the real user config.
+ * @param {string} pluginRoot
+ * @param {{run?: import('./install-types.js').HostRunner, nodePath?: string, fileExists?: (path: string) => boolean}} [options]
  */
-function codex(args) {
-  if (process.platform !== 'win32') {
-    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(quoteForShell).join(' ');
-  return spawnSync(line, { shell: true, stdio: 'pipe', windowsHide: true });
-}
-
-function main() {
-  const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+export function registerServer(pluginRoot, { run = runCodex, nodePath = process.execPath, fileExists = isFile } = {}) {
   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 (!fileExists(serverPath)) throw new Error(`Bundled MCP server is missing: ${serverPath}. Build or reinstall the plugin first.`);
+  const result = run(['mcp', 'add', 'mellos-mapping', '--', nodePath, serverPath]);
+  if (result.error) throw new Error(`Codex registration could not run: ${result.error.message}`);
+  if (result.status !== 0) {
+    const detail = result.stderr?.toString().trim();
+    throw new Error(`${describeFailure(result.status)}${detail ? `\n${detail}` : ''}`);
   }
-  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).');
+  return { serverPath, nodePath };
 }
 
-/**
- * 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;
+if (launchedAsEntry(import.meta.url)) {
   try {
-    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
-  } catch {
-    return false;
+    const installed = registerServer(dirname(dirname(fileURLToPath(import.meta.url))));
+    console.log(`mellos-mapping MCP registered with Codex: ${installed.nodePath} ${installed.serverPath}`);
+    console.log('State files resolve to each session’s working directory (.mellos/map.json).');
+    console.log('Start a new Codex conversation to load the skills and eight mmap tools.');
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
   }
 }
-
-if (launchedAsEntry()) main();