mellos-mapping 0.23.0 → 0.25.0

package/dist/watch.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
+import { createRequire as __mellosCreateRequire } from 'node:module'; const require = __mellosCreateRequire(import.meta.url);
 
 // src/watch/watch.ts
-import { realpathSync as realpathSync2, statSync as statSync2 } from "node:fs";
+import { realpathSync as realpathSync3, statSync as statSync2 } from "node:fs";
 import { dirname as dirname9, join as join8 } from "node:path";
 
 // src/domain/types.ts
@@ -262,9 +262,8 @@ function resolveProjectDirectory(cwd, stopAt = [homedir(), tmpdir()]) {
 }
 
 // src/store/transaction.ts
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname as dirname2, join as join2 } from "node:path";
-import { randomUUID, createHash } from "node:crypto";
+import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, realpathSync as realpathSync2 } from "node:fs";
+import { basename, dirname as dirname2, join as join2 } from "node:path";
 
 // src/domain/context.ts
 function sourceError(raw) {
@@ -554,6 +553,30 @@ function parseMap(raw, path) {
   return textError ? err({ kind: "bad-shape", path, detail: textError }) : ok(map);
 }
 
+// src/store/native-lock.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+var loaded;
+function nativeLock() {
+  if (loaded) return loaded;
+  if (Number(process.versions.napi ?? 0) < 9) {
+    throw new Error("Project locks require Node-API 9 (Node 18.17+ or 20.3+).");
+  }
+  const candidates = [
+    new URL("./native-lock.cjs", import.meta.url),
+    new URL("../../dist/native-lock.cjs", import.meta.url)
+  ];
+  const entry = candidates.find((candidate) => existsSync2(candidate));
+  if (!entry) throw new Error("The installed package is missing dist/native-lock.cjs; reinstall the complete package.");
+  const backend = createRequire(import.meta.url)(fileURLToPath(entry));
+  if (typeof backend.tryLock !== "function" || typeof backend.unlock !== "function") {
+    throw new Error("The installed native lock backend is invalid.");
+  }
+  loaded = backend;
+  return backend;
+}
+
 // src/store/transaction.ts
 var LedgerError = class extends Error {
   constructor(code, message, details = {}) {
@@ -564,61 +587,78 @@ var LedgerError = class extends Error {
 };
 function storeDirectory(file) {
   const dir = dirname2(file);
-  return dir.endsWith("/pages") || dir.endsWith("\\pages") ? dirname2(dir) : dir;
-}
-function deadOwner(lock) {
+  if (basename(dir).toLowerCase() === "pages") return dirname2(dir);
+  let canonical = dir;
   try {
-    const owner = JSON.parse(readFileSync(join2(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;
+    canonical = realpathSync2.native(dir);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  return basename(canonical).toLowerCase() === "pages" ? dirname2(canonical) : canonical;
+}
+function checkLockPath(lock) {
+  const entry = lstatSync(lock, { throwIfNoEntry: false });
+  if (entry?.isDirectory()) {
+    throw new LedgerError(
+      "LOCK_MIGRATION_REQUIRED",
+      `Legacy directory lock at ${lock}. Stop all old MCP servers, viewers and watchers for this project, then move that directory aside for inspection and retry. Never remove the new regular lock file.`,
+      { path: lock }
+    );
+  }
+  if (entry && !entry.isFile()) {
+    throw new LedgerError("LOCK_UNAVAILABLE", `Project lock must be a regular file, not a symlink or special file: ${lock}`, { path: lock });
   }
 }
 function withStoreLock(file, action) {
+  let backend;
+  try {
+    backend = nativeLock();
+  } catch (error) {
+    throw new LedgerError("LOCK_UNAVAILABLE", `Cannot load the operating-system lock backend: ${error instanceof Error ? error.message : String(error)}`);
+  }
   const dir = storeDirectory(file);
   mkdirSync(dir, { recursive: true });
   const lock = join2(dir, ".write-lock");
-  const owner = join2(lock, "owner.json");
-  const token = randomUUID();
+  checkLockPath(lock);
+  let fd;
   try {
-    mkdirSync(lock);
+    fd = openSync(lock, "a+", 384);
   } catch (error) {
-    if (error.code !== "EEXIST") throw error;
-    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(join2(lock, ".reap"));
-    } catch {
-      throw new LedgerError("BUSY", "Another process is recovering the writer lock.");
-    }
-    if (!deadOwner(lock)) {
-      rmSync(join2(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.");
-    }
+    checkLockPath(lock);
+    throw new LedgerError("LOCK_UNAVAILABLE", `Cannot open project lock ${lock}: ${error instanceof Error ? error.message : String(error)}`, { path: lock });
   }
-  let initialized = false;
+  let acquired = false;
   try {
-    writeFileSync(owner, JSON.stringify({ pid: process.pid, token }), { flag: "wx" });
-    initialized = true;
+    checkLockPath(lock);
+    if (!fstatSync(fd).isFile()) throw new LedgerError("LOCK_UNAVAILABLE", `Project lock is not a regular file: ${lock}`);
+    try {
+      acquired = backend.tryLock(fd);
+    } catch (error) {
+      throw new LedgerError("LOCK_UNAVAILABLE", `Cannot acquire project lock ${lock}: ${error instanceof Error ? error.message : String(error)}`, { path: lock });
+    }
+    if (!acquired) throw new LedgerError("BUSY", `Another writer owns ${lock}; retry after it completes.`);
     return action();
   } finally {
     try {
-      if (!initialized || JSON.parse(readFileSync(owner, "utf8")).token === token) rmSync(lock, { recursive: true });
+      if (acquired) backend.unlock(fd);
     } catch {
+      warnLockCleanup(`Could not explicitly unlock ${lock}; closing its file handle.`);
+    } finally {
+      try {
+        closeSync(fd);
+      } catch {
+        warnLockCleanup(`Could not close the project lock handle for ${lock}; restart this process before retrying writes.`);
+      }
     }
   }
 }
+function warnLockCleanup(message) {
+  try {
+    process.stderr.write(`mellos-mapping: ${message}
+`);
+  } catch {
+  }
+}
 
 // src/semantics/vocabulary.ts
 var STATUS_GLYPHS = {
@@ -1748,7 +1788,7 @@ function paint(scene, opts) {
 }
 
 // src/store/atomic.ts
-import { mkdirSync as mkdirSync2, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { mkdirSync as mkdirSync2, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname as dirname3 } from "node:path";
 var RENAME_BACKOFF_STEP_MS = 10;
 var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EBUSY", "EACCES", "ENOENT"]);
@@ -1757,7 +1797,7 @@ function sleepSync(ms) {
 }
 function discardTemp(tmp) {
   try {
-    rmSync2(tmp, { force: true });
+    rmSync(tmp, { force: true });
   } catch {
   }
 }
@@ -1768,7 +1808,7 @@ function writeAtomic(path, contents, maxAttempts) {
   const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
   try {
     mkdirSync2(dirname3(path), { recursive: true });
-    writeFileSync2(tmp, contents, "utf8");
+    writeFileSync(tmp, contents, "utf8");
   } catch (e) {
     discardTemp(tmp);
     return err({ kind: "save-failed", path, detail: `writing the temp file failed: ${errnoOf(e)}` });
@@ -1791,8 +1831,8 @@ function writeAtomic(path, contents, maxAttempts) {
 }
 
 // src/store/pages.ts
-import { existsSync as existsSync2, readdirSync, rmSync as rmSync3 } from "node:fs";
-import { basename, dirname as dirname4, join as join3 } from "node:path";
+import { existsSync as existsSync3, readdirSync, rmSync as rmSync2 } from "node:fs";
+import { basename as basename2, dirname as dirname4, join as join3 } from "node:path";
 var STORE_DIR_NAME = ".mellos";
 var STATE_FILE_RELATIVE_PATH = join3(STORE_DIR_NAME, "map.json");
 var PAGES_DIR_NAME = "pages";
@@ -1801,12 +1841,12 @@ function pageFilePath(defaultFile, page) {
 }
 function pageIdOfFile(defaultFile, path) {
   if (path === defaultFile) return void 0;
-  const name = basename(path);
+  const name = basename2(path);
   return name.endsWith(".json") ? name.slice(0, -".json".length) : name;
 }
 function listPageFiles(defaultFile) {
   const out = [];
-  if (existsSync2(defaultFile)) out.push(defaultFile);
+  if (existsSync3(defaultFile)) out.push(defaultFile);
   let entries = [];
   try {
     entries = readdirSync(join3(dirname4(defaultFile), PAGES_DIR_NAME));
@@ -1819,7 +1859,7 @@ function listPageFiles(defaultFile) {
 }
 function deletePageFile(path) {
   try {
-    rmSync3(path, { force: true });
+    rmSync2(path, { force: true });
     return ok(void 0);
   } catch (e) {
     return err({ kind: "delete-failed", path, detail: errnoOf(e) });
@@ -1827,7 +1867,7 @@ function deletePageFile(path) {
 }
 
 // src/store/channels.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, rmSync as rmSync5 } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync2, rmSync as rmSync4 } from "node:fs";
 import { dirname as dirname6, join as join5 } from "node:path";
 
 // src/store/json-text.ts
@@ -1839,7 +1879,7 @@ function stripBom(text) {
 }
 
 // src/store/viewers.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync2, statSync, rmSync as rmSync4 } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync, statSync, rmSync as rmSync3 } from "node:fs";
 import { dirname as dirname5, join as join4 } from "node:path";
 var VIEWERS_DIR_NAME = "viewers";
 var VIEWER_FILE_VERSION = 1;
@@ -1857,7 +1897,7 @@ function publishViewer(defaultFile, pid, report) {
 }
 function retireViewer(defaultFile, pid) {
   try {
-    rmSync4(viewerFilePath(defaultFile, pid), { force: true });
+    rmSync3(viewerFilePath(defaultFile, pid), { force: true });
   } catch {
   }
 }
@@ -1874,15 +1914,15 @@ function paneChannelPath(defaultFile, channel, pid) {
 }
 function takeFocusRequest(defaultFile, pid) {
   const targeted = pid === void 0 ? void 0 : focusFilePath(defaultFile, pid);
-  const path = targeted !== void 0 && existsSync3(targeted) ? targeted : focusFilePath(defaultFile);
+  const path = targeted !== void 0 && existsSync4(targeted) ? targeted : focusFilePath(defaultFile);
   let raw;
   try {
-    raw = readFileSync3(path, "utf8");
+    raw = readFileSync2(path, "utf8");
   } catch {
     return void 0;
   }
   try {
-    rmSync5(path, { force: true });
+    rmSync4(path, { force: true });
   } catch {
   }
   let parsed2;
@@ -1904,10 +1944,10 @@ function quitFilePath(defaultFile, pid) {
 }
 function takeQuitRequest(defaultFile, pid) {
   const targeted = pid === void 0 ? void 0 : quitFilePath(defaultFile, pid);
-  const path = targeted !== void 0 && existsSync3(targeted) ? targeted : quitFilePath(defaultFile);
+  const path = targeted !== void 0 && existsSync4(targeted) ? targeted : quitFilePath(defaultFile);
   let raw;
   try {
-    raw = readFileSync3(path, "utf8");
+    raw = readFileSync2(path, "utf8");
   } catch {
     return false;
   }
@@ -1922,7 +1962,7 @@ function takeQuitRequest(defaultFile, pid) {
 }
 function sweepQuitRequest(defaultFile, pid) {
   try {
-    rmSync5(quitFilePath(defaultFile, pid), { force: true });
+    rmSync4(quitFilePath(defaultFile, pid), { force: true });
   } catch {
   }
 }
@@ -1935,7 +1975,7 @@ function configFilePath(defaultFile) {
 }
 
 // src/store/migration.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, renameSync as renameSync2 } from "node:fs";
+import { existsSync as existsSync5, renameSync as renameSync2 } from "node:fs";
 import { dirname as dirname8, join as join7 } from "node:path";
 var LEGACY_STATE_FILE_RELATIVE_PATH = join7(".claude", "mellos-mapping.json");
 var LEGACY_PAGES_DIR_NAME = "mellos-mapping.pages";
@@ -1945,22 +1985,24 @@ function migrateLegacyStore(defaultFile) {
   const legacyDefault = join7(projectRoot, LEGACY_STATE_FILE_RELATIVE_PATH);
   const legacyPages = join7(dirname8(legacyDefault), LEGACY_PAGES_DIR_NAME);
   const legacyConfig = join7(dirname8(legacyDefault), LEGACY_CONFIG_FILE_NAME);
-  const hasLegacy = existsSync4(legacyDefault) || existsSync4(legacyPages) || existsSync4(legacyConfig);
-  const hasCurrent = existsSync4(defaultFile) || existsSync4(join7(dirname8(defaultFile), PAGES_DIR_NAME)) || existsSync4(configFilePath(defaultFile));
-  if (!hasLegacy || hasCurrent) return false;
-  mkdirSync3(dirname8(defaultFile), { recursive: true });
-  if (existsSync4(legacyDefault)) renameSync2(legacyDefault, defaultFile);
-  if (existsSync4(legacyPages)) renameSync2(legacyPages, join7(dirname8(defaultFile), PAGES_DIR_NAME));
-  if (existsSync4(legacyConfig)) renameSync2(legacyConfig, configFilePath(defaultFile));
-  return true;
+  const hasLegacy = () => existsSync5(legacyDefault) || existsSync5(legacyPages) || existsSync5(legacyConfig);
+  const hasCurrent = () => existsSync5(defaultFile) || existsSync5(join7(dirname8(defaultFile), PAGES_DIR_NAME)) || existsSync5(configFilePath(defaultFile));
+  if (!hasLegacy() || hasCurrent()) return false;
+  return withStoreLock(defaultFile, () => {
+    if (!hasLegacy() || hasCurrent()) return false;
+    if (existsSync5(legacyDefault)) renameSync2(legacyDefault, defaultFile);
+    if (existsSync5(legacyPages)) renameSync2(legacyPages, join7(dirname8(defaultFile), PAGES_DIR_NAME));
+    if (existsSync5(legacyConfig)) renameSync2(legacyConfig, configFilePath(defaultFile));
+    return true;
+  });
 }
 
 // src/store/maps.ts
-import { readFileSync as readFileSync4 } from "node:fs";
+import { readFileSync as readFileSync3 } from "node:fs";
 function loadMapFile(path) {
   let text;
   try {
-    text = readFileSync4(path, "utf8");
+    text = readFileSync3(path, "utf8");
   } catch (e) {
     const code = e.code;
     if (code === "ENOENT") return err({ kind: "not-found", path });
@@ -2345,22 +2387,22 @@ function scan(state, input) {
       pages.push(held);
       continue;
     }
-    const loaded = input.load(file);
-    if (loaded.ok) {
+    const loaded2 = input.load(file);
+    if (loaded2.ok) {
       if (!first) changed.push(file);
       const fresh = !first && file !== previousActive;
       if (fresh) freshened.push(file);
-      pages.push({ file, state: { kind: "loaded", map: loaded.value, mtimeMs }, fresh });
+      pages.push({ file, state: { kind: "loaded", map: loaded2.value, mtimeMs }, fresh });
       continue;
     }
     pages.push({
       file,
       state: {
         kind: "faulted",
-        fault: loaded.error,
+        fault: loaded2.error,
         lastGood: mapOf(held),
         mtimeMs,
-        transient: isTransient(loaded.error)
+        transient: isTransient(loaded2.error)
       },
       fresh: held?.fresh ?? false
     });
@@ -2735,12 +2777,12 @@ function viewerReportOf(pane, defaultFile) {
   const shown = pane.activeFile ?? pane.pendingFocusFile ?? defaultFile;
   return { page: pageIdOfFile(defaultFile, shown), follow: pane.follow };
 }
-function runWatcher(cfg, io = nativeWatcherIO()) {
+function runWatcher(cfg, io2 = nativeWatcherIO()) {
   const renderScene = createWindowRenderer();
   if (migrateLegacyStore(cfg.file)) console.error("mellos-mapping: moved the legacy .claude map store to .mellos/ \u2014 commit the move.");
   sweepQuitRequest(cfg.file);
   sweepQuitRequest(cfg.file, process.pid);
-  const interactive = io.interactive;
+  const interactive = io2.interactive;
   const mouseActive = interactive && cfg.mouse;
   let lastFrame = "";
   let spinnerFrame = 0;
@@ -2749,8 +2791,8 @@ function runWatcher(cfg, io = nativeWatcherIO()) {
   const standbyNotice = "waiting for the first mmap_declare ...";
   let map;
   let notice = standbyNotice;
-  let lastCols = io.output.columns ?? 0;
-  let lastRows = io.output.rows ?? 0;
+  let lastCols = io2.output.columns ?? 0;
+  let lastRows = io2.output.rows ?? 0;
   let pane = initialPaneState(
     cfg.follow,
     cfg.page === void 0 ? void 0 : pageFilePath(cfg.file, cfg.page)
@@ -2777,8 +2819,8 @@ function runWatcher(cfg, io = nativeWatcherIO()) {
     }
     return false;
   };
-  const viewWidth = () => usableColumns(io.output.columns ?? FALLBACK_COLUMNS);
-  const viewHeight = () => Math.max(1, (io.output.rows ?? FALLBACK_ROWS) - (1 + panelContentRows) - 1 - tabRows());
+  const viewWidth = () => usableColumns(io2.output.columns ?? FALLBACK_COLUMNS);
+  const viewHeight = () => Math.max(1, (io2.output.rows ?? FALLBACK_ROWS) - (1 + panelContentRows) - 1 - tabRows());
   const dividerY = () => tabRows() + viewHeight() + 1;
   const pageTabsOf = (files) => files.map((f) => {
     const entry = entryOf(pane, f);
@@ -2833,20 +2875,20 @@ function runWatcher(cfg, io = nativeWatcherIO()) {
     return lastHits.find((h) => cx >= h.x && cx < h.x + h.w && cy >= h.y && cy < h.y + h.h)?.id;
   };
   const publishPresence = () => {
-    io.report?.(viewerReportOf(pane, cfg.file));
+    io2.report?.(viewerReportOf(pane, cfg.file));
     publishViewer(cfg.file, process.pid, {
       ...viewerReportOf(pane, cfg.file),
       ...cfg.owner === void 0 ? {} : { owner: cfg.owner }
     });
   };
-  if (interactive) io.input.setRawMode(true);
-  const terminal = openTerminalSession({ interactive, mouse: cfg.mouse, write: (text) => io.output.write(text) });
+  if (interactive) io2.input.setRawMode(true);
+  const terminal = openTerminalSession({ interactive, mouse: cfg.mouse, write: (text) => io2.output.write(text) });
   const frameOutput = interactive ? createFrameOutput({
-    write: (text) => io.output.write(text),
+    write: (text) => io2.output.write(text),
     onDrain: (ready) => {
-      io.output.once("drain", ready);
+      io2.output.once("drain", ready);
       return () => {
-        io.output.off("drain", ready);
+        io2.output.off("drain", ready);
       };
     }
   }) : void 0;
@@ -2877,9 +2919,9 @@ the map pane stopped: ${e instanceof Error ? e.stack ?? e.message : String(e)}
   const paint2 = () => {
     clearTimeout(paintTimer);
     paintTimer = void 0;
-    const cols = io.output.columns ?? FALLBACK_COLUMNS;
+    const cols = io2.output.columns ?? FALLBACK_COLUMNS;
     const viewW = viewWidth();
-    panelContentRows = clampPanelRows(panelContentRows, io.output.rows ?? FALLBACK_ROWS, tabRows());
+    panelContentRows = clampPanelRows(panelContentRows, io2.output.rows ?? FALLBACK_ROWS, tabRows());
     const viewH = viewHeight();
     const focus = view.hoverId ?? view.selectedId;
     let body;
@@ -2897,6 +2939,7 @@ the map pane stopped: ${e instanceof Error ? e.stack ?? e.message : String(e)}
         lastHits = [];
       } else {
         const windowed = rendered.value;
+        if (map.nodes.length > 0) io2.onMapRendered?.();
         const maxX = Math.max(0, windowed.contentWidth - viewW);
         const maxY = Math.max(0, windowed.contentHeight - viewH);
         if (view.offsetX > maxX || view.offsetY > maxY || view.offsetX < 0 || view.offsetY < 0) {
@@ -2990,7 +3033,7 @@ the map pane stopped: ${e instanceof Error ? e.stack ?? e.message : String(e)}
     } else {
       const frame = HOME + rows.map((row) => row + ERASE_LINE_END).join("\n");
       if (frame !== lastFrame) {
-        io.output.write(frame);
+        io2.output.write(frame);
         lastFrame = frame;
       }
     }
@@ -2999,16 +3042,16 @@ the map pane stopped: ${e instanceof Error ? e.stack ?? e.message : String(e)}
     paintTimer ??= setTimeout(paint2, 16);
   };
   const handleResize = () => {
-    lastCols = io.output.columns ?? lastCols;
-    lastRows = io.output.rows ?? lastRows;
+    lastCols = io2.output.columns ?? lastCols;
+    lastRows = io2.output.rows ?? lastRows;
     lastFrame = "";
     frameOutput?.invalidate();
-    io.output.write(CLEAR_ALL);
+    io2.output.write(CLEAR_ALL);
     paint2();
   };
   const tick = () => {
     if (takeQuitRequest(cfg.file, process.pid)) quit();
-    if ((io.output.columns ?? lastCols) !== lastCols || (io.output.rows ?? lastRows) !== lastRows) {
+    if ((io2.output.columns ?? lastCols) !== lastCols || (io2.output.rows ?? lastRows) !== lastRows) {
       handleResize();
     }
     const discovered = listPageFiles(cfg.file);
@@ -3077,9 +3120,9 @@ the map pane stopped: ${e instanceof Error ? e.stack ?? e.message : String(e)}
     tick();
   };
   if (interactive) {
-    io.input.resume();
-    io.input.setEncoding("utf8");
-    io.input.on("data", (chunk) => {
+    io2.input.resume();
+    io2.input.setEncoding("utf8");
+    io2.input.on("data", (chunk) => {
       const parsed2 = parseInput(pendingInput + chunk);
       pendingInput = parsed2.rest;
       let dirty = false;
@@ -3152,7 +3195,7 @@ the map pane stopped: ${e instanceof Error ? e.stack ?? e.message : String(e)}
             break;
           case "mouse-drag":
             if (view.dividerDrag) {
-              const next = panelRowsFromDividerY(event.y, io.output.rows ?? FALLBACK_ROWS, tabRows());
+              const next = panelRowsFromDividerY(event.y, io2.output.rows ?? FALLBACK_ROWS, tabRows());
               if (next !== panelContentRows) {
                 panelContentRows = next;
                 dirty = true;
@@ -3248,7 +3291,7 @@ the map pane stopped: ${e instanceof Error ? e.stack ?? e.message : String(e)}
         else paint2();
       }
     });
-    io.output.on("resize", handleResize);
+    io2.output.on("resize", handleResize);
   }
   tick();
   setInterval(tick, cfg.intervalMs);
@@ -3263,6 +3306,73 @@ the map pane stopped: ${e instanceof Error ? e.stack ?? e.message : String(e)}
   }
 }
 
+// src/watch/cli.ts
+import { homedir as homedir2 } from "node:os";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/support/star-reminder.ts
+import { existsSync as existsSync6, readFileSync as readFileSync4, realpathSync as realpathSync4 } from "node:fs";
+import { basename as basename3, dirname as dirname10, join as join9 } from "node:path";
+var STAR_URL = "https://github.com/GuangminJu/mellos-mapping";
+var DAY_MS = 864e5;
+function isNpmInstallation(entry) {
+  try {
+    const root = dirname10(dirname10(realpathSync4(entry)));
+    if (basename3(dirname10(root)).toLowerCase() !== "node_modules" || existsSync6(join9(root, ".git")) || existsSync6(join9(root, ".codex-plugin")) || existsSync6(join9(root, ".claude-plugin"))) return false;
+    const pkg = JSON.parse(readFileSync4(join9(root, "package.json"), "utf8"));
+    return pkg.name === "mellos-mapping" && pkg.bin?.mmap === "dist/mmap.mjs";
+  } catch {
+    return false;
+  }
+}
+function starReminderFile(userBase) {
+  return join9(userBase, ".mellos", "support", "star-reminder.json");
+}
+function enabledFlag(value) {
+  return !!value && value !== "0" && value.toLowerCase() !== "false";
+}
+function validState(value) {
+  if (!value || typeof value !== "object") return false;
+  const s = value;
+  return s.version === 1 && Number.isFinite(s.firstSeen) && s.firstSeen >= 0 && Number.isSafeInteger(s.lastDay) && s.lastDay >= Math.floor(s.firstSeen / DAY_MS) && Number.isSafeInteger(s.days) && s.days >= 1 && s.days <= 3 && typeof s.notified === "boolean";
+}
+function createStarReminder(options) {
+  const eligible = isNpmInstallation(options.entry) && !enabledFlag(options.env["CI"]) && !enabledFlag(options.env["MELLOS_MAPPING_NO_STAR"]);
+  const file = starReminderFile(options.userBase);
+  return {
+    visit() {
+      if (!eligible) return false;
+      try {
+        return withStoreLock(file, () => {
+          const now = (options.now ?? Date.now)();
+          if (!Number.isFinite(now) || now < 0) return false;
+          const day = Math.floor(now / DAY_MS);
+          let state;
+          try {
+            const saved2 = JSON.parse(readFileSync4(file, "utf8"));
+            if (!validState(saved2)) return false;
+            state = saved2;
+          } catch (error) {
+            if (error.code !== "ENOENT") return false;
+            state = { version: 1, firstSeen: now, lastDay: day, days: 1, notified: false };
+          }
+          if (state.notified || now < state.firstSeen || day < state.lastDay) return false;
+          if (day > state.lastDay) {
+            state.days = Math.min(3, state.days + 1);
+            state.lastDay = day;
+          }
+          const show = state.days >= 3 && now - state.firstSeen >= 7 * DAY_MS;
+          if (show) state.notified = true;
+          const saved = writeAtomic(file, JSON.stringify(state, null, 2) + "\n", 1);
+          return saved.ok && show;
+        });
+      } catch {
+        return false;
+      }
+    }
+  };
+}
+
 // src/watch/cli.ts
 var parsed = parseArgs(process.argv.slice(2), process.cwd());
 if (!parsed.ok) {
@@ -3270,4 +3380,17 @@ if (!parsed.ok) {
 ${USAGE}`);
   process.exit(1);
 }
-runWatcher(parsed.value);
+var viewed = false;
+var io = nativeWatcherIO();
+var reminder = createStarReminder({ entry: fileURLToPath2(import.meta.url), userBase: homedir2(), env: process.env });
+runWatcher(parsed.value, { ...io, onMapRendered: () => {
+  viewed = true;
+} });
+process.on("exit", (code) => {
+  if (code === 0 && viewed && io.interactive && process.stderr.isTTY && process.env["TERM"] !== "dumb" && reminder.visit()) {
+    process.stderr.write(`
+If Mellos Mapping has been useful, a GitHub Star is welcome: ${STAR_URL}
+This optional reminder will not appear again.
+`);
+  }
+});