mellos-mapping 0.18.0 → 0.20.0

package/lib/store/store.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Layer 1b — Node-side persistence for a MellosMap.
+ *
+ * The state file IS the event bus of the whole plugin: the MCP server writes
+ * it, the terminal watcher polls it. The file FORMAT (version, page-id
+ * grammar, parse/serialize with boundary validation) lives in ./format.ts,
+ * pure of I/O so browsers can consume it; this module owns everything that
+ * touches the filesystem, and one promise:
+ *
+ *   P2. Writes are atomic: a reader polling the file either sees the previous
+ *       complete map or the new complete map, never a torn write. Achieved by
+ *       writing a sibling temp file and renaming it over the target.
+ *
+ * Expected failures (missing file, malformed JSON, invariant violations) are
+ * Result values. Only truly unexpected I/O faults (permissions, disk) are
+ * allowed to propagate as exceptions.
+ *
+ * Node consumers import everything from here; the format surface is
+ * re-exported so persistence has one import site per runtime.
+ */
+import { type MellosMap, type Result } from '../domain/types.js';
+import { type PageId, type StoreError } from './format.js';
+export { STATE_FILE_VERSION, type PageId, makePageId, type StoreError, describeStoreError, parseMap, serializeMap, } from './format.js';
+/**
+ * Project-relative location of the DEFAULT page's state file. The store lives
+ * in the tool-owned `.mellos/` directory: the map belongs to mellos-mapping,
+ * not to whichever host (Claude Code, Codex, a harness) happens to drive the
+ * server, so no host brand appears in the path. Pre-0.19 stores under
+ * `.claude/` are moved once by {@link migrateLegacyStore}.
+ */
+export declare const STATE_FILE_RELATIVE_PATH: string;
+/** Directory (next to the default file) holding the named pages. */
+export declare const PAGES_DIR_NAME = "pages";
+/** Where a page's map file lives, given the default page's file path. */
+export declare function pageFilePath(defaultFile: string, page?: PageId): string;
+/** The page id a file path denotes; undefined = the default page. */
+export declare function pageIdOfFile(defaultFile: string, path: string): PageId | undefined;
+/** Existing page files: the default page first (when present), then named pages sorted by slug. */
+export declare function listPageFiles(defaultFile: string): string[];
+/** Sibling of the default file carrying a one-shot "show this page" request. */
+export declare const FOCUS_FILE_NAME = "focus";
+export declare function focusFilePath(defaultFile: string): string;
+/** A consumed focus request: the page to show (undefined = the default page). */
+export interface FocusRequest {
+    readonly page: PageId | undefined;
+}
+/**
+ * Consume a pending focus request: read it, delete the file, return it.
+ * Absent file — the overwhelmingly common case — or junk content means no
+ * request; the channel is best-effort and junk is swept by the same delete.
+ */
+export declare function takeFocusRequest(defaultFile: string): FocusRequest | undefined;
+/** Sibling of the default file holding the project's plugin configuration. */
+export declare const CONFIG_FILE_NAME = "config.json";
+/** On-disk config format version. Bump only with a documented migration. */
+export declare const CONFIG_FILE_VERSION = 1;
+export declare function configFilePath(defaultFile: string): string;
+export declare const MAPPING_POLICIES: readonly ["always", "complex", "on-request"];
+/** How eagerly maps are opened; 'complex' is the behavior of an unconfigured project. */
+export type MappingPolicy = (typeof MAPPING_POLICIES)[number];
+export interface InvalidPolicy {
+    readonly kind: 'invalid-policy';
+    readonly raw: string;
+    readonly allowed: readonly string[];
+}
+export declare function makeMappingPolicy(raw: string): Result<MappingPolicy, InvalidPolicy>;
+/** One line of meaning per policy — the wording every surface repeats. */
+export declare function describeMappingPolicy(policy: MappingPolicy): string;
+/**
+ * The configured policy, or ok(undefined) when the project has never been
+ * set up (missing file or missing key — both mean "nobody chose yet").
+ * A file that exists but does not parse is an error, never silently ignored.
+ */
+export declare function loadMappingPolicy(defaultFile: string): Result<MappingPolicy | undefined, StoreError>;
+/** Persist the policy atomically (P2), same temp-and-rename as the map files. */
+export declare function saveMappingPolicy(defaultFile: string, policy: MappingPolicy): void;
+/** Project-relative location of the pre-0.20 default page file. */
+export declare const LEGACY_STATE_FILE_RELATIVE_PATH: string;
+/**
+ * Move a legacy `.claude` store — map, pages, and mapping-policy config —
+ * into the tool-owned `.mellos` location. Never merges: a project whose new
+ * store already holds anything keeps it untouched, whatever the legacy
+ * directory still contains.
+ * @param defaultFile - the NEW default page path (`<root>/.mellos/map.json`);
+ *   the legacy store is looked up relative to `<root>`.
+ * @returns whether a legacy store was moved.
+ */
+export declare function migrateLegacyStore(defaultFile: string): boolean;
+/** Load and validate the map file at `path`. */
+export declare function loadMapFile(path: string): Result<MellosMap, StoreError>;
+/**
+ * Write the map to `path` atomically (P2): serialize to `<path>.tmp` in the
+ * same directory, then rename over the target. Creates the parent directory
+ * if missing.
+ */
+export declare function saveMapFile(path: string, map: MellosMap): void;

