mellos-mapping 0.18.0 → 0.19.0

package/README.md

@@ -265,6 +265,21 @@ When a hidden sub-map changes in the background, the footer says so.
 | `mmap_update` | Record progress: `planned → in-progress → done` (+evidence), `regressed`, group/lane membership, node kind |
 | `mmap_remove` | Revise: drop edges, nodes, groups, lanes, empty bands |
 | `mmap_view` | Render the current map as text inline (optional `zoom`) |
+| `mmap_setup` | Get/set the project's mapping policy — when maps open |
+
+### Setup: choose when maps open
+
+Each project chooses how eager mapping is, once, via `/mmap setup` (or the
+first time the assistant declares a map — the reply nudges it to ask you):
+
+- `always` — map every structured task: workflows, designs, architecture,
+  technical dependencies.
+- `complex` — map only medium or complex tasks (the default until configured).
+- `on-request` — map only when you explicitly ask.
+
+The choice is stored in `.claude/mellos-mapping.config.json` and guides the
+assistant; it never blocks the tools, and asking for a map explicitly always
+works under any policy.
 
 Structural invariants enforced by the tools: layers form a total order by
 rank; every node lives in exactly one layer; edges point **strictly

package/README.zh-CN.md

@@ -242,6 +242,19 @@ npx -y -p mellos-mapping mellos-mapping-watch
 | `mmap_update` | 记录进度：`planned → in-progress → done`（附证据）、`regressed`、分组/泳道归属、节点 kind |
 | `mmap_remove` | 修订：删除边、节点、分组、泳道、空层 |
 | `mmap_view` | 把当前地图渲染成文本，直接在对话里看（可选 `zoom` 参数） |
+| `mmap_setup` | 查/设本项目的建图策略——什么时候开地图 |
+
+### Setup：选择什么时候建图
+
+每个项目选一次建图的积极程度，用 `/mmap setup`（或 AI 第一次 declare 时，
+工具响应会引导它来问你）：
+
+- `always` —— 任何有结构的任务都建图：流程、设计、架构、技术依赖。
+- `complex` —— 只在中等或复杂任务时建图（未配置时的默认行为）。
+- `on-request` —— 只在你明确要求时建图。
+
+选择保存在 `.claude/mellos-mapping.config.json`，用于引导 AI；它从不阻止
+工具本身——无论什么策略，明确要求建图永远有效。
 
 工具强制的结构不变量：层按 rank 构成全序；每个节点恰好属于一层；边**严格
 向下**——因此图从构造上就是无环的；节点不能依赖同层兄弟（如果 A 需要

package/dist/server.mjs

@@ -22141,6 +22141,57 @@ var PAGES_DIR_NAME = "mellos-mapping.pages";
 function pageFilePath(defaultFile, page) {
   return page === void 0 ? defaultFile : join(dirname(defaultFile), PAGES_DIR_NAME, `${page}.json`);
 }
