toolroll 0.9.92 → 0.9.94

package/dist/code-map-build.js

@@ -0,0 +1,415 @@
+/**
+ * One check of a project's recorded remote main, and the build of a new map when it moved (docs/plans/code-map.md §1-2).
+ * Toolroll's own code, in the worker: raw blobs from a private depth-1 folder, a static parse in a bounded child, no
+ * agent, no model and nothing from the repository run. The remote identity is captured first and carried unchanged to
+ * publication. Every write after the lease is fenced; a worker that lost its lease drops its result.
+ */
+import { createRequire } from "node:module";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { boundedRun, cleanupLeftover } from "./bounded-spawn.js";
+import { buildCodeMap, EXTRACTOR_TAG, externalPackage, isParsedLanguage, LIMITS, manifestEntries, unsafeName, vendoredRoot } from "./code-map-shape.js";
+import { clearOldSpawn, clearRequest, CODE_MAP_ACT, codeMapOn, currentVersion, digestOfUrl, encodeMap, extendLease, publishVersion, readRefresh, recordCheck, recordFailure, recordFolder, recordPeek, recordSpawn, releaseLease, takeLease, tidyVersions } from "./code-map-store.js";
+import { scanForSecrets } from "./evidence.js";
+import { run } from "./exec.js";
+import { pinDestination, lookupAll } from "./remote-destination.js";
+import { initPrivateDir, mapGitArgs, mapGitEnv, peekMain, readShallowMain, remoteUrlProblem } from "./remote-main.js";
+import { trustedRemoteIdentity } from "./store.js";
+export const REFRESH_EVERY_MS = 30 * 60_000;
+let extractorName = null;
+/** Pinned by the parser's own package: a parser bump rebuilds every map. */
+export function currentExtractor() {
+    if (extractorName !== null)
+        return extractorName;
+    const require = createRequire(import.meta.url);
+    const { version } = JSON.parse(readFileSync(require.resolve("typescript-parser/package.json"), "utf8"));
+    return extractorName = `typescript-parser@${version}/${EXTRACTOR_TAG}`;
+}
+let pinProven = null;
+/** Connect a pinned name that can't resolve to a local listener: only a libcurl that honours the pin reaches it. */
+export async function curlPinWorks() {
+    if (pinProven !== null)
+        return pinProven;
+    let hits = 0;
+    const server = createServer((_request, response) => { hits++; response.writeHead(404); response.end(); });
+    const port = await new Promise(done => {
+        server.once("error", () => done(null));
+        server.listen(0, "127.0.0.1", () => { const held = server.address(); done(typeof held === "object" && held !== null ? held.port : null); });
+    });
+    if (port === null)
+        return false;
+    try {
+        const host = "toolroll-pin-check.invalid";
+        await run("git", ["-c", "protocol.allow=always", "-c", `http.curloptResolve=${host}:${port}:127.0.0.1`, "ls-remote", "--", `http://${host}:${port}/x.git`], { cwd: "/", envAllowlist: ["PATH", "HOME"], env: { GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_TERMINAL_PROMPT: "0" }, timeoutMs: 10_000 });
+    }
+    finally {
+        server.closeAllConnections();
+        server.close();
+    }
+    return pinProven = hits > 0;
+}
+// ---- reading the tree --------------------------------------------------------------------------------------------
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+const textOf = (bytes) => { try {
+    return bytes.includes(0) ? null : utf8.decode(bytes);
+}
+catch {
+    return null;
+} };
+export function parseTree(output) {
+    const entries = [];
+    let at = 0;
+    while (at < output.length) {
+        let end = output.indexOf(0, at);
+        if (end < 0)
+            end = output.length;
+        const tab = output.indexOf(0x09, at);
+        if (tab > at && tab < end) {
+            const head = /^(\d{6}) (\w+) ([0-9a-f]{40,64}) +(\d+|-)$/.exec(output.subarray(at, tab).toString("latin1"));
+            if (head !== null) {
+                let path = null;
+                try {
+                    path = utf8.decode(output.subarray(tab + 1, end));
+                }
+                catch {
+                    path = null;
+                }
+                entries.push({ path, mode: head[1], kind: head[2], oid: head[3], bytes: head[4] === "-" ? 0 : Number(head[4]) });
+            }
+        }
+        at = end + 1;
+    }
+    return entries;
+}
+const pathRefused = (path) => {
+    if (path === null || unsafeName(path) || Buffer.byteLength(path) > LIMITS.pathBytes)
+        return true;
+    const parts = path.split("/");
+    return parts.length - 1 > LIMITS.pathDepth || parts.some(part => part === "" || part === "." || part === ".." || part.toLowerCase() === ".git");
+};
+/** Which of `names` a secret scan flags, by one scan over all of them. */
+function flagged(names) {
+    return new Set(scanForSecrets(names.join("\n")).map(hit => hit.line - 1));
+}
+async function readBlobs(dir, pin, bounded, wanted) {
+    const found = new Map();
+    const batches = [];
+    let batch = [], size = 0;
+    for (const one of wanted) {
+        if (batch.length > 0 && (batch.length >= 500 || size + one.bytes > 8 * 1024 * 1024)) {
+            batches.push(batch);
+            batch = [];
+            size = 0;
+        }
+        batch.push(one);
+        size += one.bytes;
+    }
+    if (batch.length > 0)
+        batches.push(batch);
+    for (const group of batches) {
+        const ran = await bounded("git", mapGitArgs(dir, pin, ["cat-file", "--batch"]), { cwd: dir, env: mapGitEnv(pin), stdin: Buffer.from(`${group.map(one => one.oid).join("\n")}\n`),
+            timeoutMs: 60_000, maxStdout: 8 * 1024 * 1024 + LIMITS.fileBytes + group.length * 128 + 4096, maxStderr: 4096, label: "code-map-blobs" });
+        if (ran.code !== 0)
+            throw new MapRefused("couldn't read main: its files couldn't be read", "failed");
+        let at = 0;
+        for (const one of group) {
+            const end = ran.stdout.indexOf(0x0a, at);
+            if (end < 0)
+                throw new MapRefused("couldn't read main: its files couldn't be read", "failed");
+            const head = /^([0-9a-f]{40,64}) (\w+) (\d+)$/.exec(ran.stdout.subarray(at, end).toString("latin1"));
+            if (head === null) {
+                at = end + 1;
+                continue;
+            }
+            const bytes = Number(head[3]);
+            if (head[1] === one.oid && head[2] === "blob" && bytes <= LIMITS.fileBytes)
+                found.set(one.path, ran.stdout.subarray(end + 1, end + 1 + bytes));
+            at = end + 1 + bytes + 1;
+        }
+    }
+    return found;
+}
+/** A failed build's reason, in the words the page shows, and the state it reads as. */
+export class MapRefused extends Error {
+    state;
+    constructor(message, state) {
+        super(message);
+        this.state = state;
+    }
+}
+/** The parser process's entry, from the installed release (the sources under a test). */
+export function parserEntry() {
+    const source = import.meta.url.endsWith(".ts");
+    const entry = fileURLToPath(new URL(source ? "./code-map-main.ts" : "./code-map-main.js", import.meta.url));
+    return { file: process.execPath, args: [`--max-old-space-size=${LIMITS.parserHeapMb}`, ...(source ? ["--import", import.meta.resolve("tsx")] : []), entry] };
+}
+async function parseBlobs(dir, bounded, files, paths, tsconfig, entry) {
+    const ran = await bounded(entry.file, entry.args, { cwd: dir, env: { PATH: process.env["PATH"] ?? "/usr/bin:/bin", HOME: dir }, stdin: Buffer.from(JSON.stringify({ files, paths, tsconfig })),
+        timeoutMs: LIMITS.parserMs, maxStdout: LIMITS.parserOutput, maxStderr: 4096, memoryBytes: 1024 ** 3, label: "code-map-parse" });
+    if (ran.code !== 0 || ran.killed !== null)
+        throw new MapRefused("couldn't finish reading", "failed");
+    try {
+        return JSON.parse(ran.stdout.toString("utf8"));
+    }
+    catch {
+        throw new MapRefused("couldn't finish reading", "failed");
+    }
+}
+/** Everything between a clean private folder and a map. Throws MapRefused when no new version can come of it. */
+export async function buildFromFolder(dir, pin, bounded, context, entry = parserEntry()) {
+    const listed = await bounded("git", mapGitArgs(dir, pin, ["ls-tree", "-r", "-l", "-z", context.commit]), { cwd: dir, env: mapGitEnv(pin), timeoutMs: 60_000, maxStdout: 16 * 1024 * 1024, maxStderr: 4096, label: "code-map-tree" });
+    if (listed.killed === "output")
+        throw new MapRefused(`too large: more than ${LIMITS.treeEntries.toLocaleString("en-US")} files`, "too-large");
+    if (listed.code !== 0)
+        throw new MapRefused("couldn't read main: its file list couldn't be read", "failed");
+    const raw = parseTree(listed.stdout);
+    if (raw.length > LIMITS.treeEntries)
+        throw new MapRefused(`too large: ${raw.length.toLocaleString("en-US")} files (the limit is ${LIMITS.treeEntries.toLocaleString("en-US")})`, "too-large");
+    let withheld = 0;
+    const named = raw.filter((entryRow) => { if (pathRefused(entryRow.path)) {
+        withheld++;
+        return false;
+    } return true; });
+    const secret = flagged(named.map(one => one.path));
+    const safe = named.filter((_one, index) => { if (secret.has(index)) {
+        withheld++;
+        return false;
+    } return true; });
+    const entries = safe.map(one => ({ path: one.path, mode: one.mode, bytes: one.bytes }));
+    const warnings = new Set();
+    const unread = new Map();
+    const toRead = [];
+    const manifestsWanted = [];
+    let tsconfigEntry = null;
+    let filesRead = 0, bytesRead = 0;
+    for (const one of safe) {
+        if (one.kind !== "blob" || (one.mode !== "100644" && one.mode !== "100755") || vendoredRoot(one.path) !== null)
+            continue;
+        const blob = { path: one.path, oid: one.oid, bytes: one.bytes };
+        if (one.path === "tsconfig.json" && one.bytes <= LIMITS.manifestBytes)
+            tsconfigEntry = blob;
+        if (one.path.endsWith("package.json") && (one.path === "package.json" || one.path.endsWith("/package.json")) && one.bytes <= LIMITS.manifestBytes)
+            manifestsWanted.push(blob);
+        if (!isParsedLanguage(one.path))
+            continue;
+        if (one.bytes > LIMITS.fileBytes) {
+            unread.set(one.path, "too-large");
+            continue;
+        }
+        if (filesRead >= LIMITS.filesRead || bytesRead + one.bytes > LIMITS.bytesRead) {
+            unread.set(one.path, "path-only");
+            warnings.add("read-limit");
+            continue;
+        }
+        toRead.push(blob);
+        filesRead++;
+        bytesRead += one.bytes;
+    }
+    const blobs = await readBlobs(dir, pin, bounded, [...toRead, ...manifestsWanted, ...(tsconfigEntry === null ? [] : [tsconfigEntry])]);
+    const files = [];
+    for (const one of toRead) {
+        const bytes = blobs.get(one.path);
+        const text = bytes === undefined ? null : textOf(bytes);
+        if (text === null)
+            unread.set(one.path, "path-only"); // not text
+        else
+            files.push({ path: one.path, text });
+    }
+    const tsconfigBytes = tsconfigEntry === null ? undefined : blobs.get(tsconfigEntry.path);
+    const tsconfig = tsconfigBytes === undefined ? null : textOf(tsconfigBytes);
+    const parsed = await parseBlobs(dir, bounded, files, entries.filter(one => vendoredRoot(one.path) === null).map(one => one.path), tsconfig, entry);
+    if (parsed.tsconfig === "extends")
+        warnings.add("tsconfig-extends");
+    if (parsed.tsconfig === "unreadable")
+        warnings.add("tsconfig-unreadable");
+    // The names the parser found: control characters and secrets are withheld here, on the parent's side.
+    const allNames = [];
+    for (const file of parsed.facts) {
+        for (const one of file.exports)
+            allNames.push(one.name);
+        for (const one of file.specifiers)
+            allNames.push(one.specifier);
+    }
+    const safeNames = allNames.map(name => name.replace(/[\r\n]/g, " "));
+    const secrets = flagged(safeNames);
+    let index = 0;
+    const facts = new Map();
+    for (const file of parsed.facts) {
+        const exports = [], imports = [], external = new Set();
+        for (const one of file.exports) {
+            const bad = secrets.has(index++) || unsafeName(one.name);
+            if (bad) {
+                withheld++;
+                continue;
+            }
+            if (one.name.length > LIMITS.symbolChars)
+                warnings.add("symbols-truncated");
+            exports.push({ name: one.name.slice(0, LIMITS.symbolChars), kind: one.kind, line: one.line });
+        }
+        for (const one of file.specifiers) {
+            const bad = secrets.has(index++) || unsafeName(one.specifier);
+            if (bad) {
+                withheld++;
+                continue;
+            }
+            if (one.to !== null) {
+                imports.push({ to: one.to, kind: one.kind, line: one.line });
+                continue;
+            }
+            const name = externalPackage(one.specifier);
+            if (name !== null)
+                external.add(name);
+        }
+        facts.set(file.path, { exports, imports, external: [...external], parseFailed: file.parseFailed });
+    }
+    const manifests = new Map();
+    for (const one of manifestsWanted) {
+        const bytes = blobs.get(one.path);
+        const text = bytes === undefined ? null : textOf(bytes);
+        const read = text === null ? null : manifestEntries(text);
+        if (read === null)
+            continue;
+        const named2 = read.name !== null && !unsafeName(read.name) && flagged([read.name]).size === 0 ? read.name : null;
+        if (read.name !== null && named2 === null)
+            withheld++;
+        manifests.set(one.path, { name: named2, entries: read.entries.filter(entryName => !unsafeName(entryName)) });
+    }
+    return buildCodeMap({ repo: context.repo, commit: context.commit, remote: { urlDigest: context.urlDigest, record: context.record }, builtAt: context.builtAt, extractor: context.extractor,
+        entries, entryCount: raw.length, withheld, facts, unread, manifests, warnings: [...warnings] });
+}
+/** Claim the instance's one build, in the transaction that records the folder for crash cleanup. */
+function claimBuild(store, lease, folder, now) {
+    return store.transact(() => {
+        const other = store.handle.prepare("SELECT 1 FROM code_map_refresh WHERE repo <> ? AND spawn_folder IS NOT NULL AND lease_owner IS NOT NULL AND lease_until > ? LIMIT 1").get(lease.repo, now.toISOString());
+        return other === undefined && recordFolder(store, lease, folder);
+    });
+}
+/** Check one project; build and publish when main moved. Never throws for a remote's sake. */
+export async function checkCodeMap(store, repo, deps) {
+    const clock = deps.clock ?? (() => new Date());
+    const bounded = deps.bounded ?? boundedRun;
+    const owner = deps.owner ?? `worker-${process.pid}`;
+    // Identity first: everything after this is judged against what is captured here.
+    const identity = trustedRemoteIdentity(store, repo);
+    if (identity === null || remoteUrlProblem(identity.url) !== null || !codeMapOn(store, repo))
+        return "unavailable";
+    const urlDigest = digestOfUrl(identity.url);
+    const lease = takeLease(store, repo, owner, clock());
+    if (lease === null)
+        return "held";
+    mkdirSync(deps.scratch, { recursive: true });
+    // What a crashed build left, before anything else.
+    cleanupLeftover(lease.previous, realpathSync(deps.scratch));
+    if (lease.previous.pid !== null || lease.previous.folder !== null)
+        clearOldSpawn(store, lease);
+    const started = currentVersion(store, repo);
+    const extractor = currentExtractor();
+    const folder = mkdtempSync(join(realpathSync(deps.scratch), ".code-map-"));
+    const ledger = (outcome, detail) => { store.recordAction({ at: clock().toISOString(), actor: "toolroll", repo, taskId: null, runId: null, action: CODE_MAP_ACT, outcome, source: "work", detail }); };
+    const finishCheck = (state, commit, extra = {}) => {
+        if (!recordCheck(store, lease, { digest: urlDigest, record: identity.record, commit, extractor, state, ...extra }, clock()))
+            return false;
+        clearRequest(store, lease);
+        ledger(commit ?? "unread", state);
+        return true;
+    };
+    const fail = (why, state) => {
+        if (!recordFailure(store, lease, why, state, clock()))
+            return "lease-lost";
+        clearRequest(store, lease);
+        ledger("unread", why.slice(0, 300));
+        return state;
+    };
+    try {
+        const pinned = await pinDestination(identity.url, deps.env ?? process.env, deps.lookup ?? lookupAll);
+        if (!pinned.ok)
+            return fail(`couldn't read main: ${pinned.why}`, "failed");
+        const pin = pinned.pin;
+        if (pin.env["GIT_SSH_COMMAND"] === undefined && !(await (deps.pinWorks ?? curlPinWorks)()))
+            return fail("couldn't read main: this git can't pin its connection", "failed");
+        await initPrivateDir(folder, bounded);
+        const peek = await peekMain(identity.url, folder, pin, bounded, deps.helper);
+        if (!peek.ok)
+            return fail(peek.reason === "moved" ? peek.why : `couldn't read main: ${peek.why}`, "failed");
+        if (peek.commit === null)
+            return finishCheck("no-main", null) ? "no-main" : "lease-lost";
+        if (!recordPeek(store, lease, peek.commit))
+            return "lease-lost";
+        if (started !== null && started.remoteDigest === urlDigest && started.remoteRecord === identity.record && started.commit === peek.commit && started.extractor === extractor) {
+            return finishCheck("current", peek.commit, { proxy: pin.proxy }) ? "fresh" : "lease-lost";
+        }
+        if (!claimBuild(store, lease, folder, clock())) {
+            if (readRefresh(store, repo)?.leaseToken !== lease.token)
+                return "lease-lost";
+            return "waits";
+        }
+        await deps.atStage?.("before-fetch");
+        const fetched = await readShallowMain(identity.url, folder, pin, bounded, spawn => { recordSpawn(store, lease, spawn); }, deps.helper);
+        if (!fetched.ok)
+            return fail(fetched.reason === "moved" ? fetched.why : `couldn't read main: ${fetched.why}`, "failed");
+        await deps.atStage?.("after-fetch");
+        if (!extendLease(store, lease, clock()))
+            return "lease-lost";
+        const builtAt = clock().toISOString();
+        let map;
+        try {
+            map = await buildFromFolder(folder, pin, bounded, { repo, commit: fetched.commit, urlDigest, record: identity.record, builtAt, extractor });
+        }
+        catch (error) {
+            if (error instanceof MapRefused)
+                return fail(error.message, error.state);
+            return fail("couldn't finish reading", "failed");
+        }
+        if (!extendLease(store, lease, clock()))
+            return "lease-lost";
+        const encoded = encodeMap(map);
+        if (encoded.bytes > LIMITS.storedBytes)
+            return fail("too large to store", "too-large");
+        await deps.atStage?.("before-publish");
+        const report = JSON.stringify({ enforced: fetched.enforced, proxy: pin.proxy });
+        const published = publishVersion(store, lease, { map, encoded, identity, startedFrom: started?.id ?? null, report }, clock());
+        if (published === null)
+            return "lease-lost";
+        const state = map.counts.entries === 0 ? "empty" : published.current ? "current" : published.why;
+        if (!finishCheck(state, fetched.commit, { enforced: fetched.enforced, proxy: pin.proxy }))
+            return "lease-lost";
+        if (published.current)
+            tidyVersions(store, repo);
+        return published.current ? (map.counts.entries === 0 ? "empty" : "published") : "stored";
+    }
+    finally {
+        try {
+            rmSync(folder, { recursive: true, force: true });
+        }
+        catch { /* a later takeover removes it */ }
+        releaseLease(store, lease);
+    }
+}
+/** Projects due a check: the map on, a remote recorded, past any back-off, and a request queued or 30 minutes since the
+ * last completed check. */
+export function dueProjects(store, now) {
+    const rows = store.handle.prepare(`SELECT p.path, r.requested_at, r.retry_after, r.last_checked_at FROM project p LEFT JOIN code_map_refresh r ON r.repo = p.path
+    WHERE p.code_map = 1 AND p.remote_url IS NOT NULL AND p.remote_url <> '' ORDER BY p.path`).all();
+    return rows.filter(row => {
+        const retry = row["retry_after"];
+        if (typeof retry === "string" && Date.parse(retry) > now.getTime())
+            return false;
+        const last = row["last_checked_at"];
+        return row["requested_at"] !== null && row["requested_at"] !== undefined || typeof last !== "string" || now.getTime() - Date.parse(last) >= REFRESH_EVERY_MS;
+    }).map(row => String(row["path"]));
+}
+/** The watch loop's step: every due project in turn, one build at a time. */
+export async function refreshCodeMaps(store, deps) {
+    const clock = deps.clock ?? (() => new Date());
+    let checked = 0;
+    for (const repo of dueProjects(store, clock())) {
+        try {
+            await checkCodeMap(store, repo, deps);
+            checked++;
+        }
+        catch { /* the next pass tries again */ }
+    }
+    return checked;
+}

