Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
import { type SpawnOptions, spawn } from "node:child_process";
import { randomBytes, timingSafeEqual } from "node:crypto";
import { existsSync, type FSWatcher, watch } from "node:fs";
import { readFile } from "node:fs/promises";
import {
createServer as createHttpServer,
type IncomingMessage,
type ServerResponse,
} from "node:http";
import { createRequire } from "node:module";
import type { AddressInfo } from "node:net";
import { basename, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import pkg from "../package.json" with { type: "json" };
import { defaultAgent } from "./agents/index.js";
import { buildProject } from "./commands/build.js";
import { regenerateShape } from "./commands/shape.js";
import { diffTooLarge, isDiffSha, readCommitDiff } from "./diff.js";
import { defaultsPrompter, type Io } from "./io.js";
import { Config } from "./schema/config.js";
import {
CAPTURE_ID,
CaptureTransitionError,
setCaptureState,
UnknownCaptureError,
} from "./store/captures.js";
import { dismissInboxSession } from "./store/inbox-state.js";
import { LockBusyError } from "./store/lock.js";
import { MAX_OPEN, readMapView, setOpenSessions, setRowWidth } from "./store/map-view.js";
import { globalPaths, projectPaths } from "./store/paths.js";
import { loadConfig, loadRegistry, updateConfig } from "./store/stores.js";
import { builtBy } from "./view/lineage.js";
import {
isPanelEditableKey,
LIVE_META_NAME,
TOKEN_HEADER_NAME,
TOKEN_META_NAME,
} from "./view/model.js";
import { buildPanel, panelSettings } from "./view/panel.js";
import { editableSettings } from "./view/settings.js";
/** The CLI's version: a server of another version is not reused (see `ensureServer`). */
const VERSION: string = pkg.version;
/** A page nobody is looking at is a dead server after this long. */
export const DEFAULT_IDLE_MS = 30 * 60 * 1000;
/** How long `open` waits for a freshly spawned server to answer. */
export const START_WAIT_MS = 1500;
const HOST = "127.0.0.1";
const LIVE_META = `<meta name="${LIVE_META_NAME}" content="1">`;
/** Header a settings write must carry, with the token from the panel page. */
export const CONFIG_TOKEN_HEADER = TOKEN_HEADER_NAME;
/** A settings write is a tiny JSON object; anything larger is not ours. */
export const CONFIG_BODY_LIMIT = 4096;
/**
* Marks a page as served by the local server. The page only subscribes to
* rebuild events when this tag is present, so `file://` pages (and the Vite dev
* server) stay silent.
*/
export function injectLiveMeta(html: string): string {
if (html.includes(LIVE_META)) return html;
return html.replace(/<head(\s[^>]*)?>/i, (head) => `${head}${LIVE_META}`);
}
/**
* Carries the per-server token into every page the server serves (Story 8.13):
* both the panel and each project map open a settings modal that reads and
* writes through `/api/config`.
*/
export function injectTokenMeta(html: string, token: string): string {
const meta = `<meta name="${TOKEN_META_NAME}" content="${token}">`;
if (html.includes(meta)) return html;
return html.replace(/<head(\s[^>]*)?>/i, (head) => `${head}${meta}`);
}
export interface MapServerOptions {
env?: NodeJS.ProcessEnv;
/** 0 lets the OS pick a free port (tests). */
port: number;
hostname?: string;
/** Exit after this long without a connected page (tests use a short one). */
idleMs?: number;
/** Quiet time after the last transcript write before a map rebuild (tests use a short one). */
transcriptDebounceMs?: number;
/** The Mermaid file the map's diagrams load; defaults to `mermaidFile()`. */
mermaidFile?: string;
}
export interface MapServer {
port: number;
host: string;
/** `http://127.0.0.1:<port>`; pages live under `/map` and `/panel`. */
url: string;
close: () => Promise<void>;
/** Resolves once the server has closed (including the idle exit). */
closed: Promise<void>;
}
interface PageTarget {
/** The HTML file served for the page and watched for rebuilds. */
file: string;
/** Directory to watch: atomic writes replace the file, the directory keeps its name. */
dir: string;
/** The registered project the map belongs to; absent for the panel. */
root?: string;
}
interface WatchedPage {
watcher?: FSWatcher;
clients: Set<ServerResponse>;
timer: NodeJS.Timeout | null;
/** The project to rebuild while this page has a transcript write (Story 9.5). */
root?: string;
}
function hostAllowed(host: string | undefined, port: number): boolean {
return host === `${HOST}:${port}` || host === `localhost:${port}`;
}
function respond(res: ServerResponse, status: number, body: string): void {
// A stream that already started (the event endpoint) can only be ended.
if (!res.headersSent) res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
res.end(body);
}
/** An API answer as JSON; the diff endpoint's body is text, so it needs this. */
function respondJson(res: ServerResponse, status: number, body: unknown): void {
if (!res.headersSent)
res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
res.end(JSON.stringify(body));
}
/** The root of a registered project, or null when the request names another path. */
async function registeredRoot(env: NodeJS.ProcessEnv, dir: string): Promise<string | null> {
const requested = resolve(dir);
const registry = await loadRegistry(env);
if (!registry.found || !registry.ok) return null;
return registry.data.projects.some((entry) => resolve(entry.path) === requested)
? requested
: null;
}
/**
* What a request may see: the panel, or the map of a project in the registry.
* Nothing else in the filesystem is reachable, which is what keeps this server
* a viewer and not a file server.
*/
async function pageTarget(env: NodeJS.ProcessEnv, url: URL): Promise<PageTarget | null> {
const panel = (): PageTarget => {
const paths = globalPaths(env);
return { file: paths.panel, dir: paths.base };
};
if (url.pathname === "/") return panel();
if (url.pathname === "/map" || url.pathname === "/events") {
const raw = url.searchParams.get("dir");
// The panel's event stream lives at /events without a directory.
if (!raw) return url.pathname === "/events" ? panel() : null;
const root = await registeredRoot(env, raw);
if (!root) return null;
const paths = projectPaths(root);
return { file: paths.html, dir: paths.base, root };
}
return null;
}
/**
* Mermaid for the Shape diagrams (Story 13.6). It is too big to embed in every
* map, so the build copies it next to `dist/cli.js` and the map loads it from
* here; from source (tests, `tsx`) the package's own copy is used.
*/
export const MERMAID_PATH = "/assets/mermaid.js";
export function mermaidFile(): string {
const bundled = fileURLToPath(new URL("./mermaid.min.js", import.meta.url));
if (existsSync(bundled)) return bundled;
return createRequire(import.meta.url).resolve("mermaid/dist/mermaid.min.js");
}
async function serveMermaid(res: ServerResponse, file: string): Promise<void> {
let body: Buffer;
try {
body = await readFile(file);
} catch {
respond(res, 404, "not found");
return;
}
res.writeHead(200, {
"content-type": "text/javascript; charset=utf-8",
"cache-control": "public, max-age=86400",
});
res.end(body);
}
/** URL of a project's map on a running server. */
export function mapPageUrl(base: string, root: string): string {
return `${base}/map?dir=${encodeURIComponent(root)}`;
}
/**
* Starts the local map server. It serves the panel and the maps of registered
* projects, tells connected pages when one is rebuilt and exits after `idleMs`
* without a connected page. It binds `127.0.0.1` only and rejects a `Host`
* header that names any other host (DNS rebinding).
*/
export async function startMapServer(opts: MapServerOptions): Promise<MapServer> {
const env = opts.env ?? process.env;
const hostname = opts.hostname ?? HOST;
const idleMs = opts.idleMs ?? DEFAULT_IDLE_MS;
const transcriptDebounceMs = opts.transcriptDebounceMs ?? 1000;
const pages = new Map<string, WatchedPage>();
/** A quiet build IO: rebuilds a page without printing to a terminal nobody watches. */
const buildIo: Io = {
prompt: defaultsPrompter,
out: () => {},
warn: () => {},
env,
now: () => new Date().toISOString(),
};
/** Watches Claude Code's transcripts while somebody has a map open (9.5). */
let transcriptWatcher: FSWatcher | undefined;
let transcriptTimer: NodeJS.Timeout | null = null;
/** Rebuilds run one after another, so a write during a build is never dropped. */
let rebuildQueue: Promise<void> = Promise.resolve();
/** One random token per server start; the panel page carries it into a write. */
const token = randomBytes(24).toString("hex");
let openPages = 0;
let idleTimer: NodeJS.Timeout | null = null;
let closing: Promise<void> | null = null;
let resolveClosed: () => void = () => {};
const closed = new Promise<void>((done) => {
resolveClosed = done;
});
function clearIdle(): void {
if (idleTimer !== null) clearTimeout(idleTimer);
idleTimer = null;
}
function scheduleIdle(ms: number): void {
clearIdle();
idleTimer = setTimeout(() => {
idleTimer = null;
void close();
}, ms);
}
function broadcast(page: WatchedPage): void {
for (const client of page.clients) {
if (client.writableEnded) continue;
client.write("event: change\ndata: rebuilt\n\n");
}
}
function watched(file: string, dir: string, root?: string): WatchedPage {
const existing = pages.get(file);
if (existing) return existing;
const page: WatchedPage = {
clients: new Set(),
timer: null,
...(root === undefined ? {} : { root }),
};
try {
page.watcher = watch(dir, { persistent: false }, (_event, name) => {
// A null name means "something in here changed" on some platforms.
if (name !== null && name.toString() !== basename(file)) return;
if (page.timer !== null) clearTimeout(page.timer);
// One rebuild emits several events; tell the page once.
page.timer = setTimeout(() => {
page.timer = null;
broadcast(page);
}, 50);
});
} catch {
// The page can still be viewed; it just will not refresh by itself.
}
pages.set(file, page);
return page;
}
function release(file: string, page: WatchedPage): void {
if (page.clients.size > 0) return;
page.watcher?.close();
if (page.timer !== null) clearTimeout(page.timer);
pages.delete(file);
}
/**
* Rebuilds every map somebody is looking at, from the records and the
* transcripts. The write itself reaches the page through the page watcher; a
* failing project is skipped so one broken record never stops the others.
*/
async function rebuildOpenMaps(): Promise<void> {
const roots = new Set<string>();
for (const page of pages.values()) {
if (page.root !== undefined && page.clients.size > 0) roots.add(page.root);
}
for (const root of roots) {
try {
await buildProject({ dir: root, io: buildIo, quiet: true });
} catch {
// Already a warning where the project is read; keep the page up.
}
}
}
/** Queues a rebuild behind any running one; the debounce already collapsed the burst. */
function queueRebuild(): void {
rebuildQueue = rebuildQueue.then(() => rebuildOpenMaps());
}
/**
* Follows Claude Code's transcripts while a map page is open (Story 9.5), so
* the map is live without the plugin's Stop hook. One recursive watcher over
* the Claude projects directory covers every registered project, and a turn's
* many writes collapse into one debounced rebuild. No page, no watch.
*/
function startTranscriptWatch(): void {
if (transcriptWatcher !== undefined) return;
const dir = join(defaultAgent().configDir(env), "projects");
try {
transcriptWatcher = watch(dir, { persistent: false, recursive: true }, (_event, name) => {
if (name === null || !name.toString().endsWith(".jsonl")) return;
if (transcriptTimer !== null) clearTimeout(transcriptTimer);
transcriptTimer = setTimeout(() => {
transcriptTimer = null;
queueRebuild();
}, transcriptDebounceMs);
});
} catch {
// No Claude home (or no recursive watch here): the Stop hook still rebuilds.
transcriptWatcher = undefined;
}
}
function stopTranscriptWatch(): void {
transcriptWatcher?.close();
transcriptWatcher = undefined;
if (transcriptTimer !== null) clearTimeout(transcriptTimer);
transcriptTimer = null;
}
/** Whether any project map (not just the panel) still has a viewer. */
function mapPagesOpen(): boolean {
return [...pages.values()].some((page) => page.root !== undefined && page.clients.size > 0);
}
const server = createHttpServer((req, res) => {
// A broken registry or an unexpected error must not take the server down.
void handle(req, res).catch(() => respond(res, 500, "internal error"));
});
function tokenMatches(given: string | string[] | undefined): boolean {
const value = Array.isArray(given) ? given[0] : given;
if (typeof value !== "string") return false;
const a = Buffer.from(value);
const b = Buffer.from(token);
return a.length === b.length && timingSafeEqual(a, b);
}
/** Same origin only: a page from another site cannot post even with its own Host. */
function originAllowed(origin: string | undefined, port: number): boolean {
return origin === `http://${HOST}:${port}` || origin === `http://localhost:${port}`;
}
/**
* A same-origin GET carries no Origin header, so absence is fine; a present
* Origin must still be this server (Story 8.13).
*/
function readOriginAllowed(origin: string | undefined, port: number): boolean {
return origin === undefined || originAllowed(origin, port);
}
async function readLimitedBody(req: IncomingMessage): Promise<string | null> {
const chunks: Buffer[] = [];
let size = 0;
for await (const chunk of req) {
const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
size += buf.length;
if (size > CONFIG_BODY_LIMIT) {
req.resume();
return null;
}
chunks.push(buf);
}
return Buffer.concat(chunks).toString("utf8");
}
/**
* Rebuilds the data of the pages somebody is looking at, as `build` does, so
* the open pages get a change event with the new settings. Best effort: the
* write already landed, so a failed rebuild must not fail the request.
*/
async function refreshOpenPages(): Promise<void> {
let rebuiltMap = false;
const registry = await loadRegistry(env);
if (registry.found && registry.ok) {
for (const entry of registry.data.projects) {
const page = pages.get(projectPaths(entry.path).html);
if (!page || page.clients.size === 0) continue;
try {
await buildProject({ dir: entry.path, io: buildIo, quiet: true });
rebuiltMap = true;
} catch {
// A broken project is already a warning elsewhere; keep serving.
}
}
}
if (rebuiltMap) return;
try {
// `buildProject` rebuilds the panel too; without an open map, do it here.
await buildPanel({ env, io: buildIo });
} catch {
// An unwritable global directory leaves the old page in place.
}
}
/**
* `GET /api/config`: the values the settings modal opens with (Story 8.13).
* Same Host, Origin and token checks as the write, and only the keys the modal
* may change; the setup-time keys never leave the config file.
*/
async function readConfig(
req: IncomingMessage,
res: ServerResponse,
port: number,
): Promise<void> {
if (
!readOriginAllowed(req.headers.origin, port) ||
!tokenMatches(req.headers[CONFIG_TOKEN_HEADER])
) {
respond(res, 403, "forbidden");
return;
}
const config = await loadConfig(env);
res.writeHead(200, {
"content-type": "application/json",
"cache-control": "no-store",
});
res.end(JSON.stringify({ ok: true, settings: editableSettings(panelSettings(config)) }));
}
/**
* `GET /api/map-view?dir`: how the user left the map (open sessions, row
* widths) as stored now. The page embeds it at build time, but a reload can
* come before the rebuild that a write starts, so the page asks here too. Same
* Origin and token checks as the settings read, and a registered project only.
*/
async function readMapViewRequest(
req: IncomingMessage,
res: ServerResponse,
port: number,
url: URL,
): Promise<void> {
if (
!readOriginAllowed(req.headers.origin, port) ||
!tokenMatches(req.headers[CONFIG_TOKEN_HEADER])
) {
respond(res, 403, "forbidden");
return;
}
const dir = url.searchParams.get("dir");
if (!dir) {
respond(res, 400, "dir is required");
return;
}
const root = await registeredRoot(env, dir);
if (root === null) {
respond(res, 403, "not a registered project");
return;
}
res.writeHead(200, {
"content-type": "application/json",
"cache-control": "no-store",
});
const view = await readMapView(root);
res.end(JSON.stringify({ ok: true, rowWidths: view.rowWidths, open: view.open }));
}
/**
* `GET /api/diff?dir&commit[&file]` (Story 10.5): one commit's patch for the
* message details. Read-only, a registered project only, and the same Origin
* and token checks as the settings read. A bad or unknown hash is a 4xx, and
* an oversized patch comes back as a one-line notice instead of the bytes.
*/
async function readDiff(
req: IncomingMessage,
res: ServerResponse,
port: number,
url: URL,
): Promise<void> {
if (
!readOriginAllowed(req.headers.origin, port) ||
!tokenMatches(req.headers[CONFIG_TOKEN_HEADER])
) {
respond(res, 403, "forbidden");
return;
}
const dir = url.searchParams.get("dir");
const commit = url.searchParams.get("commit");
const file = url.searchParams.get("file") || undefined;
if (!dir) {
respond(res, 400, "dir is required");
return;
}
if (commit === null || !isDiffSha(commit)) {
respond(res, 400, "commit must be 7–40 hex characters");
return;
}
const root = await registeredRoot(env, dir);
if (root === null) {
respond(res, 403, "not a registered project");
return;
}
const result = await readCommitDiff(root, commit, file);
if (!result.ok) {
if (result.reason === "file-not-in-commit") {
respond(res, 400, "file is not part of this commit");
return;
}
if (result.reason === "unknown-commit") {
respond(res, 404, "commit not found");
return;
}
if (result.reason === "no-git") {
respond(res, 404, "not a git repository");
return;
}
respondJson(res, 200, { ok: true, text: diffTooLarge(commit) });
return;
}
respondJson(res, 200, { ok: true, text: result.text });
}
/**
* `POST /api/config` { key, value }: the modal's only write. Host, Origin,
* content type and token all have to match, the key must be one the modal may
* change and the value has to pass the config schema. Anything else is a 4xx
* and the file stays untouched.
*/
async function writeConfig(
req: IncomingMessage,
res: ServerResponse,
port: number,
): Promise<void> {
if (
!originAllowed(req.headers.origin, port) ||
!tokenMatches(req.headers[CONFIG_TOKEN_HEADER])
) {
respond(res, 403, "forbidden");
return;
}
const type = req.headers["content-type"];
if (
typeof type !== "string" ||
type.split(";")[0]?.trim().toLowerCase() !== "application/json"
) {
respond(res, 415, "content-type must be application/json");
return;
}
const body = await readLimitedBody(req);
if (body === null) {
respond(res, 413, "request body too large");
return;
}
let parsed: unknown;
try {
parsed = JSON.parse(body);
} catch {
respond(res, 400, "invalid JSON");
return;
}
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
respond(res, 400, "expected a JSON object");
return;
}
const { key, value } = parsed as Record<string, unknown>;
if (typeof key !== "string" || !isPanelEditableKey(key)) {
respond(res, 400, `unknown or read-only key: ${String(key)}`);
return;
}
const next = Config.safeParse({ ...(await loadConfig(env)), [key]: value });
if (!next.success) {
respond(res, 400, `invalid value for ${key}: ${next.error.issues[0]?.message ?? "rejected"}`);
return;
}
try {
// A page is waiting: give the lock a moment, not the CLI's usual 10 s.
await updateConfig((c) => ({ ...c, [key]: next.data[key] }), env, { timeoutMs: 500 });
} catch (err) {
respond(res, err instanceof LockBusyError ? 409 : 500, "could not write the config");
return;
}
// Story 9.3: un-ignore (or hide) the conversation store in every project.
res.writeHead(200, {
"content-type": "application/json",
"cache-control": "no-store",
});
res.end(JSON.stringify({ ok: true, key, value: next.data[key] }));
void refreshOpenPages();
}
/**
* `POST /api/shape/regenerate` { dir, sessionId, nodeId }: the Shape modal's
* Regenerate button. Runs the side model for that message the way the
* post-commit hook does — behind the session's shape lock — and then rebuilds
* the open maps, so the page shows the Shape it wrote. Every check a write
* carries holds here too; the model call can take a minute.
*/
async function writeShapeRegenerate(
req: IncomingMessage,
res: ServerResponse,
port: number,
): Promise<void> {
if (
!originAllowed(req.headers.origin, port) ||
!tokenMatches(req.headers[CONFIG_TOKEN_HEADER])
) {
respond(res, 403, "forbidden");
return;
}
const type = req.headers["content-type"];
if (
typeof type !== "string" ||
type.split(";")[0]?.trim().toLowerCase() !== "application/json"
) {
respond(res, 415, "content-type must be application/json");
return;
}
const body = await readLimitedBody(req);
if (body === null) {
respond(res, 413, "request body too large");
return;
}
let parsed: unknown;
try {
parsed = JSON.parse(body);
} catch {
respond(res, 400, "invalid JSON");
return;
}
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
respond(res, 400, "expected a JSON object");
return;
}
const { dir, sessionId, nodeId } = parsed as Record<string, unknown>;
if (
typeof dir !== "string" ||
typeof sessionId !== "string" ||
typeof nodeId !== "string" ||
!/^[A-Za-z0-9._:-]{1,128}$/.test(sessionId) ||
!/^h[0-9a-f]{12}$/.test(nodeId)
) {
respond(res, 400, "expected { dir, sessionId, nodeId }");
return;
}
const root = await registeredRoot(env, dir);
if (root === null) {
respond(res, 403, "not a registered project");
return;
}
let result: Awaited<ReturnType<typeof regenerateShape>>;
try {
result = await regenerateShape(root, sessionId, nodeId, buildIo);
} catch (err) {
respond(res, 500, err instanceof Error ? err.message : "could not regenerate the shape");
return;
}
if (!result.ok) {
respond(res, result.reason.startsWith("no such") ? 404 : 409, result.reason);
return;
}
res.writeHead(200, {
"content-type": "application/json",
"cache-control": "no-store",
});
res.end(JSON.stringify({ ok: true, sessionId, nodeId }));
void queueRebuild();
}
/**
* `POST /api/inbox/dismiss` { dir, sessionId, at } (Story 11.1): the inbox's
* dismiss button. It writes the project's local state file, and the turn time
* is stored so a newer agent turn brings the row back. Same Host, Origin,
* content-type and token checks as a config write, and `dir` must be registered.
*/
async function writeInboxDismiss(
req: IncomingMessage,
res: ServerResponse,
port: number,
): Promise<void> {
if (
!originAllowed(req.headers.origin, port) ||
!tokenMatches(req.headers[CONFIG_TOKEN_HEADER])
) {
respond(res, 403, "forbidden");
return;
}
const type = req.headers["content-type"];
if (
typeof type !== "string" ||
type.split(";")[0]?.trim().toLowerCase() !== "application/json"
) {
respond(res, 415, "content-type must be application/json");
return;
}
const body = await readLimitedBody(req);
if (body === null) {
respond(res, 413, "request body too large");
return;
}
let parsed: unknown;
try {
parsed = JSON.parse(body);
} catch {
respond(res, 400, "invalid JSON");
return;
}
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
respond(res, 400, "expected a JSON object");
return;
}
const { dir, sessionId, at } = parsed as Record<string, unknown>;
if (typeof dir !== "string" || typeof sessionId !== "string" || typeof at !== "string") {
respond(res, 400, "expected { dir, sessionId, at }");
return;
}
if (!/^[A-Za-z0-9._:-]{1,128}$/.test(sessionId) || Number.isNaN(Date.parse(at))) {
respond(res, 400, "sessionId or at is not valid");
return;
}
const root = await registeredRoot(env, dir);
if (root === null) {
respond(res, 403, "not a registered project");
return;
}
try {
await dismissInboxSession(root, sessionId, at);
} catch {
respond(res, 500, "could not write the inbox state");
return;
}
res.writeHead(200, {
"content-type": "application/json",
"cache-control": "no-store",
});
res.end(JSON.stringify({ ok: true, sessionId, at }));
}
/**
* `POST /api/captures/state` { dir, id, state } (Story 15.1): the map's
* Accept, Dismiss and Done buttons. Only the user's own transitions are
* allowed (`suggested` → `open`|`dismissed`, `open` → `done`); an unknown id
* is a 404 and an impossible transition a 409. Same Host, Origin,
* content-type and token checks as an inbox dismissal, and `dir` must be a
* registered project. The open maps are rebuilt so the list follows.
*/
async function writeCaptureState(
req: IncomingMessage,
res: ServerResponse,
port: number,
): Promise<void> {
if (
!originAllowed(req.headers.origin, port) ||
!tokenMatches(req.headers[CONFIG_TOKEN_HEADER])
) {
respond(res, 403, "forbidden");
return;
}
const type = req.headers["content-type"];
if (
typeof type !== "string" ||
type.split(";")[0]?.trim().toLowerCase() !== "application/json"
) {
respond(res, 415, "content-type must be application/json");
return;
}
const body = await readLimitedBody(req);
if (body === null) {
respond(res, 413, "request body too large");
return;
}
let parsed: unknown;
try {
parsed = JSON.parse(body);
} catch {
respond(res, 400, "invalid JSON");
return;
}
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
respond(res, 400, "expected a JSON object");
return;
}
const { dir, id, state } = parsed as Record<string, unknown>;
if (typeof dir !== "string" || typeof id !== "string" || typeof state !== "string") {
respond(res, 400, "expected { dir, id, state }");
return;
}
if (!CAPTURE_ID.test(id)) {
respond(res, 400, "id is not a captured item id");
return;
}
if (state !== "open" && state !== "dismissed" && state !== "done") {
respond(res, 400, "state must be open, dismissed or done");
return;
}
const root = await registeredRoot(env, dir);
if (root === null) {
respond(res, 403, "not a registered project");
return;
}
try {
await setCaptureState(root, id, state, new Date().toISOString());
} catch (err) {
if (err instanceof UnknownCaptureError) {
respond(res, 404, err.message);
return;
}
if (err instanceof CaptureTransitionError) {
respond(res, 409, err.message);
return;
}
respond(res, 500, "could not write the captured list");
return;
}
res.writeHead(200, {
"content-type": "application/json",
"cache-control": "no-store",
});
res.end(JSON.stringify({ ok: true, id, state }));
void queueRebuild();
}
/**
* The checks every map-view write shares: Origin and token, a JSON object body
* within the size cap, and a registered `dir`. Answers the request itself and
* returns null when one fails.
*/
async function mapViewWrite(
req: IncomingMessage,
res: ServerResponse,
port: number,
): Promise<{ root: string; body: Record<string, unknown> } | null> {
if (
!originAllowed(req.headers.origin, port) ||
!tokenMatches(req.headers[CONFIG_TOKEN_HEADER])
) {
respond(res, 403, "forbidden");
return null;
}
const type = req.headers["content-type"];
if (
typeof type !== "string" ||
type.split(";")[0]?.trim().toLowerCase() !== "application/json"
) {
respond(res, 415, "content-type must be application/json");
return null;
}
const raw = await readLimitedBody(req);
if (raw === null) {
respond(res, 413, "request body too large");
return null;
}
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
respond(res, 400, "invalid JSON");
return null;
}
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
respond(res, 400, "expected a JSON object");
return null;
}
const body = parsed as Record<string, unknown>;
if (typeof body.dir !== "string") {
respond(res, 400, "dir is required");
return null;
}
const root = await registeredRoot(env, body.dir);
if (root === null) {
respond(res, 403, "not a registered project");
return null;
}
return { root, body };
}
/**
* `POST /api/row-width` { dir, sessionId, width }: the map's row edge, sent
* when a drag ends. `width` null forgets the session (the double-click reset).
* It writes the project's local state file, never a committed one.
*/
async function writeRowWidth(
req: IncomingMessage,
res: ServerResponse,
port: number,
): Promise<void> {
const write = await mapViewWrite(req, res, port);
if (write === null) return;
const { sessionId, width } = write.body;
if (
typeof sessionId !== "string" ||
!/^[A-Za-z0-9._:-]{1,128}$/.test(sessionId) ||
(width !== null &&
!(typeof width === "number" && Number.isInteger(width) && width > 0 && width <= 10_000))
) {
respond(res, 400, "expected { dir, sessionId, width }");
return;
}
try {
await setRowWidth(write.root, sessionId, width);
} catch {
respond(res, 500, "could not write the row width");
return;
}
res.writeHead(200, {
"content-type": "application/json",
"cache-control": "no-store",
});
res.end(JSON.stringify({ ok: true, sessionId, width }));
}
/**
* `POST /api/open-sessions` { dir, open }: the sessions open on the map, sent
* whenever one opens or closes, so a reload opens them again. It writes the
* project's local state file, never a committed one.
*/
async function writeOpenSessions(
req: IncomingMessage,
res: ServerResponse,
port: number,
): Promise<void> {
const write = await mapViewWrite(req, res, port);
if (write === null) return;
const { open } = write.body;
if (
!Array.isArray(open) ||
open.length > MAX_OPEN ||
!open.every((id) => typeof id === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(id))
) {
respond(res, 400, "expected { dir, open: [session ids] }");
return;
}
try {
await setOpenSessions(write.root, open as string[]);
} catch {
respond(res, 500, "could not write the open sessions");
return;
}
res.writeHead(200, {
"content-type": "application/json",
"cache-control": "no-store",
});
res.end(JSON.stringify({ ok: true, open }));
}
async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
const port = (server.address() as AddressInfo | null)?.port ?? opts.port;
if (req.method === "POST") {
if (!hostAllowed(req.headers.host, port)) {
respond(res, 403, "forbidden");
return;
}
const url = new URL(req.url ?? "/", `http://${HOST}:${port}`);
// `open` of a newer cogit retires a server of another version. Browsers
// always send Origin on a POST, so no web page can stop it.
if (url.pathname === "/api/stop") {
if (req.headers.origin !== undefined) {
respond(res, 403, "forbidden");
return;
}
respond(res, 200, "stopping");
void close();
return;
}
if (url.pathname === "/api/inbox/dismiss") {
await writeInboxDismiss(req, res, port);
return;
}
if (url.pathname === "/api/captures/state") {
await writeCaptureState(req, res, port);
return;
}
if (url.pathname === "/api/row-width") {
await writeRowWidth(req, res, port);
return;
}
if (url.pathname === "/api/open-sessions") {
await writeOpenSessions(req, res, port);
return;
}
if (url.pathname === "/api/shape/regenerate") {
await writeShapeRegenerate(req, res, port);
return;
}
if (url.pathname !== "/api/config") {
respond(res, 405, "method not allowed");
return;
}
await writeConfig(req, res, port);
return;
}
if (req.method !== "GET" && req.method !== "HEAD") {
respond(res, 405, "method not allowed");
return;
}
if (!hostAllowed(req.headers.host, port)) {
respond(res, 403, "forbidden");
return;
}
const url = new URL(req.url ?? "/", `http://${HOST}:${port}`);
if (url.pathname === "/api/diff") {
if (req.method !== "GET") {
respond(res, 405, "method not allowed");
return;
}
await readDiff(req, res, port, url);
return;
}
if (url.pathname === "/api/map-view") {
if (req.method !== "GET") {
respond(res, 405, "method not allowed");
return;
}
await readMapViewRequest(req, res, port, url);
return;
}
if (url.pathname === "/api/config") {
if (req.method !== "GET") {
respond(res, 405, "method not allowed");
return;
}
await readConfig(req, res, port);
return;
}
if (url.pathname === MERMAID_PATH) {
await serveMermaid(res, opts.mermaidFile ?? mermaidFile());
return;
}
if (url.pathname === "/health") {
res.writeHead(200, {
"content-type": "application/json",
"cache-control": "no-store",
});
res.end(
JSON.stringify({ ok: true, name: "cogit", home: globalPaths(env).base, version: VERSION }),
);
return;
}
const target = await pageTarget(env, url);
if (!target) {
respond(res, 404, "not found");
return;
}
if (url.pathname === "/events") {
res.writeHead(200, {
"content-type": "text/event-stream",
"cache-control": "no-cache",
connection: "keep-alive",
});
res.write("retry: 1000\n\n");
const page = watched(target.file, target.dir, target.root);
page.clients.add(res);
res.on("error", () => page.clients.delete(res));
openPages += 1;
clearIdle();
// The panel does not need the transcripts; a map page does (Story 9.5).
if (target.root !== undefined) startTranscriptWatch();
req.on("close", () => {
page.clients.delete(res);
release(target.file, page);
openPages = Math.max(0, openPages - 1);
if (!mapPagesOpen()) stopTranscriptWatch();
if (openPages === 0) scheduleIdle(idleMs);
});
return;
}
let html: string;
try {
html = await readFile(target.file, "utf8");
// A map another cogit wrote (an older plugin's hook, a server before an
// upgrade) would show that version's page; build it again with this one.
if (target.root !== undefined && builtBy(html) !== VERSION) {
await buildProject({ dir: target.root, io: buildIo, quiet: true }).catch(() => undefined);
html = await readFile(target.file, "utf8");
}
} catch {
respond(res, 404, "not found");
return;
}
res.writeHead(200, {
"content-type": "text/html; charset=utf-8",
"cache-control": "no-store",
});
res.end(req.method === "HEAD" ? undefined : injectTokenMeta(injectLiveMeta(html), token));
}
await new Promise<void>((done, fail) => {
const onError = (err: Error): void => fail(err);
server.once("error", onError);
server.listen(opts.port, hostname, () => {
server.off("error", onError);
done();
});
});
const port = (server.address() as AddressInfo).port;
const url = `http://${hostname}:${port}`;
function close(): Promise<void> {
if (closing) return closing;
closing = (async () => {
clearIdle();
stopTranscriptWatch();
for (const page of pages.values()) {
page.watcher?.close();
if (page.timer !== null) clearTimeout(page.timer);
for (const client of page.clients) client.end();
page.clients.clear();
}
pages.clear();
await new Promise<void>((done) => server.close(() => done()));
resolveClosed();
})();
return closing;
}
// Nothing may look at the page in the first moments after `open` spawns the
// server; the same idle rule covers that start.
scheduleIdle(idleMs);
return { port, host: hostname, url, close, closed };
}
interface HealthBody {
name?: unknown;
home?: unknown;
version?: unknown;
}
/** This user's cogit server on the port, with its version; undefined otherwise. */
async function serverVersion(url: string, env: NodeJS.ProcessEnv): Promise<string | undefined> {
try {
const response = await fetch(`${url}/health`, { signal: AbortSignal.timeout(500) });
if (!response.ok) return undefined;
const body = (await response.json()) as HealthBody;
if (body.name !== "cogit" || body.home !== globalPaths(env).base) return undefined;
return typeof body.version === "string" ? body.version : "";
} catch {
return undefined;
}
}
/**
* Asks a server of another cogit version (an upgrade left it running) to stop,
* so `open` does not serve pages with old code. A server too old to know the
* request keeps running; `open` then falls back to the file.
*/
export async function stopStaleServer(url: string, env: NodeJS.ProcessEnv): Promise<boolean> {
const version = await serverVersion(url, env);
if (version === undefined || version === VERSION) return false;
try {
const response = await fetch(`${url}/api/stop`, {
method: "POST",
signal: AbortSignal.timeout(500),
});
if (!response.ok) return false;
} catch {
return false;
}
for (let i = 0; i < 20; i++) {
await delay(50);
if ((await serverVersion(url, env)) === undefined) return true;
}
return false;
}
/**
* True when a cogit server for this user's home answers on the port. The
* home check keeps two users (or two `COGIT_HOME`s) apart on one port.
*/
export async function checkHealth(url: string, env: NodeJS.ProcessEnv): Promise<boolean> {
try {
const response = await fetch(`${url}/health`, { signal: AbortSignal.timeout(500) });
if (!response.ok) return false;
const body = (await response.json()) as HealthBody;
return body.name === "cogit" && body.home === globalPaths(env).base && body.version === VERSION;
} catch {
return false;
}
}
type SpawnFn = (command: string, args: string[], options: SpawnOptions) => { unref: () => void };
const systemSpawn: SpawnFn = (command, args, options) => spawn(command, args, options);
/** Starts `node <cli> serve --port <port>` detached, with hooks silenced in the child. */
export function spawnServerProcess(
cli: string,
port: number,
env: NodeJS.ProcessEnv,
spawnFn: SpawnFn = systemSpawn,
): void {
spawnFn(process.execPath, [cli, "serve", "--port", String(port)], {
detached: true,
stdio: "ignore",
env: { ...env, COGIT_DISABLE: "1" },
}).unref();
}
export interface EnsureServerDeps {
/** The CLI file the detached server runs; defaults to the running script. */
cli?: string;
/** Starts the detached server; tests observe instead of spawning. */
spawn?: (cli: string, port: number, env: NodeJS.ProcessEnv) => void;
/** Health probe; tests replace the network with a function. */
health?: (url: string, env: NodeJS.ProcessEnv) => Promise<boolean>;
/** Retires a server of another version before a new one starts. */
stopStale?: (url: string, env: NodeJS.ProcessEnv) => Promise<boolean>;
/** How long to wait for a spawned server before giving up. */
waitMs?: number;
}
function delay(ms: number): Promise<void> {
return new Promise((done) => setTimeout(done, ms));
}
/**
* Returns the base URL of a running map server for this user, starting one
* detached when needed. Null means "cannot have a server" (the port answers as
* something else, or the child never came up): the caller opens the file.
*/
export async function ensureServer(
env: NodeJS.ProcessEnv,
deps: EnsureServerDeps = {},
): Promise<string | null> {
const { serverPort } = await loadConfig(env);
const base = `http://${HOST}:${serverPort}`;
const health = deps.health ?? checkHealth;
if (await health(base, env)) return base;
await (deps.stopStale ?? stopStaleServer)(base, env);
const cli = deps.cli ?? process.argv[1] ?? fileURLToPath(import.meta.url);
(deps.spawn ?? spawnServerProcess)(cli, serverPort, env);
const deadline = Date.now() + (deps.waitMs ?? START_WAIT_MS);
while (Date.now() < deadline) {
await delay(50);
if (await health(base, env)) return base;
}
return null;
}