+var CONFIG_FILE_NAME = "mellos-mapping.config.json";
+var CONFIG_FILE_VERSION = 1;
+function configFilePath(defaultFile) {
+  return join(dirname(defaultFile), 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(defaultFile) {
+  const path = configFilePath(defaultFile);
+  let text2;
+  try {
+    text2 = readFileSync(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return ok(void 0);
+    throw e;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text2);
+  } 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 saveMappingPolicy(defaultFile, policy) {
+  const path = configFilePath(defaultFile);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = path + ".tmp";
+  writeFileSync(tmp, JSON.stringify({ version: CONFIG_FILE_VERSION, policy }, null, 2) + "\n", "utf8");
+  renameSync(tmp, path);
+}
 function describeStoreError(e) {
   switch (e.kind) {
     case "not-found":
@@ -22515,7 +22566,7 @@ function summarize(map) {
 
 // src/server/server.ts
 var SERVER_NAME = "mellos-mapping";
-var SERVER_VERSION = "0.18.0";
+var SERVER_VERSION = "0.19.0";
 var ID = external_exports.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/, "lowercase letters, digits and dashes, 1-64 chars").describe("stable kebab-case identifier");
 var PAGE = ID.optional().describe(
   "page (parallel map) this call targets; omit for the default page. One effort = one page: start a NEW effort on its own page named after the effort, so concurrent sessions never write over each other and the pane can switch between pages."
@@ -22552,6 +22603,13 @@ function buildServer(stateFile) {
     saveMapFile(file, applied.value);
     return text(summarize(applied.value) + (page !== void 0 ? ` [page: ${page}]` : ""));
   };
+  const setupNudge = () => {
+    const policy = loadMappingPolicy(stateFile);
+    if (!policy.ok) return `
+note: ${describeStoreError(policy.error)} \u2014 fix it or rerun setup (mmap_setup).`;
+    if (policy.value !== void 0) return "";
+    return "\nnote: mapping policy not set for this project. Ask the user when maps should open \u2014 " + MAPPING_POLICIES.map((p) => `${p} (${describeMappingPolicy(p)})`).join("; ") + " \u2014 then record the answer with mmap_setup.";
+  };
   server.registerTool(
     "mmap_declare",
     {
@@ -22599,7 +22657,12 @@ function buildServer(stateFile) {
         edges: external_exports.array(EDGE.extend({ label: external_exports.string().max(80).optional().describe("what flows along the edge") })).optional()
       }
     },
-    (input) => mutate(input.page, (map) => applyDeclare(map, input))
+    (input) => {
+      const result = mutate(input.page, (map) => applyDeclare(map, input));
+      if (result.isError === true) return result;
+      const nudge = setupNudge();
+      return nudge === "" ? result : text((result.content[0]?.text ?? "") + nudge);
+    }
   );
   server.registerTool(
     "mmap_update",
@@ -22641,6 +22704,31 @@ function buildServer(stateFile) {
     },
     (input) => mutate(input.page, (map) => applyRemove(map, input))
   );
+  server.registerTool(
+    "mmap_setup",
+    {
+      title: "Configure when maps open",
+      description: `Get or set this project's mapping policy \u2014 WHEN the assistant opens a Mellos map. Call with no arguments to read it. If it reports "not set", ask the USER to choose (never pick for them): always = ` + describeMappingPolicy("always") + "; complex = " + describeMappingPolicy("complex") + "; on-request = " + describeMappingPolicy("on-request") + ". Then call again with their choice to persist it. The policy guides you; it never blocks the tools, and an explicit user request for a map always wins.",
+      inputSchema: {
+        policy: external_exports.enum(MAPPING_POLICIES).optional().describe("the user's choice to persist; omit to read the current policy")
+      }
+    },
+    (input) => {
+      if (input.policy !== void 0) {
+        const policy = input.policy;
+        saveMappingPolicy(stateFile, policy);
+        return text(`mapping policy set: ${policy} \u2014 ${describeMappingPolicy(policy)} [${configFilePath(stateFile)}]`);
+      }
+      const loaded = loadMappingPolicy(stateFile);
+      if (!loaded.ok) return text(describeStoreError(loaded.error), true);
+      if (loaded.value === void 0) {
+        return text(
+          "mapping policy not set. Ask the user to choose one of: " + MAPPING_POLICIES.map((p) => `${p} (${describeMappingPolicy(p)})`).join("; ") + " \u2014 then call mmap_setup with their choice. Until then act as complex."
+        );
+      }
+      return text(`mapping policy: ${loaded.value} \u2014 ${describeMappingPolicy(loaded.value)}`);
+    }
+  );
   server.registerTool(
     "mmap_view",
     {

package/dist/watch.mjs

@@ -3,7 +3,7 @@ import { createRequire } from 'node:module'; const require = createRequire(impor
 
 // src/watch/watch.ts
 import { realpathSync, statSync } from "node:fs";
-import { join as join2 } from "node:path";
+import { dirname as dirname2, join as join2 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // src/domain/types.ts
@@ -1535,19 +1535,8 @@ function nodePanel(map, focusId, unicode, width, pinned, rows = PANEL_CONTENT_RO
   }
   return lines.slice(0, rows);
 }
-var SPLASH_FONT = {
-  M: ["#   #", "## ##", "# # #", "#   #", "#   #"],
-  E: ["####", "#", "###", "#", "####"],
-  L: ["#", "#", "#", "#", "####"],
-  O: [" ###", "#   #", "#   #", "#   #", " ###"],
-  S: [" ####", "#", " ###", "    #", "####"],
-  A: [" ###", "#   #", "#####", "#   #", "#   #"],
-  P: ["####", "#   #", "####", "#", "#"],
-  I: ["###", " #", " #", " #", "###"],
-  N: ["#   #", "##  #", "# # #", "#  ##", "#   #"],
-  G: [" ####", "#", "#  ##", "#   #", " ###"]
-};
-var SPLASH_ROWS = 5;
+var WATER_ROWS = 7;
+var WATER_COLS_MAX = 60;
 var SPLASH_SHADES = {
   unicode: ["\u2591", "\u2591", "\u2592", "\u2592", "\u2593", "\u2593", "\u2588", "\u2588"],
   ascii: [".", ".", ":", ":", "=", "=", "#", "#"]
@@ -1557,23 +1546,24 @@ var SPINNER_FRAMES = {
   unicode: ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"],
   ascii: ["|", "/", "-", "\\"]
 };
-function wordArt(word) {
-  const glyphs = [...word.toUpperCase()].map((ch) => SPLASH_FONT[ch]).filter((g) => g !== void 0);
-  const widths = glyphs.map((g) => Math.max(...g.map((r) => r.length)));
-  const rows = [];
-  for (let r = 0; r < SPLASH_ROWS; r++) {
-    rows.push(glyphs.map((g, i) => (g[r] ?? "").padEnd(widths[i], " ")).join(" "));
-  }
-  return rows;
-}
-function splashArt() {
-  const words = [wordArt("MELLOS"), wordArt("MAPPING")];
-  const width = Math.max(...words.flat().map((r) => r.length));
-  const centered = words.map((rows) => {
-    const own = Math.max(...rows.map((r) => r.length));
-    return rows.map((r) => " ".repeat(Math.floor((width - own) / 2)) + r);
-  });
-  return [...centered[0], "", ...centered[1]];
+function elapsedLabel(ms) {
+  const s = Math.max(0, Math.floor(ms / 1e3));
+  const m = Math.floor(s / 60);
+  const h = Math.floor(m / 60);
+  const two = (n) => String(n).padStart(2, "0");
+  return h > 0 ? `${h}:${two(m % 60)}:${two(s % 60)}` : `${m}:${two(s % 60)}`;
+}
+function waitingInfo(s, width) {
+  const w = Math.max(1, width);
+  const clock = s.elapsedMs !== void 0 ? ` \xB7 waiting ${elapsedLabel(s.elapsedMs)}` : "";
+  const lines = [
+    `watching  ${s.defaultFile}`,
+    `      and ${join2(s.pagesDir, "*.json")}`,
+    `polling every ${s.intervalMs} ms${clock}`
+  ];
+  for (const b of s.broken) lines.push(`! ${b}`);
+  lines.push("the map appears at the first mmap_declare");
+  return lines.map((l) => fitWidth(l, w));
 }
 var WAVE_INTERVAL = 18;
 var WAVE_LIFETIME = 64;
@@ -1624,39 +1614,41 @@ function waveAt(ripples, x, y) {
 function waveLevel(value) {
   return Math.max(-WAVE_LEVELS, Math.min(WAVE_LEVELS, Math.round(value * WAVE_GAIN)));
 }
-function splashFrame(notice, frame, width, height, unicode, color) {
-  const art = splashArt();
-  const artWidth = Math.max(...art.map((r) => r.length));
-  if (width < artWidth + 2 || height < art.length + 2) return void 0;
+function splashFrame(notice, info, frame, width, height, unicode, color) {
+  const fieldW = Math.min(width - 4, WATER_COLS_MAX);
+  if (fieldW < 24 || height < WATER_ROWS + info.length + 3) return void 0;
   const mode = unicode ? "unicode" : "ascii";
   const shades = SPLASH_SHADES[mode];
-  const solid = shades[shades.length - 1];
-  const indent = " ".repeat(Math.floor((width - artWidth) / 2));
-  const ripples = liveRipples(frame, artWidth, art.length);
-  const inkOf = (x, y) => {
-    const level = waveLevel(waveAt(ripples, x, y));
-    return color ? `38;5;${WAVE_RAMP[WAVE_LEVELS + level]}` : shades[Math.abs(level)];
-  };
-  const paintRow = (row, y) => {
-    const cells = [...row].map((ch, x) => ch === "#" ? inkOf(x, y) : void 0);
+  const indent = " ".repeat(Math.max(0, Math.floor((width - fieldW) / 2)));
+  const ripples = liveRipples(frame, fieldW, WATER_ROWS);
+  const paintRow = (y) => {
+    const levels = Array.from({ length: fieldW }, (_, x) => waveLevel(waveAt(ripples, x, y)));
     let out = "";
-    for (let i = 0; i < cells.length; ) {
-      const cell = cells[i];
+    for (let i = 0; i < fieldW; ) {
+      const level = levels[i];
       let j = i;
-      while (j < cells.length && cells[j] === cell) j++;
-      if (cell === void 0) out += " ".repeat(j - i);
-      else out += color ? `\x1B[${cell}m${solid.repeat(j - i)}${RESET}` : cell.repeat(j - i);
+      while (j < fieldW && levels[j] === level) j++;
+      if (level === 0) out += " ".repeat(j - i);
+      else {
+        const ink = shades[Math.abs(level)].repeat(j - i);
+        out += color ? `\x1B[38;5;${WAVE_RAMP[WAVE_LEVELS + level]}m${ink}${RESET}` : ink;
+      }
       i = j;
     }
     return out;
   };
+  const dim = (s) => color ? `\x1B[90m${s}${RESET}` : s;
   const spinner = SPINNER_FRAMES[mode];
   const status = fitWidth(`${spinner[frame % spinner.length]} ${notice}`, Math.max(1, width - 2));
   const statusIndent = " ".repeat(Math.max(0, Math.floor((width - displayWidth(status)) / 2)));
+  const infoWidth = Math.max(0, ...info.map((l) => displayWidth(l)));
+  const infoIndent = " ".repeat(Math.max(0, Math.floor((width - infoWidth) / 2)));
   const block = [
-    ...art.map((row, y) => row.trim() === "" ? "" : indent + paintRow(row, y)),
+    ...Array.from({ length: WATER_ROWS }, (_, y) => indent + paintRow(y)),
     "",
-    statusIndent + (color ? `\x1B[90m${status}${RESET}` : status)
+    statusIndent + dim(status),
+    "",
+    ...info.map((l) => infoIndent + dim(l))
   ];
   return [...Array.from({ length: Math.max(0, Math.floor((height - block.length) / 2)) }, () => ""), ...block];
 }
@@ -1685,8 +1677,10 @@ function main() {
   let lastFrame = "";
   let spinnerFrame = 0;
   let splashTick = 0;
+  const startedAt = Date.now();
+  const standbyNotice = "waiting for the first mmap_declare ...";
   let map;
-  let notice = `waiting for ${cfg.file} ...`;
+  let notice = standbyNotice;
   let lastCols = process.stdout.columns ?? 0;
   let lastRows = process.stdout.rows ?? 0;
   let pageFiles = [cfg.file];
@@ -1755,7 +1749,7 @@ function main() {
     const entry = pageData.get(file);
     if (entry !== void 0 && entry.fresh) pageData.set(file, { ...entry, fresh: false });
     map = entry?.map;
-    notice = map === void 0 ? `waiting for ${file} ...` : "";
+    notice = map !== void 0 ? "" : entry?.error ?? (file === cfg.file ? standbyNotice : `waiting for ${file} ...`);
     const top = topFiles();
     const tabIndex = top.indexOf(file);
     if (tabIndex >= 0) tabScroll = tabScrollFor(pageTabsOf(top), viewWidth(), cfg.unicode, tabScroll, tabIndex);
@@ -1813,7 +1807,17 @@ function main() {
       lastContent = { w: windowed.contentWidth, h: windowed.contentHeight };
       if (offsetX !== 0 || offsetY !== 0) panned = `  (+${offsetX},+${offsetY})`;
     } else {
-      body = (interactive ? splashFrame(notice, splashTick, viewW, viewH, cfg.unicode, cfg.color) : void 0) ?? [fitWidth(notice, viewW)];
+      const info = waitingInfo(
+        {
+          defaultFile: cfg.file,
+          pagesDir: join2(dirname2(cfg.file), PAGES_DIR_NAME),
+          intervalMs: cfg.intervalMs,
+          elapsedMs: interactive ? Date.now() - startedAt : void 0,
+          broken: [...pageData.values()].flatMap((e) => e.map === void 0 && e.error !== void 0 ? [e.error] : [])
+        },
+        Math.max(1, viewW - 2)
+      );
+      body = (interactive ? splashFrame(notice, info, splashTick, viewW, viewH, cfg.unicode, cfg.color) : void 0) ?? [fitWidth(notice, viewW), "", ...info.map((l) => fitWidth(` ${l}`, viewW))];
     }
     if (notice !== "" && map !== void 0) {
       body[body.length - 1] = fitWidth(`  ${notice}`, viewW);
@@ -1917,8 +1921,15 @@ function main() {
           flash = { text: `${cfg.unicode ? "\u229E " : ""}${title} updated`, until: Date.now() + 4e3 };
         }
       } else if (loaded.error.kind === "malformed-json") {
+        pageData.set(file, {
+          map: entry?.map,
+          mtimeMs: entry?.mtimeMs ?? -1,
+          fresh: entry?.fresh ?? false,
+          error: describeStoreError(loaded.error)
+        });
+        if (file === activeFile && entry?.map === void 0) notice = describeStoreError(loaded.error);
       } else {
-        pageData.set(file, { map: entry?.map, mtimeMs, fresh: entry?.fresh ?? false });
+        pageData.set(file, { map: entry?.map, mtimeMs, fresh: entry?.fresh ?? false, error: describeStoreError(loaded.error) });
         if (file === activeFile) notice = describeStoreError(loaded.error);
       }
     }
@@ -2143,6 +2154,7 @@ export {
   clampPanelRows,
   diveOrigin,
   dividerRow,
+  elapsedLabel,
   fitWidth,
   launchedAsEntry,
   liveRipples,
@@ -2153,14 +2165,13 @@ export {
   pageTabRow,
   panelRowsFromDividerY,
   parseArgs,
-  splashArt,
   splashFrame,
   tabScrollFor,
   topLevelFiles,
   usableColumns,
+  waitingInfo,
   waveAt,
   waveHash,
   waveLevel,
-  wordArt,
   wrapWidth
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.18.0",
+  "version": "0.19.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",