mellos-mapping 0.26.2 → 0.27.0

package/dist/server.mjs

@@ -24650,7 +24650,7 @@ function launcherViewerPid(run) {
 
 // src/server/server.ts
 var SERVER_NAME = "mellos-mapping";
-var SERVER_VERSION = "0.26.2";
+var SERVER_VERSION = "0.27.0";
 function text(s, isError = false) {
   return { content: [{ type: "text", text: s }], ...isError ? { isError: true } : {} };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.26.2",
+  "version": "0.27.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",
@@ -70,9 +70,22 @@
       "./dist/omp-extension.mjs"
     ]
   },
+  "pi": {
+    "extensions": [
+      "./dist/pi-extension.mjs"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./commands"
+    ]
+  },
   "files": [
     "dist",
     "lib",
+    "skills",
+    "commands",
     "README.zh-CN.md",
     "docs/codex.md",
     "docs/map-api.md",

package/skills/mellos-mapping/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: mellos-mapping
+description: >-
+  Maintain a live layered dependency map (Mellos map) while doing bottom-up
+  development. Use when starting any non-trivial implementation or
+  architecture task — multiple modules, layers, or more than roughly an hour
+  of work. Resume existing maps first; declare missing design, then light nodes up
+  bottom-to-top as they are built and verified. Also use when the user asks
+  for a mellos map, /mmap, a dependency map, or wants to see development
+  progress as a picture. The user's mmap_setup policy decides how eager
+  mapping is — always / complex tasks only / on-request.
+---
+
+# Mellos Mapping — the map discipline
+
+Eight MCP tools (`mmap_declare`, `mmap_update`, `mmap_remove`, `mmap_view`,
+`mmap_setup`, `mmap_open`, `mmap_read`, `mmap_batch`)
+maintain a **Mellos map**: a layered dependency map of the system under
+construction, persisted in `.mellos/map.json` (default page) plus
+`.mellos/pages/<slug>.json` (named pages) and rendered live in
+a terminal split pane, a desktop Markdown file panel, or an interactive local web viewer beside the conversation. To learn whether a map already
+exists — and under which page slugs — call `mmap_view`: every response ends
+with a `pages:` line naming the pages this project has and which one you are
+looking at. Never probe the default file to decide: it is absent whenever all
+work lives on named pages.
+
+With current servers, prefer mmap_read {resource: "pages"}: it returns page
+summaries, saved context and revisions. A new conversation or compaction is not
+a new effort. Resume the matching page, read relevant nodes by ID/filter and
+request detail/evidence only when needed. Use the IDs returned by mmap_read,
+not display labels. Declare only missing structure. Keep context.summary and
+context.next current so another conversation can continue without rebuilding.
+Pass expectedRevision on writes; reread on CONFLICT. mmap_batch applies mixed
+changes atomically to one page. mmap_read changes checks linked source hashes;
+record sources[].sha256 only after verification. Older servers can fall back
+to mmap_view discovery and the saved JSON for precise IDs.
+
+The map is a **ledger, not a judge**: the tools only refuse structural
+corruption; *when* to declare, start, or complete nodes is YOUR discipline,
+spelled out here. Report honestly — an unflattering map is doing its job.
+
+## When to open a map
+
+The USER chooses how eager mapping is — once, for themselves, not once per
+project. Where the host runs a session adapter, the answer is already in this
+session's context, stated before the conversation begins, so there is nothing to
+probe: Claude Code runs the plugin's `SessionStart` hook, and omp (Oh My Pi) and
+pi load the same paragraph through the plugin's host adapters
+(`dist/omp-extension.mjs` and `dist/pi-extension.mjs`, declared in
+`package.json#omp.extensions` and `package.json#pi.extensions`, read from the
+same store). In hosts without one (Codex CLI, a bare MCP client) call
+`mmap_setup` with no arguments before the first map decision of the session; the
+reply names both scopes and which one governs.
+
+- `always` — map every structured task: workflows, designs, architecture,
+  technical dependencies. Small effort, small map — but a map.
+- `complex` — map only medium or complex tasks: several interacting modules,
+  a new subsystem, layered refactoring — roughly an hour of work or more.
+  Skip trivial edits; a map of one node is noise. When unsure, ask.
+- `on-request` — open a map only when the user explicitly asks.
+
+Under `always` and `complex`, the recorded policy is STANDING CONSENT: on a
+task it covers, declare the ghost design and open the pane yourself, without
+asking first. Re-asking for permission the user has already given is the
+failure mode this policy exists to remove.
+
+If the policy is not set anywhere, ask the USER to choose — present the three
+options, never pick for them — then persist the answer with
+`mmap_setup {policy, scope: "user"}`. That is asked ONCE EVER: the choice is
+saved in the user's own `.mellos/config.json` and applies to every project.
+A project that genuinely needs to differ takes
+`mmap_setup {policy, scope: "project"}`, which overrides the user choice
+there; `/mmap setup` reruns the question for either scope. Until they answer,
+act as `complex`. Two things always outrank the policy: an explicit user
+request for a map wins under any policy, and a map that is already open keeps
+getting honest updates whatever the policy says.
+
+Caught mid-implementation without a map on work that deserves one? Stop and
+declare it with honest statuses (written-but-unverified is `in-progress`, not
+`done`). If the mmap tools are missing from the session, explain that mapping
+is unavailable and continue the user's implementation. In Codex, look for
+tools by their `mmap_*` suffix: a host may add a server namespace. Installing
+or repairing the plugin includes running
+`node <plugin root>/scripts/codex-register.mjs`, then starting a new
+conversation. Existing installation authorization covers this registration;
+ordinary implementation work alone does not authorize changing host config.
+The plugin root is two directories above this skill's directory. See
+`<plugin root>/docs/codex.md` for Codex packaging and installation details.
+
+## Automatic desktop terminal in a browser
+
+In ChatGPT desktop Codex mode, prefer `mmap_open {surface: "web-terminal", page}`
+when no other surface was chosen. Pass its `hostOpen` object to `open_in_codex`
+in the current conversation: right placement, browser target, returned URL.
+The page starts the existing mmap terminal automatically, with independent font
+size. No manual paste or Computer Use is needed. An older schema can use
+`node "<plugin root>/dist/web.mjs" "<project>" --terminal --page <slug>`.
+Respect manually pinned pages and report queued opening honestly. Native Claude
+Code terminal placement remains the default for terminal hosts.
+
+## Desktop document panel
+
+When the current host exposes a file side panel (for example Codex desktop's
+`open_in_codex`) and the user requests a document or no browser panel is available, use the Markdown
+surface. This replaces the terminal-placement instructions in step 2 below.
+
+1. Call `mmap_open {surface: "markdown", page: "<effort-slug>"}`. This generates
+   local Markdown with a colored SVG map and enables automatic preview updates
+   after successful map mutations in this project. It starts no terminal or web
+   server. Keep the JSON maps as the source; generated documents are not inputs.
+2. Pass the returned absolute `markdown:` path to the host's file-opening tool,
+   in the current conversation's right panel. With `open_in_codex`, use
+   `placement: "right"` and `target: {type: "file", path: "<returned path>"}`.
+   Do not set another conversation id unless the user asked for that placement.
+3. A generated file is not evidence that the user sees it. Report `queued`
+   opening as queued, and do not claim a live viewer or automatic UI refresh.
+   If the preview stays stale, regenerate with `mmap_open` and reopen the same
+   file. Avoid reopening after every write when the viewer already refreshes.
+4. `preview: STALE` means the map mutation succeeded but export failed. Fix
+   the export problem and regenerate; do not repeat the map mutation. A terminal
+   `pane:` report does not describe the desktop file panel.
+
+If this conversation still has the previous MCP schema after a local upgrade,
+use `node "<plugin root>/dist/preview.mjs" "<project directory>" --page <slug>`
+to generate the same files. Until a new conversation loads the updated server,
+rerun this command after map writes. Use the actual installed runtime path from
+`docs/codex.md` when the skill cache differs from the runtime install.
+
+The document contains a static vector image, module details, evidence and
+links to existing child pages. Image nodes do not support dragging, hover
+details, animated spinners or double-click navigation. Desktop rendering and
+refresh behavior belong to the host, not the plugin.
+
+## Optional interactive web panel
+
+Keep the user's chosen surface. Markdown/SVG remains available with its existing
+workflow; adding the web viewer never disables or replaces it. When the user
+asks for a web map or live interaction, call `mmap_open {surface: "web", page:
+"<effort-slug>"}`. Pass the returned `web:` URL to the host's browser-opening
+tool. In Codex use `open_in_codex` with `placement: "right"` and
+`target: {type: "browser", url: "<returned URL>"}` in the current conversation.
+Report queued opening honestly; a running local service does not prove visibility.
+
+The viewer reads the same project maps and refreshes automatically, including
+writes from older MCP clients. It supports zoom/pan, hover and pinned details,
+dependency highlighting, search/status filters, page selection, child-map
+navigation, groups, lanes, light/dark themes and confirmed page deletion.
+Manual page selection disables auto-follow; do not override a pinned page.
+Web page deletion also refreshes enabled Markdown previews.
+
+If this conversation has an older schema, run
+`node "<plugin root>/dist/web.mjs" "<project directory>" --page <slug>` and open
+the JSON response's `url`. It reuses a local service for that project; no public
+hosting or dependency download is required. Close an unused service with the
+same command plus `--stop` instead of `--page <slug>`. It also exits after five
+minutes without browser requests. Reopen with the tool/CLI after that, or after
+a plugin update. A `web: configured` report describes a runtime record, not a
+confirmed open desktop panel. See `docs/codex.md` for transport and lifecycle details.
+
+## The working loop
+
+1. **Resume first, then fill gaps.** Read existing pages and the matching effort's
+   records. For a new effort, declare its intended design with `mmap_declare`: `title`,
+   layer bands (rank 0 = most primitive, at the bottom), every planned node,
+   and the edges. Everything starts `planned` — the user can veto the ghost
+   design before any code exists.
+2. **Put the map on screen — that is YOUR job, not the user's.** Use the
+   desktop document flow above when applicable. For terminal hosts, at the first
+   map decision in a session, ensure the requested placement with `mmap_open`
+   even if a project viewer is already reported. Use no page for this initial
+   placement check so an existing pane pinned by the user keeps its view;
+   subsequent opens name the effort's page as usual. A project-wide viewer
+   report alone does not prove this session has its right split. Every
+   declare, update, remove and view answers with a `pane:` line telling you
+   who is actually looking. Read it and act on it:
+   - `pane: CLOSED` — nobody is. Call `mmap_open {page: "<slug>"}` at once,
+     without asking first: a recorded mapping policy IS the user's standing
+     consent to see the map. Confirm it is live only after the tool succeeds.
+     If automatic opening already failed, relay the reason and copyable command
+     once; retry only after the environment changes or the user asks.
+   - `pane: open on this page` — they are watching this land. Carry on.
+   - `pane: open on <other>, auto-follow on` — the pane follows the page
+     last written, so your next write brings the audience along by itself.
+   - `pane: open on <other>, auto-follow OFF` — the user pinned that page by
+     hand. Your changes are real and NOT on their screen: say so, and
+     retarget with `mmap_open {page}` only if they want it moved. A pane
+     with follow off is a deliberate choice — don't fight it.
+   Default open means a right split beside THIS conversation. A live viewer in
+   another window is not proof of that placement. If opening reports that the
+   source tab is inactive or Windows refused focus, relay it and ask the user
+   to activate this conversation's terminal tab before retrying. Do not retry
+   with `window: true` unless the user chose a separate window.
+   Always pass the page your effort lives on. Without it a fresh pane opens
+   on whichever page was written last, which after a gap is rarely the one
+   under discussion — and declaring on a named page makes YOU responsible
+   for the audience, rather than telling the user which tab to click.
+   `mmap_open {window: true}` puts the map in its own window instead of
+   splitting the conversation's, for users who want it separate. It never
+   CLOSES a pane: that is the user's (the `q` key, or `mmap` in any terminal
+   of the project, which toggles) — so a pane that vanishes is them, not a
+   fault.
+   On Linux/macOS, the same tool automatically opens tmux, using the inherited
+   session/pane or the single attached session when `TMUX` is missing. Multiple
+   attached sessions require `MELLOS_MAPPING_TMUX_TARGET`; custom sockets use
+   `MELLOS_MAPPING_TMUX_SOCKET` in the MCP server environment. `window: true`
+   requests a new tmux window. Do not guess between attached sessions.
+   Under omp (Oh My Pi) nothing about this changes: the same tool runs the same
+   launcher, splitting the Windows Terminal window hosting the omp session
+   (tmux split on Linux/macOS) and reusing the pane already bound to it. omp has
+   no pane of its own inside its TUI, so the split IS the map's home there —
+   never claim a map is visible when the tool reported it could not open one.
+   Where the tool cannot help — a client without it, or a machine without
+   Windows Terminal or an attached tmux session — relay the launcher's complete
+   quoted watcher command for a visible terminal, or use:
+   `node <plugin root>/dist/watch.mjs --file <project>/.mellos/map.json
+   --page <slug>` in a second terminal or tmux split (this skill file lives
+   under `<plugin root>/skills/mellos-mapping/`). `mmap_view` shows the map
+   inline anywhere.
+3. **Work bottom-up.** Set a node `in-progress` before implementing it, and
+   prefer finishing its lower dependencies first. Independent same-band
+   siblings need no artificial queue — building them together (several
+   spinners at once) is honest reporting, not a violation. If you
+   deliberately build above an unfinished dependency, say why in
+   conversation.
+4. **`done` requires evidence.** Mark `done` only when verification actually
+   passed, with what passed in `evidence` (e.g. `vitest: 23 passed`). No
+   evidence, no done.
+5. **Regression spreads upward.** If later work breaks a `done` node, set it
+   `regressed` (breakage in `evidence`) BEFORE fixing. Then walk every node
+   that uses it, directly or transitively: their `done` was proven against a
+   foundation that no longer holds. Default them to `regressed` too; keep one
+   green only with a stated reason (its own verification re-ran green, or it
+   never touches the broken behavior). After the fix, restore each node only
+   as its own verification passes again.
+6. **Revise the ghost honestly.** The design is a hypothesis, and everything
+   it declared can be revised. When a node splits, a primitive appears, or a
+   band was wrong, fix the map in the same turn you change the plan:
+   `mmap_update` moves a node to another band (`layer`), renames or re-ranks
+   a band, relabels a group or a lane, and clears any optional field with
+   `null` (never an empty string); it also edits title, kind and edge labels.
+   `mmap_declare` grows the map; `mmap_remove` drops edges, nodes, groups, lanes
+   and bands you have emptied. A map that no longer matches your intent is
+   the one failure mode this system cannot survive.
+7. **Clean up a finished effort.** Pages accumulate — one effort, one page —
+   so when an effort is over and its map has served its purpose, offer to
+   remove it: `mmap_remove {pages: ["slug"]}` deletes those page files for
+   good. Only with the user behind it, never on your own initiative, and
+   never a page someone might still be reading. (In the pane the user can do
+   it themselves: `x` twice, or the `×` on the active tab.)
+
+## Modeling guidance
+
+- **Nodes are units of buildable, verifiable work** (a module, a contract, a
+  renderer) — not tasks like "write tests" and not files.
+- **Declare groups when one band grows crowded** (`groups` in
+  `mmap_declare`, `group` on members): labeled subsystems within that band,
+  worth declaring once a single band holds roughly five or more nodes — the
+  far zoom renders groups, and a crowded band without them degrades into
+  anonymous glyphs. A group must be a strict subset of its band: a group
+  holding the whole band merely renames it. A map spread thin across many
+  bands needs no groups at all. Group status is derived from members —
+  never invent it.
+- **Every node carries `detail`**: one to three sentences on responsibility,
+  contract, and the key decision. Update it when the design shifts — a stale
+  detail is a small lie on the map.
+- **Push state to the top.** Lower layers take values in, give values out;
+  mutable state concentrates in the topmost orchestrator, which owns it
+  explicitly and hands it down as parameters. Stateless layers are cheap to
+  maintain: testable with values alone, rewritable without ceremony. A lower
+  node whose `detail` must describe state it keeps between calls is a design
+  smell — restructure before building on it.
+- **Layers encode dependency direction, nothing else.** If A needs sibling B,
+  either B is really lower-layer or A and B are one node — restructure rather
+  than force an edge.
+- **Edges mean "uses"** — the upper node genuinely calls, composes, or reads
+  the lower one. No aspirational edges.
+- Ids are stable kebab-case slugs; labels are short display names (CJK fine),
+  renameable without breaking edges.
+- **One effort = one page.** A genuinely separate effort (parallel session,
+  unrelated subsystem) gets its own page via the `page` parameter — don't mix
+  efforts or overwrite a finished map.
+- **Sub-maps: dive, don't cram.** When a node's internals genuinely deserve
+  their own picture, declare a separate page and set `submap: <page-slug>` on
+  the node — the pane badges it ⊞; double-click dives in, Backspace climbs
+  back. Your judgment: most nodes need no sub-map; create one only when the
+  child map would carry a handful of nodes of its own.
+
+## Diagram kinds
+
+The default kind is `dev` — the living progress ledger described above.
+`mmap_declare` also accepts documentation kinds, rendered neutrally (no
+ghosts, no spinners, no progress counts). Use them when the user asks for a
+picture of a system rather than a picture of work; one diagram = one page.
+
+- `architecture` — layered components; also module dependencies, call graphs.
+- `dataflow` — pipeline stages as layers, sources at rank 0; label edges
+  with the data that flows.
+- `behavior-tree` — leaves (actions) at rank 0, root on top; node `kind`
+  selector | sequence | parallel | decorator | condition | action renders
+  as a glyph. Also fits mind maps and WBS.
+- `sequence` — the classic call/return diagram. rank = time step, rank 0 =
+  earliest; the pane draws sequence pages TOP-DOWN (earliest step on top,
+  under the participant headers). Declare participants as `lanes`; every
+  call AND every return is its own event node in the ACTING participant's
+  lane, so a round trip zigzags into the callee's lane and back out. Label
+  each edge with the message.
+- State machines are out of scope: transitions cycle, and edges here only
+  point downward. Say so rather than forcing one in.
+
+Edge labels and node kinds work on `dev` maps too.
+
+## Standing state
+
+At any moment the pane should answer at a glance: what is designed, what is
+built and verified, what is in progress RIGHT NOW, and whether any foundation
+is cracked. If a glance would mislead on any of these, fix the map first.