balladeer 0.0.4 → 1.0.0

package/dist/commands/status.d.ts

@@ -0,0 +1,35 @@
+export type StatusOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    /**
+     * One promise, by id, instead of the whole picture.
+     *
+     * It is the second half of the line a person copies out of a broken promise:
+     * "Run balladeer status <id> first." An agent that starts here reads what the
+     * failing run actually reported and repairs the behavior; one that starts from
+     * the claim alone rewrites the test until it goes green.
+     */
+    promiseId?: string;
+    /** The repository whose connection to use, named as `owner/name`. */
+    repo?: string;
+    /** The repository whose connection to use, named by id, as `mcp` takes it. */
+    repository?: string;
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    write: (text: string) => void;
+}>;
+/**
+ * What Balladeer looks like right now, read from the server and never from
+ * anything this machine remembers.
+ *
+ * It reads two different things over two different credentials, because they are
+ * two different questions. This repository's own state comes over its agent
+ * connection, which setup issued and which does not expire, so an agent asked
+ * "are we set up here" gets an answer months after pairing. The whole workspace,
+ * every repository in it, is a person's view and stays on the delegated setup
+ * session; when no live session is stored this says so rather than reporting a
+ * workspace it could not read.
+ *
+ * It changes nothing.
+ */
+export declare function runStatus(options: StatusOptions): Promise<number>;

package/dist/commands/status.js

