balladeer 1.0.15 → 1.0.16

package/dist/commands/map.js

@@ -0,0 +1,601 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { BEHAVIOR_MAP_DIRECTORY, BEHAVIOR_MAP_SCHEMA_VERSION, ENTRY_POINT_KINDS, PROMISE_ID, RESOURCE_ACCESS, RESOURCE_KINDS, SYMBOL_KINDS, SYMBOL_ROLES, parseBehaviorMap, serializeBehaviorMap, } from "../behavior-map-schema.js";
+import { repositoryRoot } from "../git.js";
+import { runHeadlessAgent, } from "../headless-agent.js";
+import { mapPrompt } from "../map-brief.js";
+import { connectionReader, meaningExcerpt, readPromiseFile, } from "../promise-meaning.js";
+import { addScratchWorktree, resolveCommit } from "../scratch-worktree.js";
+import { normalizeControlPlane, StoreError } from "../store.js";
+import { CLI_INVOCATION, DEFAULT_CONTROL_PLANE } from "../wire.js";
+/** Tools a map builder or a judge may use, and the ones refused whatever else is allowed. */
+export const AGENT_TOOLS = ["Read", "Grep", "Glob", "Bash"];
+export const REFUSED_TOOL_RULES = ["Bash(git push:*)", "Bash(gh:*)"];
+const DEFAULT_MAP_TIMEOUT_MS = 15 * 60_000;
+export const MAP_USAGE = `  ${CLI_INVOCATION} map <promise id> | --all | --check | --stale
+                [--from-file <promise.json>] [--repo <root>] [--out <dir>]
+                [--client auto|claude|codex] [--timeout <seconds>] [--json]
+      Build a behavior map for a promise with your own coding agent: where its
+      behavior starts, the code on its path, what it depends on, the tests that
+      exercise it and where each failing case would show. The agent works in a
+      throwaway read-only checkout, on the Claude Code or Codex login already on
+      this machine, and the map is written to .continuity/behavior-maps/<id>.json
+      for your team to commit. It never leaves this machine. --all maps every
+      agreed promise; --check reports maps whose code or meaning has moved
+      (exit 1 when any has) and --stale prints just their ids, both without a
+      model. --from-file reads the promise from a file instead of Balladeer.
+`;
+export function parseMapArguments(argv) {
+    const args = [...argv];
+    const positional = [];
+    let all = false;
+    let check = false;
+    let stale = false;
+    let json = false;
+    let fromFile;
+    let repo;
+    let out;
+    let repository;
+    let controlPlane;
+    let client = "auto";
+    let timeoutMs = DEFAULT_MAP_TIMEOUT_MS;
+    const value = (flag, inline) => {
+        const next = inline ?? args.shift();
+        if (next === undefined || next === "")
+            throw new StoreError("usage", `${flag} needs a value.`);
+        return next;
+    };
+    while (args.length > 0) {
+        const arg = args.shift();
+        if (!arg.startsWith("--")) {
+            positional.push(arg);
+            continue;
+        }
+        const [name, ...rest] = arg.split("=");
+        const inline = rest.length > 0 ? rest.join("=") : undefined;
+        if (name === "--all")
+            all = true;
+        else if (name === "--check")
+            check = true;
+        else if (name === "--stale")
+            stale = true;
+        else if (name === "--json")
+            json = true;
+        else if (name === "--from-file")
+            fromFile = value(name, inline);
+        else if (name === "--repo")
+            repo = value(name, inline);
+        else if (name === "--out")
+            out = value(name, inline);
+        else if (name === "--repository")
+            repository = value(name, inline);
+        else if (name === "--control-plane")
+            controlPlane = value(name, inline);
+        else if (name === "--client") {
+            const requested = value(name, inline);
+            if (requested !== "auto" && requested !== "claude" && requested !== "codex")
+                throw new StoreError("usage", "--client needs auto, claude or codex.");
+            client = requested;
+        }
+        else if (name === "--timeout") {
+            const seconds = Number(value(name, inline));
+            if (!Number.isFinite(seconds) || seconds <= 0)
+                throw new StoreError("usage", "--timeout needs a number of seconds.");
+            timeoutMs = Math.round(seconds * 1000);
+        }
+        else
+            throw new StoreError("usage", `Unknown option ${arg} for map.`);
+    }
+    if (positional.length > 1)
+        throw new StoreError("usage", "map takes at most one promise id.");
+    const modes = [positional.length === 1, all, check, stale, fromFile !== undefined].filter(Boolean);
+    if (modes.length === 0)
+        throw new StoreError("usage", "map needs a promise id, --all, --check, --stale or --from-file.");
+    if (modes.length > 1)
+        throw new StoreError("usage", "map takes one of: a promise id, --all, --check, --stale, --from-file.");
+    const promiseId = positional[0];
+    if (promiseId !== undefined && !PROMISE_ID.test(promiseId))
+        throw new StoreError("usage", `"${promiseId}" is not a promise id.`);
+    const chosen = controlPlane ?? process.env.BALLADEER_CONTROL_PLANE?.trim() ?? DEFAULT_CONTROL_PLANE;
+    return {
+        ...(promiseId === undefined ? {} : { promiseId }),
+        all,
+        check,
+        stale,
+        ...(fromFile === undefined ? {} : { fromFile }),
+        ...(repo === undefined ? {} : { repo }),
+        ...(out === undefined ? {} : { out }),
+        client,
+        timeoutMs,
+        json,
+        ...(repository === undefined ? {} : { repository }),
+        controlPlane: normalizeControlPlane(chosen),
+    };
+}
+/**
+ * One promise's behavior map, built by the person's own agent from the code at
+ * HEAD, in a disposable checkout, and checked against the contract before it is
+ * returned. Nothing is written here; the caller decides where the map goes.
+ */
+export async function buildBehaviorMap(input) {
+    const sha = await resolveCommit(input.root, "HEAD");
+    if (sha === undefined)
+        return { ok: false, reason: "this repository has no commit to map" };
+    const tree = await addScratchWorktree(input.root, sha, `map-${input.promise.promiseId}`, input.scratch);
+    if (!tree.ok)
+        return { ok: false, reason: tree.reason };
+    try {
+        const agent = await (input.runAgent ?? runHeadlessAgent)({
+            client: input.client,
+            cwd: tree.worktree.path,
+            prompt: mapPrompt(input.promise),
+            allowedTools: AGENT_TOOLS,
+            disallowedTools: REFUSED_TOOL_RULES,
+            sandbox: "read-only",
+            timeoutMs: input.timeoutMs,
+            env: input.env,
+            jsonOutput: true,
+            ...(input.prefer === undefined ? {} : { prefer: input.prefer }),
+            ...(input.login === undefined ? {} : { login: input.login }),
+            ...(input.scratch === undefined ? {} : { scratch: input.scratch }),
+        });
+        if (!agent.ok || agent.json === undefined)
+            return { ok: false, reason: agentFailure(agent), agent };
+        const { map, dropped, coerced } = mapFromAgent(agent.json, {
+            promise: input.promise,
+            sha,
+            client: agent.client === "codex" ? "codex" : "claude",
+            model: agent.model ?? "",
+            at: (input.now?.() ?? new Date()).toISOString(),
+            tree: tree.worktree.path,
+        });
+        const parsed = parseBehaviorMap(map);
+        if (!parsed.ok)
+            return {
+                ok: false,
+                reason: "the agent's map does not match the behavior map contract",
+                agent,
+                errors: parsed.errors,
+            };
+        return { ok: true, map: parsed.value, agent, dropped, coerced };
+    }
+    finally {
+        await tree.worktree.remove();
+    }
+}
+export function agentFailure(agent) {
+    switch (agent.reason) {
+        case "no_verified_login":
+            return "no Claude Code signed in through claude.ai, and no Codex signed in with ChatGPT, is on this machine";
+        case "spawn_failed":
+            return "the coding agent could not be started";
+        case "timed_out":
+            return `the agent was still working after ${Math.round(agent.durationMs / 1000)} seconds and was stopped`;
+        case "aborted":
+            return "the time allowed ran out and the agent was stopped";
+        case "output_bounded":
+            return "the agent printed more than this command keeps, and was stopped";
+        case "exit_nonzero":
+            return `the agent exited with code ${agent.exitCode ?? "none"}${agent.stderrTail ? `: ${agent.stderrTail.split("\n").pop()}` : ""}`;
+        case "no_answer":
+            return "the agent finished without an answer";
+        case "no_json":
+            return "the agent's answer held no JSON object";
+        default:
+            return "the agent did not answer";
+    }
+}
+/** A path the agent wrote, as a repository-relative forward-slash path, or nothing. */
+function repositoryRelative(value, tree) {
+    if (typeof value !== "string" || value.trim() === "")
+        return undefined;
+    let path = value.trim().replace(/\\/g, "/");
+    if (isAbsolute(path)) {
+        const inside = relative(tree, path);
+        if (inside.startsWith("..") || isAbsolute(inside))
+            return undefined;
+        path = inside.split(sep).join("/");
+    }
+    path = path.replace(/^\.\//, "");
+    if (path === "" || path.split("/").includes(".."))
+        return undefined;
+    return path;
+}
+const asText = (value, fallback = "") => typeof value === "string" ? value : fallback;
+const asList = (value) => (Array.isArray(value) ? value : []);
+const asRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+/**
+ * The agent's answer made into a map: the runner's own fields filled in, paths
+ * made repository-relative, and every entry whose file does not exist at the
+ * mapped commit dropped and named, because a map pointing at nothing reads as
+ * stale forever. The meaning excerpt is taken from the promise itself rather
+ * than from the agent's copy, so a transcription slip cannot change it.
+ */
+export function mapFromAgent(json, context) {
+    const dropped = [];
+    const coerced = [];
+    const exists = (path, what) => {
+        if (path !== undefined && existsSync(join(context.tree, path)))
+            return true;
+        dropped.push(`${what} ${path ?? "(no path)"}`);
+        return false;
+    };
+    // The contract's closed lists are the contract's, not the agent's. An agent
+    // that calls a maintenance sweep a "sweep" or a resource "database" has
+    // still found the right thing; refusing the whole map over one word threw
+    // away a minute of a person's subscription on the first live run. So the
+    // word is read as the nearest allowed one and the reading is reported, never
+    // silent, so a person can see what the agent actually said.
+    const pick = (value, allowed, fallback, what) => {
+        if (typeof value === "string" && allowed.includes(value))
+            return value;
+        coerced.push(`${what} "${typeof value === "string" ? value : String(value)}" read as ${fallback}`);
+        return fallback;
+    };
+    const entryPoints = asList(json.entryPoints).flatMap((raw) => {
+        const row = asRecord(raw);
+        const file = repositoryRelative(row.file, context.tree);
+        if (!exists(file, "entry point in"))
+            return [];
+        return [
+            {
+                file,
+                symbol: asText(row.symbol),
+                kind: pick(row.kind, ENTRY_POINT_KINDS, "function", `entry point kind in ${file}`),
+                note: asText(row.note),
+            },
+        ];
+    });
+    const symbols = asList(json.symbols).flatMap((raw) => {
+        const row = asRecord(raw);
+        const file = repositoryRelative(row.file, context.tree);
+        if (!exists(file, "symbol in"))
+            return [];
+        return [
+            {
+                file,
+                name: asText(row.name),
+                kind: pick(row.kind, SYMBOL_KINDS, "function", `symbol kind of ${asText(row.name)}`),
+                role: pick(row.role, SYMBOL_ROLES, "supporting", `symbol role of ${asText(row.name)}`),
+            },
+        ];
+    });
+    const linkedTests = asList(json.linkedTests).flatMap((raw) => {
+        const row = asRecord(raw);
+        const file = repositoryRelative(row.file, context.tree);
+        if (!exists(file, "linked test"))
+            return [];
+        return [{ file, name: asText(row.name), cases: asList(row.cases) }];
+    });
+    const resources = asList(json.resources).map((raw) => {
+        const row = asRecord(raw);
+        return {
+            kind: pick(row.kind, RESOURCE_KINDS, "config", `resource kind of ${asText(row.name)}`),
+            name: asText(row.name),
+            access: pick(row.access, RESOURCE_ACCESS, "both", `resource access of ${asText(row.name)}`),
+        };
+    });
+    const sinks = asList(json.sinks).flatMap((raw) => {
+        const row = asRecord(raw);
+        // A sink names the failing case it belongs to, and a case id the meaning
+        // does not have points at nothing. Left out and named, like a missing file.
+        if (typeof row.caseId !== "string" || !/^failing-[1-9][0-9]*$/.test(row.caseId)) {
+            dropped.push(`sink with case id ${typeof row.caseId === "string" ? row.caseId : "(none)"}`);
+            return [];
+        }
+        return [
+            {
+                caseId: row.caseId,
+                effect: asText(row.effect),
+                resources: asList(row.resources),
+                symbols: asList(row.symbols).flatMap((reference) => {
+                    if (typeof reference !== "string")
+                        return [];
+                    const hash = reference.indexOf("#");
+                    const file = repositoryRelative(hash > 0 ? reference.slice(0, hash) : undefined, context.tree);
+                    if (!exists(file, "sink symbol in"))
+                        return [];
+                    return [`${file}#${reference.slice(hash + 1)}`];
+                }),
+            },
+        ];
+    });
+    const rawConfidence = typeof json.confidence === "number" ? json.confidence : 0;
+    return {
+        map: {
+            schemaVersion: BEHAVIOR_MAP_SCHEMA_VERSION,
+            promiseId: context.promise.promiseId,
+            semanticDigest: context.promise.semanticDigest,
+            mappedAt: { sha: context.sha, at: context.at, client: context.client, model: context.model },
+            entryPoints,
+            symbols,
+            resources,
+            linkedTests,
+            sinks,
+            confidence: Math.min(1, Math.max(0, rawConfidence)),
+            notes: asText(json.notes).slice(0, 2000),
+            meaning: meaningExcerpt(context.promise),
+        },
+        dropped,
+        coerced,
+    };
+}
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** The name a file must still contain for a mapped symbol to count as present. */
+function searchName(name) {
+    const parts = name.split(/[.#:]+|\(\)/).filter((part) => part.trim() !== "");
+    return (parts[parts.length - 1] ?? name).trim();
+}
+function fileHas(root, file, name) {
+    let content;
+    try {
+        const path = join(root, file);
+        if (!statSync(path).isFile())
+            return false;
+        content = readFileSync(path, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const needle = searchName(name);
+    if (needle === "")
+        return true;
+    if (IDENTIFIER.test(needle)) {
+        const escaped = needle.replace(/\$/g, "\\$");
+        return new RegExp(`(^|[^A-Za-z0-9_$])${escaped}($|[^A-Za-z0-9_$])`, "m").test(content);
+    }
+    return content.includes(needle);
+}
+/**
+ * Whether a map still points at real code, answered without a model.
+ *
+ * Stale when a mapped symbol is no longer in its file (a plain search for its
+ * name, the way a person would grep for it), when a mapped file is gone, or,
+ * when the current digest is known, when the promise's meaning has moved on
+ * since the map was built.
+ */
+export function mapStaleness(root, map, currentDigest) {
+    const reasons = [];
+    for (const entry of map.entryPoints)
+        if (!fileHas(root, entry.file, entry.symbol))
+            reasons.push(`entry point ${entry.symbol} is no longer in ${entry.file}`);
+    for (const symbol of map.symbols) {
+        const present = symbol.kind === "module"
+            ? existsSync(join(root, symbol.file))
+            : fileHas(root, symbol.file, symbol.name);
+        if (!present)
+            reasons.push(`${symbol.name} is no longer in ${symbol.file}`);
+    }
+    for (const test of map.linkedTests)
+        if (!existsSync(join(root, test.file)))
+            reasons.push(`linked test ${test.file} is gone`);
+    for (const sink of map.sinks)
+        for (const reference of sink.symbols) {
+            const hash = reference.indexOf("#");
+            const file = reference.slice(0, hash);
+            const name = reference.slice(hash + 1);
+            if (!fileHas(root, file, name))
+                reasons.push(`${name} is no longer in ${file}`);
+        }
+    if (currentDigest !== undefined && currentDigest !== map.semanticDigest)
+        reasons.push("the promise's agreed meaning has changed since this map was built");
+    return {
+        stale: reasons.length > 0,
+        reasons: [...new Set(reasons)],
+        digestChecked: currentDigest !== undefined,
+    };
+}
+/** Every map in a directory, read and checked; an unreadable one is listed with why. */
+export function readBehaviorMaps(directory) {
+    if (!existsSync(directory))
+        return [];
+    const out = [];
+    for (const name of readdirSync(directory).sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        const path = join(directory, name);
+        const promiseId = name.slice(0, -".json".length);
+        try {
+            const parsed = parseBehaviorMap(JSON.parse(readFileSync(path, "utf8")));
+            out.push(parsed.ok
+                ? { promiseId, path, map: parsed.value }
+                : { promiseId, path, errors: parsed.errors });
+        }
+        catch {
+            out.push({ promiseId, path, errors: ["the file is not JSON"] });
+        }
+    }
+    return out;
+}
+export function readBehaviorMap(root, promiseId) {
+    const path = join(root, BEHAVIOR_MAP_DIRECTORY, `${promiseId}.json`);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = parseBehaviorMap(JSON.parse(readFileSync(path, "utf8")));
+        return parsed.ok ? parsed.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `balladeer map`, from arguments already parsed. */
+export async function runMap(options) {
+    const { args } = options;
+    const emit = (step) => {
+        if (args.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    const say = (line) => {
+        if (!args.json)
+            options.write(`${line}\n`);
+    };
+    const fail = (reason, message, exitCode) => {
+        if (args.json)
+            emit({ step: "error", reason, message, changed: false, exitCode });
+        else
+            options.write(`${message}\n`);
+        return exitCode;
+    };
+    const root = args.repo !== undefined ? resolve(options.cwd, args.repo) : await repositoryRoot(options.cwd);
+    if (root === undefined || !existsSync(root))
+        return fail("not_a_repository", "This is not a git repository, so there is nothing to map.", 4);
+    const directory = args.out !== undefined ? resolve(options.cwd, args.out) : join(root, BEHAVIOR_MAP_DIRECTORY);
+    let reader = options.deps?.reader ?? undefined;
+    let readerProblem;
+    if (options.deps?.reader === undefined && args.fromFile === undefined) {
+        const connection = connectionReader({
+            environment: options.environment,
+            controlPlane: args.controlPlane,
+            cwd: root,
+            ...(args.repository === undefined ? {} : { repository: args.repository }),
+        });
+        if (connection.ok)
+            reader = connection.reader;
+        else
+            readerProblem = connection.reason;
+    }
+    if (args.check || args.stale) {
+        const stored = readBehaviorMaps(directory);
+        if (stored.length === 0) {
+            say(`There are no behavior maps in ${relative(options.cwd, directory) || "."} yet.`);
+            emit({ step: "behavior_maps", checked: 0, stale: [], digestChecked: false });
+            return 0;
+        }
+        const stale = [];
+        let digestChecked = reader !== undefined;
+        for (const entry of stored) {
+            if (entry.map === undefined) {
+                stale.push(entry.promiseId);
+                if (args.check)
+                    say(`unreadable  ${entry.promiseId}: ${(entry.errors ?? []).slice(0, 3).join("; ")}`);
+                continue;
+            }
+            let current;
+            if (reader !== undefined) {
+                const read = await reader.get(entry.promiseId);
+                if (read.ok)
+                    current = read.promise.semanticDigest;
+                else
+                    digestChecked = false;
+            }
+            const verdict = mapStaleness(root, entry.map, current);
+            const title = entry.map.meaning?.title ?? "";
+            if (verdict.stale) {
+                stale.push(entry.promiseId);
+                if (args.check)
+                    say(`stale  ${entry.promiseId}${title ? ` (${title})` : ""}: ${verdict.reasons.slice(0, 5).join("; ")}`);
+            }
+            else if (args.check)
+                say(`fresh  ${entry.promiseId}${title ? ` (${title})` : ""}`);
+        }
+        if (args.stale && !args.json)
+            for (const id of stale)
+                options.write(`${id}\n`);
+        if (args.check && !digestChecked)
+            say(`Meaning changes were not checked${readerProblem ? ` (${readerProblem})` : ""}; only the code each map points at was.`);
+        emit({ step: "behavior_maps", checked: stored.length, stale, digestChecked });
+        return args.check && stale.length > 0 ? 1 : 0;
+    }
+    const promises = [];
+    if (args.fromFile !== undefined) {
+        const read = readPromiseFile(resolve(options.cwd, args.fromFile));
+        if (!read.ok)
+            return fail("promise_unreadable", read.reason, 4);
+        promises.push(read.promise);
+    }
+    else {
+        if (reader === undefined)
+            return fail("no_agent_connection", `Reading the promise needs this repository's Balladeer connection: ${readerProblem ?? "none was found"}. Pass --from-file with the promise instead.`, 4);
+        const ids = [];
+        if (args.all) {
+            const listed = await reader.list();
+            if (!listed.ok)
+                return fail("promise_list_failed", `Balladeer did not list the promises: ${listed.reason}`, 5);
+            ids.push(...listed.ids);
+        }
+        else if (args.promiseId !== undefined)
+            ids.push(args.promiseId);
+        for (const id of ids) {
+            const read = await reader.get(id);
+            if (!read.ok) {
+                say(`${id} was not mapped: ${read.reason}`);
+                emit({ step: "behavior_map", promiseId: id, status: "failed", reason: read.reason });
+                continue;
+            }
+            promises.push(read.promise);
+        }
+    }
+    let failures = 0;
+    for (const promise of promises) {
+        const built = await buildBehaviorMap({
+            root,
+            promise,
+            client: args.client,
+            env: options.environment,
+            timeoutMs: args.timeoutMs,
+            ...(options.deps?.login === undefined ? {} : { login: options.deps.login }),
+            ...(options.deps?.now === undefined ? {} : { now: options.deps.now }),
+            ...(options.deps?.runAgent === undefined ? {} : { runAgent: options.deps.runAgent }),
+        });
+        if (!built.ok) {
+            failures += 1;
+            say(`${promise.promiseId} was not mapped: ${built.reason}.`);
+            for (const error of (built.errors ?? []).slice(0, 8))
+                say(`  ${error}`);
+            emit({
+                step: "behavior_map",
+                promiseId: promise.promiseId,
+                status: "failed",
+                reason: built.reason,
+                ...(built.errors === undefined ? {} : { errors: built.errors.slice(0, 20) }),
+            });
+            if (built.agent?.reason === "no_verified_login")
+                break;
+            continue;
+        }
+        mkdirSync(directory, { recursive: true });
+        const path = join(directory, `${promise.promiseId}.json`);
+        writeFileSync(path, serializeBehaviorMap(built.map), "utf8");
+        const shown = relative(options.cwd, path) || path;
+        const minutes = (built.agent.durationMs / 60_000).toFixed(1);
+        say(`Mapped ${promise.promiseId} (${promise.title}): ${built.map.entryPoints.length} entry points, ` +
+            `${built.map.symbols.length} symbols, ${built.map.linkedTests.length} linked tests, ` +
+            `confidence ${built.map.confidence}, in ${shown}. ` +
+            `${built.agent.client}${built.agent.model ? ` ${built.agent.model}` : ""}, ${minutes} min.`);
+        if (built.dropped.length > 0)
+            say(`  Left out because the file does not exist: ${built.dropped.slice(0, 8).join("; ")}`);
+        if (built.coerced.length > 0)
+            say(`  Read as the nearest allowed kind: ${built.coerced.slice(0, 8).join("; ")}`);
+        emit({
+            step: "behavior_map",
+            promiseId: promise.promiseId,
+            status: "written",
+            path,
+            client: built.agent.client === "codex" ? "codex" : "claude",
+            ...(built.agent.model === undefined ? {} : { model: built.agent.model }),
+            durationMs: built.agent.durationMs,
+            ...(built.agent.inputTokens === undefined ? {} : { inputTokens: built.agent.inputTokens }),
+            ...(built.agent.outputTokens === undefined ? {} : { outputTokens: built.agent.outputTokens }),
+            dropped: built.dropped.length,
+            coerced: built.coerced.length,
+        });
+    }
+    if (promises.length > 0 && failures === 0)
+        say("The map stays in this repository. Balladeer is never sent it.");
+    return failures > 0 ? 1 : 0;
+}
+/** `balladeer map ...` from raw arguments, as `cli.ts` hands them over. */
+export async function mapCommand(argv, io) {
+    let args;
+    try {
+        args = parseMapArguments(argv);
+    }
+    catch (error) {
+        io.error(`${error instanceof Error ? error.message : String(error)}\n\n${MAP_USAGE}`);
+        return 4;
+    }
+    return runMap({ args, cwd: io.cwd, environment: io.environment, write: io.write });
+}