mellos-mapping 0.20.2 → 0.22.1

package/lib/store/pages.d.ts

@@ -0,0 +1,46 @@
+import { type Result } from '../domain/types.js';
+import { type StoreError } from './format.js';
+import { type PageId } from './format.js';
+/**
+ * The directory a store lives in, under a project root or under a user's home.
+ * It is tool-owned: 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.20 stores under `.claude/` are moved once
+ * by {@link migrateLegacyStore}.
+ */
+export declare const STORE_DIR_NAME = ".mellos";
+/** Project-relative location of the DEFAULT page's state file. */
+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[];
+/**
+ * Delete one page's file — a named page, or the DEFAULT page (whose file is
+ * optional by design, so removing it is a legal state, not a mutilation).
+ *
+ * Preconditions: none. Postcondition on ok: no file at `path` — an already
+ * absent one is ok too, because the goal state is what is promised, not the
+ * act. Postcondition on error: the file is still there and the caller may
+ * retry or report; the errno is carried in the detail.
+ *
+ * Concurrency, stated plainly: deletion races a concurrent writer and THE
+ * WRITER WINS. A server saving that page while this runs simply recreates the
+ * file (its rename is atomic and needs no existing target), so the page comes
+ * back. That is accepted rather than defended against — the store has no
+ * lost-update protection anywhere (see the module header), and locking one
+ * operation would only make the race rarer, never absent, while claiming
+ * otherwise. Pages are the isolation unit: nobody deletes a page another
+ * session is writing.
+ *
+ * What it deliberately does NOT do: sweep `<path>.<pid>.<random>.tmp`
+ * siblings. Those temps are private to a save IN FLIGHT, and a live writer
+ * whose temp vanished would fail its rename — turning a harmless leftover
+ * into a broken save. A stray temp only exists when a write failed AND its
+ * own cleanup failed; it is inert, and the README documents it.
+ */
+export declare function deletePageFile(path: string): Result<void, StoreError>;

package/lib/store/pages.js

@@ -0,0 +1,89 @@
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { err, ok } from '../domain/types.js';
+import { errnoOf } from './atomic.js';
+/**
+ * The directory a store lives in, under a project root or under a user's home.
+ * It is tool-owned: 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.20 stores under `.claude/` are moved once
+ * by {@link migrateLegacyStore}.
+ */
+export const STORE_DIR_NAME = '.mellos';
+/** Project-relative location of the DEFAULT page's state file. */
+export const STATE_FILE_RELATIVE_PATH = join(STORE_DIR_NAME, '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;
+}
+/**
+ * Delete one page's file — a named page, or the DEFAULT page (whose file is
+ * optional by design, so removing it is a legal state, not a mutilation).
+ *
+ * Preconditions: none. Postcondition on ok: no file at `path` — an already
+ * absent one is ok too, because the goal state is what is promised, not the
+ * act. Postcondition on error: the file is still there and the caller may
+ * retry or report; the errno is carried in the detail.
+ *
+ * Concurrency, stated plainly: deletion races a concurrent writer and THE
+ * WRITER WINS. A server saving that page while this runs simply recreates the
+ * file (its rename is atomic and needs no existing target), so the page comes
+ * back. That is accepted rather than defended against — the store has no
+ * lost-update protection anywhere (see the module header), and locking one
+ * operation would only make the race rarer, never absent, while claiming
+ * otherwise. Pages are the isolation unit: nobody deletes a page another
+ * session is writing.
+ *
+ * What it deliberately does NOT do: sweep `<path>.<pid>.<random>.tmp`
+ * siblings. Those temps are private to a save IN FLIGHT, and a live writer
+ * whose temp vanished would fail its rename — turning a harmless leftover
+ * into a broken save. A stray temp only exists when a write failed AND its
+ * own cleanup failed; it is inert, and the README documents it.
+ */
+export function deletePageFile(path) {
+    try {
+        // force: an absent file is the goal state already, not a failure.
+        // No `recursive`: a DIRECTORY where a page file belongs is a fault to
+        // report, never a tree to erase.
+        rmSync(path, { force: true });
+        return ok(undefined);
+    }
+    catch (e) {
+        return err({ kind: 'delete-failed', path, detail: errnoOf(e) });
+    }
+}