package/dist/code-map-cli.d.ts

@@ -0,0 +1,153 @@
+import { type MapDoor } from "./code-map-acts.js";
+import type { Store } from "./store.js";
+export declare const MAP_DESCRIPTORS: readonly [{
+    readonly action: "";
+    readonly synopsis: "a project's code map: its areas, and how they use each other";
+    readonly mutation: "none";
+    readonly positional: null;
+    readonly flags: readonly [Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>, Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>, Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>];
+}, {
+    readonly action: "area";
+    readonly synopsis: "one area's files, exported names, tests and connections: map area <id>";
+    readonly mutation: "none";
+    readonly positional: "the area's id";
+    readonly flags: readonly Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>[];
+}, {
+    readonly action: "file";
+    readonly synopsis: "one file's exported names, imports and who imports it: map file <path>";
+    readonly mutation: "none";
+    readonly positional: "the file's exact path";
+    readonly flags: readonly Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>[];
+}, {
+    readonly action: "search";
+    readonly synopsis: "search files and exported names: map search <words>";
+    readonly mutation: "none";
+    readonly positional: "words to search for";
+    readonly flags: readonly Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>[];
+}, {
+    readonly action: "refresh";
+    readonly synopsis: "ask for a check of main now; it runs on the next pass";
+    readonly mutation: "unkeyed";
+    readonly positional: null;
+    readonly flags: readonly [Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>, Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>];
+}, {
+    readonly action: "report";
+    readonly synopsis: "builds with and without the map, by assigned arm";
+    readonly mutation: "none";
+    readonly positional: null;
+    readonly flags: readonly [Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>, Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>];
+}, {
+    readonly action: "on";
+    readonly synopsis: "turn a project's code map on (a person, or this computer's owner)";
+    readonly mutation: "unkeyed";
+    readonly positional: null;
+    readonly flags: readonly [Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>, Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>];
+    readonly audience: "operator";
+}, {
+    readonly action: "off";
+    readonly synopsis: "turn a project's code map off (a person, or this computer's owner)";
+    readonly mutation: "unkeyed";
+    readonly positional: null;
+    readonly flags: readonly [Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>, Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>];
+    readonly audience: "operator";
+}, {
+    readonly action: "holdout end";
+    readonly synopsis: "stop enrolling new builds in the holdout; existing ones keep their arm (a person)";
+    readonly mutation: "unkeyed";
+    readonly positional: null;
+    readonly flags: readonly [Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>, Readonly<{
+        [x: string]: unknown;
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }>];
+    readonly audience: "operator";
+}];
+export type MapCliContext = {
+    store: Store;
+    write: (line: string) => void;
+    json: boolean;
+    now: Date;
+    actor: string | null;
+    repos: readonly string[];
+    /** Whether the caller stands as an approver of this project, proved now (a lead token does; a local owner doesn't). */
+    approver: (repo: string) => boolean;
+    /** Who may change this project's map, as proved for this command; null when nobody was. */
+    door: (repo: string) => MapDoor | null;
+};
+export declare function runMapCommand(positional: readonly string[], options: Map<string, string | true>, context: MapCliContext): Promise<number>;

