balladeer 0.0.5 → 1.0.0

package/dist/commands/discover.js

@@ -0,0 +1,395 @@
+import { readFileSync } from "node:fs";
+import { callAgentTool, selectAgent, structuredString } from "../agent.js";
+import { reviewLink } from "../client.js";
+import { commandLine } from "../release.js";
+import { repositoryHint } from "../repository.js";
+import { StoreError, findSession, readCredentials } from "../store.js";
+import {} from "../wire.js";
+import { readTeachBackFile } from "./propose.js";
+/**
+ * Ten promises at 64 KiB each, which is the per-promise cap `propose` already
+ * enforces. The whole file is measured before it is parsed, so a file nobody
+ * meant to hand this command is refused on its size rather than after a parser
+ * has walked it.
+ */
+export const MAX_PROMISES = 10;
+const MAX_CATALOG_BYTES = MAX_PROMISES * 64 * 1024;
+/** The only key this command reads at the top level of a catalog file. */
+const ALLOWED_CATALOG_KEYS = ["promises"];
+/**
+ * The shape check that happens on the developer's machine, for a whole catalog.
+ *
+ * It is `readTeachBackFile` run over every entry rather than a second, looser
+ * gate written beside it. That matters more here than it does for one proposal:
+ * this command exists because an agent has just walked a repository's tests,
+ * pull requests, documents and reverts, and everything it read while doing that
+ * is exactly what Balladeer promises never to receive. One entry that carries a
+ * path, a transcript, a diff, or a stray key it picked up on the way is refused
+ * here, before anything leaves the machine.
+ *
+ * So it returns the exact objects to send rather than a verdict on the file, and
+ * one bad entry refuses the whole catalog. Sending the good half of a file
+ * somebody has to fix anyway would leave a person a review page they cannot
+ * finish and a second run that duplicates what already landed.
+ */
+export function readCatalogFile(raw) {
+    if (Buffer.byteLength(raw, "utf8") > MAX_CATALOG_BYTES) {
+        return { ok: false, reason: `the file is larger than ${MAX_PROMISES * 64} KiB` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: "the file is not JSON" };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            reason: "the file is not a JSON object with a promises array in it",
+        };
+    }
+    const extra = Object.keys(parsed).filter((key) => !ALLOWED_CATALOG_KEYS.includes(key));
+    if (extra.length > 0) {
+        return {
+            ok: false,
+            reason: `it carries ${extra.join(", ")}, which a catalog does not have and this command will not send`,
+        };
+    }
+    const promises = parsed.promises;
+    if (!Array.isArray(promises)) {
+        return { ok: false, reason: "it has no promises array" };
+    }
+    if (promises.length === 0) {
+        return { ok: false, reason: "its promises array is empty, so there is nothing to propose" };
+    }
+    if (promises.length > MAX_PROMISES) {
+        return {
+            ok: false,
+            reason: `it carries ${promises.length} promises and the cap is ${MAX_PROMISES}, because a person has to read every one of them`,
+        };
+    }
+    const value = [];
+    for (const [index, entry] of promises.entries()) {
+        // Re-serialized rather than passed as an object, so the entry meets the very
+        // same guard a single-proposal file meets, including its size cap and its
+        // refusal of a key this command does not send.
+        const read = readTeachBackFile(JSON.stringify(entry));
+        if (!read.ok) {
+            return {
+                ok: false,
+                reason: `promise ${index + 1} of ${promises.length} is not one this command will send: ${read.reason}`,
+            };
+        }
+        value.push(read.value);
+    }
+    return { ok: true, value };
+}
+/**
+ * The repository a proposal is about, taken from the connection rather than from
+ * the file, exactly as `propose` takes it.
+ */
+function scopedMeaning(meaning, repositoryId) {
+    const scope = meaning.scope;
+    if (scope === null || typeof scope !== "object" || Array.isArray(scope))
+        return meaning;
+    return { ...meaning, scope: { ...scope, repositoryId } };
+}
+/** The active members this connection may name as a promise's owner. */
+function membersOf(structured) {
+    if (structured === null || typeof structured !== "object")
+        return [];
+    const members = structured.members;
+    if (!Array.isArray(members))
+        return [];
+    return members.flatMap((member) => {
+        const id = structuredString(member, "membershipId");
+        const name = structuredString(member, "displayName");
+        return id === undefined ? [] : [{ membershipId: id, displayName: name ?? id }];
+    });
+}
+/** How a refused member list reads, in the words each failure needs. */
+function memberListRefusal(kind, controlPlane) {
+    switch (kind) {
+        case "unreachable":
+            return `Balladeer could not be reached at ${controlPlane}, so I could not read who may own these promises.`;
+        case "unauthorized":
+            return "Balladeer refused this repository's agent connection, so I could not read who may own these promises.";
+        default:
+            return "Balladeer could not tell me who may own these promises.";
+    }
+}
+/**
+ * The title of one promise, for the list a person reads back. Absent rather than
+ * guessed: a numbered line with no title is better than a line naming the wrong
+ * promise.
+ */
+function titleOf(request) {
+    const title = request.teachBack.meaning.title;
+    return typeof title === "string" && title.trim().length > 0
+        ? title.trim().slice(0, 160)
+        : "untitled promise";
+}
+/**
+ * The one link that opens every promise this run filed.
+ *
+ * A person who has just been handed eight proposals should be handed one page,
+ * not eight. The ids travel in the query string because the batch is exactly
+ * these promises and nothing else: a link to the whole inbox would also open
+ * whatever was already waiting there, and a filter by repository would open a
+ * different set tomorrow.
+ */
+export function batchReviewLink(controlPlane, candidateIds) {
+    return reviewLink(controlPlane, `candidates/review?ids=${candidateIds.join(",")}`);
+}
+/**
+ * Failures of the connection rather than of one promise, which is the
+ * difference between trying the next one and stopping.
+ *
+ * A revoked credential or a server nobody can reach answers the tenth promise
+ * exactly as it answered the first, so carrying on spends nine more timeouts to
+ * print the same sentence nine more times. The remaining promises are reported
+ * as not attempted instead, which is also what tells a person a second run has
+ * work left to do.
+ */
+const FATAL_REASONS = [
+    "control_plane_unreachable",
+    "agent_connection_revoked",
+    "client_too_old",
+    "agent_endpoint_unsafe",
+];
+/**
+ * A refusal about the state of the workspace rather than about the promise in
+ * hand, recognized without reading the server's words.
+ *
+ * The one that bites in practice is the open-proposal cap: a repository that
+ * already has proposals waiting refuses every promise in a catalog for the same
+ * reason, and printing that sentence ten times is not ten pieces of
+ * information. Matching on the message rather than on its wording keeps this
+ * working when the server rewords the refusal, and keeps a genuinely
+ * per-promise refusal, a malformed meaning, from stopping the run: two
+ * different promises get two different sentences.
+ */
+function repeatsTheLastRefusal(refused, message) {
+    const previous = refused[refused.length - 1];
+    return previous !== undefined && previous.message === message;
+}
+/**
+ * Files a whole discovered catalog over this repository's own agent connection,
+ * every promise owned by the person who ran setup, and hands back one link.
+ *
+ * The owner is named explicitly on every proposal rather than left to a server
+ * default. Who owns a promise decides who may agree to it, and a catalog of ten
+ * promises waiting on nobody is a catalog nobody can finish; naming the person
+ * who ran setup is the one honest answer this command can give without asking
+ * anyone anything.
+ */
+export async function runDiscover(options) {
+    const emit = (step) => {
+        if (options.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    const fail = (reason, message, exitCode) => {
+        if (options.json)
+            emit({ step: "error", reason, message, changed: false, exitCode });
+        else
+            options.write(`${message}\n`);
+        return exitCode;
+    };
+    if (!options.file) {
+        return fail("usage", "Give a catalog file: balladeer discover --file <path>.", 4);
+    }
+    let raw;
+    try {
+        raw = readFileSync(options.file, "utf8");
+    }
+    catch {
+        return fail("catalog_unreadable", `I could not read ${options.file}.`, 4);
+    }
+    const catalog = readCatalogFile(raw);
+    if (!catalog.ok) {
+        return fail("catalog_malformed", `${options.file} is not a promise catalog: ${catalog.reason}. Nothing was sent.`, 4);
+    }
+    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 selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHint(options.cwd));
+    if (selection.kind === "refused") {
+        return fail("no_agent_connection", `${selection.reason} Run \`${commandLine(null, "setup")}\` in this repository first. Nothing was sent.`, 4);
+    }
+    const { agent } = selection;
+    // Whoever ran setup here, or whoever the caller named instead. Read before
+    // anything is sent, so a catalog is never half filed against an owner
+    // Balladeer then refuses.
+    const paired = findSession(credentials, options.controlPlane);
+    const ownerId = options.owner ?? paired?.membershipId;
+    if (ownerId === undefined) {
+        return fail("no_owner", "I do not know who to name as the owner of these promises, so nothing was sent. " +
+            `Run \`${commandLine(null, "setup")}\` here again to pair this machine, which records who you are, or name the owner yourself with --owner <membership id> from the members list on the Balladeer MCP server's setup tool.`, 4);
+    }
+    const setup = await callAgentTool(agent, "get_promise_setup", {});
+    if (setup.kind !== "result") {
+        return fail("owner_unverified", `${memberListRefusal(setup.kind, options.controlPlane)} Nothing was sent.`, 5);
+    }
+    const members = membersOf(setup.structured);
+    const owner = members.find((member) => member.membershipId === ownerId);
+    if (owner === undefined) {
+        const known = members
+            .map((member) => `    ${member.membershipId}  ${member.displayName}`)
+            .join("\n");
+        return fail("owner_not_a_member", `${ownerId} is not an active member of this workspace, so nothing was sent.\n  Name one of these instead with --owner:\n${known}`, 4);
+    }
+    const filed = [];
+    const refused = [];
+    let stoppedAfter;
+    for (const [index, request] of catalog.value.entries()) {
+        const outcome = await proposeOne(agent, request, ownerId);
+        const title = titleOf(request);
+        if (outcome.ok) {
+            const entry = {
+                index: index + 1,
+                title,
+                candidateId: outcome.candidateId,
+                reviewUrl: reviewLink(options.controlPlane, `candidates/${outcome.candidateId}`),
+            };
+            filed.push(entry);
+            emit({
+                step: "promise",
+                status: "proposed",
+                candidateId: entry.candidateId,
+                reviewUrl: entry.reviewUrl,
+            });
+            continue;
+        }
+        const twice = repeatsTheLastRefusal(refused, outcome.message);
+        refused.push({ index: index + 1, title, reason: outcome.reason, message: outcome.message });
+        if (twice || FATAL_REASONS.includes(outcome.reason)) {
+            stoppedAfter = index + 1;
+            break;
+        }
+    }
+    const notAttempted = stoppedAfter === undefined ? 0 : catalog.value.length - stoppedAfter;
+    const reviewUrl = batchReviewLink(options.controlPlane, filed.map((entry) => entry.candidateId));
+    emit({
+        step: "discovery",
+        status: refused.length === 0 ? "proposed" : "partial",
+        proposed: filed.length,
+        requested: catalog.value.length,
+        ownerId,
+        candidateIds: filed.map((entry) => entry.candidateId),
+        ...(filed.length === 0 ? {} : { reviewUrl }),
+        ...(notAttempted === 0 ? {} : { notAttempted }),
+        ...(refused.length === 0
+            ? {}
+            : {
+                failures: refused.map((entry) => ({
+                    promise: entry.index,
+                    reason: entry.reason,
+                    message: entry.message,
+                })),
+            }),
+    });
+    if (!options.json) {
+        const where = agent.repository ?? "this repository";
+        if (filed.length > 0) {
+            options.write(`Proposed ${filed.length} of ${catalog.value.length} promises from ${where}, owned by ${owner.displayName}.\n`);
+            for (const entry of filed)
+                options.write(`  ${entry.index}. ${entry.title}\n`);
+            options.write(`Read all ${filed.length} on one page: ${reviewUrl}\n`);
+            options.write(`${owner.displayName} reads each one and clicks Agree. Nothing this command can run agrees to one.\n`);
+        }
+        for (const entry of refused) {
+            options.write(`Promise ${entry.index}, ${entry.title}, was not recorded: ${entry.message}\n`);
+        }
+        if (notAttempted > 0) {
+            options.write(`I stopped there: the remaining ${notAttempted} ${notAttempted === 1 ? "promise was" : "promises were"} not sent, because that failure would answer every one of them the same way. Run this again once it is fixed.\n`);
+        }
+        if (filed.length > 0) {
+            options.write(`Sent over ${where}'s Balladeer agent connection, which does not expire.\n`);
+        }
+    }
+    return refused.length === 0 ? 0 : 5;
+}
+/**
+ * One promise, over the same tool call `propose` makes, with the owner named.
+ *
+ * Nothing here reads the file again: it sends the object the catalog guard
+ * returned, with the repository stamped from the connection.
+ */
+async function proposeOne(agent, request, ownerId) {
+    const call = await callAgentTool(agent, "propose_promise", {
+        explicitHumanAction: true,
+        source: "protect_behavior",
+        explicitIntent: request.explicitIntent,
+        meaning: scopedMeaning(request.teachBack.meaning, agent.repositoryId),
+        unresolvedQuestions: request.teachBack.unresolvedQuestions ?? [],
+        // The person who ran setup, named on every promise. A file that named
+        // somebody else loses that argument: the catalog is waiting on one person,
+        // and a promise waiting on another is one nobody watches.
+        proposedOwnerId: ownerId,
+        // Read from the file, exactly as `propose` reads it. A discovery run is
+        // where a hedged number matters most: nine promises drawn from nine sources
+        // are not nine equally certain readings, and an owner deciding which to read
+        // first is entitled to see which one the agent was least sure of.
+        confidence: request.teachBack.confidence,
+    });
+    switch (call.kind) {
+        case "endpoint_refused":
+            return { ok: false, reason: "agent_endpoint_unsafe", message: call.reason };
+        case "unreachable":
+            return {
+                ok: false,
+                reason: "control_plane_unreachable",
+                message: "Balladeer could not be reached, and nothing was recorded for it.",
+            };
+        case "client_too_old":
+            return {
+                ok: false,
+                reason: "client_too_old",
+                message: `this copy of the Balladeer command is too old for the server. Update it with: ${call.update}`,
+            };
+        case "unauthorized":
+            return {
+                ok: false,
+                reason: "agent_connection_revoked",
+                message: "Balladeer refused this repository's agent connection: it was revoked, or the repository it was bound to is no longer enrolled. Retrying will not help.",
+            };
+        case "tool_refusal":
+            return {
+                ok: false,
+                reason: "propose_refused",
+                message: `Balladeer refused it: ${call.text}`,
+            };
+        case "http":
+            return {
+                ok: false,
+                reason: "propose_failed",
+                message: `Balladeer answered ${call.status}, and nothing was recorded for it.`,
+            };
+        case "malformed":
+            return {
+                ok: false,
+                reason: "propose_failed",
+                message: "Balladeer could not record it.",
+            };
+        case "result":
+            break;
+    }
+    const candidateId = structuredString(call.structured, "id");
+    const status = structuredString(call.structured, "status");
+    if (candidateId === undefined) {
+        return { ok: false, reason: "propose_failed", message: "Balladeer could not record it." };
+    }
+    if (status !== "pending_review") {
+        return {
+            ok: false,
+            reason: "candidate_not_pending",
+            message: `Balladeer matched an existing proposal, ${candidateId}, which is ${status ?? "in an unreported state"}. Nothing new was recorded.`,
+        };
+    }
+    return { ok: true, candidateId };
+}

package/dist/commands/explain.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What this release of the command actually performs, stamped with its own
+ * version and kept strictly outside the boundary copy.
+ *
+ * The boundary copy describes the product's boundary and is timeless; it names
+ * two credentials, a CI workflow, and a check on pull requests. In balladeer
+ * 1.0.0 the command reaches none of those, so saying so is the difference
+ * between an explanation and a claim.
+ */
+export declare const RELEASE_PREFACE: string;
+/**
+ * Where a person watches this after the terminal has scrolled away.
+ *
+ * The boundary copy says what Balladeer receives and the release preface says
+ * what the command does; neither of them ever said where any of it shows up.
+ * Somebody who has just agreed to their first promise and closed the terminal
+ * had, until this paragraph, no way to find it again from anything the product
+ * printed. The address is the deployment this command is talking to rather than
+ * a literal, because a person running against a staging deployment reading a
+ * production link would be sent to somebody else's workspace.
+ */
+export declare function whereToWatch(controlPlane: string): string;
+/**
+ * What leaving costs, answered before anybody has to ask.
+ *
+ * A person deciding whether to put their team's promises somewhere is deciding
+ * how hard it would be to stop, and the honest answer here is unusually good:
+ * the tests are theirs and stay theirs. It was written down in
+ * `docs/customer-operability.md` and reachable from no command, so the one
+ * audience who most needs it, the engineer being asked to try this, never met
+ * it.
+ */
+export declare function ifYouStop(controlPlane: string): string;
+export declare function explainText(controlPlane?: string): string;
+export declare function runExplain(write: (text: string) => void, controlPlane?: string): number;

package/dist/commands/explain.js

@@ -0,0 +1,90 @@
+import { BOUNDARY_COPY } from "../copy.js";
+import { CLI_VERSION, DEFAULT_CONTROL_PLANE } from "../wire.js";
+/**
+ * What this release of the command actually performs, stamped with its own
+ * version and kept strictly outside the boundary copy.
+ *
+ * The boundary copy describes the product's boundary and is timeless; it names
+ * two credentials, a CI workflow, and a check on pull requests. In balladeer
+ * 1.0.0 the command reaches none of those, so saying so is the difference
+ * between an explanation and a claim.
+ */
+export const RELEASE_PREFACE = [
+    `In balladeer ${CLI_VERSION} this command performs all five steps: it pairs this session, adds`,
+    `this repository, connects this coding agent, records the CI identity and opens the pull request`,
+    `whose run proves it, and hands you the playbook for discovering this repository's own promises.`,
+    `The two things it never does are sign you in and agree to a promise; both of those are yours,`,
+    `in a browser.`,
+].join("\n");
+/**
+ * Where a person watches this after the terminal has scrolled away.
+ *
+ * The boundary copy says what Balladeer receives and the release preface says
+ * what the command does; neither of them ever said where any of it shows up.
+ * Somebody who has just agreed to their first promise and closed the terminal
+ * had, until this paragraph, no way to find it again from anything the product
+ * printed. The address is the deployment this command is talking to rather than
+ * a literal, because a person running against a staging deployment reading a
+ * production link would be sent to somebody else's workspace.
+ */
+export function whereToWatch(controlPlane) {
+    return [
+        "Where to watch this",
+        "",
+        `Everything Balladeer holds for your team is at ${controlPlane}. The catalog lists every promise`,
+        "with who owns it and whether anything is checking it. Each promise has its own page, which is",
+        "the one to keep: it shows what your team agreed the software must do, in their words, and then",
+        "every run that has checked it since, newest first, with the commit each one checked. That page",
+        "is how a promise reads over time rather than today, and it is where a broken one says what",
+        "broke and when.",
+        "",
+        "Balladeer also has a Slack app, and a workspace administrator installs it from workspace",
+        "settings. Once it is installed, the person who owns a promise gets a direct message when their",
+        "promise goes live, when a run on your default branch breaks it, and once a week about promises",
+        "nothing is checking yet. Until an administrator installs it, nothing is sent anywhere and the",
+        "product is somewhere you look rather than something that tells you.",
+    ].join("\n");
+}
+/**
+ * What leaving costs, answered before anybody has to ask.
+ *
+ * A person deciding whether to put their team's promises somewhere is deciding
+ * how hard it would be to stop, and the honest answer here is unusually good:
+ * the tests are theirs and stay theirs. It was written down in
+ * `docs/customer-operability.md` and reachable from no command, so the one
+ * audience who most needs it, the engineer being asked to try this, never met
+ * it.
+ */
+export function ifYouStop(controlPlane) {
+    return [
+        "If you stop using Balladeer",
+        "",
+        "Your tests are yours and they keep running. The verifier package, its fixtures and the workflow",
+        "file all live in your own repository, they run in your own CI, and disconnecting Balladeer",
+        "changes nothing about any of them: nothing here is a dependency your test suite acquires.",
+        "",
+        `An administrator can download everything Balladeer holds for your team at any time, at`,
+        `${controlPlane}/settings: every promise and what it means, who agreed to it and when, the`,
+        "verifier each one is bound to, every run that reported, and the history of every change. It is",
+        "one JSON file and it needs nobody's permission but your own.",
+        "",
+        "Disconnecting produces that same download in the response that ends hosted access, so nobody",
+        "ends up locked out of their own history by the act of leaving. After it, every credential this",
+        "setup issued stops working and Balladeer stops accepting results. Your repository is untouched.",
+    ].join("\n");
+}
+export function explainText(controlPlane = DEFAULT_CONTROL_PLANE) {
+    return [
+        BOUNDARY_COPY,
+        RELEASE_PREFACE,
+        "",
+        whereToWatch(controlPlane),
+        "",
+        ifYouStop(controlPlane),
+        "",
+    ].join("\n");
+}
+export function runExplain(write, controlPlane = DEFAULT_CONTROL_PLANE) {
+    write(explainText(controlPlane));
+    return 0;
+}

package/dist/commands/invite.d.ts

@@ -0,0 +1,24 @@
+export type InviteRole = "admin" | "contributor" | "viewer";
+export type InviteOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    emails: readonly string[];
+    role: InviteRole;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+}>;
+export declare const ROLE_NAMES: Readonly<Record<InviteRole, string>>;
+/** What each role may do, in one clause, so nobody invites by guessing. */
+export declare const ROLE_MEANINGS: Readonly<Record<InviteRole, string>>;
+export declare function parseRole(value: string | undefined): InviteRole | undefined;
+export declare function looksLikeEmail(value: string): boolean;
+/**
+ * Invites teammates by email, one at a time, and says what happened to each.
+ *
+ * Per address rather than per run. Sending four invitations is four separate
+ * things that can each succeed or be refused on their own, and a person reading
+ * "3 of 4 sent" cannot tell whose email is missing. Every address gets its own
+ * line and its own object, and the exit code says only whether every one of
+ * them went.
+ */
+export declare function runInvite(options: InviteOptions): Promise<number>;