@@ -0,0 +1,482 @@
+import { callAgentTool, noAgentCredentialSentence, selectAgent, structuredString, } from "../agent.js";
+import { ClientTooOldError, RefusalError, TransportError, request } from "../client.js";
+import { repositoryRoot } from "../git.js";
+import { MARKER_OBSERVATION_LIMITS, observeMissingMarkers, staleMarkerRow, } from "../markers.js";
+import { commandLine } from "../release.js";
+import { repositoryHint } from "../repository.js";
+import { SEALED_PATHS_SHOWN, sealedPromises } from "../seals.js";
+import { StoreError, findSession, readCredentials } from "../store.js";
+import {} from "../wire.js";
+/**
+ * The bounded code for "this machine holds no credential for that repository".
+ * It is its own code rather than the session's: an agent branching on
+ * `session_expired` pairs again and still holds nothing.
+ */
+const NO_CREDENTIAL_HERE = "no_agent_credential_on_this_machine";
+function noSessionSentence(controlPlane) {
+    return `Every repository in the workspace is read over a setup session, and none is stored for ${controlPlane}. Run \`${commandLine(null, "setup")}\` to read the whole workspace.`;
+}
+/**
+ * What Balladeer looks like right now, read from the server and never from
+ * anything this machine remembers.
+ *
+ * It reads two different things over two different credentials, because they are
+ * two different questions. This repository's own state comes over its agent
+ * connection, which setup issued and which does not expire, so an agent asked
+ * "are we set up here" gets an answer months after pairing. The whole workspace,
+ * every repository in it, is a person's view and stays on the delegated setup
+ * session; when no live session is stored this says so rather than reporting a
+ * workspace it could not read.
+ *
+ * It changes nothing.
+ */
+export async function runStatus(options) {
+    const code = await reportBalladeer(options);
+    // Last, and on every path out of the report above, including the ones that
+    // could read nothing at all. Which directories are sealed is a fact about
+    // this checkout rather than about any credential, and a session that has just
+    // been told it holds none is exactly the session about to edit something.
+    await reportSealedPaths(options, (step) => {
+        if (options.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    }, (text) => {
+        if (!options.json)
+            options.write(`${text}\n`);
+    });
+    return code;
+}
+async function reportBalladeer(options) {
+    const emit = (step) => {
+        if (options.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    const say = (text) => {
+        if (!options.json)
+            options.write(`${text}\n`);
+    };
+    const fail = (reason, message, exitCode) => {
+        if (options.json)
+            emit({ step: "error", reason, message, changed: false, exitCode });
+        else
+            options.write(`${message}\n`);
+        return exitCode;
+    };
+    let credentials;
+    try {
+        credentials = readCredentials(options.environment);
+    }
+    catch (error) {
+        return fail(error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
+    }
+    const here = options.repo ?? repositoryHint(options.cwd);
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, here);
+    const session = findSession(credentials, options.controlPlane);
+    // The credential this machine holds is what this repository is read over, so
+    // its absence is the first thing said, and it is said in its own words. What
+    // the founder got instead was the workspace half's refusal, "Balladeer refused
+    // to report this workspace (session_expired). Run setup to pair again", which
+    // named the wrong credential, the wrong remedy and the wrong machine: the
+    // repository was connected, in a browser, and this machine had never been
+    // issued anything.
+    if (selection.kind === "refused" && selection.missingFor !== undefined) {
+        const message = noAgentCredentialSentence(selection.missingFor);
+        if (options.json) {
+            emit({ step: "error", reason: NO_CREDENTIAL_HERE, message, changed: false, exitCode: 4 });
+        }
+        else {
+            options.write(`${message}\n`);
+        }
+        if (session === undefined) {
+            sayWorkspaceUnavailable(emit, say, "no_stored_setup_session", noSessionSentence(options.controlPlane));
+        }
+        else {
+            // A different question, over a different credential, so it is still
+            // answered underneath. Its outcome never becomes this run's exit code:
+            // this repository went unreported whatever the workspace read did.
+            await reportWorkspace(options, session, here, emit, say, true);
+        }
+        return 4;
+    }
+    if (selection.kind === "refused" && session === undefined) {
+        // Nothing stored can answer anything, so this names the form that always
+        // works: the one this copy was run as.
+        return fail("nothing_stored", `${selection.reason} No Balladeer setup session is stored for ${options.controlPlane} either. Run: ${commandLine(null, "setup")}`, 4);
+    }
+    // One promise, by id: a different question, answered over the same connection
+    // and on its own. Somebody who pasted the repair line wants what the failing
+    // run reported, not a repository-wide report they have to read past to find
+    // it, and the workspace-wide half needs a setup session this person may not
+    // have any more.
+    if (options.promiseId !== undefined) {
+        if (selection.kind !== "agent") {
+            return fail("nothing_stored", `${selection.reason} A promise is read over this repository's own agent connection, so nothing here could answer for ${options.promiseId}.`, 4);
+        }
+        return reportOnePromise(options, options.promiseId, selection.agent, emit, say);
+    }
+    let reported = false;
+    if (selection.kind === "agent") {
+        reported = await reportThisRepository(options, selection.agent, emit, say);
+    }
+    if (session === undefined) {
+        sayWorkspaceUnavailable(emit, say, "no_stored_setup_session", noSessionSentence(options.controlPlane));
+        return reported ? 0 : 4;
+    }
+    return reportWorkspace(options, session, here, emit, say, reported);
+}
+/**
+ * This repository, over its own agent connection.
+ *
+ * `get_promise_setup` is the tool the setup probe already uses, and it answers
+ * for the one repository the connection is bound to. An answer naming a
+ * different repository is a failure rather than a curiosity: it would mean this
+ * machine reported one repository's state under another's name.
+ */
+async function reportThisRepository(options, agent, emit, say) {
+    const call = await callAgentTool(agent, "get_promise_setup", {});
+    if (call.kind !== "result") {
+        say(`This repository could not be read over its Balladeer agent connection: ${reason(call)}`);
+        return false;
+    }
+    const repositoryId = structuredString(call.structured, "repositoryId");
+    const repository = structuredString(call.structured, "repository");
+    if (repositoryId === undefined || repositoryId !== agent.repositoryId) {
+        say("That connection answered for a different repository, so nothing about this one was reported. Issue the connection again from the Balladeer setup page, and do not use it.");
+        return false;
+    }
+    const structured = call.structured;
+    const enrolled = structured.enrolled === true;
+    const memberCount = Array.isArray(structured.members) ? structured.members.length : 0;
+    emit({
+        step: "connection",
+        status: "agent",
+        repositoryId,
+        ...(repository === undefined ? {} : { repository }),
+        enrolled,
+        memberCount,
+    });
+    say(`${repository ?? repositoryId}, read over this repository's Balladeer agent connection.`);
+    say("  Agent: connected. This connection has no expiry; a person revokes it in Balladeer.");
+    say(`  Attestor release: ${enrolled ? "enrolled, so CI has a runner to pin" : "not enrolled, so there is no runner to pin yet"}.`);
+    say(`  People who may be named as a promise's owner: ${memberCount}.`);
+    await reportStaleMarkers(options, agent, emit, say);
+    return true;
+}
+/**
+ * The promises this repository keeps that name a path it no longer has.
+ *
+ * This is the one fact about a catalog that only the machine holding the
+ * checkout can establish. Balladeer stores the markers a person approved and
+ * has no way to look at the tree, so a rename that leaves a promise
+ * unretrievable is invisible everywhere except here. It is read over the same
+ * connection as the rest of this half, it changes nothing, and its failure is
+ * silence: a status run whose catalog could not be read still reported the
+ * repository.
+ */
+async function reportStaleMarkers(options, agent, emit, say) {
+    const root = await repositoryRoot(options.cwd);
+    if (root === undefined)
+        return;
+    // One page, deliberately. The index is bounded and so is this: a status run
+    // is not the place to walk a thousand-promise catalog, and the row says when
+    // it stopped rather than reporting a clean tree it did not finish reading.
+    const call = await callAgentTool(agent, "list_promises", { limit: 100 });
+    if (call.kind !== "result")
+        return;
+    const structured = call.structured;
+    if (!Array.isArray(structured?.promises))
+        return;
+    const subjects = [];
+    for (const entry of structured.promises) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const row = entry;
+        if (typeof row.promiseId !== "string")
+            continue;
+        subjects.push({
+            promiseId: row.promiseId,
+            title: typeof row.title === "string" ? row.title : row.promiseId,
+            surfaces: Array.isArray(row.surfaces)
+                ? row.surfaces.filter((value) => typeof value === "string")
+                : [],
+            labels: Array.isArray(row.labels)
+                ? row.labels.filter((value) => typeof value === "string")
+                : [],
+        });
+    }
+    if (subjects.length === 0)
+        return;
+    const observed = observeMissingMarkers(root, subjects, MARKER_OBSERVATION_LIMITS);
+    const total = typeof structured.total === "number" ? structured.total : subjects.length;
+    emit({
+        step: "attention",
+        reason: "scope_marker_missing",
+        observed: observed.observations.length,
+        considered: subjects.length,
+        total,
+        stoppedEarly: observed.stoppedEarly,
+        promises: observed.observations.map((observation) => ({
+            promiseId: observation.promiseId,
+            missing: [...observation.missing],
+        })),
+    });
+    const row = staleMarkerRow(observed);
+    if (row !== undefined)
+        say(row);
+    if (subjects.length < total) {
+        say(`  This looked at ${subjects.length} of ${total} promises, so there may be more paths to check.`);
+    }
+}
+/**
+ * One promise, read by id over this repository's agent connection.
+ *
+ * What it prints on a promise that is not holding is exactly what a repair
+ * starts from, and every line of it came off a stored row: the commit the
+ * failing run checked, the bounded reason it could not report green, and the
+ * cases in the meaning its owner agreed to that the run was checking. The note
+ * about what those cases are is printed with them rather than left in a
+ * document, because the one thing worse than not naming them is naming them in
+ * a way that reads as a verdict on each one.
+ *
+ * A promise that is holding says so in one line. It is not an error and does
+ * not exit non-zero: somebody who ran this after a fix wants to hear that the
+ * behavior is back, and a red exit would tell their agent to keep going.
+ */
+async function reportOnePromise(options, promiseId, agent, emit, say) {
+    const call = await callAgentTool(agent, "get_promise", { promiseId });
+    if (call.kind !== "result") {
+        const message = `${promiseId} could not be read over this repository's Balladeer agent connection: ${reason(call)}`;
+        emit({ step: "promise", status: "unreadable", promiseId, message });
+        say(message);
+        return 5;
+    }
+    const structured = call.structured;
+    if (structured.found === false) {
+        const message = structuredString(call.structured, "reason") ??
+            `No current approved promise with the id ${promiseId} is available to this repository.`;
+        emit({ step: "promise", status: "unreadable", promiseId, message });
+        say(message);
+        return 4;
+    }
+    const title = structuredString(call.structured, "title");
+    const posture = structuredString(call.structured, "posture");
+    const ownerName = structuredString(call.structured, "ownerName");
+    const promiseUrl = structuredString(call.structured, "promiseUrl");
+    const threat = structured.threat;
+    const named = {
+        promiseId,
+        ...(title === undefined ? {} : { title }),
+        ...(posture === undefined ? {} : { protectionPosture: posture }),
+        ...(ownerName === undefined ? {} : { ownerName }),
+        ...(promiseUrl === undefined ? {} : { promiseUrl }),
+    };
+    if (threat === undefined) {
+        emit({ step: "promise", status: "holding", ...named });
+        say(`${title ?? promiseId} (${promiseId})`);
+        if (posture !== undefined)
+            say(`  Balladeer reports this promise as ${posture}.`);
+        say("  Nothing is reported broken here, so there is nothing to repair.");
+        if (promiseUrl !== undefined)
+            say(`  Promise page: ${promiseUrl}`);
+        return 0;
+    }
+    const kind = threat.kind === "refuted" ? "refuted" : "unknown";
+    const sourceSha = typeof threat.sourceSha === "string" ? threat.sourceSha : undefined;
+    const reasonCode = typeof threat.reasonCode === "string" ? threat.reasonCode : "unknown";
+    const caseIds = Array.isArray(threat.refutedCaseIds)
+        ? threat.refutedCaseIds.filter((value) => typeof value === "string")
+        : [];
+    const caseNote = typeof threat.refutedCaseNote === "string" ? threat.refutedCaseNote : undefined;
+    const observedAt = typeof threat.observedAt === "string" ? threat.observedAt : undefined;
+    emit({
+        step: "promise",
+        status: "not_holding",
+        ...named,
+        kind,
+        ...(sourceSha === undefined ? {} : { sourceSha }),
+        reasonCode,
+        refutedCaseIds: caseIds,
+        ...(caseNote === undefined ? {} : { refutedCaseNote: caseNote }),
+        ...(observedAt === undefined ? {} : { observedAt }),
+    });
+    say(`${title ?? promiseId} (${promiseId})`);
+    say(kind === "refuted"
+        ? "  A verifier ran and the behavior no longer holds."
+        : "  The check could not reach a verdict, so this behavior is unmeasured rather than broken.");
+    say(`  Commit the failing run checked: ${sourceSha ?? "not recorded for this run"}`);
+    say(`  Reason: ${reasonCode}`);
+    say(caseIds.length === 0
+        ? "  Cases named by this run: none."
+        : `  Cases the run was checking: ${caseIds.join(", ")}`);
+    if (caseNote !== undefined)
+        say(`  ${caseNote}`);
+    if (observedAt !== undefined)
+        say(`  Observed: ${observedAt}`);
+    if (ownerName !== undefined)
+        say(`  Owner: ${ownerName}`);
+    if (promiseUrl !== undefined)
+        say(`  Promise page: ${promiseUrl}`);
+    return 0;
+}
+/**
+ * Which directories in this checkout are sealed, read off the customer's own
+ * sealed packages rather than asked of anybody.
+ *
+ * It is here because this is the command an agent runs before it plans, and a
+ * coder who learns after the fact that a rename swept a promise's directory has
+ * cost its owner an afternoon of qualifying it again. Offline, bounded, and
+ * silent in a repository that seals nothing: a line about zero sealed
+ * directories is noise in the twelve repositories that have none yet.
+ */
+async function reportSealedPaths(options, emit, say) {
+    // The sealed directories are named from the repository root, so the answer
+    // must not depend on which directory somebody happened to run this from.
+    const sealed = sealedPromises((await repositoryRoot(options.cwd)) ?? options.cwd);
+    if (sealed.length === 0)
+        return;
+    const shown = sealed.slice(0, SEALED_PATHS_SHOWN);
+    emit({
+        step: "sealed_paths",
+        total: sealed.length,
+        shown: shown.map((promise) => ({
+            promiseId: promise.promiseId,
+            sealedPath: promise.sealedPath,
+            ...(promise.title === undefined ? {} : { title: promise.title }),
+        })),
+    });
+    say("");
+    say(sealed.length === 1
+        ? "  One promise seals a directory in this checkout. Editing anything in it breaks the seal:"
+        : `  ${sealed.length} promises seal a directory in this checkout. Editing anything in one breaks its seal:`);
+    for (const promise of shown)
+        say(`    ${promise.sealedPath}${promise.title === undefined ? "" : `  ${promise.title}`}`);
+    if (sealed.length > shown.length)
+        say(`    and ${sealed.length - shown.length} more, not listed here.`);
+    say("  Run `balladeer check-seals` before you push to find out whether your change broke one.");
+}
+function reason(call) {
+    switch (call.kind) {
+        case "endpoint_refused":
+            return call.reason;
+        case "unreachable":
+            return "Balladeer could not be reached from this machine.";
+        case "client_too_old":
+            return `this copy of the command is too old for that Balladeer. Update it with: ${call.update}`;
+        case "unauthorized":
+            return "the connection was revoked, or the repository it was bound to is no longer enrolled.";
+        case "tool_refusal":
+            return call.text;
+        case "http":
+            return `Balladeer answered ${call.status}.`;
+        default:
+            return "Balladeer's answer was not a tool result.";
+    }
+}
+/**
+ * The workspace-wide half, named as missing rather than reported as empty.
+ *
+ * A run that reported this repository and then said nothing about the workspace
+ * would read as a workspace with one repository in it.
+ */
+function sayWorkspaceUnavailable(emit, say, reasonCode, sentence) {
+    emit({ step: "workspace", status: "unavailable", reason: reasonCode, message: sentence });
+    say("");
+    say(sentence);
+}
+/** Every repository in the workspace, which only a setup session can read. */
+async function reportWorkspace(options, session, here, emit, say, alreadyReported) {
+    let state;
+    try {
+        state = await request(options.controlPlane, {
+            method: "GET",
+            path: "/api/setup/v1/state",
+            bearer: session.token,
+        });
+    }
+    catch (error) {
+        const code = error instanceof ClientTooOldError
+            ? "client_too_old"
+            : error instanceof TransportError
+                ? "control_plane_unreachable"
+                : error instanceof RefusalError
+                    ? error.code
+                    : "setup_state_unreadable";
+        if (alreadyReported) {
+            // This repository has already been reported over its own connection, so
+            // the workspace-wide half is a view this run could not read rather than a
+            // command that failed.
+            sayWorkspaceUnavailable(emit, say, code, `Every repository in the workspace is read over a setup session, and the stored one could not be used (${code}). Run \`${commandLine(null, "setup")}\` to read the whole workspace.`);
+            return 0;
+        }
+        if (error instanceof ClientTooOldError) {
+            return failOutside(options, emit, code, error.message, 3);
+        }
+        if (error instanceof TransportError) {
+            return failOutside(options, emit, code, `Balladeer could not be reached at ${options.controlPlane}: ${error.message}. Nothing was changed.`, 5);
+        }
+        if (error instanceof RefusalError) {
+            return failOutside(options, emit, code, `Balladeer refused to report this workspace (${code}). Run \`${commandLine(null, "setup")}\` to pair again. Nothing was changed.`, 5);
+        }
+        return failOutside(options, emit, code, "Balladeer could not report this workspace.", 5);
+    }
+    const active = state.repositories.filter((repository) => repository.status === "active");
+    emit({
+        step: "receipt",
+        setup: {
+            complete: active.some((item) => item.agentConfigured && item.ciConfigured),
+            sentence: `${active.length} repositor${active.length === 1 ? "y" : "ies"} enrolled in ${state.workspace.name}.`,
+        },
+        firstPromise: { complete: false, sentence: "See each repository below." },
+        protection: { complete: false, sentence: "See each repository below." },
+        connection: {
+            complete: active.some((item) => item.agentConfigured),
+            sentence: "Proposing and reporting run over each repository's agent connection, which does not expire.",
+        },
+        repositories: active.map((repository) => ({
+            repository: repository.displayName,
+            agent: repository.agentConfigured ? "agent connected" : "no agent connection",
+            ci: repository.ciConfigured
+                ? `CI connected, ${repository.ciValidatedRunCount} authenticated run${repository.ciValidatedRunCount === 1 ? "" : "s"}`
+                : repository.ciIdentityRecorded
+                    ? "CI identity recorded, waiting for the first authenticated run"
+                    : "CI not recorded",
+        })),
+    });
+    if (options.json)
+        return 0;
+    const setupCommand = commandLine(state.client.publishedVersion, "setup");
+    say("");
+    say(`Workspace "${state.workspace.name}" (${state.workspace.slug}).`);
+    if (active.length === 0) {
+        say(`No repository is enrolled yet. Run \`${setupCommand}\` inside one.`);
+        return 0;
+    }
+    for (const repository of active) {
+        const mark = repository.displayName.toLowerCase() === here.toLowerCase() ? " (this one)" : "";
+        say(`\n${repository.displayName}${mark}`);
+        say(`  Default branch: ${repository.defaultBranch}`);
+        say(`  Agent: ${repository.agentConfigured ? "connected" : "not connected"}`);
+        say(`  CI: ${repository.ciConfigured
+            ? `connected, ${repository.ciValidatedRunCount} authenticated run${repository.ciValidatedRunCount === 1 ? "" : "s"}, first observed ${repository.ciFirstValidatedAt ?? "at an earlier run"}`
+            : repository.ciIdentityRecorded
+                ? "identity recorded, waiting for the first authenticated run"
+                : "not recorded"}`);
+        // `candidateCount` counts only what is genuinely waiting for a person, so a
+        // promise somebody already agreed to is never also listed as a proposal
+        // awaiting them, and a rejected proposal is listed nowhere at all.
+        say(`  Promises: ${repository.promiseCount} agreed, ${repository.candidateCount} proposed and awaiting a person.`);
+        if (repository.firstPromiseId !== null) {
+            say(`  First promise: ${options.controlPlane}/promises/${repository.firstPromiseId}`);
+        }
+        if (repository.latestCandidateId !== null) {
+            say(`  Newest proposal: ${options.controlPlane}/candidates/${repository.latestCandidateId}`);
+        }
+    }
+    return 0;
+}
+function failOutside(options, emit, reasonCode, message, exitCode) {
+    if (options.json)
+        emit({ step: "error", reason: reasonCode, message, changed: false, exitCode });
+    else
+        options.write(`${message}\n`);
+    return exitCode;
+}

package/dist/commands/touch-map.d.ts

@@ -0,0 +1,42 @@
+import { type TouchMap } from "../touch-map.js";
+export type TouchMapOptions = Readonly<{
+    cwd: string;
+    json: boolean;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    /** The clock, so a test can pin the timestamp the document carries. */
+    now?: () => Date;
+}>;
+/**
+ * Where the promises are, which is not always the git root.
+ *
+ * A repository keeps its promises at its top level, so the git root is the
+ * answer almost every time. It is not the answer when somebody is standing in a
+ * sub-tree that carries its own `.continuity/` directory, which is how this
+ * repository's own dogfood packages are laid out, and running there and mapping
+ * the outer tree instead would answer a question nobody asked.
+ */
+export declare function promiseRoot(cwd: string): Promise<string | undefined>;
+/**
+ * The command that turns "which files does this verifier read" from a guess
+ * into a measurement.
+ *
+ * It runs every sealed promise in this checkout under V8's coverage recorder
+ * and writes what each one executed to `.continuity/touch-map.json`. The file
+ * stays on the customer's disk. Nothing here posts it, and the map is a list of
+ * a customer's own file names, which is exactly the thing the boundary copy
+ * promises Balladeer never receives.
+ */
+export declare function runTouchMap(options: TouchMapOptions): Promise<number>;
+/**
+ * Write the map, and leave the file alone when nothing about it changed.
+ *
+ * The timestamp is the only field that moves on every run, so comparing the
+ * document without it is what makes a second run a no-op. A command that
+ * rewrote a byte of a committed file every time it was asked a question would
+ * put a diff in front of somebody who changed nothing.
+ */
+export declare function writeTouchMap(root: string, map: TouchMap): Readonly<{
+    changed: boolean;
+    bytes: number;
+}>;