package/lib/store/store.js

@@ -0,0 +1,281 @@
+/**
+ * Layer 1b — Node-side persistence for a MellosMap.
+ *
+ * The state file IS the event bus of the whole plugin: the MCP server writes
+ * it, the terminal watcher polls it. The file FORMAT (version, page-id
+ * grammar, parse/serialize with boundary validation) lives in ./format.ts,
+ * pure of I/O so browsers can consume it; this module owns everything that
+ * touches the filesystem, and one promise:
+ *
+ *   P2. Writes are atomic: a reader polling the file either sees the previous
+ *       complete map or the new complete map, never a torn write. Achieved by
+ *       writing a sibling temp file and renaming it over the target.
+ *
+ * Expected failures (missing file, malformed JSON, invariant violations) are
+ * Result values. Only truly unexpected I/O faults (permissions, disk) are
+ * allowed to propagate as exceptions.
+ *
+ * Node consumers import everything from here; the format surface is
+ * re-exported so persistence has one import site per runtime.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { err, ok } from '../domain/types.js';
+import { makePageId, parseMap, serializeMap } from './format.js';
+export { STATE_FILE_VERSION, makePageId, describeStoreError, parseMap, serializeMap, } from './format.js';
+/**
+ * Project-relative location of the DEFAULT page's state file. The store lives
+ * in the tool-owned `.mellos/` directory: the map belongs to mellos-mapping,
+ * not to whichever host (Claude Code, Codex, a harness) happens to drive the
+ * server, so no host brand appears in the path. Pre-0.19 stores under
+ * `.claude/` are moved once by {@link migrateLegacyStore}.
+ */
+export const STATE_FILE_RELATIVE_PATH = join('.mellos', 'map.json');
+// ---------------------------------------------------------------------------
+// pages — a project may keep several maps side by side (one effort = one page)
+// ---------------------------------------------------------------------------
+//
+// The default page IS the classic map.json. Named pages live in a sibling
+// directory, one file each: file-per-page keeps concurrent sessions isolated —
+// two writers on two pages can never clobber each other, because every save
+// renames a whole file.
+/** Directory (next to the default file) holding the named pages. */
+export const PAGES_DIR_NAME = 'pages';
+/** Where a page's map file lives, given the default page's file path. */
+export function pageFilePath(defaultFile, page) {
+    return page === undefined ? defaultFile : join(dirname(defaultFile), PAGES_DIR_NAME, `${page}.json`);
+}
+/** The page id a file path denotes; undefined = the default page. */
+export function pageIdOfFile(defaultFile, path) {
+    if (path === defaultFile)
+        return undefined;
+    const name = basename(path);
+    return name.endsWith('.json') ? name.slice(0, -'.json'.length) : name;
+}
+/** Existing page files: the default page first (when present), then named pages sorted by slug. */
+export function listPageFiles(defaultFile) {
+    const out = [];
+    if (existsSync(defaultFile))
+        out.push(defaultFile);
+    let entries = [];
+    try {
+        entries = readdirSync(join(dirname(defaultFile), PAGES_DIR_NAME));
+    }
+    catch {
+        // no pages directory — a single-page project, the common case
+    }
+    for (const e of entries.sort()) {
+        if (e.endsWith('.json'))
+            out.push(join(dirname(defaultFile), PAGES_DIR_NAME, e));
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// focus requests — "show this page" messages from pane openers to the watcher
+// ---------------------------------------------------------------------------
+//
+// State files flow one way, MCP server → watcher; a launcher that wants an
+// ALREADY-RUNNING pane to show a particular page has no channel to it. The
+// focus file is that channel, one-shot on purpose: the watcher consumes the
+// request AND DELETES the file, so a request lives about one poll tick —
+// nothing stale survives to misdirect tomorrow's pane, and the project's git
+// status barely ever sees the file exist.
+/** Sibling of the default file carrying a one-shot "show this page" request. */
+export const FOCUS_FILE_NAME = 'focus';
+export function focusFilePath(defaultFile) {
+    return join(dirname(defaultFile), FOCUS_FILE_NAME);
+}
+/**
+ * Consume a pending focus request: read it, delete the file, return it.
+ * Absent file — the overwhelmingly common case — or junk content means no
+ * request; the channel is best-effort and junk is swept by the same delete.
+ */
+export function takeFocusRequest(defaultFile) {
+    const path = focusFilePath(defaultFile);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // deletion is a courtesy: re-consuming next tick is harmless because
+        // switching to the already-shown page is a no-op
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const page = parsed.page;
+    if (page === undefined || page === null)
+        return { page: undefined };
+    if (typeof page !== 'string')
+        return undefined;
+    const id = makePageId(page);
+    return id.ok ? { page: id.value } : undefined;
+}
+// ---------------------------------------------------------------------------
+// mapping policy — WHEN the assistant should open a map, chosen by the user
+// ---------------------------------------------------------------------------
+//
+// Plugin configuration, not map data: it never enters a MellosMap and the
+// ledger never enforces it (the ledger is not a judge). It lives in its own
+// sibling file so hand-editing or corrupting it can never touch a map.
+/** Sibling of the default file holding the project's plugin configuration. */
+export const CONFIG_FILE_NAME = 'config.json';
+/** On-disk config format version. Bump only with a documented migration. */
+export const CONFIG_FILE_VERSION = 1;
+export function configFilePath(defaultFile) {
+    return join(dirname(defaultFile), CONFIG_FILE_NAME);
+}
+export const MAPPING_POLICIES = ['always', 'complex', 'on-request'];
+export function makeMappingPolicy(raw) {
+    return MAPPING_POLICIES.includes(raw)
+        ? ok(raw)
+        : err({ kind: 'invalid-policy', raw, allowed: MAPPING_POLICIES });
+}
+/** One line of meaning per policy — the wording every surface repeats. */
+export function describeMappingPolicy(policy) {
+    switch (policy) {
+        case 'always':
+            return 'map every structured task — workflows, designs, architecture, technical dependencies';
+        case 'complex':
+            return 'map only medium or complex tasks — several modules, a new subsystem, roughly an hour or more';
+        case 'on-request':
+            return 'map only when the user explicitly asks';
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * The configured policy, or ok(undefined) when the project has never been
+ * set up (missing file or missing key — both mean "nobody chose yet").
+ * A file that exists but does not parse is an error, never silently ignored.
+ */
+export function loadMappingPolicy(defaultFile) {
+    const path = configFilePath(defaultFile);
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return ok(undefined);
+        throw e; // unexpected I/O fault: fail fast, nothing meaningful to recover here
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    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 === undefined)
+        return ok(undefined);
+    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(' | ')}` });
+}
+/** Persist the policy atomically (P2), same temp-and-rename as the map files. */
+export 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);
+}
+// ---------------------------------------------------------------------------
+// legacy migration — stores written under the old host-coupled location
+// ---------------------------------------------------------------------------
+//
+// Up to 0.18 the store lived in `.claude/mellos-mapping.*`: the map's home
+// was coupled to one host brand, which turned absurd the moment another host
+// (a harness, Codex) drove the same server. The move is one-time and
+// explicit — entry points call it before touching the store; nothing here
+// runs as a hidden side effect of ordinary loads.
+/** Project-relative location of the pre-0.20 default page file. */
+export const LEGACY_STATE_FILE_RELATIVE_PATH = join('.claude', 'mellos-mapping.json');
+const LEGACY_PAGES_DIR_NAME = 'mellos-mapping.pages';
+const LEGACY_CONFIG_FILE_NAME = 'mellos-mapping.config.json';
+/**
+ * Move a legacy `.claude` store — map, pages, and mapping-policy config —
+ * into the tool-owned `.mellos` location. Never merges: a project whose new
+ * store already holds anything keeps it untouched, whatever the legacy
+ * directory still contains.
+ * @param defaultFile - the NEW default page path (`<root>/.mellos/map.json`);
+ *   the legacy store is looked up relative to `<root>`.
+ * @returns whether a legacy store was moved.
+ */
+export function migrateLegacyStore(defaultFile) {
+    const projectRoot = dirname(dirname(defaultFile));
+    const legacyDefault = join(projectRoot, LEGACY_STATE_FILE_RELATIVE_PATH);
+    const legacyPages = join(dirname(legacyDefault), LEGACY_PAGES_DIR_NAME);
+    const legacyConfig = join(dirname(legacyDefault), LEGACY_CONFIG_FILE_NAME);
+    const hasLegacy = existsSync(legacyDefault) || existsSync(legacyPages) || existsSync(legacyConfig);
+    const hasCurrent = existsSync(defaultFile)
+        || existsSync(join(dirname(defaultFile), PAGES_DIR_NAME))
+        || existsSync(configFilePath(defaultFile));
+    if (!hasLegacy || hasCurrent)
+        return false;
+    mkdirSync(dirname(defaultFile), { recursive: true });
+    if (existsSync(legacyDefault))
+        renameSync(legacyDefault, defaultFile);
+    if (existsSync(legacyPages))
+        renameSync(legacyPages, join(dirname(defaultFile), PAGES_DIR_NAME));
+    if (existsSync(legacyConfig))
+        renameSync(legacyConfig, configFilePath(defaultFile));
+    return true;
+}
+/** Load and validate the map file at `path`. */
+export function loadMapFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT')
+            return err({ kind: 'not-found', path });
+        throw e; // unexpected I/O fault: fail fast, nothing meaningful to recover here
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        // Expected at this boundary: hand-edited files, or a reader racing a
+        // non-atomic writer from a foreign tool.
+        return err({ kind: 'malformed-json', path, detail: e.message });
+    }
+    return parseMap(raw, path);
+}
+/**
+ * Write the map to `path` atomically (P2): serialize to `<path>.tmp` in the
+ * same directory, then rename over the target. Creates the parent directory
+ * if missing.
+ */
+export function saveMapFile(path, map) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = path + '.tmp';
+    writeFileSync(tmp, serializeMap(map), 'utf8');
+    renameSync(tmp, path);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.18.0",
+  "version": "0.20.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",
@@ -27,11 +27,39 @@
     "mellos-mapping": "dist/server.mjs",
     "mellos-mapping-watch": "dist/watch.mjs"
   },
+  "exports": {
+    "./domain/types": {
+      "types": "./lib/domain/types.d.ts",
+      "default": "./lib/domain/types.js"
+    },
+    "./domain/ops": {
+      "types": "./lib/domain/ops.d.ts",
+      "default": "./lib/domain/ops.js"
+    },
+    "./format": {
+      "types": "./lib/store/format.d.ts",
+      "default": "./lib/store/format.js"
+    },
+    "./store": {
+      "types": "./lib/store/store.d.ts",
+      "default": "./lib/store/store.js"
+    },
+    "./semantics": {
+      "types": "./lib/semantics/semantics.d.ts",
+      "default": "./lib/semantics/semantics.js"
+    },
+    "./render": {
+      "types": "./lib/render/render.d.ts",
+      "default": "./lib/render/render.js"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
   "files": [
     "dist",
+    "lib",
     "README.zh-CN.md",
     "scripts/codex-register.mjs",
     "scripts/open-pane.mjs"
@@ -42,7 +70,7 @@
   "scripts": {
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "build": "node build.mjs",
+    "build": "node build.mjs && tsc -p tsconfig.lib.json",
     "verify": "npm run typecheck && npm run test && npm run build"
   },
   "devDependencies": {

package/scripts/codex-register.mjs

@@ -45,4 +45,4 @@ if (added.error !== undefined || added.status !== 0) {
 }
 process.stdout.write(added.stdout ?? '');
 console.log(`mellos-mapping MCP registered with Codex: node ${serverPath}`);
-console.log('State files resolve to each session’s working directory (.claude/mellos-mapping.json).');
+console.log('State files resolve to each session’s working directory (.mellos/map.json).');

package/scripts/open-pane.mjs

@@ -84,7 +84,7 @@ if (!existsSync(watchPath)) {
   console.error(`watcher not found (is the plugin built?): ${watchPath}`);
   process.exit(1);
 }
-const mapFile = join(projectDir, '.claude', 'mellos-mapping.json');
+const mapFile = join(projectDir, '.mellos', 'map.json');
 
 function runPowerShell(script) {
   const encoded = Buffer.from(script, 'utf16le').toString('base64');