package/lib/store/policy.d.ts

@@ -0,0 +1,74 @@
+import { type Result } from '../domain/types.js';
+import { type StoreError } from './format.js';
+/** Name of the file holding a mapping-policy configuration, in either scope. */
+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;
+/** The PROJECT-scope configuration file: sibling of the default page. */
+export declare function configFilePath(defaultFile: string): string;
+/**
+ * The USER-scope configuration file: the same store directory name, under the
+ * user's own base directory.
+ *
+ * @param userBase - the user's home directory. Always passed in, never read
+ *   from the environment down here: a function that reached for os.homedir()
+ *   itself would make every spec a gamble on the developer's real
+ *   configuration, and one of them would eventually write it. Entry points
+ *   resolve the home once and hand it down.
+ */
+export declare function userConfigFilePath(userBase: 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 policy recorded in ONE configuration file, or ok(undefined) when nobody
+ * has chosen there (missing file or missing key — both mean the same thing).
+ * A file that exists but does not parse is an error, never silently ignored.
+ *
+ * @param path - the configuration file itself: {@link configFilePath} for a
+ *   project, {@link userConfigFilePath} for the user. One loader, two scopes.
+ */
+export declare function loadMappingPolicy(path: string): Result<MappingPolicy | undefined, StoreError>;
+/**
+ * Persist the policy atomically (P2), same write as the map files.
+ * @param path - the configuration file to write; see {@link loadMappingPolicy}.
+ * @returns ok when the file holds the policy; save-failed leaves the previous
+ *   configuration in place.
+ */
+export declare function saveMappingPolicy(path: string, policy: MappingPolicy): Result<void, StoreError>;
+/** The two places a mapping policy can be recorded, in override order. */
+export declare const POLICY_SCOPES: readonly ["user", "project"];
+export type PolicyScope = (typeof POLICY_SCOPES)[number];
+/** What both scopes say, and which of them actually governs. */
+export interface MappingPolicyScopes {
+    readonly project: MappingPolicy | undefined;
+    readonly user: MappingPolicy | undefined;
+    /** What to act on. undefined = nobody has chosen yet, anywhere. */
+    readonly effective: MappingPolicy | undefined;
+    /** Where `effective` came from; undefined exactly when `effective` is. */
+    readonly source: PolicyScope | undefined;
+}
+/**
+ * Resolve the policy that governs this project: the PROJECT file if it names
+ * one, otherwise the USER file, otherwise nothing.
+ *
+ * Both scopes are reported, not just the winner — a surface that says "always"
+ * without saying where it came from cannot tell a user why changing their
+ * user-level choice did nothing here.
+ *
+ * @param projectConfigFile - see {@link configFilePath}.
+ * @param userConfigFile - see {@link userConfigFilePath}.
+ * @returns err as soon as EITHER file exists and is broken, project first: a
+ *   configuration nobody can read is not the same as a configuration nobody
+ *   wrote, and silently falling through to the other scope would act on a
+ *   choice the user did not make.
+ */
+export declare function effectiveMappingPolicy(projectConfigFile: string, userConfigFile: string): Result<MappingPolicyScopes, StoreError>;

package/lib/store/policy.js

@@ -0,0 +1,144 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { err, ok } from '../domain/types.js';
+import { STORE_DIR_NAME } from './pages.js';
+import { writeFileAtomic } from './atomic.js';
+import { isRecord, stripBom } from './json-text.js';
+// ---------------------------------------------------------------------------
+// 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
+// file so hand-editing or corrupting it can never touch a map.
+//
+// TWO SCOPES, one file format:
+//
+//   user    <home>/.mellos/config.json — the normal one. The question "when
+//           should maps open?" is about how somebody works, not about a
+//           particular repository, so it is asked ONCE, right after install,
+//           and answered for every project they will ever open.
+//   project <root>/.mellos/config.json — the override. A project that needs a
+//           different answer from its owner's habit says so, and wins.
+//
+// PROJECT beats USER wherever both are set (effectiveMappingPolicy); neither
+// set means nobody has chosen yet, which is the one state that still prompts.
+// Both are read and written by the same pair of functions, which take the
+// CONFIG FILE PATH — not a map path — precisely so neither scope can grow a
+// loader of its own.
+/** Name of the file holding a mapping-policy configuration, in either scope. */
+export const CONFIG_FILE_NAME = 'config.json';
+/** On-disk config format version. Bump only with a documented migration. */
+export const CONFIG_FILE_VERSION = 1;
+/** The PROJECT-scope configuration file: sibling of the default page. */
+export function configFilePath(defaultFile) {
+    return join(dirname(defaultFile), CONFIG_FILE_NAME);
+}
+/**
+ * The USER-scope configuration file: the same store directory name, under the
+ * user's own base directory.
+ *
+ * @param userBase - the user's home directory. Always passed in, never read
+ *   from the environment down here: a function that reached for os.homedir()
+ *   itself would make every spec a gamble on the developer's real
+ *   configuration, and one of them would eventually write it. Entry points
+ *   resolve the home once and hand it down.
+ */
+export function userConfigFilePath(userBase) {
+    return join(userBase, STORE_DIR_NAME, 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';
+    }
+}
+/**
+ * The policy recorded in ONE configuration file, or ok(undefined) when nobody
+ * has chosen there (missing file or missing key — both mean the same thing).
+ * A file that exists but does not parse is an error, never silently ignored.
+ *
+ * @param path - the configuration file itself: {@link configFilePath} for a
+ *   project, {@link userConfigFilePath} for the user. One loader, two scopes.
+ */
+export function loadMappingPolicy(path) {
+    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(stripBom(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 write as the map files.
+ * @param path - the configuration file to write; see {@link loadMappingPolicy}.
+ * @returns ok when the file holds the policy; save-failed leaves the previous
+ *   configuration in place.
+ */
+export function saveMappingPolicy(path, policy) {
+    const body = JSON.stringify({ version: CONFIG_FILE_VERSION, policy }, null, 2) + '\n';
+    return writeFileAtomic(path, body);
+}
+/** The two places a mapping policy can be recorded, in override order. */
+export const POLICY_SCOPES = ['user', 'project'];
+/**
+ * Resolve the policy that governs this project: the PROJECT file if it names
+ * one, otherwise the USER file, otherwise nothing.
+ *
+ * Both scopes are reported, not just the winner — a surface that says "always"
+ * without saying where it came from cannot tell a user why changing their
+ * user-level choice did nothing here.
+ *
+ * @param projectConfigFile - see {@link configFilePath}.
+ * @param userConfigFile - see {@link userConfigFilePath}.
+ * @returns err as soon as EITHER file exists and is broken, project first: a
+ *   configuration nobody can read is not the same as a configuration nobody
+ *   wrote, and silently falling through to the other scope would act on a
+ *   choice the user did not make.
+ */
+export function effectiveMappingPolicy(projectConfigFile, userConfigFile) {
+    const project = loadMappingPolicy(projectConfigFile);
+    if (!project.ok)
+        return project;
+    const user = loadMappingPolicy(userConfigFile);
+    if (!user.ok)
+        return user;
+    const effective = project.value ?? user.value;
+    const source = project.value !== undefined ? 'project' : user.value !== undefined ? 'user' : undefined;
+    return ok({ project: project.value, user: user.value, effective, source });
+}

package/lib/store/store.d.ts

@@ -3,8 +3,8 @@
  *
  * The state file IS the event bus of the whole plugin: the MCP server writes
  * it, the terminal watcher polls it — and the watcher reports back what it is
- * showing (see viewers below), which is how a writer can tell whether anybody
- * is actually SEEING the map it is updating. The file FORMAT (version, page-id
+ * showing (see viewers below). These are process reports; terminal visibility
+ * is checked separately by the host adapter. 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:
@@ -39,258 +39,11 @@
  * 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';
-/**
- * The directory a store lives in, under a project root or under a user's home.
- * It is tool-owned: 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.20 stores under `.claude/` are moved once
- * by {@link migrateLegacyStore}.
- */
-export declare const STORE_DIR_NAME = ".mellos";
-/** Project-relative location of the DEFAULT page's state file. */
-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[];
-/**
- * Delete one page's file — a named page, or the DEFAULT page (whose file is
- * optional by design, so removing it is a legal state, not a mutilation).
- *
- * Preconditions: none. Postcondition on ok: no file at `path` — an already
- * absent one is ok too, because the goal state is what is promised, not the
- * act. Postcondition on error: the file is still there and the caller may
- * retry or report; the errno is carried in the detail.
- *
- * Concurrency, stated plainly: deletion races a concurrent writer and THE
- * WRITER WINS. A server saving that page while this runs simply recreates the
- * file (its rename is atomic and needs no existing target), so the page comes
- * back. That is accepted rather than defended against — the store has no
- * lost-update protection anywhere (see the module header), and locking one
- * operation would only make the race rarer, never absent, while claiming
- * otherwise. Pages are the isolation unit: nobody deletes a page another
- * session is writing.
- *
- * What it deliberately does NOT do: sweep `<path>.<pid>.<random>.tmp`
- * siblings. Those temps are private to a save IN FLIGHT, and a live writer
- * whose temp vanished would fail its rename — turning a harmless leftover
- * into a broken save. A stray temp only exists when a write failed AND its
- * own cleanup failed; it is inert, and the README documents it.
- */
-export declare function deletePageFile(path: string): Result<void, StoreError>;
-/** 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 carrying a one-shot "close the pane" request. */
-export declare const QUIT_FILE_NAME = "quit";
-export declare function quitFilePath(defaultFile: string): string;
-/**
- * Consume a pending quit request: read it, delete the file, say whether there
- * was one. Absent file — the overwhelmingly common case — or content that is
- * not a JSON object means NO request; the channel is best-effort and junk is
- * swept by the same delete.
- *
- * The empty JSON object is the whole grammar. It exists so that a stray file
- * of this name — an editor backup, a half-written write from a foreign tool —
- * cannot take a live pane down by accident; a pane closing is the one thing
- * in this channel a user cannot undo by waiting.
- */
-export declare function takeQuitRequest(defaultFile: string): boolean;
-/**
- * Delete a quit request WITHOUT acting on it — the same file, read as a
- * leftover rather than as a message.
- *
- * A toggle that wrote the request and then lost its watcher (a crash, a
- * closed window, a `taskkill`) leaves the file behind, and the next pane to
- * open would consume it on its first tick and close instantly. The watcher
- * sweeps at STARTUP for exactly that: a request that predates the pane cannot
- * have been addressed to it. Best-effort, like every delete in this channel.
- */
-export declare function sweepQuitRequest(defaultFile: string): void;
-/** Directory (next to the default file) holding one report per live pane. */
-export declare const VIEWERS_DIR_NAME = "viewers";
-/** On-disk report format version. Bump only with a documented migration. */
-export declare const VIEWER_FILE_VERSION = 1;
-/**
- * How often a pane refreshes its report — the pane's timer, and the unit the
- * two thresholds below are counted in.
- */
-export declare const VIEWER_HEARTBEAT_MS = 1000;
-/**
- * A report older than this is not a pane, it is a pane's remains. Five missed
- * heartbeats: long enough to survive a garbage collection, a slow repaint or
- * a busy disk, short enough that a closed pane is known closed before anyone
- * asks twice.
- */
-export declare const VIEWER_STALE_MS = 5000;
-/**
- * A report this old is deleted on sight by whoever reads it. A pane that was
- * killed leaves its file behind forever, and a file that outlives every pane
- * would keep answering for one. The gap to VIEWER_STALE_MS is deliberate
- * slack: a machine that just woke from sleep has stale reports whose panes
- * are alive and about to beat again, and there is no reason to make them pay
- * for the sleep with a deleted file.
- */
-export declare const VIEWER_SWEEP_MS = 60000;
-/** Where a store's viewer reports live, given the default page's file path. */
-export declare function viewersDirPath(defaultFile: string): string;
-/** Where ONE pane's report lives. The pid in the name is the pane's identity. */
-export declare function viewerFilePath(defaultFile: string, pid: number): string;
-/** What a pane says about itself while it is up. */
-export interface ViewerReport {
-    /** The page on screen right now; undefined = the default page. */
-    readonly page: PageId | undefined;
-    /** Auto-follow: whether the pane will switch to whatever page is written next. */
-    readonly follow: boolean;
-}
-/** A report fresh enough to be a pane, with whose it is and how old. */
-export interface LiveViewer extends ViewerReport {
-    readonly pid: number;
-    /** Age of the report in ms — how long ago that pane last said anything. */
-    readonly ageMs: number;
-}
-/**
- * Publish this pane's report, atomically (P2) — a reader polling the file
- * sees the previous whole report or the new one, never half of one.
- *
- * Preconditions: none; the viewers directory is created if missing.
- * Postcondition on ok: the pane's file holds `report` and its mtime is now,
- * which is what says the pane is alive. On error nothing about the pane is
- * claimed, and the next heartbeat is the whole recovery — so a caller reports
- * a failed beat at most once and keeps beating.
- */
-export declare function publishViewer(defaultFile: string, pid: number, report: ViewerReport): Result<void, StoreError>;
-/**
- * Take this pane's report back — the pane is going away and says so, rather
- * than leaving readers to wait out VIEWER_STALE_MS for the same conclusion.
- *
- * Best-effort by contract: an exit path is the worst place to raise, and a
- * report nobody could delete goes stale on its own within seconds.
- */
-export declare function retireViewer(defaultFile: string, pid: number): void;
-/**
- * Every pane currently showing this store, youngest report first.
- *
- * @param nowMs - the caller's clock (Date.now()), passed in so the ageing
- *   rules can be tested without waiting for real seconds to pass.
- * @returns the live reports; an EMPTY array means nobody is seeing this map.
- *
- * Reading sweeps: a report past VIEWER_SWEEP_MS is deleted here, because the
- * pane that would have refreshed it is provably gone and no other code runs
- * often enough to notice. A report between stale and sweep is ignored but
- * kept — see VIEWER_SWEEP_MS. Nothing here has an opinion about WHOSE pane a
- * report is: a viewer started by hand counts exactly like one the launcher
- * opened, because the user can see both.
- */
-export declare function readLiveViewers(defaultFile: string, nowMs: number): readonly LiveViewer[];
-/** Name of the file holding a mapping-policy configuration, in either scope. */
-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;
-/** The PROJECT-scope configuration file: sibling of the default page. */
-export declare function configFilePath(defaultFile: string): string;
-/**
- * The USER-scope configuration file: the same store directory name, under the
- * user's own base directory.
- *
- * @param userBase - the user's home directory. Always passed in, never read
- *   from the environment down here: a function that reached for os.homedir()
- *   itself would make every spec a gamble on the developer's real
- *   configuration, and one of them would eventually write it. Entry points
- *   resolve the home once and hand it down.
- */
-export declare function userConfigFilePath(userBase: 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 policy recorded in ONE configuration file, or ok(undefined) when nobody
- * has chosen there (missing file or missing key — both mean the same thing).
- * A file that exists but does not parse is an error, never silently ignored.
- *
- * @param path - the configuration file itself: {@link configFilePath} for a
- *   project, {@link userConfigFilePath} for the user. One loader, two scopes.
- */
-export declare function loadMappingPolicy(path: string): Result<MappingPolicy | undefined, StoreError>;
-/**
- * Persist the policy atomically (P2), same write as the map files.
- * @param path - the configuration file to write; see {@link loadMappingPolicy}.
- * @returns ok when the file holds the policy; save-failed leaves the previous
- *   configuration in place.
- */
-export declare function saveMappingPolicy(path: string, policy: MappingPolicy): Result<void, StoreError>;
-/** The two places a mapping policy can be recorded, in override order. */
-export declare const POLICY_SCOPES: readonly ["user", "project"];
-export type PolicyScope = (typeof POLICY_SCOPES)[number];
-/** What both scopes say, and which of them actually governs. */
-export interface MappingPolicyScopes {
-    readonly project: MappingPolicy | undefined;
-    readonly user: MappingPolicy | undefined;
-    /** What to act on. undefined = nobody has chosen yet, anywhere. */
-    readonly effective: MappingPolicy | undefined;
-    /** Where `effective` came from; undefined exactly when `effective` is. */
-    readonly source: PolicyScope | undefined;
-}
-/**
- * Resolve the policy that governs this project: the PROJECT file if it names
- * one, otherwise the USER file, otherwise nothing.
- *
- * Both scopes are reported, not just the winner — a surface that says "always"
- * without saying where it came from cannot tell a user why changing their
- * user-level choice did nothing here.
- *
- * @param projectConfigFile - see {@link configFilePath}.
- * @param userConfigFile - see {@link userConfigFilePath}.
- * @returns err as soon as EITHER file exists and is broken, project first: a
- *   configuration nobody can read is not the same as a configuration nobody
- *   wrote, and silently falling through to the other scope would act on a
- *   choice the user did not make.
- */
-export declare function effectiveMappingPolicy(projectConfigFile: string, userConfigFile: string): Result<MappingPolicyScopes, StoreError>;
-/** 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 a private sibling
- * temp file, then rename it over the target, retrying a rename the OS
- * refuses transiently. Creates the parent directory if missing.
- * @returns ok when the file holds the new map; save-failed when it does not,
- *   in which case the previous content is intact and the call may be retried.
- */
-export declare function saveMapFile(path: string, map: MellosMap): Result<void, StoreError>;
+export { writeFileAtomic } from './atomic.js';
+export { STORE_DIR_NAME, STATE_FILE_RELATIVE_PATH, PAGES_DIR_NAME, pageFilePath, pageIdOfFile, listPageFiles, deletePageFile } from './pages.js';
+export { FOCUS_FILE_NAME, focusFilePath, type FocusRequest, takeFocusRequest, QUIT_FILE_NAME, quitFilePath, takeQuitRequest, sweepQuitRequest } from './channels.js';
+export { VIEWERS_DIR_NAME, VIEWER_FILE_VERSION, VIEWER_HEARTBEAT_MS, VIEWER_STALE_MS, VIEWER_SWEEP_MS, viewersDirPath, viewerFilePath, type ViewerReport, type LiveViewer, publishViewer, retireViewer, readLiveViewers } from './viewers.js';
+export { CONFIG_FILE_NAME, CONFIG_FILE_VERSION, configFilePath, userConfigFilePath, MAPPING_POLICIES, type MappingPolicy, type InvalidPolicy, makeMappingPolicy, describeMappingPolicy, loadMappingPolicy, saveMappingPolicy, POLICY_SCOPES, type PolicyScope, type MappingPolicyScopes, effectiveMappingPolicy } from './policy.js';
+export { LEGACY_STATE_FILE_RELATIVE_PATH, migrateLegacyStore } from './migration.js';
+export { loadMapFile, saveMapFile } from './maps.js';