akm-cli 0.10.261005-beta → 0.10.261007-beta

package/dist/commands/ui/proposal-actions.js

@@ -0,0 +1,179 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The only writes `akm ui` makes: accept and reject a proposal, and accept
+ * several at once. Each handler calls the function `akm proposal accept` /
+ * `reject` calls, with the arguments the CLI passes, so a UI decision is
+ * recorded exactly like a CLI one (same state.db rows, events and commit).
+ *
+ * The server decides whether a request may reach this module (token header,
+ * Origin, content type, body size); see `server.ts`. Everything else in the UI
+ * stays read-only and lives in `api.ts`.
+ */
+import { AkmError, TransientError, UsageError } from "../../core/errors.js";
+import { acquireAssetMutationLease } from "../../indexer/index-writer-lock.js";
+import { akmProposalAccept, akmProposalAcceptMany, akmProposalReject, } from "../proposal/proposal.js";
+import { proposalSummary } from "./api.js";
+import { readBundleGitStatus } from "./git-read.js";
+export const MAX_REJECT_REASON = 2000;
+export const MAX_BATCH_IDS = 200;
+/** The three POST paths the UI may write through; `null` for anything else. */
+export function matchWriteRoute(pathname) {
+    if (pathname === "/api/proposals/accept")
+        return { kind: "accept-many" };
+    const match = /^\/api\/proposals\/([^/]+)\/(accept|reject)$/.exec(pathname);
+    if (!match)
+        return null;
+    let id;
+    try {
+        id = decodeURIComponent(match[1]);
+    }
+    catch {
+        return null;
+    }
+    return { kind: match[2], id };
+}
+// ── Errors ───────────────────────────────────────────────────────────────────
+const STALE_MESSAGE = /target (?:changed after|was created after) proposal|^Retire proposal \S+ (?:target \(.*\) no longer exists|is stale )/;
+const NOT_PENDING_MESSAGE = /is not pending \(current status/;
+const LEASE_MESSAGE = /timed out waiting for asset mutation lease/;
+const NOT_FOUND_MESSAGE = /^Proposal ".*" not found|^No proposal found for ref/;
+/** A stable code for an error the accept path reports only as text (a failed id inside a batch). */
+function codeForMessage(message) {
+    if (STALE_MESSAGE.test(message))
+        return "PROPOSAL_STALE";
+    if (NOT_PENDING_MESSAGE.test(message))
+        return "PROPOSAL_NOT_PENDING";
+    if (LEASE_MESSAGE.test(message))
+        return "ASSET_MUTATION_LEASE_HELD";
+    if (NOT_FOUND_MESSAGE.test(message))
+        return "PROPOSAL_NOT_FOUND";
+    return null;
+}
+/** HTTP status and code for an error thrown by an accept or reject: 409 stale, not pending or lease held; 404; 400. */
+export function classifyProposalError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const byMessage = codeForMessage(message);
+    if (error instanceof AkmError) {
+        if (byMessage === "PROPOSAL_STALE" || byMessage === "PROPOSAL_NOT_PENDING") {
+            return { status: 409, code: byMessage, message };
+        }
+        switch (error.kind) {
+            case "transient":
+                return { status: 409, code: error.code, message };
+            case "not-found":
+                return { status: 404, code: error.code, message };
+            case "usage":
+                return { status: 400, code: error.code, message };
+            default:
+                return { status: 500, code: error.code, message };
+        }
+    }
+    if (byMessage === "ASSET_MUTATION_LEASE_HELD")
+        return { status: 409, code: byMessage, message };
+    return { status: 500, code: "INTERNAL_ERROR", message };
+}
+// ── Input ────────────────────────────────────────────────────────────────────
+function bodyObject(body) {
+    if (body === undefined || body === null)
+        return {};
+    if (typeof body !== "object" || Array.isArray(body)) {
+        throw new UsageError("The request body must be a JSON object.", "INVALID_JSON_ARGUMENT");
+    }
+    return body;
+}
+function rejectReason(body) {
+    const reason = bodyObject(body).reason;
+    if (typeof reason !== "string" || reason.trim() === "") {
+        throw new UsageError('A rejection needs a reason: {"reason": "..."}.', "MISSING_REQUIRED_ARGUMENT");
+    }
+    const trimmed = reason.trim();
+    if (trimmed.length > MAX_REJECT_REASON) {
+        throw new UsageError(`The reason is too long (${trimmed.length} characters; at most ${MAX_REJECT_REASON}).`);
+    }
+    return trimmed;
+}
+function batchIds(body) {
+    const ids = bodyObject(body).ids;
+    if (!Array.isArray(ids) || ids.length === 0 || ids.length > MAX_BATCH_IDS) {
+        throw new UsageError(`"ids" must be a list of 1 to ${MAX_BATCH_IDS} proposal ids.`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    for (const id of ids) {
+        if (typeof id !== "string" || id.trim() === "" || id.length > 200) {
+            throw new UsageError('Every entry of "ids" must be a non-empty proposal id string.');
+        }
+    }
+    return [...new Set(ids.map((id) => id.trim()))];
+}
+// ── Execution ────────────────────────────────────────────────────────────────
+/**
+ * Fail fast when another writer holds the asset-mutation lease. The accept and
+ * reject functions would wait up to ten minutes for it, which in a browser is a
+ * hung button; the probe turns a held lease into an immediate, retryable 409.
+ */
+async function assertWriteLeaseFree(purpose) {
+    const lease = await acquireAssetMutationLease({ mode: "try", purpose });
+    if (!lease) {
+        throw new TransientError("Another akm process or request is writing to the bundle right now. Try again in a moment.", "ASSET_MUTATION_LEASE_HELD");
+    }
+    lease.release();
+}
+/**
+ * The commit an accept just made, if any. The accept functions do not return it,
+ * so read the head commit of each accepted proposal's repository and keep one
+ * that carries akm's accept subject and is newer than the request. `null` for a
+ * bundle that is not a git repository (nothing was committed).
+ */
+async function acceptCommit(accepted, startedMs) {
+    const roots = new Set();
+    for (const result of accepted) {
+        const root = result.proposal.acceptedTarget?.root;
+        if (root)
+            roots.add(root);
+    }
+    for (const root of roots) {
+        const last = (await readBundleGitStatus(root))?.lastCommit;
+        if (!last || !/^akm (?:proposal )?accept:/.test(last.subject))
+            continue;
+        if (Date.parse(last.time) < startedMs - 2000)
+            continue;
+        return { ...last, repo: root };
+    }
+    return null;
+}
+function acceptedView(result) {
+    return { ...result, proposal: proposalSummary(result.proposal) };
+}
+function failedView(failure) {
+    return { ...failure, code: codeForMessage(failure.error) ?? "ACCEPT_FAILED" };
+}
+/** Run one of the three write routes; errors propagate for the server to classify with {@link classifyProposalError}. */
+export async function handleWriteRequest(route, body) {
+    const startedMs = Date.now();
+    switch (route.kind) {
+        case "accept": {
+            await assertWriteLeaseFree("ui-proposal-accept");
+            const result = await akmProposalAccept({ id: route.id });
+            return { ...acceptedView(result), commit: await acceptCommit([result], startedMs) };
+        }
+        case "reject": {
+            const reason = rejectReason(body);
+            await assertWriteLeaseFree("ui-proposal-reject");
+            const result = await akmProposalReject({ id: route.id, reason });
+            return { ...result, proposal: proposalSummary(result.proposal) };
+        }
+        case "accept-many": {
+            const ids = batchIds(body);
+            await assertWriteLeaseFree("ui-proposal-accept");
+            const results = await akmProposalAcceptMany({ ids });
+            const accepted = results.filter((r) => r.ok);
+            return {
+                accepted: accepted.length,
+                failed: results.length - accepted.length,
+                results: results.map((r) => (r.ok ? acceptedView(r) : failedView(r))),
+                commit: accepted.length > 0 ? await acceptCommit(accepted, startedMs) : null,
+            };
+        }
+    }
+}

package/dist/commands/ui/redact.js

@@ -0,0 +1,88 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Redaction for `akm ui`'s config view. Starts from `listConfig` (which already
+ * drops literal `apiKey` values and normalises registry URLs) and then masks
+ * anything secret-like by key name, because the UI shows config the CLI's
+ * `config list` never had to defend against a browser leaking.
+ *
+ * Symbolic references (`$VAR`, `${VAR}`, `secret://name`) are kept: they say
+ * where a credential comes from without being one.
+ */
+const REDACTED = "[redacted]";
+/** Key names whose string values are credentials, or sit in a bag of them. */
+const SECRET_KEY = /(api[-_]?key|token|password|passwd|secret|credential|authorization|bearer|private[-_]?key)/i;
+/** A whole subtree of values (`env`, `secrets`) that is data, not settings. */
+const SECRET_BAG_KEY = /^(env|secrets?)$/i;
+const SYMBOLIC_REFERENCE = /^(\$[A-Za-z_][A-Za-z0-9_]*|\$\{[A-Za-z_][A-Za-z0-9_]*\}|secret:\/\/.+)$/;
+/** Query parameters that carry a credential in a URL. */
+const SECRET_QUERY_PARAM = /^(api[-_]?key|key|token|access[-_]?token|auth|password|secret|sig|signature)$/i;
+/** `scheme://user:pass@host/?token=x` with the credentials masked. Anything that is not a URL is returned as is. */
+export function redactUrlCredentials(value) {
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(value))
+        return value;
+    try {
+        const url = new URL(value);
+        let changed = false;
+        if (url.username || url.password) {
+            url.username = "";
+            url.password = "";
+            changed = true;
+        }
+        for (const key of [...url.searchParams.keys()]) {
+            if (SECRET_QUERY_PARAM.test(key)) {
+                url.searchParams.set(key, REDACTED);
+                changed = true;
+            }
+        }
+        return changed ? url.toString() : value;
+    }
+    catch {
+        return value;
+    }
+}
+/** `text` with the credentials in every URL it contains masked (`llm default: https://host/?token=x`). */
+export function redactUrlsInText(text) {
+    return text.includes("://") ? text.replace(/https?:\/\/[^\s"'<>)\]]+/gi, (url) => redactUrlCredentials(url)) : text;
+}
+/**
+ * Deep copy of an API response with the credentials in any URL masked. The
+ * last line of defence for every endpoint: health and metrics evidence quotes
+ * configured endpoints verbatim, and a configured URL can carry a token.
+ */
+export function scrubUrlCredentials(value) {
+    if (typeof value === "string")
+        return redactUrlsInText(value);
+    if (Array.isArray(value))
+        return value.map(scrubUrlCredentials);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, scrubUrlCredentials(child)]));
+}
+/** Deep copy of `value` with every secret-like string masked. */
+export function redactForUi(value, inSecretBag = false) {
+    if (Array.isArray(value))
+        return value.map((child) => redactForUi(child, inSecretBag));
+    if (typeof value === "string") {
+        if (SYMBOLIC_REFERENCE.test(value))
+            return value;
+        return inSecretBag ? REDACTED : redactUrlCredentials(value);
+    }
+    if (!value || typeof value !== "object")
+        return inSecretBag && value !== null ? REDACTED : value;
+    const result = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (typeof child === "string" && SECRET_KEY.test(key) && !SYMBOLIC_REFERENCE.test(child)) {
+            result[key] = REDACTED;
+        }
+        else {
+            result[key] = redactForUi(child, inSecretBag || SECRET_BAG_KEY.test(key));
+        }
+    }
+    return result;
+}
+/** Whether an environment variable name looks like it holds a credential. */
+export function isSecretEnvName(name) {
+    return SECRET_KEY.test(name);
+}

