mellos-mapping 0.22.1 → 0.24.0

package/dist/web.mjs

@@ -2271,7 +2271,7 @@ var require_websocket = __commonJS({
     var http = __require("http");
     var net = __require("net");
     var tls = __require("tls");
-    var { randomBytes: randomBytes2, createHash: createHash3 } = __require("crypto");
+    var { randomBytes: randomBytes2, createHash: createHash4 } = __require("crypto");
     var { Duplex, Readable } = __require("stream");
     var { URL: URL2 } = __require("url");
     var PerMessageDeflate2 = require_permessage_deflate();
@@ -2939,7 +2939,7 @@ var require_websocket = __commonJS({
           abortHandshake(websocket, socket, "Invalid Upgrade header");
           return;
         }
-        const digest = createHash3("sha1").update(key + GUID).digest("base64");
+        const digest = createHash4("sha1").update(key + GUID).digest("base64");
         if (res.headers["sec-websocket-accept"] !== digest) {
           abortHandshake(websocket, socket, "Invalid Sec-WebSocket-Accept header");
           return;
@@ -3308,7 +3308,7 @@ var require_websocket_server = __commonJS({
     var EventEmitter = __require("events");
     var http = __require("http");
     var { Duplex } = __require("stream");
-    var { createHash: createHash3 } = __require("crypto");
+    var { createHash: createHash4 } = __require("crypto");
     var extension2 = require_extension();
     var PerMessageDeflate2 = require_permessage_deflate();
     var subprotocol2 = require_subprotocol();
@@ -3615,7 +3615,7 @@ var require_websocket_server = __commonJS({
           );
         }
         if (this._state > RUNNING) return abortHandshake(socket, 503);
-        const digest = createHash3("sha1").update(key + GUID).digest("base64");
+        const digest = createHash4("sha1").update(key + GUID).digest("base64");
         const headers = [
           "HTTP/1.1 101 Switching Protocols",
           "Upgrade: websocket",
@@ -3703,9 +3703,10 @@ var require_websocket_server = __commonJS({
 });
 
 // src/web/cli.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4, realpathSync as realpathSync2, rmSync as rmSync3, statSync as statSync2 } from "node:fs";
-import { dirname as dirname7, join as join5, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync6, realpathSync as realpathSync3, rmSync as rmSync4, statSync as statSync2 } from "node:fs";
+import { dirname as dirname9, join as join7, resolve as resolve2 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { homedir } from "node:os";
 
 // src/domain/types.ts
 var ok = (value) => ({ ok: true, value });
@@ -3924,12 +3925,37 @@ function updateNode(map, input) {
   return ok({ ...map, nodes: map.nodes.map((n) => n.id === input.id ? updated : n) });
 }
 
+// src/domain/context.ts
+function sourceError(raw) {
+  if (!Array.isArray(raw) || raw.length > 100) return "sources must be an array of at most 100 file references";
+  for (const item of raw) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return "source must be an object";
+    const s = item;
+    if (Object.keys(s).some((k) => k !== "path" && k !== "sha256")) return "unknown source field";
+    if (typeof s.path !== "string" || s.path.length > 1024 || !s.path || /[\u0000-\u001f\u007f-\u009f\\:]/.test(s.path) || s.path.startsWith("/") || s.path.split("/").some((p) => !p || p === "." || p === "..")) return "source path must be relative to the project, with forward slashes and no traversal";
+    if (s.sha256 !== void 0 && (typeof s.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(s.sha256))) return "source sha256 must be a lowercase SHA256 hash";
+  }
+  return void 0;
+}
+function contextError(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return "context must be an object";
+  for (const [key, value] of Object.entries(raw)) {
+    if (key !== "summary" && key !== "next") return "unknown context field";
+    if (typeof value !== "string" || value.length > 2e3 || /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/.test(value)) return "context fields must be text of at most 2000 characters";
+  }
+  return void 0;
+}
+
 // src/domain/text.ts
 var NO_CONTROLS = /^[^\u0000-\u001f\u007f-\u009f]*$/;
 var NO_CONTROLS_TEXT = "one line of text; control characters (ESC, newline, tab) are not allowed";
 var NO_CONTROLS_BUT_BREAKS = /^[^\u0000-\u0008\u000b-\u001f\u007f-\u009f]*$/;
 var NO_CONTROLS_BUT_BREAKS_TEXT = "text with optional newlines (\\n) and tabs; other control characters (ESC, BEL, CR) are not allowed";
 function mapTextError(map) {
+  if (map.context !== void 0) {
+    const error2 = contextError(map.context);
+    if (error2) return error2;
+  }
   const check = (field, value, multiline = false) => value === void 0 || (multiline ? NO_CONTROLS_BUT_BREAKS : NO_CONTROLS).test(value) ? void 0 : `${field}: ${multiline ? NO_CONTROLS_BUT_BREAKS_TEXT : NO_CONTROLS_TEXT}`;
   let error = check("title", map.title);
   if (error) return error;
@@ -3944,6 +3970,10 @@ function mapTextError(map) {
     }
   }
   for (const [i, node] of map.nodes.entries()) {
+    if (node.sources !== void 0) {
+      const error2 = sourceError(node.sources);
+      if (error2) return `nodes[${i}]: ${error2}`;
+    }
     for (const name of ["label", "evidence", "detail"]) {
       error = check(`nodes[${i}].${name}`, node[name], name !== "label");
       if (error) return error;
@@ -4006,8 +4036,8 @@ function optionalString(rec, key, where, path) {
 }
 function parseMap(raw, path) {
   if (!isRecord(raw)) return err({ kind: "bad-shape", path, detail: "root is not an object" });
-  if (raw["version"] !== STATE_FILE_VERSION) {
-    return err({ kind: "bad-shape", path, detail: `version is ${String(raw["version"])}, expected ${STATE_FILE_VERSION}` });
+  if (raw["version"] !== STATE_FILE_VERSION && raw["version"] !== 2) {
+    return err({ kind: "bad-shape", path, detail: `version is ${String(raw["version"])}, expected ${STATE_FILE_VERSION} or 2` });
   }
   const layers = arrayField(raw, "layers", path, "required");
   if (!layers.ok) return layers;
@@ -4020,6 +4050,11 @@ function parseMap(raw, path) {
   const groups = arrayField(raw, "groups", path, "optional");
   if (!groups.ok) return groups;
   let map = EMPTY_MAP;
+  if (raw["context"] !== void 0) {
+    const error = contextError(raw["context"]);
+    if (error) return err({ kind: "bad-shape", path, detail: error });
+    map = { ...map, context: raw["context"] };
+  }
   const title = optionalString(raw, "title", "map", path);
   if (!title.ok) return title;
   if (title.value !== void 0) map = setTitle(map, title.value);
@@ -4148,6 +4183,11 @@ function parseMap(raw, path) {
       if (!updated.ok) return err({ kind: "invariant-violation", path, violation: updated.error });
       map = updated.value;
     }
+    if (rawNode["sources"] !== void 0) {
+      const error = sourceError(rawNode["sources"]);
+      if (error) return err({ kind: "bad-shape", path, detail: `${where}: ${error}` });
+      map = { ...map, nodes: map.nodes.map((n) => n.id === id.value ? { ...n, sources: rawNode["sources"] } : n) };
+    }
   }
   for (const [i, rawEdge] of edges.value.entries()) {
     const where = `edges[${i}]`;
@@ -4282,15 +4322,84 @@ function loadMapFile(path) {
   return parseMap(raw, path);
 }
 
+// src/store/transaction.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname4, join as join3 } from "node:path";
+import { randomUUID, createHash } from "node:crypto";
+var LedgerError = class extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+};
+function storeDirectory(file) {
+  const dir = dirname4(file);
+  return dir.endsWith("/pages") || dir.endsWith("\\pages") ? dirname4(dir) : dir;
+}
+function deadOwner(lock) {
+  try {
+    const owner = JSON.parse(readFileSync2(join3(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;
+  }
+}
+function withStoreLock(file, action) {
+  const dir = storeDirectory(file);
+  mkdirSync2(dir, { recursive: true });
+  const lock = join3(dir, ".write-lock");
+  const owner = join3(lock, "owner.json");
+  const token = randomUUID();
+  try {
+    mkdirSync2(lock);
+  } 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 {
+      mkdirSync2(join3(lock, ".reap"));
+    } catch {
+      throw new LedgerError("BUSY", "Another process is recovering the writer lock.");
+    }
+    if (!deadOwner(lock)) {
+      rmSync3(join3(lock, ".reap"), { recursive: true, force: true });
+      throw new LedgerError("BUSY", "Writer ownership changed.");
+    }
+    rmSync3(lock, { recursive: true });
+    try {
+      mkdirSync2(lock);
+    } catch {
+      throw new LedgerError("BUSY", "Another writer acquired the recovered lock.");
+    }
+  }
+  let initialized = false;
+  try {
+    writeFileSync2(owner, JSON.stringify({ pid: process.pid, token }), { flag: "wx" });
+    initialized = true;
+    return action();
+  } finally {
+    try {
+      if (!initialized || JSON.parse(readFileSync2(owner, "utf8")).token === token) rmSync3(lock, { recursive: true });
+    } catch {
+    }
+  }
+}
+
 // src/web/launcher.ts
 import { spawn } from "node:child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-import { dirname as dirname5, join as join3 } from "node:path";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
+import { dirname as dirname6, join as join4 } from "node:path";
 
 // src/web/source.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import { statSync } from "node:fs";
-import { basename as basename2, dirname as dirname4 } from "node:path";
+import { basename as basename2, dirname as dirname5 } from "node:path";
 function readWebSnapshot(defaultFile) {
   const pages = listPageFiles(defaultFile).map((file) => {
     const id = pageIdOfFile(defaultFile, file) ?? "";
@@ -4305,15 +4414,15 @@ function readWebSnapshot(defaultFile) {
     }
   });
   if (pages.length === 0) pages.push({ id: "", title: "\u7B49\u5F85\u7B2C\u4E00\u5F20\u5730\u56FE", modified: 0, map: EMPTY_MAP });
-  const value = { project: basename2(dirname4(dirname4(defaultFile))), pages };
-  return { revision: createHash("sha256").update(JSON.stringify(value)).digest("hex"), value };
+  const value = { project: basename2(dirname5(dirname5(defaultFile))), pages };
+  return { revision: createHash2("sha256").update(JSON.stringify(value)).digest("hex"), value };
 }
 
 // src/web/launcher.ts
-var webRuntimeFile = (defaultFile) => join3(dirname5(defaultFile), "web", "server.json");
+var webRuntimeFile = (defaultFile) => join4(dirname6(defaultFile), "web", "server.json");
 async function runningWebUrl(defaultFile) {
   try {
-    const info = JSON.parse(readFileSync2(webRuntimeFile(defaultFile), "utf8"));
+    const info = JSON.parse(readFileSync3(webRuntimeFile(defaultFile), "utf8"));
     if (!Number.isInteger(info.port) || info.port < 1 || info.port > 65535 || !/^[a-f0-9]{48}$/.test(info.token)) return void 0;
     const url = `http://127.0.0.1:${info.port}/${info.token}/`;
     const response = await fetch(`${url}api/health`, { signal: AbortSignal.timeout(700) });
@@ -4325,14 +4434,14 @@ async function runningWebUrl(defaultFile) {
 async function openWebPreview(defaultFile, entry, page, terminal = false) {
   if (page !== void 0 && (!ID_RULE.test(page) || !readWebSnapshot(defaultFile).value.pages.some((p) => p.id === page))) throw new Error(`No map page named "${page}".`);
   let url = await runningWebUrl(defaultFile);
-  if (url && terminal) {
+  if (url) {
     const health = await fetch(`${url}api/health`, { signal: AbortSignal.timeout(2e3) });
     const info = await health.json();
-    if (!info.surfaces?.includes("web-terminal")) {
+    if (!info.formats?.includes(2) || terminal && !info.surfaces?.includes("web-terminal")) {
       await fetch(`${url}api/stop`, { method: "POST", signal: AbortSignal.timeout(2e3) });
       const deadline = Date.now() + 3e3;
       while (await runningWebUrl(defaultFile)) {
-        if (Date.now() > deadline) throw new Error("Old web viewer is still stopping. Retry opening the terminal.");
+        if (Date.now() > deadline) throw new Error("Old web viewer is still stopping. Retry opening the map.");
         await new Promise((resolve3) => setTimeout(resolve3, 100));
       }
       url = void 0;
@@ -4365,9 +4474,9 @@ import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 
 // src/preview/publisher.ts
-import { createHash as createHash2 } from "node:crypto";
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, readdirSync as readdirSync2, realpathSync, rmdirSync } from "node:fs";
-import { dirname as dirname6, join as join4, resolve } from "node:path";
+import { createHash as createHash3 } from "node:crypto";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync4, readdirSync as readdirSync2, realpathSync, rmdirSync } from "node:fs";
+import { dirname as dirname7, join as join5, resolve } from "node:path";
 
 // src/semantics/vocabulary.ts
 var STATUS_GLYPHS = {
@@ -5084,15 +5193,15 @@ var PREVIEW_DIR_NAME = "previews";
 var ENABLED = ".enabled";
 var PUBLISH_LOCK = ".publish-lock";
 function previewDirectory(defaultFile) {
-  return join4(dirname6(defaultFile), PREVIEW_DIR_NAME);
+  return join5(dirname7(defaultFile), PREVIEW_DIR_NAME);
 }
 function previewFile(defaultFile, page) {
   if (page !== void 0 && !ID_RULE.test(page)) throw new Error("Invalid preview page id.");
-  return join4(previewDirectory(defaultFile), documentName(page));
+  return join5(previewDirectory(defaultFile), documentName(page));
 }
 function save(path, contents) {
   try {
-    if (readFileSync3(path, "utf8") === contents) return;
+    if (readFileSync4(path, "utf8") === contents) return;
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
@@ -5100,19 +5209,19 @@ function save(path, contents) {
   if (!result.ok) throw new Error(describeStoreError(result.error));
 }
 function ownedDirectory(path) {
-  mkdirSync2(path, { recursive: true });
-  const expected = join4(realpathSync(dirname6(path)), path.slice(dirname6(path).length + 1));
+  mkdirSync3(path, { recursive: true });
+  const expected = join5(realpathSync(dirname7(path)), path.slice(dirname7(path).length + 1));
   const actual = realpathSync(path);
   if (process.platform === "win32" ? actual.toLowerCase() !== expected.toLowerCase() : actual !== expected) {
     throw new Error(`Preview directory redirects outside its parent: ${path}`);
   }
 }
 function acquireLock(directory) {
-  const path = join4(directory, PUBLISH_LOCK);
+  const path = join5(directory, PUBLISH_LOCK);
   const deadline = Date.now() + 2e3;
   while (true) {
     try {
-      mkdirSync2(path);
+      mkdirSync3(path);
       return () => rmdirSync(path);
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
@@ -5123,7 +5232,7 @@ function acquireLock(directory) {
 }
 function createPreviewPublisher(defaultFile) {
   const directory = previewDirectory(defaultFile);
-  const enabledFile = join4(directory, ENABLED);
+  const enabledFile = join5(directory, ENABLED);
   const enabled = () => existsSync3(enabledFile);
   const refresh = (page) => {
     try {
@@ -5141,24 +5250,24 @@ function createPreviewPublisher(defaultFile) {
         }
         if (page !== void 0 && !pages.some((p) => p.page === page)) return err(`No map page named "${page}".`);
         if (page === void 0 && !pages.some((p) => p.page === void 0)) pages.unshift({ page: void 0, map: EMPTY_MAP });
-        const images = join4(directory, "images");
+        const images = join5(directory, "images");
         ownedDirectory(images);
         const present = /* @__PURE__ */ new Set();
         for (const item of pages) {
           const svg = renderMapSvg(item.map);
-          const digest = createHash2("sha256").update(svg).digest("hex");
+          const digest = createHash3("sha256").update(svg).digest("hex");
           const image = `images/${digest}.svg`;
-          save(join4(images, `${digest}.svg`), svg);
+          save(join5(images, `${digest}.svg`), svg);
           const filename = documentName(item.page);
-          save(join4(directory, filename), renderMapMarkdown(item.map, image, pages));
+          save(join5(directory, filename), renderMapMarkdown(item.map, image, pages));
           present.add(filename);
         }
         for (const filename of readdirSync2(directory)) {
           if (/^(map|page-[a-z0-9][a-z0-9-]{0,63})\.md$/.test(filename) && !present.has(filename)) {
-            save(join4(directory, filename), "# \u5730\u56FE\u5DF2\u5220\u9664\n\n\u6B64\u9875\u9762\u5DF2\u4E0D\u5728\u9879\u76EE\u5730\u56FE\u4E2D\u3002\n\n[\u8FD4\u56DE\u5730\u56FE\u76EE\u5F55](index.md)\n");
+            save(join5(directory, filename), "# \u5730\u56FE\u5DF2\u5220\u9664\n\n\u6B64\u9875\u9762\u5DF2\u4E0D\u5728\u9879\u76EE\u5730\u56FE\u4E2D\u3002\n\n[\u8FD4\u56DE\u5730\u56FE\u76EE\u5F55](index.md)\n");
           }
         }
-        const index = join4(directory, "index.md");
+        const index = join5(directory, "index.md");
         save(index, renderPreviewIndex(pages));
         return ok({ path: resolve(path), index: resolve(index), pages: pages.length });
       } finally {
@@ -5327,12 +5436,117 @@ function attachTerminalService(server, options) {
   };
 }
 
+// src/support/open-star.ts
+import { spawn as spawn3 } from "node:child_process";
+import { win32 } from "node:path";
+
+// src/support/star-reminder.ts
+import { existsSync as existsSync4, readFileSync as readFileSync5, realpathSync as realpathSync2 } from "node:fs";
+import { basename as basename3, dirname as dirname8, join as join6 } from "node:path";
+var STAR_URL = "https://github.com/GuangminJu/mellos-mapping";
+var DAY_MS = 864e5;
+function isNpmInstallation(entry) {
+  try {
+    const root = dirname8(dirname8(realpathSync2(entry)));
+    if (basename3(dirname8(root)).toLowerCase() !== "node_modules" || existsSync4(join6(root, ".git")) || existsSync4(join6(root, ".codex-plugin")) || existsSync4(join6(root, ".claude-plugin"))) return false;
+    const pkg = JSON.parse(readFileSync5(join6(root, "package.json"), "utf8"));
+    return pkg.name === "mellos-mapping" && pkg.bin?.mmap === "dist/mmap.mjs";
+  } catch {
+    return false;
+  }
+}
+function starReminderFile(userBase) {
+  return join6(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(readFileSync5(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/support/open-star.ts
+function starBrowserCommand(platform, windowsRoot = "C:\\Windows") {
+  if (platform === "win32") return {
+    file: win32.join(windowsRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+    args: [
+      "-NoLogo",
+      "-NoProfile",
+      "-NonInteractive",
+      "-WindowStyle",
+      "Hidden",
+      "-Command",
+      `$ErrorActionPreference = 'Stop'; Start-Process -FilePath '${STAR_URL}'`
+    ]
+  };
+  if (platform === "darwin") return { file: "/usr/bin/open", args: [STAR_URL] };
+  if (platform === "linux") return { file: "xdg-open", args: [STAR_URL] };
+  throw new Error("No supported desktop browser launcher");
+}
+function openStarInDefaultBrowser() {
+  const command = starBrowserCommand(process.platform, process.env["SystemRoot"]);
+  return new Promise((resolve3, reject) => {
+    const child = spawn3(command.file, command.args, { windowsHide: true, stdio: "ignore" });
+    let finished = false;
+    const finish = (error) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(deadline);
+      child.unref();
+      if (error) reject(error);
+      else resolve3();
+    };
+    const deadline = setTimeout(() => finish(), 5e3);
+    child.once("error", (error) => finish(error));
+    child.once("exit", (code) => finish(code === 0 ? void 0 : new Error("Default browser launch failed")));
+  });
+}
+
 // src/web/service.ts
 async function startWebService(defaultFile, assets, options = {}) {
   const token = options.token ?? randomBytes(24).toString("hex");
   if (!/^[a-f0-9]{48}$/.test(token)) throw new Error("Invalid web token");
   const prefix = `/${token}/`;
   let origin = "", lastRequest = Date.now(), closed = false;
+  let openingStar = false;
   const send = (res, code, body, type = "application/json; charset=utf-8") => {
     res.writeHead(code, {
       "Content-Type": type,
@@ -5381,7 +5595,37 @@ async function startWebService(defaultFile, assets, options = {}) {
         }
       }
       if (req.method === "GET" && route === "api/health") {
-        send(res, 200, JSON.stringify({ file: defaultFile, pid: process.pid, surfaces: terminalService ? ["web", "web-terminal"] : ["web"] }));
+        send(res, 200, JSON.stringify({ file: defaultFile, pid: process.pid, formats: [1, 2], surfaces: terminalService ? ["web", "web-terminal"] : ["web"] }));
+        return;
+      }
+      if (req.method === "POST" && route === "api/star-reminder/open") {
+        if (req.headers.origin !== origin) {
+          send(res, 403, '{"error":"Origin refused"}');
+          return;
+        }
+        if (req.url !== `${prefix}api/star-reminder/open` || req.headers["transfer-encoding"] || Number(req.headers["content-length"] ?? 0) !== 0) {
+          send(res, 400, '{"error":"No parameters accepted"}');
+          return;
+        }
+        if (openingStar) {
+          send(res, 409, '{"error":"Browser is already opening"}');
+          return;
+        }
+        openingStar = true;
+        void Promise.resolve().then(options.openStar ?? openStarInDefaultBrowser).then(() => {
+          send(res, 200, '{"opened":true}');
+        }, () => {
+          send(res, 503, '{"error":"\u65E0\u6CD5\u6253\u5F00\u9ED8\u8BA4\u6D4F\u89C8\u5668"}');
+        }).finally(() => {
+          openingStar = false;
+        });
+        return;
+      }
+      if (req.method === "POST" && route === "api/star-reminder/visit") {
+        const requested = new URL(req.url, origin).searchParams.get("page");
+        const id = !requested || requested === "_default" ? "" : requested;
+        const hasMap = options.starReminder && readWebSnapshot(defaultFile).value.pages.some((page) => page.id === id && !page.error && (page.map?.nodes.length ?? 0) > 0);
+        send(res, 200, JSON.stringify({ show: !!hasMap && options.starReminder.visit() }));
         return;
       }
       if (req.method === "GET" && route === "api/state") {
@@ -5396,23 +5640,26 @@ async function startWebService(defaultFile, assets, options = {}) {
         return;
       }
       if (req.method === "DELETE" && route.startsWith("api/pages/")) {
-        const id = route.slice("api/pages/".length);
-        if (id !== "_default" && !ID_RULE.test(id)) {
-          send(res, 400, '{"error":"Invalid page"}');
-          return;
-        }
-        if (req.headers["if-match"] !== `"${readWebSnapshot(defaultFile).revision}"`) {
-          send(res, 409, '{"error":"\u5730\u56FE\u5DF2\u66F4\u65B0\uFF0C\u8BF7\u91CD\u65B0\u786E\u8BA4\u5220\u9664\u3002"}');
-          return;
-        }
-        const result = deletePageFile(pageFilePath(defaultFile, id === "_default" ? void 0 : id));
-        if (!result.ok) {
-          send(res, 500, JSON.stringify({ error: describeStoreError(result.error) }));
+        withStoreLock(defaultFile, () => {
+          const id = route.slice("api/pages/".length);
+          if (id !== "_default" && !ID_RULE.test(id)) {
+            send(res, 400, '{"error":"Invalid page"}');
+            return;
+          }
+          if (req.headers["if-match"] !== `"${readWebSnapshot(defaultFile).revision}"`) {
+            send(res, 409, '{"error":"\u5730\u56FE\u5DF2\u66F4\u65B0\uFF0C\u8BF7\u91CD\u65B0\u786E\u8BA4\u5220\u9664\u3002"}');
+            return;
+          }
+          const result = deletePageFile(pageFilePath(defaultFile, id === "_default" ? void 0 : id));
+          if (!result.ok) {
+            send(res, 500, JSON.stringify({ error: describeStoreError(result.error) }));
+            return;
+          }
+          const previews = createPreviewPublisher(defaultFile);
+          const refreshed = previews.enabled() ? previews.refresh() : void 0;
+          send(res, 200, JSON.stringify({ deleted: true, ...refreshed && !refreshed.ok ? { warning: `\u5730\u56FE\u5DF2\u5220\u9664\uFF0CMarkdown \u9884\u89C8\u5F85\u91CD\u65B0\u751F\u6210\uFF1A${refreshed.error}` } : {} }));
           return;
-        }
-        const previews = createPreviewPublisher(defaultFile);
-        const refreshed = previews.enabled() ? previews.refresh() : void 0;
-        send(res, 200, JSON.stringify({ deleted: true, ...refreshed && !refreshed.ok ? { warning: `\u5730\u56FE\u5DF2\u5220\u9664\uFF0CMarkdown \u9884\u89C8\u5F85\u91CD\u65B0\u751F\u6210\uFF1A${refreshed.error}` } : {} }));
+        });
         return;
       }
       if (req.method === "POST" && route === "api/stop") {
@@ -5422,7 +5669,7 @@ async function startWebService(defaultFile, assets, options = {}) {
       }
       send(res, 404, '{"error":"Not found"}');
     } catch (error) {
-      send(res, 500, JSON.stringify({ error: String(error) }));
+      send(res, error instanceof LedgerError && error.code === "BUSY" ? 409 : 500, JSON.stringify({ error: String(error) }));
     }
   });
   const terminalService = assets.terminal && options.terminalWorker ? attachTerminalService(server, {
@@ -5471,19 +5718,19 @@ async function runWeb(args) {
   if (args[0] === "--serve" && args.length === 2) {
     const file2 = resolve2(args[1]);
     if (await runningWebUrl(file2)) return;
-    const directory = dirname7(webRuntimeFile(file2));
-    mkdirSync3(directory, { recursive: true });
-    if (realpathSync2(directory).toLowerCase() !== join5(realpathSync2(dirname7(directory)), "web").toLowerCase()) throw new Error("Redirected web runtime directory");
-    const assets = join5(dirname7(entry), "web");
+    const directory = dirname9(webRuntimeFile(file2));
+    mkdirSync4(directory, { recursive: true });
+    if (realpathSync3(directory).toLowerCase() !== join7(realpathSync3(dirname9(directory)), "web").toLowerCase()) throw new Error("Redirected web runtime directory");
+    const assets = join7(dirname9(entry), "web");
     let service;
     service = await startWebService(file2, {
-      html: readFileSync4(join5(assets, "index.html"), "utf8"),
-      javascript: readFileSync4(join5(assets, "app.js"), "utf8"),
-      css: readFileSync4(join5(assets, "app.css"), "utf8"),
-      terminal: { html: readFileSync4(join5(assets, "terminal.html"), "utf8"), javascript: readFileSync4(join5(assets, "terminal.js"), "utf8"), css: readFileSync4(join5(assets, "terminal.css"), "utf8"), xtermCss: readFileSync4(join5(assets, "xterm.css"), "utf8") }
-    }, { terminalWorker: join5(dirname7(entry), "terminal-worker.mjs"), onClose: () => {
+      html: readFileSync6(join7(assets, "index.html"), "utf8"),
+      javascript: readFileSync6(join7(assets, "app.js"), "utf8"),
+      css: readFileSync6(join7(assets, "app.css"), "utf8"),
+      terminal: { html: readFileSync6(join7(assets, "terminal.html"), "utf8"), javascript: readFileSync6(join7(assets, "terminal.js"), "utf8"), css: readFileSync6(join7(assets, "terminal.css"), "utf8"), xtermCss: readFileSync6(join7(assets, "xterm.css"), "utf8") }
+    }, { starReminder: createStarReminder({ entry, userBase: homedir(), env: process.env }), terminalWorker: join7(dirname9(entry), "terminal-worker.mjs"), onClose: () => {
       try {
-        if (JSON.parse(readFileSync4(webRuntimeFile(file2), "utf8")).token === service.token) rmSync3(webRuntimeFile(file2));
+        if (JSON.parse(readFileSync6(webRuntimeFile(file2), "utf8")).token === service.token) rmSync4(webRuntimeFile(file2));
       } catch {
       }
     } });
@@ -5514,8 +5761,8 @@ async function runWeb(args) {
     else throw new Error(usage);
   }
   const project = resolve2(args[0]);
-  if (!existsSync4(project) || !statSync2(project).isDirectory()) throw new Error(`Project directory does not exist: ${project}`);
-  const file = join5(project, STATE_FILE_RELATIVE_PATH);
+  if (!existsSync5(project) || !statSync2(project).isDirectory()) throw new Error(`Project directory does not exist: ${project}`);
+  const file = join7(project, STATE_FILE_RELATIVE_PATH);
   if (stop) {
     const url = await runningWebUrl(file);
     if (url) await fetch(`${url}api/stop`, { method: "POST", signal: AbortSignal.timeout(2e3) });
@@ -5524,7 +5771,7 @@ async function runWeb(args) {
   }
   console.log(JSON.stringify({ surface: terminal ? "web-terminal" : "web", url: await openWebPreview(file, entry, page, terminal), visibility: "unconfirmed" }));
 }
-if (process.argv[1] && existsSync4(process.argv[1]) && import.meta.url === pathToFileURL(realpathSync2(process.argv[1])).href) {
+if (process.argv[1] && existsSync5(process.argv[1]) && import.meta.url === pathToFileURL(realpathSync3(process.argv[1])).href) {
   runWeb(process.argv.slice(2)).catch((error) => {
     console.error(String(error));
     process.exitCode = 1;

package/docs/codex.md

@@ -12,7 +12,7 @@ From the `chatgpt-app` branch run `node install.mjs`; from `main` run
 
 The installer checks file hashes and a real MCP handshake, copies the runtime to
 `~/.mellos/installations/chatgpt-app/`, registers the `mellos-mapping-codex`
-marketplace, installs the skill, and registers the six MCP tools at user scope.
+marketplace, installs the skill, and registers the eight MCP tools at user scope.
 The runtime uses an absolute Node executable and leaves its working directory
 unset so each conversation writes to its own project. The clone can be deleted
 or moved after installation. Other plugins, maps and mapping policies are preserved.
@@ -41,6 +41,12 @@ publish the package into OpenAI's public plugin directory.
 
 ## Automatic web terminal
 
+For saved-map discovery, structured CRUD, checkpoints and concurrent updates,
+see [the persistent-map API guide](map-api.md). Start by reading existing pages;
+a new conversation does not require a new map. Restart older MCP/native watchers
+before writing maps with format-2 context or source references. Reopening a Web
+surface replaces services without format-2 support and returns a new URL.
+
 Call `mmap_open {surface: "web-terminal", page: "<slug>"}` and pass the returned
 `hostOpen` object to `open_in_codex`. It uses `placement: "right"` and a browser
 target in the current conversation. The local service starts mmap when the