@extenshi/mcp 0.20.0 → 0.21.0

package/README.md

@@ -102,10 +102,10 @@ stdio or CLI. See the [development workflow](https://docs.extenshi.io/developers
 | `record_project_evidence` | Store metadata bound to the exact artifact, input hash, browser and source revision | Requires evidence.write for OAuth |
 | `get_release_readiness` | Explain current, stale and missing release checks by browser and locale. With a linked Pay application, the payment check is derived from Extenshi's payment ledger (source `platform`); a live-mode purchase that reached an installation passes it | Pro project; project read access |
 | `list_my_projects` | Your projects, repository bindings and claimed listings | Free; identity required |
-| `create_project` | Create a project through the Dojo wizard's service; idempotent per key; returns id, next steps and open owner decisions | Requires project.write for OAuth |
+| `create_project` | Create a project through the Dojo wizard's service; idempotent per key; returns id, next steps and open owner decisions; the local server adds `buildMap` | Requires project.write for OAuth |
 | `get_decisions` | Owner decisions (AMO add-on id, license, seller identity, pricing, targets): status, suggested default, what each blocks | Free; identity required |
 | `propose_decision` | Propose a decision value with rationale; the owner decides in Dojo, and decided keys are refused | Requires project.write for OAuth |
-| `get_project_state` | Manifest summaries (imported or generated, digest, keys that differ from the imported files), selected types, saved-state index, hosted URLs and exact integration file; `manifests: "full"` returns the manifest bodies | Free; identity required |
+| `get_project_state` | Manifest summaries (imported or generated, digest, keys that differ from the imported files), selected types, saved-state index, hosted URLs and exact integration file; `manifests: "full"` returns the manifest bodies; the local server adds `buildMap` (whether the build map is open, its address, and whether the author declined it) | Free; identity required |
 | `get_project_scaffold` | Starter files for one project and target browser | Free; identity required |
 | `list_privacy_policy_versions` | Hosted policy version history | Pro project; no read credit |
 | `get_privacy_policy_version` | One hosted policy's markdown and HTML | Pro project; no read credit |

package/dist/build-map-store.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Where the build map lives and how every client touches it (plan
+ * 2026-11-03-extension-build-map §6.1).
+ *
+ * ONE MAP PER PROJECT, whoever asks. Agents often work on one extension in
+ * parallel, each in its own git worktree, and `.extenshi/` is usually ignored by
+ * git, so a per-checkout file would give every agent its own map and the author
+ * one browser tab per agent. The map therefore lives in the MAIN checkout: from
+ * a linked worktree, `resolveMapHome` maps the directory to the same path in the
+ * main working tree. Every agent, from any worktree, reads and writes the same
+ * `.extenshi/build-map.json` and finds the same server.
+ *
+ * Files under `<home>/.extenshi/`:
+ *   build-map.json         the state (BuildMapState); written under build-map.lock
+ *   build-map.lock/        held for one read-modify-write; stale after a crash is taken over
+ *   build-map.server.json  the running server: pid, port, instance id, shutdown token (0600);
+ *                          a stopped server leaves it with pid 0 so the next start reuses the port
+ *   build-map.server.lock/ held while a server starts, so two starts cannot both listen
+ *   build-map.log          output of the background server
+ *
+ * Writes go to a temporary file in the same directory and are renamed over the
+ * target, so a reader never sees half a file.
+ *
+ * The stdio MCP server (`@extenshi/mcp`) is the map's other client and ships a
+ * byte-identical copy at tools/extenshi-mcp/src/build-map-store.ts, so both find
+ * the same home and the same server; build-map-store-sync.test.ts there fails on
+ * any drift. Edit this file, then copy it over.
+ */
+import { type BuildMapState } from '@extenshi/contracts';
+export declare const MAP_DIR = ".extenshi";
+export declare const MAP_STATE_FILE = "build-map.json";
+export declare const MAP_SERVER_FILE = "build-map.server.json";
+export declare const MAP_LOG_FILE = "build-map.log";
+/** Bumped when the page/server protocol changes: a newer CLI replaces an older server instead of reusing it. */
+export declare const MAP_PROTOCOL = 1;
+export type MapHome = {
+    /** Where the map's files live: this project directory in the main checkout. */
+    home: string;
+    /** The directory the command ran in. */
+    dir: string;
+    /** `dir` is inside a linked git worktree, and the map lives in the main checkout. */
+    worktree: boolean;
+};
+export declare const mapPath: (home: string, file: string) => string;
+/**
+ * The map home for `dir`: `dir` itself, unless it sits in a linked git worktree
+ * whose main working tree has the same directory — then that one. Outside git,
+ * in a bare-repository worktree or a submodule, the directory stays its own home.
+ */
+export declare function resolveMapHome(dir: string): Promise<MapHome>;
+/** Every checkout of the repository `home` belongs to (main first), mapped to the project directory in each. */
+export declare function projectCheckouts(home: string): Promise<string[]>;
+export declare function pidAlive(pid: number): boolean;
+/**
+ * Run `work` holding a directory lock. `mkdir` is atomic, so exactly one
+ * process creates the directory; its `owner.json` carries a random token. A
+ * lock whose owner died on this machine, or that is older than `staleMs`, is
+ * taken over — but the verdict is checked again under the breaker
+ * (`withBreaker`) before anything is removed, and a release removes the lock
+ * only while it still carries this holder's token.
+ */
+export declare function withDirLock<T>(lockDir: string, work: () => Promise<T>, options?: {
+    timeoutMs?: number;
+    staleMs?: number;
+    what?: string;
+}): Promise<T>;
+/** Write JSON so a concurrent reader sees the old file or the new one, never a mix. */
+export declare function writeJsonAtomic(file: string, value: unknown, mode?: number): Promise<void>;
+export type StateRead = {
+    state: BuildMapState;
+    exists: boolean;
+    problem?: string;
+};
+/** Read the state for display: a missing or broken file reads as empty, with the problem named. */
+export declare function readMapState(home: string): Promise<StateRead>;
+/**
+ * Read, change and write the state as one step, under the state lock, so two
+ * agents reporting at the same moment both land. Refuses to write over a file
+ * it cannot read rather than replace someone's edit with an empty map.
+ */
+export declare function updateMapState(home: string, change: (state: BuildMapState) => BuildMapState | undefined): Promise<BuildMapState>;
+export type MapServerRecord = {
+    pid: number;
+    host: string;
+    port: number;
+    url: string;
+    /** Random per start: tells this server from another that later got the same pid or port. */
+    instance: string;
+    /** Authorizes /api/shutdown; the file is readable by the owner only. */
+    token: string;
+    protocol: number;
+    version: string;
+    home: string;
+    startedAt: string;
+};
+export type MapHealth = {
+    instance: string;
+    home: string;
+    protocol: number;
+    version: string;
+    clients: number;
+};
+export declare function readServerRecord(home: string): Promise<MapServerRecord | undefined>;
+export declare function fetchHealth(port: number, timeoutMs?: number): Promise<MapHealth | undefined>;
+export type RunningServer = MapServerRecord & {
+    clients: number;
+};
+/**
+ * The server recorded for `home`, if it is really up: same machine, process
+ * alive, and its health answer carries the recorded instance id and home. A
+ * record left by a crash, by another machine (a synced folder) or a reused pid
+ * reads as no server.
+ */
+export declare function probeServer(home: string): Promise<RunningServer | undefined>;
+export declare const serverLockPath: (home: string) => string;
+/**
+ * Mark the server record stopped, but only if it still names `instance` —
+ * never a successor's. The port stays in it, so the next start binds the same
+ * address and a tab left open reconnects by itself; pid 0 and no token make it
+ * read as no server.
+ */
+export declare function retireServerRecord(home: string, instance: string): Promise<void>;
+//# sourceMappingURL=build-map-store.d.ts.map

package/dist/build-map-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-map-store.d.ts","sourceRoot":"","sources":["../src/build-map-store.ts"],"names":[],"mappings":"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"}

package/dist/build-map-store.js

@@ -0,0 +1,347 @@
+/**
+ * Where the build map lives and how every client touches it (plan
+ * 2026-11-03-extension-build-map §6.1).
+ *
+ * ONE MAP PER PROJECT, whoever asks. Agents often work on one extension in
+ * parallel, each in its own git worktree, and `.extenshi/` is usually ignored by
+ * git, so a per-checkout file would give every agent its own map and the author
+ * one browser tab per agent. The map therefore lives in the MAIN checkout: from
+ * a linked worktree, `resolveMapHome` maps the directory to the same path in the
+ * main working tree. Every agent, from any worktree, reads and writes the same
+ * `.extenshi/build-map.json` and finds the same server.
+ *
+ * Files under `<home>/.extenshi/`:
+ *   build-map.json         the state (BuildMapState); written under build-map.lock
+ *   build-map.lock/        held for one read-modify-write; stale after a crash is taken over
+ *   build-map.server.json  the running server: pid, port, instance id, shutdown token (0600);
+ *                          a stopped server leaves it with pid 0 so the next start reuses the port
+ *   build-map.server.lock/ held while a server starts, so two starts cannot both listen
+ *   build-map.log          output of the background server
+ *
+ * Writes go to a temporary file in the same directory and are renamed over the
+ * target, so a reader never sees half a file.
+ *
+ * The stdio MCP server (`@extenshi/mcp`) is the map's other client and ships a
+ * byte-identical copy at tools/extenshi-mcp/src/build-map-store.ts, so both find
+ * the same home and the same server; build-map-store-sync.test.ts there fails on
+ * any drift. Edit this file, then copy it over.
+ */
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { emptyBuildMapState, normalizeBuildMapState } from '@extenshi/contracts';
+export const MAP_DIR = '.extenshi';
+export const MAP_STATE_FILE = 'build-map.json';
+export const MAP_SERVER_FILE = 'build-map.server.json';
+export const MAP_LOG_FILE = 'build-map.log';
+const STATE_LOCK = 'build-map.lock';
+const SERVER_LOCK = 'build-map.server.lock';
+/** Bumped when the page/server protocol changes: a newer CLI replaces an older server instead of reusing it. */
+export const MAP_PROTOCOL = 1;
+export const mapPath = (home, file) => path.join(home, MAP_DIR, file);
+function git(cwd, args) {
+    return new Promise((resolve) => {
+        execFile('git', args, { cwd, timeout: 5_000, windowsHide: true }, (error, stdout) => resolve(error ? undefined : stdout));
+    });
+}
+async function isDirectory(location) {
+    try {
+        return (await stat(location)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The map home for `dir`: `dir` itself, unless it sits in a linked git worktree
+ * whose main working tree has the same directory — then that one. Outside git,
+ * in a bare-repository worktree or a submodule, the directory stays its own home.
+ */
+export async function resolveMapHome(dir) {
+    const real = await realpath(path.resolve(dir));
+    const own = { home: real, dir: real, worktree: false };
+    const out = await git(real, ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir']);
+    const [top, common] = (out ?? '').trim().split('\n');
+    if (!top || !common || path.basename(common) !== '.git')
+        return own;
+    let mainRoot;
+    let topReal;
+    try {
+        mainRoot = await realpath(path.dirname(common));
+        topReal = await realpath(top);
+    }
+    catch {
+        return own;
+    }
+    if (mainRoot === topReal)
+        return own;
+    const candidate = path.join(mainRoot, path.relative(topReal, real));
+    if (!(await isDirectory(candidate)))
+        return own;
+    return { home: candidate, dir: real, worktree: true };
+}
+/** Every checkout of the repository `home` belongs to (main first), mapped to the project directory in each. */
+export async function projectCheckouts(home) {
+    const out = await git(home, ['worktree', 'list', '--porcelain']);
+    const top = (await git(home, ['rev-parse', '--show-toplevel']))?.trim();
+    if (!out || !top)
+        return [home];
+    const relative = path.relative(top, home);
+    const roots = out
+        .split('\n')
+        .filter((line) => line.startsWith('worktree '))
+        .map((line) => line.slice('worktree '.length));
+    const dirs = [home];
+    for (const root of roots) {
+        const candidate = path.join(root, relative);
+        if (!dirs.includes(candidate) && (await isDirectory(candidate)))
+            dirs.push(candidate);
+    }
+    return dirs;
+}
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function readOwner(lockDir) {
+    try {
+        return JSON.parse(await readFile(path.join(lockDir, 'owner.json'), 'utf8'));
+    }
+    catch {
+        return undefined; // created a moment ago and not written yet, or a crash in between
+    }
+}
+/**
+ * Whether the lock as it is now may be taken over: its owner died on this
+ * machine, or it is older than `staleMs` (the critical sections take
+ * milliseconds). `undefined` when the lock is gone.
+ */
+async function lockIsStale(lockDir, staleMs) {
+    const owner = await readOwner(lockDir);
+    let age;
+    try {
+        age = Date.now() - (owner?.at ?? (await stat(lockDir)).mtimeMs);
+    }
+    catch {
+        return undefined;
+    }
+    const dead = owner !== undefined && owner.host === os.hostname() && !pidAlive(owner.pid);
+    return dead || age > staleMs;
+}
+/**
+ * Hold `<lockDir>.breaker` while removing `lockDir`. Every removal — a release
+ * and a takeover alike — happens under it and re-checks the lock it is about to
+ * remove, so a waiter that judged a dead owner's lock stale a moment ago cannot
+ * delete the fresh lock another waiter has taken since. The breaker is held for
+ * a few file operations; one older than 10 s belongs to a process that crashed
+ * inside them.
+ */
+async function withBreaker(lockDir, deadline, remove) {
+    const breaker = `${lockDir}.breaker`;
+    for (;;) {
+        try {
+            await mkdir(breaker);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        try {
+            if (Date.now() - (await stat(breaker)).mtimeMs > 10_000)
+                await rm(breaker, { recursive: true, force: true });
+        }
+        catch {
+            // released while we looked
+        }
+        if (Date.now() > deadline)
+            throw new Error(`${path.basename(breaker)} is held; remove it if no extenshi command runs.`);
+        await sleep(2 + Math.floor(Math.random() * 8));
+    }
+    try {
+        await remove();
+    }
+    finally {
+        await rm(breaker, { recursive: true, force: true });
+    }
+}
+/** Move the lock directory aside, then delete it: after the rename, `mkdir(lockDir)` is free again. */
+async function removeLockDir(lockDir) {
+    const aside = `${lockDir}.gone-${randomUUID()}`;
+    try {
+        await rename(lockDir, aside);
+    }
+    catch {
+        return; // already gone
+    }
+    await rm(aside, { recursive: true, force: true });
+}
+/**
+ * Run `work` holding a directory lock. `mkdir` is atomic, so exactly one
+ * process creates the directory; its `owner.json` carries a random token. A
+ * lock whose owner died on this machine, or that is older than `staleMs`, is
+ * taken over — but the verdict is checked again under the breaker
+ * (`withBreaker`) before anything is removed, and a release removes the lock
+ * only while it still carries this holder's token.
+ */
+export async function withDirLock(lockDir, work, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const staleMs = options.staleMs ?? 30_000;
+    const deadline = Date.now() + timeoutMs;
+    await mkdir(path.dirname(lockDir), { recursive: true });
+    for (;;) {
+        try {
+            await mkdir(lockDir);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        const stale = await lockIsStale(lockDir, staleMs);
+        if (stale === undefined)
+            continue; // released while we looked
+        if (stale) {
+            await withBreaker(lockDir, deadline, async () => {
+                if (await lockIsStale(lockDir, staleMs))
+                    await removeLockDir(lockDir);
+            });
+            continue;
+        }
+        if (Date.now() > deadline)
+            throw new Error(`${options.what ?? path.basename(lockDir)} is held by process ${(await readOwner(lockDir))?.pid ?? 'unknown'}. ` +
+                'If no extenshi command is running, remove the lock directory.');
+        await sleep(20 + Math.floor(Math.random() * 40));
+    }
+    const token = randomUUID();
+    try {
+        const owner = { pid: process.pid, host: os.hostname(), at: Date.now(), token };
+        await writeFile(path.join(lockDir, 'owner.json'), JSON.stringify(owner));
+        return await work();
+    }
+    finally {
+        await withBreaker(lockDir, Date.now() + 15_000, async () => {
+            if ((await readOwner(lockDir))?.token === token)
+                await removeLockDir(lockDir);
+        });
+    }
+}
+/** Write JSON so a concurrent reader sees the old file or the new one, never a mix. */
+export async function writeJsonAtomic(file, value, mode = 0o644) {
+    await mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        const handle = await open(temporary, 'wx', mode);
+        try {
+            await handle.writeFile(`${JSON.stringify(value, null, '\t')}\n`);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Read the state for display: a missing or broken file reads as empty, with the problem named. */
+export async function readMapState(home) {
+    let text;
+    try {
+        text = await readFile(mapPath(home, MAP_STATE_FILE), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { state: emptyBuildMapState(), exists: false };
+        return { state: emptyBuildMapState(), exists: true, problem: error.message };
+    }
+    try {
+        return { state: normalizeBuildMapState(JSON.parse(text)), exists: true };
+    }
+    catch (error) {
+        return {
+            state: emptyBuildMapState(),
+            exists: true,
+            problem: `${MAP_STATE_FILE}: ${error.message}`,
+        };
+    }
+}
+/**
+ * Read, change and write the state as one step, under the state lock, so two
+ * agents reporting at the same moment both land. Refuses to write over a file
+ * it cannot read rather than replace someone's edit with an empty map.
+ */
+export async function updateMapState(home, change) {
+    return withDirLock(mapPath(home, STATE_LOCK), async () => {
+        const read = await readMapState(home);
+        if (read.problem)
+            throw new Error(`Cannot update the build map: ${read.problem}`);
+        const next = change(read.state) ?? read.state;
+        await writeJsonAtomic(mapPath(home, MAP_STATE_FILE), next);
+        return next;
+    }, { what: `${MAP_DIR}/${STATE_LOCK}` });
+}
+export async function readServerRecord(home) {
+    try {
+        const record = JSON.parse(await readFile(mapPath(home, MAP_SERVER_FILE), 'utf8'));
+        if (typeof record?.port !== 'number' || typeof record?.instance !== 'string')
+            return undefined;
+        return record;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function fetchHealth(port, timeoutMs = 1_500) {
+    try {
+        const response = await fetch(`http://127.0.0.1:${port}/api/health`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            return undefined;
+        return (await response.json());
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The server recorded for `home`, if it is really up: same machine, process
+ * alive, and its health answer carries the recorded instance id and home. A
+ * record left by a crash, by another machine (a synced folder) or a reused pid
+ * reads as no server.
+ */
+export async function probeServer(home) {
+    const record = await readServerRecord(home);
+    if (!record || record.host !== os.hostname() || !pidAlive(record.pid))
+        return undefined;
+    const health = await fetchHealth(record.port);
+    if (!health || health.instance !== record.instance || health.home !== home)
+        return undefined;
+    return { ...record, clients: health.clients };
+}
+export const serverLockPath = (home) => mapPath(home, SERVER_LOCK);
+/**
+ * Mark the server record stopped, but only if it still names `instance` —
+ * never a successor's. The port stays in it, so the next start binds the same
+ * address and a tab left open reconnects by itself; pid 0 and no token make it
+ * read as no server.
+ */
+export async function retireServerRecord(home, instance) {
+    const record = await readServerRecord(home);
+    if (record?.instance !== instance)
+        return;
+    await writeJsonAtomic(mapPath(home, MAP_SERVER_FILE), { ...record, pid: 0, token: '', stoppedAt: new Date().toISOString() }, 0o600);
+}
+//# sourceMappingURL=build-map-store.js.map

package/dist/build-map-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-map-store.js","sourceRoot":"","sources":["../src/build-map-store.ts"],"names":[],"mappings":"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"}

package/dist/build-map-summary.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `buildMap` in the local server's create_project and get_project_state answers
+ * (plan 2026-11-03-extension-build-map §6.7): whether the author's build map is
+ * open, its address, and how offering it went. Read from the same home and the
+ * same server record the CLI uses (build-map-store.ts, a copy of the CLI's), so
+ * every agent, from any git worktree of the project, sees the one map there is.
+ *
+ * Local only. The hosted connector has no access to the author's files and
+ * registers the tools without `readBuildMap`, so the field is absent there.
+ * Reading never starts a server and never writes the state file.
+ */
+export type BuildMapSummary = {
+    /** A map server for this project answers on this machine. */
+    running: boolean;
+    /** The page while it runs; `#node=<step>` opens one step. */
+    url?: string;
+    /** The author has been asked about the map at least once. */
+    offered: boolean;
+    /** The author's latest answer was no, and no map runs. */
+    declined: boolean;
+    /** How many times the author answered the offer, yes or no. */
+    offers: number;
+    /** The project directory whose `.extenshi/` holds the map: the main checkout when the given one is a linked git worktree. */
+    home: string;
+    /** Why the state file could not be read, when it exists but could not. */
+    problem?: string;
+};
+export declare function readBuildMapSummary(dir: string): Promise<BuildMapSummary>;
+//# sourceMappingURL=build-map-summary.d.ts.map

package/dist/build-map-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-map-summary.d.ts","sourceRoot":"","sources":["../src/build-map-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,MAAM,eAAe,GAAG;IAC7B,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAA;IAChB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAA;IAChB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAA;IACjB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAA;IACd,6HAA6H;IAC7H,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAgB/E"}

package/dist/build-map-summary.js

@@ -0,0 +1,30 @@
+/**
+ * `buildMap` in the local server's create_project and get_project_state answers
+ * (plan 2026-11-03-extension-build-map §6.7): whether the author's build map is
+ * open, its address, and how offering it went. Read from the same home and the
+ * same server record the CLI uses (build-map-store.ts, a copy of the CLI's), so
+ * every agent, from any git worktree of the project, sees the one map there is.
+ *
+ * Local only. The hosted connector has no access to the author's files and
+ * registers the tools without `readBuildMap`, so the field is absent there.
+ * Reading never starts a server and never writes the state file.
+ */
+import { probeServer, readMapState, resolveMapHome } from './build-map-store.js';
+export async function readBuildMapSummary(dir) {
+    const where = await resolveMapHome(dir);
+    const [read, server] = await Promise.all([readMapState(where.home), probeServer(where.home)]);
+    const { offer } = read.state;
+    const declinedAt = Date.parse(offer.declinedAt ?? '');
+    const acceptedAt = Date.parse(offer.acceptedAt ?? '');
+    return {
+        running: Boolean(server),
+        ...(server ? { url: server.url } : {}),
+        offered: offer.count > 0 || Boolean(offer.offeredAt ?? offer.acceptedAt ?? offer.declinedAt),
+        // A map the author opened after saying no (acceptedAt later, or a server up now) is not declined.
+        declined: !server && Number.isFinite(declinedAt) && !(acceptedAt > declinedAt),
+        offers: offer.count,
+        home: where.home,
+        ...(read.problem ? { problem: read.problem } : {}),
+    };
+}
+//# sourceMappingURL=build-map-summary.js.map

package/dist/build-map-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-map-summary.js","sourceRoot":"","sources":["../src/build-map-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAmBhF,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAW;IACpD,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;IACvC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAC7F,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,CAAA;IAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAA;IACrD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAA;IACrD,OAAO;QACN,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC;QACxB,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,OAAO,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,CAAC;QAC5F,kGAAkG;QAClG,QAAQ,EAAE,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,UAAU,GAAG,UAAU,CAAC;QAC9E,MAAM,EAAE,KAAK,CAAC,KAAK;QACnB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClD,CAAA;AACF,CAAC"}

package/dist/development-guide.d.ts

@@ -104,7 +104,7 @@ export declare const DEVELOPMENT_SERVICES: readonly [{
     readonly urls: readonly [string, "https://dojo.extenshi.io/payments"];
 }];
 /** Top-level sections of the full guide, selectable via the `sections` parameter. */
-export declare const GUIDE_SECTIONS: readonly ["tools", "localActions", "services", "repository", "workflow", "handoff", "storeMedia"];
+export declare const GUIDE_SECTIONS: readonly ["tools", "localActions", "services", "repository", "workflow", "buildMap", "handoff", "storeMedia"];
 export type GuideSection = (typeof GUIDE_SECTIONS)[number];
 declare function buildSections(registeredTools: readonly GuideTool[]): {
     tools: {
@@ -265,6 +265,23 @@ declare function buildSections(registeredTools: readonly GuideTool[]): {
         readonly relatedTools: readonly ["get_reviews", "get_security", "get_project_state"];
         readonly doneWhen: "A handoff records repository/commit, artifacts, URLs, checks, remaining blockers, support owner and follow-up work.";
     }];
+    buildMap: {
+        readonly what: "A local page served by @extenshi/cli on 127.0.0.1: the build steps of the extension, from the idea to the live store listing, with the dependencies between them. Each step is done, in progress, waiting on the author, blocked by an unfinished step, or not needed for this extension. Steps waiting on the author (icon choice, approval of listing copy and screenshots, store accounts, submission) are counted in the header and open from there.";
+        readonly forTheAuthor: "One page shows what is done, what an agent is working on and where a decision is needed, instead of a long chat; visual choices such as the icon are compared there side by side. The page runs on the author’s machine, reads the project locally and works without an account.";
+        readonly commands: {
+            readonly open: "npx @extenshi/cli@latest map: starts the map server of the project when none runs and opens the page; with the page already open in a tab, no second tab opens.";
+            readonly status: "npx @extenshi/cli@latest map status --json: progress, steps waiting on the author, steps in progress and steps that can start now; starts nothing.";
+            readonly decline: "npx @extenshi/cli@latest map decline: records that the author declined the map.";
+            readonly stop: "npx @extenshi/cli@latest map stop: stops the server; the next start reuses its port, so open tabs and links keep working.";
+            readonly stepLink: "<map url>#node=<step id> opens one step, for example #node=iconConcepts.";
+        };
+        readonly oneMapPerProject: "A project has exactly one map and one map server, however many agents work on it. The map lives in the main checkout: from a linked git worktree the CLI resolves the same directory in the main working tree, so every agent and every worktree reads the same .extenshi/build-map.json and reaches the same server. Running `map` again, from any terminal, agent or worktree, returns the server already running; simultaneous starts end with one server.";
+        readonly progress: "Statuses are derived on every read, not stored: from the project files in the main checkout (manifest and the files it names, icons, builds, packages, the store folder, CI workflows); from the Dojo project the directory is bound to (owner decisions, and release evidence and readiness gates while the map server runs with an API key, refreshed every minute); and from .extenshi/build-map.json, which holds per-step progress, open reviews, the offer record and a log. Work on an agent branch appears once it is in the main checkout. The CLI writes the state file under .extenshi/build-map.lock; per-step progress reports from agents arrive with a later CLI version.";
+        readonly offer: "The map is an offer to the author, not a required step. It is offered once, after the extension idea is clear and before the first step that needs the author, in the author’s language and with a plain yes or no; the server starts only after a yes. After a no, the map comes up once more at the first visual choice (usually the icon), and after a second no it is not offered again. The answer is recorded in .extenshi/build-map.json (offer: count, acceptedAt, declinedAt): `map` records a yes and `map decline` a no, so a later agent session reads the answer instead of asking again.";
+        readonly withoutTheMap: "Everything also works in chat: previews are linked there and the author answers there. The state file is kept either way, so a map opened later shows the whole history.";
+        readonly localServerField: "On the local stdio server, create_project and get_project_state carry buildMap {running, url (while running), offered, declined, offers, home} for projectDir (default: the server’s working directory). The hosted connector has no access to the author’s files and returns no buildMap; there the map opens from a terminal on the author’s machine.";
+        readonly docs: `${string}#extenshi-map`;
+    };
     storeMedia: {
         readonly screenshots: {
             readonly command: "npx @extenshi/cli@latest screenshots <unpacked-dir|zip> --scenes scenes.json [--locales en,de] [--store chrome,edge,firefox] [--small] [--out store-screenshots] [--json] [--evidence --listing <file> [--evidence-browser chrome,edge,firefox]]";

package/dist/development-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"development-guide.d.ts","sourceRoot":"","sources":["../src/development-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,eAAe,CAAC,EAAE,OAAO,CAAA;KACzB,CAAA;CACD;AAKD,eAAO,MAAM,qBAAqB,QAA+B,CAAA;AAEjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiQvB,CAAA;AAgIV,qFAAqF;AACrF,eAAO,MAAM,cAAc,mGAQjB,CAAA;AACV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AA2F1D,iBAAS,aAAa,CAAC,eAAe,EAAE,SAAS,SAAS,EAAE;;;cAnfrD,MAAM;qBACC,MAAM;qBACN;YACZ,YAAY,CAAC,EAAE,OAAO,CAAA;YACtB,eAAe,CAAC,EAAE,OAAO,CAAA;SACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyiBD;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAA;AAE5D,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,EAAE,CAIlF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,eAAe,EAAE,SAAS,SAAS,EAAE,EACrC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAC3B;IAAE,aAAa,EAAE,CAAC,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,aAAa,CAAC,GAC5F,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBvB"}
+{"version":3,"file":"development-guide.d.ts","sourceRoot":"","sources":["../src/development-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,eAAe,CAAC,EAAE,OAAO,CAAA;KACzB,CAAA;CACD;AAKD,eAAO,MAAM,qBAAqB,QAA+B,CAAA;AAEjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiQvB,CAAA;AA+JV,qFAAqF;AACrF,eAAO,MAAM,cAAc,+GASjB,CAAA;AACV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AA6F1D,iBAAS,aAAa,CAAC,eAAe,EAAE,SAAS,SAAS,EAAE;;;cArhBrD,MAAM;qBACC,MAAM;qBACN;YACZ,YAAY,CAAC,EAAE,OAAO,CAAA;YACtB,eAAe,CAAC,EAAE,OAAO,CAAA;SACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4kBD;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAA;AAE5D,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,EAAE,CAIlF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,eAAe,EAAE,SAAS,SAAS,EAAE,EACrC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAC3B;IAAE,aAAa,EAAE,CAAC,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,aAAa,CAAC,GAC5F,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBvB"}