package/dist/commands/ui/server.js

@@ -0,0 +1,352 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The HTTP server behind `akm ui`: `node:http` so one implementation serves
+ * Bun, Node and the compiled binary alike.
+ *
+ * Trust model: the server is for the person at this machine. It binds loopback
+ * by default, every `/api/` request must carry the per-launch token, and the
+ * `Host` header must be the address the server is bound to, which stops a web
+ * page from reaching it through DNS rebinding. Static UI files are served
+ * without the token and embed no data. Only GET (and HEAD) is accepted, except
+ * for the three proposal writes (accept, reject, accept several): a POST to one
+ * of those must carry the token in the `X-Akm-Ui-Token` header (never the
+ * query string), a JSON content type and an `Origin` that is this server's own,
+ * so another web page cannot make the browser send one.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import appJs from "../../assets/ui/app.js" with { type: "text" };
+import assetJs from "../../assets/ui/asset.js" with { type: "text" };
+import bundlesJs from "../../assets/ui/bundles.js" with { type: "text" };
+import changesJs from "../../assets/ui/changes.js" with { type: "text" };
+import chartsJs from "../../assets/ui/charts.js" with { type: "text" };
+import configJs from "../../assets/ui/config.js" with { type: "text" };
+import diffJs from "../../assets/ui/diff.js" with { type: "text" };
+import diffViewJs from "../../assets/ui/diff-view.js" with { type: "text" };
+import indexHtml from "../../assets/ui/index.html" with { type: "text" };
+import libJs from "../../assets/ui/lib.js" with { type: "text" };
+import markdownJs from "../../assets/ui/markdown.js" with { type: "text" };
+import overviewJs from "../../assets/ui/overview.js" with { type: "text" };
+import proposalActionsJs from "../../assets/ui/proposal-actions.js" with { type: "text" };
+import proposalsJs from "../../assets/ui/proposals.js" with { type: "text" };
+import searchJs from "../../assets/ui/search.js" with { type: "text" };
+import stylesCss from "../../assets/ui/styles.css" with { type: "text" };
+import { AkmError } from "../../core/errors.js";
+import { getDirname } from "../../runtime.js";
+import { handleApiRequest, NO_SUCH_ROUTE } from "./api.js";
+import { classifyProposalError, handleWriteRequest, matchWriteRoute } from "./proposal-actions.js";
+import { scrubUrlCredentials } from "./redact.js";
+export const TOKEN_HEADER = "x-akm-ui-token";
+/** Largest request body a write route reads. */
+export const MAX_BODY_BYTES = 64 * 1024;
+const UI_DIR = path.join(getDirname(import.meta.url), "../../assets/ui");
+/**
+ * The UI files embedded at build time. Disk stays primary (an edit shows
+ * without a rebuild, and files added beside these are served from disk), the
+ * embedded copy covers the compiled standalone binary, where `assets/ui` is not
+ * on any real filesystem. Same arrangement as the HTML report templates in
+ * `src/output/html-render.ts`. A file the standalone binary must serve has to be
+ * imported above and listed here.
+ */
+export const EMBEDDED_UI = {
+    "index.html": indexHtml,
+    "app.js": appJs,
+    "asset.js": assetJs,
+    "bundles.js": bundlesJs,
+    "changes.js": changesJs,
+    "charts.js": chartsJs,
+    "config.js": configJs,
+    "diff-view.js": diffViewJs,
+    "diff.js": diffJs,
+    "lib.js": libJs,
+    "markdown.js": markdownJs,
+    "overview.js": overviewJs,
+    "proposal-actions.js": proposalActionsJs,
+    "proposals.js": proposalsJs,
+    "search.js": searchJs,
+    "styles.css": stylesCss,
+};
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".txt": "text/plain; charset=utf-8",
+};
+/**
+ * Same-origin only: the UI is plain files with no network access of its own
+ * (nothing is fetched at runtime). Inline styles are allowed so a chart can set
+ * a computed colour; inline scripts are not.
+ */
+const STATIC_CSP = "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; " +
+    "connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+const SECURITY_HEADERS = {
+    "Cache-Control": "no-store",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+};
+/** Whether `host` binds every interface, so the `Host` header can be any address of this machine. */
+function isWildcardHost(host) {
+    return host === "0.0.0.0" || host === "::" || host === "[::]";
+}
+function isLoopbackHost(host) {
+    return host === "localhost" || host === "::1" || host === "[::1]" || /^127\./.test(host);
+}
+/** `host` as it appears in a URL or a `Host` header (IPv6 literals in brackets). */
+function urlHost(host) {
+    return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+export function isLoopbackBind(host) {
+    return isLoopbackHost(host);
+}
+function hostAllowed(header, host, port) {
+    if (!header)
+        return false;
+    const given = header.toLowerCase();
+    if (given === `${urlHost(host).toLowerCase()}:${port}`)
+        return true;
+    if (!isWildcardHost(host))
+        return false;
+    // A wildcard bind is reached by whatever address the machine has; DNS names stay refused (rebinding uses names).
+    const match = /^(\[[0-9a-f:.]+\]|\d{1,3}(?:\.\d{1,3}){3}):(\d+)$/.exec(given);
+    return match !== null && Number(match[2]) === port;
+}
+function tokenMatches(given, expected) {
+    if (!given)
+        return false;
+    // Hash both so the comparison is constant-time whatever the lengths.
+    return timingSafeEqual(createHash("sha256").update(given).digest(), createHash("sha256").update(expected).digest());
+}
+function sendJson(req, res, status, body, extra = {}) {
+    const payload = JSON.stringify(body, (_key, value) => (typeof value === "bigint" ? Number(value) : value));
+    res.writeHead(status, {
+        ...SECURITY_HEADERS,
+        ...extra,
+        "Content-Type": "application/json; charset=utf-8",
+        "Content-Length": Buffer.byteLength(payload),
+    });
+    res.end(req.method === "HEAD" ? undefined : payload);
+}
+function sendError(req, res, status, code, error, extra = {}) {
+    sendJson(req, res, status, { ok: false, error, code }, extra);
+}
+/** Whether `origin` is this server's own origin: the validated `Host` over plain http. */
+function originAllowed(origin, hostHeader) {
+    if (!origin || !hostHeader)
+        return false;
+    return origin.toLowerCase() === `http://${hostHeader.toLowerCase()}`;
+}
+function isJsonContentType(header) {
+    return (header ?? "").split(";")[0]?.trim().toLowerCase() === "application/json";
+}
+/** The request body as text, or `null` when it is larger than {@link MAX_BODY_BYTES}. */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const declared = Number(req.headers["content-length"]);
+        if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+            resolve(null);
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        let tooLarge = false;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES)
+                tooLarge = true;
+            else
+                chunks.push(chunk);
+        });
+        req.on("end", () => resolve(tooLarge ? null : Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+/** HTTP status for an error thrown by an API handler: the CLI's error classes, mapped. */
+function statusFor(error) {
+    if (!(error instanceof AkmError))
+        return 500;
+    switch (error.kind) {
+        case "usage":
+            return 400;
+        case "not-found":
+            return 404;
+        case "transient":
+            return 503;
+        default:
+            return 500;
+    }
+}
+/** The file `urlPath` names under the UI directory, or the embedded copy; `null` when there is none. */
+function readUiAsset(urlPath) {
+    let relative;
+    try {
+        relative = decodeURIComponent(urlPath).replace(/^\/+/, "");
+    }
+    catch {
+        return null;
+    }
+    if (relative === "")
+        relative = "index.html";
+    if (relative.includes("\0") || relative.includes("\\"))
+        return null;
+    const resolved = path.resolve(UI_DIR, relative);
+    const inside = path.relative(UI_DIR, resolved);
+    if (inside === "" || inside.startsWith("..") || path.isAbsolute(inside))
+        return null;
+    const type = CONTENT_TYPES[path.extname(resolved).toLowerCase()];
+    if (!type)
+        return null;
+    try {
+        if (fs.statSync(resolved).isFile())
+            return { body: fs.readFileSync(resolved), type };
+    }
+    catch {
+        // Not on disk: fall back to the embedded copy below.
+    }
+    const embedded = EMBEDDED_UI[inside.split(path.sep).join("/")];
+    return embedded === undefined ? null : { body: embedded, type };
+}
+export async function startUiServer(options = {}) {
+    const host = options.host ?? "127.0.0.1";
+    const token = options.token ?? randomBytes(24).toString("base64url");
+    const startedAt = new Date().toISOString();
+    // Filled in once the socket is listening; requests cannot arrive before that.
+    let info = { startedAt, host, port: 0 };
+    const server = http.createServer((req, res) => {
+        void handle(req, res).catch((error) => {
+            if (res.headersSent) {
+                res.destroy();
+                return;
+            }
+            sendError(req, res, 500, "INTERNAL_ERROR", error instanceof Error ? error.message : String(error));
+        });
+    });
+    async function handle(req, res) {
+        if (!hostAllowed(req.headers.host, host, info.port)) {
+            sendError(req, res, 403, "HOST_NOT_ALLOWED", "The Host header does not match the address akm ui is bound to.");
+            return;
+        }
+        const url = new URL(req.url ?? "/", "http://akm-ui.invalid");
+        const isApi = url.pathname === "/api" || url.pathname.startsWith("/api/");
+        const writeRoute = req.method === "POST" ? matchWriteRoute(url.pathname) : null;
+        if (writeRoute) {
+            await handleWrite(req, res, writeRoute);
+            return;
+        }
+        // Only a GET of a static file is open; the API, and anything that is not a GET, needs the token.
+        const readMethod = req.method === "GET" || req.method === "HEAD";
+        if (isApi || !readMethod) {
+            const given = req.headers[TOKEN_HEADER];
+            const provided = (Array.isArray(given) ? given[0] : given) ?? url.searchParams.get("token");
+            if (!tokenMatches(provided, token)) {
+                sendError(req, res, 401, "UNAUTHORIZED", "Missing or invalid session token.", {
+                    "WWW-Authenticate": "X-Akm-Ui-Token",
+                });
+                return;
+            }
+        }
+        if (!readMethod) {
+            sendError(req, res, 405, "METHOD_NOT_ALLOWED", "Only GET is accepted here. akm ui writes only through POST /api/proposals/:id/accept, /reject and /api/proposals/accept.", {
+                Allow: "GET, HEAD",
+            });
+            return;
+        }
+        if (isApi) {
+            try {
+                const data = await handleApiRequest(url.pathname, url.searchParams, info);
+                if (data === NO_SUCH_ROUTE) {
+                    sendError(req, res, 404, "NOT_FOUND", `No such API route: ${url.pathname}`);
+                    return;
+                }
+                sendJson(req, res, 200, { ok: true, data: scrubUrlCredentials(data) });
+            }
+            catch (error) {
+                const code = error instanceof AkmError ? error.code : "INTERNAL_ERROR";
+                sendError(req, res, statusFor(error), code, error instanceof Error ? error.message : String(error));
+            }
+            return;
+        }
+        const asset = readUiAsset(url.pathname);
+        if (!asset) {
+            sendError(req, res, 404, "NOT_FOUND", `No such file: ${url.pathname}`);
+            return;
+        }
+        res.writeHead(200, {
+            ...SECURITY_HEADERS,
+            "Content-Type": asset.type,
+            "Content-Length": Buffer.byteLength(asset.body),
+            "Content-Security-Policy": STATIC_CSP,
+        });
+        res.end(req.method === "HEAD" ? undefined : asset.body);
+    }
+    /** The three proposal writes. Every check runs before the body is read. */
+    async function handleWrite(req, res, route) {
+        // The header only: a token in the URL ends up in history and logs, and a link can carry it.
+        const given = req.headers[TOKEN_HEADER];
+        if (!tokenMatches(Array.isArray(given) ? given[0] : given, token)) {
+            sendError(req, res, 401, "UNAUTHORIZED", "Writes need the session token in the X-Akm-Ui-Token header.", {
+                "WWW-Authenticate": "X-Akm-Ui-Token",
+            });
+            return;
+        }
+        if (!originAllowed(req.headers.origin, req.headers.host)) {
+            sendError(req, res, 403, "ORIGIN_NOT_ALLOWED", "The Origin header must be the address akm ui is serving.");
+            return;
+        }
+        if (!isJsonContentType(req.headers["content-type"])) {
+            sendError(req, res, 415, "UNSUPPORTED_MEDIA_TYPE", "Writes must be sent as Content-Type: application/json.");
+            return;
+        }
+        const text = await readBody(req);
+        if (text === null) {
+            sendError(req, res, 413, "BODY_TOO_LARGE", `The request body is larger than ${MAX_BODY_BYTES} bytes.`, {
+                Connection: "close",
+            });
+            return;
+        }
+        let body;
+        try {
+            body = text.trim() === "" ? undefined : JSON.parse(text);
+        }
+        catch {
+            sendError(req, res, 400, "INVALID_JSON_ARGUMENT", "The request body is not valid JSON.");
+            return;
+        }
+        try {
+            const data = await handleWriteRequest(route, body);
+            sendJson(req, res, 200, { ok: true, data: scrubUrlCredentials(data) });
+        }
+        catch (error) {
+            const { status, code, message } = classifyProposalError(error);
+            sendError(req, res, status, code, message);
+        }
+    }
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? 0, host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const port = server.address().port;
+    info = { startedAt, host, port };
+    return {
+        ...info,
+        token,
+        url: `http://${urlHost(host)}:${port}/?token=${token}`,
+        close: () => new Promise((resolve) => {
+            // Keep-alive sockets would hold close() open until they time out.
+            server.closeAllConnections?.();
+            server.close(() => resolve());
+        }),
+    };
+}

package/dist/commands/ui/ui-cli.js

@@ -0,0 +1,62 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm ui` — a local web UI, read-only apart from accepting and rejecting proposals, over the same data the CLI reports:
+ * health and metrics, bundles, config, the proposal queue, recent changes and
+ * search. See `docs/reference/ui-api.md` for the API the page reads.
+ */
+import { defineJsonCommand } from "../../cli/shared.js";
+import { UsageError } from "../../core/errors.js";
+import { info, warn } from "../../core/warn.js";
+import { openBrowser } from "./open-browser.js";
+import { isLoopbackBind, startUiServer } from "./server.js";
+function parsePort(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return 0;
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed) || Number(trimmed) > 65535) {
+        throw new UsageError(`Invalid --port value: "${raw}". Must be a port number from 0 to 65535.`, "INVALID_FLAG_VALUE");
+    }
+    return Number(trimmed);
+}
+export const uiCommand = defineJsonCommand({
+    meta: {
+        name: "ui",
+        description: "Experimental: serve a local web UI (health, bundles, config, proposals, recent changes, search) and open it in your browser. It is read-only except that you can accept and reject proposals in it. The URL carries a per-launch token. Press Ctrl-C to stop.",
+    },
+    args: {
+        port: { type: "string", description: "Port to listen on (default: a random free port)" },
+        host: { type: "string", description: "Address to bind (default 127.0.0.1; anything else exposes the stash)" },
+        // citty treats `--no-open` as the negation of `open`; declare the positive flag (see `akm health --probe`).
+        open: {
+            type: "boolean",
+            default: true,
+            description: "Open the UI in your default browser (on by default).",
+            negativeDescription: "Print the URL without opening a browser.",
+        },
+    },
+    async run({ args }) {
+        const host = args.host?.trim() || "127.0.0.1";
+        const server = await startUiServer({ host, port: parsePort(args.port) });
+        if (!isLoopbackBind(host)) {
+            warn(`[ui] Listening on ${host}, not just this machine: anyone who can reach it and has the token can read your stash, config and proposals. Keep the URL private.`);
+        }
+        // The URL is the command's output, so it goes to stdout like any other result.
+        process.stdout.write(`akm ui: ${server.url}\n`);
+        info("Press Ctrl-C to stop.");
+        if (args.open !== false && !(await openBrowser(server.url))) {
+            info("Could not open a browser; open the URL above yourself.");
+        }
+        await new Promise((resolve) => {
+            const stop = () => {
+                process.off("SIGINT", stop);
+                process.off("SIGTERM", stop);
+                resolve();
+            };
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+        });
+        await server.close();
+    },
+});