package/dist/code-map-cli.js

@@ -0,0 +1,103 @@
+/**
+ * `toolroll map` (docs/plans/code-map.md §5-7): the same reader and acts as the page. A read needs project access;
+ * `refresh` any approver, the lead included; `on`/`off` and `holdout end` a person, re-proved inside the write.
+ */
+import { resolve } from "node:path";
+import { answerMap, areaRows, codeMapStatus, openMap } from "./code-map-read.js";
+import { endHoldout, setCodeMapSwitch } from "./code-map-acts.js";
+import { codeMapReport, NOT_ENOUGH, reportRows } from "./code-map-report.js";
+import { requestRefresh } from "./code-map-store.js";
+import { canonicalProject } from "./project.js";
+import { envelopeJson } from "./envelope.js";
+const jsonFlag = { name: "json", takesValue: false, meaning: "answer with one machine envelope on stdout" };
+const repoFlag = { name: "repo", takesValue: true, meaning: "which project" };
+const pageFlags = [jsonFlag, repoFlag, { name: "cursor", takesValue: true, meaning: "the next page, from the answer before it" }];
+export const MAP_DESCRIPTORS = [
+    { action: "", synopsis: "a project's code map: its areas, and how they use each other", mutation: "none", positional: null, flags: [jsonFlag, repoFlag, pageFlags[2]] },
+    { action: "area", synopsis: "one area's files, exported names, tests and connections: map area <id>", mutation: "none", positional: "the area's id", flags: pageFlags },
+    { action: "file", synopsis: "one file's exported names, imports and who imports it: map file <path>", mutation: "none", positional: "the file's exact path", flags: pageFlags },
+    { action: "search", synopsis: "search files and exported names: map search <words>", mutation: "none", positional: "words to search for", flags: pageFlags },
+    { action: "refresh", synopsis: "ask for a check of main now; it runs on the next pass", mutation: "unkeyed", positional: null, flags: [jsonFlag, repoFlag] },
+    { action: "report", synopsis: "builds with and without the map, by assigned arm", mutation: "none", positional: null, flags: [jsonFlag, repoFlag] },
+    { action: "on", synopsis: "turn a project's code map on (a person, or this computer's owner)", mutation: "unkeyed", positional: null, flags: [jsonFlag, repoFlag], audience: "operator" },
+    { action: "off", synopsis: "turn a project's code map off (a person, or this computer's owner)", mutation: "unkeyed", positional: null, flags: [jsonFlag, repoFlag], audience: "operator" },
+    { action: "holdout end", synopsis: "stop enrolling new builds in the holdout; existing ones keep their arm (a person)", mutation: "unkeyed", positional: null, flags: [jsonFlag, repoFlag], audience: "operator" },
+];
+const printable = (text) => [...text].map(char => (/[\p{C}]/u.test(char) ? `\\u{${char.codePointAt(0).toString(16)}}` : char)).join("");
+function linesOf(answer) {
+    const lines = [`Code map · main at ${answer.commit.slice(0, 7)}`, answer.label, ""];
+    for (const item of answer.items)
+        lines.push(printable(JSON.stringify(item)));
+    if (answer.omitted > 0)
+        lines.push(`${answer.omitted} too long to show.`);
+    if (answer.cursor !== null)
+        lines.push(`More: --cursor ${answer.cursor}`);
+    return lines;
+}
+export async function runMapCommand(positional, options, context) {
+    const { store, now } = context;
+    const first = positional[0];
+    const action = first === undefined || first.startsWith("/") || first.startsWith(".") ? "" : first;
+    const named = action === "" ? first : undefined;
+    const command = action === "" ? "map" : `map ${action}`;
+    const fail = (reason, message) => { context.write(context.json ? envelopeJson({ ok: false, command, reason, message }) : printable(message)); return reason === "usage" ? 2 : 1; };
+    const ok = (result, lines) => { context.write(context.json ? envelopeJson({ ok: true, command, ...result }) : lines.join("\n")); return 0; };
+    if (!["", "area", "file", "search", "refresh", "report", "on", "off", "holdout"].includes(action))
+        return fail("usage", "Use map [<project>] | area <id> | file <path> | search <words> | refresh | report | on | off | holdout end.");
+    const open = context.repos;
+    const asked = options.get("repo") ?? named;
+    if (asked === true)
+        return fail("usage", "--repo takes a project path.");
+    const wanted = asked === undefined ? (open.length === 1 ? open[0] : null) : canonicalProject(asked) ?? resolve(asked);
+    if (wanted === null)
+        return fail("usage", "Name the project: --repo <path>.");
+    if (!open.includes(wanted))
+        return fail("refused", "That project isn't one you can open here.");
+    if (action === "refresh") {
+        if (context.actor === null)
+            return fail("unauthenticated", "Sign in first: an approver asks for a check.");
+        if (!context.approver(wanted))
+            return fail("refused", "Only an approver asks for a check.");
+        const said = requestRefresh(store, wanted, context.actor, now);
+        return ok({ repo: wanted, request: said }, [said === "queued" ? "Queued: main is checked on the next pass." : "Already queued."]);
+    }
+    if (action === "on" || action === "off" || action === "holdout") {
+        if (action === "holdout" && (positional[1] !== "end" || positional.length !== 2))
+            return fail("usage", "Use map holdout end.");
+        const door = context.door(wanted);
+        if (door === null)
+            return fail("unauthenticated", "This takes your own sign-in: --as <you> --token <password>.");
+        const done = action === "holdout" ? endHoldout(store, door, wanted, now) : setCodeMapSwitch(store, door, wanted, action === "on", now);
+        if (!done.ok)
+            return fail("refused", done.problem);
+        return ok({ repo: wanted, ...(action === "holdout" ? { holdout: "ended" } : { codeMap: action }) }, [action === "holdout" ? "The holdout has ended: no new builds are enrolled, and existing ones keep their arm." : `The code map is ${action} for this project.`]);
+    }
+    if (action === "report") {
+        const report = codeMapReport(store, wanted, now);
+        return ok({ report }, ["Builds with and without the map", ...reportRows(report).map(row => `${row.label}: with ${row.map} · without ${row.holdout}`), ...(report.enough ? [] : [NOT_ENOUGH])]);
+    }
+    const cursor = options.get("cursor");
+    if (cursor === true)
+        return fail("usage", "--cursor takes the value the last answer gave.");
+    if (action === "") {
+        const status = codeMapStatus(store, wanted, now);
+        if (status.version === null)
+            return ok({ map: { v: 1, ok: false, state: status.state, message: status.words }, state: status.state }, [status.words]);
+        const answer = answerMap(store, { repo: wanted, view: "overview", ...(cursor === undefined ? {} : { cursor }) });
+        if (!answer.ok)
+            return ok({ map: answer, state: status.state }, [answer.message]);
+        if (context.json)
+            return ok({ map: answer, state: status.state }, []);
+        const opened = openMap(store, wanted, answer.version);
+        const rows = opened.ok ? areaRows(opened.map) : [];
+        return ok({}, [`Code map · main at ${answer.commit.slice(0, 7)} · ${status.words}`, answer.label, "", ...rows.slice(0, 60).map(one => printable(`${one.id} · ${one.files} files · ${one.languages.join(", ") || "no code"}${one.uses.length === 0 ? "" : ` · uses ${one.uses.slice(0, 3).map(use => use.id).join(", ")}`}`)), ...(rows.length > 60 ? [`${rows.length - 60} more: use --json with --cursor.`] : [])]);
+    }
+    const view = action;
+    const query = positional.slice(1).join(" ");
+    if (query === "")
+        return fail("usage", action === "search" ? "Say what to search for." : `Name it: map ${action} <${action === "area" ? "id" : "path"}>.`);
+    const answer = answerMap(store, { repo: wanted, view, ...(view === "search" ? { query } : { id: positional[1] }), ...(cursor === undefined ? {} : { cursor }) });
+    if (!answer.ok)
+        return answer.state === "not-found" || answer.state === "usage" ? fail(answer.state === "usage" ? "usage" : "not-found", answer.message) : ok({ map: answer }, [answer.message]);
+    return ok({ map: answer }, linesOf(answer));
+}