balladeer 1.0.16 → 1.0.18

package/dist/commands/map.d.ts

@@ -1,4 +1,4 @@
-import { type BehaviorMap } from "../behavior-map-schema.js";
+import { type BehaviorMap, type BehaviorMapLinkedTest } from "../behavior-map-schema.js";
 import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
 import { type PromiseDocument, type PromiseReader } from "../promise-meaning.js";
 /** Tools a map builder or a judge may use, and the ones refused whatever else is allowed. */
@@ -17,8 +17,15 @@ export type MapArguments = Readonly<{
     json: boolean;
     repository?: string;
     controlPlane: string;
+    /** `--link-test`: add one test to a promise's map, with no model and no server. */
+    linkTest?: Readonly<{
+        promiseId: string;
+        file: string;
+        name: string;
+        cases: string[];
+    }>;
 }>;
-export declare const MAP_USAGE = "  npx -y balladeer@latest map <promise id> | --all | --check | --stale\n                [--from-file <promise.json>] [--repo <root>] [--out <dir>]\n                [--client auto|claude|codex] [--timeout <seconds>] [--json]\n      Build a behavior map for a promise with your own coding agent: where its\n      behavior starts, the code on its path, what it depends on, the tests that\n      exercise it and where each failing case would show. The agent works in a\n      throwaway read-only checkout, on the Claude Code or Codex login already on\n      this machine, and the map is written to .continuity/behavior-maps/<id>.json\n      for your team to commit. It never leaves this machine. --all maps every\n      agreed promise; --check reports maps whose code or meaning has moved\n      (exit 1 when any has) and --stale prints just their ids, both without a\n      model. --from-file reads the promise from a file instead of Balladeer.\n";
+export declare const MAP_USAGE = "  npx -y balladeer@latest map <promise id> | --all | --check | --stale\n                [--from-file <promise.json>] [--repo <root>] [--out <dir>]\n                [--client auto|claude|codex] [--timeout <seconds>] [--json]\n  npx -y balladeer@latest map --link-test <promise id> <test file>\n                [--name <test name>] [--case <case id>]... [--repo <root>] [--json]\n      Build a behavior map for a promise with your own coding agent: where its\n      behavior starts, the code on its path, what it depends on, the tests that\n      exercise it and where each failing case would show. The agent works in a\n      throwaway read-only checkout, on the Claude Code or Codex login already on\n      this machine, and the map is written to .continuity/behavior-maps/<id>.json\n      for your team to commit. It never leaves this machine. --all maps every\n      agreed promise; --check reports maps whose code or meaning has moved\n      (exit 1 when any has) and --stale prints just their ids, both without a\n      model. --from-file reads the promise from a file instead of Balladeer.\n      --link-test adds a test in this repository to a promise's existing map,\n      naming the cases it covers (passing-1, failing-2), so later judges run it\n      and a change to it counts as risk to the promise. It changes nothing else\n      in the map, calls no model and sends nothing anywhere.\n";
 export declare function parseMapArguments(argv: readonly string[]): MapArguments;
 export type MapDependencies = Readonly<{
     runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
@@ -102,6 +109,43 @@ export type StoredMap = Readonly<{
 /** Every map in a directory, read and checked; an unreadable one is listed with why. */
 export declare function readBehaviorMaps(directory: string): StoredMap[];
 export declare function readBehaviorMap(root: string, promiseId: string): BehaviorMap | undefined;
+export type LinkTestResult = Readonly<{
+    ok: true;
+    changed: boolean;
+    path: string;
+    entry: BehaviorMapLinkedTest;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+    message: string;
+}>;
+/**
+ * The map's text with one entry added at the end of its top-level
+ * `linkedTests` list, and every other character left where it was, so the
+ * change a reviewer reads is the new entry and one comma. The entry is written
+ * the way this repository's formatter writes JSON: an object per line group,
+ * two-space indents, and the case list on one line while it fits in a
+ * hundred columns. Undefined when the list cannot be found.
+ */
+export declare function insertLinkedTest(text: string, entry: BehaviorMapLinkedTest): string | undefined;
+/**
+ * Link one test in this repository to a promise's behavior map, the way a
+ * person would by hand, without a model: the test is appended to the map's
+ * `linkedTests` unless an equal entry is already there, and nothing else in
+ * the map changes. The map must already exist, the file must exist inside this
+ * repository and not be ignored by git (a test git ignores never reaches the
+ * repository's suite), the list must have room, and the result must pass the
+ * map checker. The map is written beside itself and renamed into place.
+ */
+export declare function linkTestToMap(input: Readonly<{
+    root: string;
+    directory: string;
+    cwd: string;
+    promiseId: string;
+    file: string;
+    name: string;
+    cases: readonly string[];
+}>): Promise<LinkTestResult>;
 export type MapOptions = Readonly<{
     args: MapArguments;
     cwd: string;

package/dist/commands/map.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, 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 { BEHAVIOR_MAP_DIRECTORY, BEHAVIOR_MAP_SCHEMA_VERSION, CASE_ID, ENTRY_POINT_KINDS, MAP_LIMITS, PROMISE_ID, RESOURCE_ACCESS, RESOURCE_KINDS, SYMBOL_KINDS, SYMBOL_ROLES, parseBehaviorMap, serializeBehaviorMap, } from "../behavior-map-schema.js";
+import { runCommand } from "../gh.js";
 import { repositoryRoot } from "../git.js";
 import { runHeadlessAgent, } from "../headless-agent.js";
 import { mapPrompt } from "../map-brief.js";
@@ -15,6 +16,8 @@ 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]
+  ${CLI_INVOCATION} map --link-test <promise id> <test file>
+                [--name <test name>] [--case <case id>]... [--repo <root>] [--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
@@ -24,6 +27,10 @@ export const MAP_USAGE = `  ${CLI_INVOCATION} map <promise id> | --all | --check
       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.
+      --link-test adds a test in this repository to a promise's existing map,
+      naming the cases it covers (passing-1, failing-2), so later judges run it
+      and a change to it counts as risk to the promise. It changes nothing else
+      in the map, calls no model and sends nothing anywhere.
 `;
 export function parseMapArguments(argv) {
     const args = [...argv];
@@ -39,6 +46,9 @@ export function parseMapArguments(argv) {
     let controlPlane;
     let client = "auto";
     let timeoutMs = DEFAULT_MAP_TIMEOUT_MS;
+    let linkTest;
+    let testName;
+    const cases = [];
     const value = (flag, inline) => {
         const next = inline ?? args.shift();
         if (next === undefined || next === "")
@@ -83,16 +93,45 @@ export function parseMapArguments(argv) {
                 throw new StoreError("usage", "--timeout needs a number of seconds.");
             timeoutMs = Math.round(seconds * 1000);
         }
+        else if (name === "--link-test") {
+            const id = value(name, inline);
+            const file = args.shift();
+            if (file === undefined || file === "" || file.startsWith("--"))
+                throw new StoreError("usage", "--link-test needs a promise id and then a test file.");
+            linkTest = { promiseId: id, file };
+        }
+        else if (name === "--name")
+            testName = value(name, inline);
+        else if (name === "--case") {
+            for (const id of value(name, inline).split(",")) {
+                const caseId = id.trim();
+                if (!CASE_ID.test(caseId))
+                    throw new StoreError("usage", `"${caseId}" is not a case id; a case id names a case of the promise, such as passing-1 or failing-2.`);
+                if (!cases.includes(caseId))
+                    cases.push(caseId);
+            }
+        }
         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);
+    const modes = [
+        positional.length === 1,
+        all,
+        check,
+        stale,
+        fromFile !== undefined,
+        linkTest !== undefined,
+    ].filter(Boolean);
     if (modes.length === 0)
-        throw new StoreError("usage", "map needs a promise id, --all, --check, --stale or --from-file.");
+        throw new StoreError("usage", "map needs a promise id, --all, --check, --stale, --from-file or --link-test.");
     if (modes.length > 1)
-        throw new StoreError("usage", "map takes one of: a promise id, --all, --check, --stale, --from-file.");
+        throw new StoreError("usage", "map takes one of: a promise id, --all, --check, --stale, --from-file, --link-test.");
+    if (linkTest === undefined && (testName !== undefined || cases.length > 0))
+        throw new StoreError("usage", "--name and --case go with --link-test.");
+    if (linkTest !== undefined && !PROMISE_ID.test(linkTest.promiseId))
+        throw new StoreError("usage", `"${linkTest.promiseId}" is not a promise id.`);
     const promiseId = positional[0];
     if (promiseId !== undefined && !PROMISE_ID.test(promiseId))
         throw new StoreError("usage", `"${promiseId}" is not a promise id.`);
@@ -110,6 +149,7 @@ export function parseMapArguments(argv) {
         json,
         ...(repository === undefined ? {} : { repository }),
         controlPlane: normalizeControlPlane(chosen),
+        ...(linkTest === undefined ? {} : { linkTest: { ...linkTest, name: testName ?? "", cases } }),
     };
 }
 /**
@@ -181,6 +221,8 @@ export function agentFailure(agent) {
             return "the agent finished without an answer";
         case "no_json":
             return "the agent's answer held no JSON object";
+        case "output_capped":
+            return `the agent wrote ${agent.outputTokens ?? "more"} output tokens, past its cap, so its answer was not used`;
         default:
             return "the agent did not answer";
     }
@@ -421,6 +463,171 @@ export function readBehaviorMap(root, promiseId) {
         return undefined;
     }
 }
+/** Two linked tests are the same entry when file, name and the set of cases match. */
+function sameLinkedTest(a, b) {
+    return (a.file === b.file &&
+        a.name === b.name &&
+        a.cases.length === b.cases.length &&
+        a.cases.every((id) => b.cases.includes(id)));
+}
+/** Where a JSON string that starts at `at` ends: the index of its closing quote. */
+function stringEnd(text, at) {
+    let index = at + 1;
+    while (index < text.length && text[index] !== '"')
+        index += text[index] === "\\" ? 2 : 1;
+    return index;
+}
+/**
+ * The map's text with one entry added at the end of its top-level
+ * `linkedTests` list, and every other character left where it was, so the
+ * change a reviewer reads is the new entry and one comma. The entry is written
+ * the way this repository's formatter writes JSON: an object per line group,
+ * two-space indents, and the case list on one line while it fits in a
+ * hundred columns. Undefined when the list cannot be found.
+ */
+export function insertLinkedTest(text, entry) {
+    let depth = 0;
+    let key = -1;
+    let open = -1;
+    for (let index = 0; index < text.length && open < 0; index += 1) {
+        const char = text[index];
+        if (char === '"') {
+            const end = stringEnd(text, index);
+            if (depth === 1 && text.slice(index, end + 1) === '"linkedTests"') {
+                const rest = /^\s*:\s*\[/.exec(text.slice(end + 1));
+                if (rest !== null) {
+                    key = index;
+                    open = end + rest[0].length;
+                }
+            }
+            index = end;
+        }
+        else if (char === "{" || char === "[")
+            depth += 1;
+        else if (char === "}" || char === "]")
+            depth -= 1;
+    }
+    if (open < 0)
+        return undefined;
+    let close = -1;
+    depth = 0;
+    for (let index = open; index < text.length; index += 1) {
+        const char = text[index];
+        if (char === '"')
+            index = stringEnd(text, index);
+        else if (char === "[" || char === "{")
+            depth += 1;
+        else if (char === "]" || char === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                close = index;
+                break;
+            }
+        }
+    }
+    if (close < 0)
+        return undefined;
+    const indent = text.slice(text.lastIndexOf("\n", key) + 1, key);
+    if (!/^[ \t]*$/.test(indent))
+        return undefined;
+    const element = `${indent}  `;
+    const field = `${indent}    `;
+    const inline = `[${entry.cases.map((id) => JSON.stringify(id)).join(", ")}]`;
+    const cases = `${field}"cases": ${inline}`.length <= 100
+        ? inline
+        : `[\n${entry.cases.map((id) => `${field}  ${JSON.stringify(id)}`).join(",\n")}\n${field}]`;
+    const block = `${element}{\n` +
+        `${field}"file": ${JSON.stringify(entry.file)},\n` +
+        `${field}"name": ${JSON.stringify(entry.name)},\n` +
+        `${field}"cases": ${cases}\n` +
+        `${element}}`;
+    if (text.slice(open + 1, close).trim() === "")
+        return `${text.slice(0, open)}[\n${block}\n${indent}]${text.slice(close + 1)}`;
+    let last = close - 1;
+    while (last > open && /\s/.test(text[last] ?? ""))
+        last -= 1;
+    return `${text.slice(0, last + 1)},\n${block}${text.slice(last + 1)}`;
+}
+/**
+ * Link one test in this repository to a promise's behavior map, the way a
+ * person would by hand, without a model: the test is appended to the map's
+ * `linkedTests` unless an equal entry is already there, and nothing else in
+ * the map changes. The map must already exist, the file must exist inside this
+ * repository and not be ignored by git (a test git ignores never reaches the
+ * repository's suite), the list must have room, and the result must pass the
+ * map checker. The map is written beside itself and renamed into place.
+ */
+export async function linkTestToMap(input) {
+    const refuse = (reason, message) => ({
+        ok: false,
+        reason,
+        message,
+    });
+    const path = join(input.directory, `${input.promiseId}.json`);
+    if (!existsSync(path))
+        return refuse("no_behavior_map", `${input.promiseId} has no behavior map here yet, so there is nothing to link a test to. Run \`balladeer map ${input.promiseId}\` first.`);
+    const target = resolve(input.cwd, input.file);
+    if (!existsSync(target))
+        return refuse("test_not_found", `${input.file} does not exist, so it was not linked.`);
+    const root = realpathSync(input.root);
+    const real = realpathSync(target);
+    const inside = relative(root, real);
+    if (inside === "" || inside.startsWith("..") || isAbsolute(inside))
+        return refuse("outside_repository", `${input.file} is outside this repository, so it was not linked. A linked test lives in this repository's own tests.`);
+    if (!statSync(real).isFile())
+        return refuse("not_a_file", `${input.file} is not a file, so it was not linked.`);
+    const file = inside.split(sep).join("/");
+    const ignored = await runCommand("git", ["-C", root, "check-ignore", "-q", "--", file]);
+    if (ignored.code === 0)
+        return refuse("ignored_by_git", `${file} is ignored by git, so it would never reach this repository's tests and was not linked. Move it into the repository's own tests first.`);
+    const text = readFileSync(path, "utf8");
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return refuse("map_unreadable", `${path} is not JSON, so nothing was linked.`);
+    }
+    const current = parseBehaviorMap(raw);
+    if (!current.ok)
+        return refuse("map_unreadable", `${path} is not a usable behavior map, so nothing was linked: ${current.errors.slice(0, 3).join("; ")}.`);
+    if (current.value.promiseId !== input.promiseId)
+        return refuse("map_mismatch", `${path} is the map of ${current.value.promiseId}, not ${input.promiseId}, so nothing was linked.`);
+    const entry = { file, name: input.name, cases: [...input.cases] };
+    if (current.value.linkedTests.some((test) => sameLinkedTest(test, entry)))
+        return { ok: true, changed: false, path, entry };
+    if (current.value.linkedTests.length >= MAP_LIMITS.linkedTests)
+        return refuse("linked_tests_full", `${input.promiseId}'s behavior map already links ${MAP_LIMITS.linkedTests} tests, the most a map holds, so ${file} was not linked. Remove one it no longer needs from linkedTests first.`);
+    const next = { ...raw, linkedTests: [...current.value.linkedTests, entry] };
+    const checked = parseBehaviorMap(next);
+    if (!checked.ok)
+        return refuse("invalid_link", `Linking ${file} would make the map invalid, so nothing was linked: ${checked.errors.slice(0, 3).join("; ")}.`);
+    // A map in the form this command writes stays in that form; any other is
+    // edited in place, and the edit is kept only if it reads back as exactly
+    // the intended map.
+    const plain = `${JSON.stringify(next, null, 2)}\n`;
+    const edited = text === `${JSON.stringify(raw, null, 2)}\n` ? undefined : insertLinkedTest(text, entry);
+    let written = plain;
+    if (edited !== undefined) {
+        try {
+            if (JSON.stringify(JSON.parse(edited)) === JSON.stringify(next))
+                written = edited;
+        }
+        catch {
+            /* The plain form is written instead. */
+        }
+    }
+    const staging = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(staging, written, "utf8");
+        renameSync(staging, path);
+    }
+    catch (error) {
+        rmSync(staging, { force: true });
+        return refuse("write_failed", `${path} could not be written, so nothing was linked: ${error instanceof Error ? error.message : String(error)}.`);
+    }
+    return { ok: true, changed: true, path, entry };
+}
 /** `balladeer map`, from arguments already parsed. */
 export async function runMap(options) {
     const { args } = options;
@@ -443,6 +650,38 @@ export async function runMap(options) {
     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);
+    if (args.linkTest !== undefined) {
+        // Deterministic and local: no connection, no model, nothing sent.
+        const linked = await linkTestToMap({
+            root,
+            directory,
+            cwd: options.cwd,
+            ...args.linkTest,
+        });
+        if (!linked.ok)
+            return fail(linked.reason, linked.message, 4);
+        // Shown from where the command ran, through any link in either path (a
+        // temp directory on macOS is one), so a person reads a short path.
+        const here = existsSync(options.cwd) ? realpathSync(options.cwd) : options.cwd;
+        const shown = relative(here, realpathSync(linked.path)) || linked.path;
+        if (!linked.changed) {
+            const message = `${linked.entry.file} is already linked to ${args.linkTest.promiseId} in ${shown}, so nothing was changed.`;
+            if (args.json)
+                emit({ step: "error", reason: "already_linked", message, changed: false, exitCode: 0 });
+            else
+                say(message);
+            return 0;
+        }
+        const cases = linked.entry.cases.length > 0 ? ` for ${linked.entry.cases.join(", ")}` : "";
+        say(`Linked ${linked.entry.file} to ${args.linkTest.promiseId}${cases} in ${shown}. Nothing else in the map changed. Commit the map with the test.`);
+        emit({
+            step: "behavior_map",
+            promiseId: args.linkTest.promiseId,
+            status: "written",
+            path: linked.path,
+        });
+        return 0;
+    }
     let reader = options.deps?.reader ?? undefined;
     let readerProblem;
     if (options.deps?.reader === undefined && args.fromFile === undefined) {

package/dist/commands/mcp.js

@@ -5,7 +5,7 @@ import { noteServerVersion, updateNotice } from "../currency.js";
 import { repositoryHint, repositoryHints } from "../repository.js";
 import { CLI_VERSION } from "../wire.js";
 import { untrackedLine } from "./guidance.js";
-import { HOOKS_AWAITING_TRUST_NOTICE, hooksAwaitingTrust, trustingHost } from "../hook-trust.js";
+import { hooksAwaitingTrust, hooksAwaitingTrustNotice, trustingHost } from "../hook-trust.js";
 import { StoreError, readCredentials } from "../store.js";
 // The three commands that use an agent connection select and address it through
 // one module. These are re-exported because this is where the forwarder's
@@ -260,7 +260,7 @@ export async function runMcp(options) {
             host !== undefined &&
             request?.method === "tools/call" &&
             hooksAwaitingTrust(options.environment, host)) {
-            const noted = withNotice(text, HOOKS_AWAITING_TRUST_NOTICE);
+            const noted = withNotice(text, hooksAwaitingTrustNotice(options.environment, host));
             if (noted !== undefined) {
                 saidTrust = true;
                 options.write(`${noted}\n`);