balladeer 0.0.4 → 1.0.0

package/dist/commands/propose.js

@@ -0,0 +1,262 @@
+import { readFileSync } from "node:fs";
+import { callAgentTool, noAgentCredentialSentence, selectAgent, structuredString, } from "../agent.js";
+import { reviewLink } from "../client.js";
+import { commandLine } from "../release.js";
+import { repositoryHint } from "../repository.js";
+import { StoreError, readCredentials } from "../store.js";
+import {} from "../wire.js";
+const MAX_FILE_BYTES = 64 * 1024;
+/**
+ * Every field the server's schema requires with no default. It is every
+ * required key of `semanticMeaningSchema` and nothing else: three of these were
+ * missing once, and a file without them passed this gate, left the machine, and
+ * was refused on the other side, which is exactly what this check exists to
+ * prevent. `refactorExamples` is deliberately absent because the schema now
+ * accepts a meaning without one; a file that still carries one is still sent.
+ */
+const REQUIRED_MEANING_FIELDS = [
+    "title",
+    "beneficiary",
+    "trigger",
+    "preconditions",
+    "observableOutcome",
+    "allowedVariations",
+    "nonGoals",
+    "passingExamples",
+    "failingExamples",
+    "scope",
+];
+/** The only keys this command sends, at each of the two levels it reads. */
+const ALLOWED_TOP_LEVEL = ["teachBack", "explicitIntent"];
+const ALLOWED_TEACH_BACK = [
+    "meaning",
+    "unresolvedQuestions",
+    "proposedOwnerId",
+    "confidence",
+];
+function unexpectedKeys(value, allowed) {
+    return Object.keys(value).filter((key) => !allowed.includes(key));
+}
+/**
+ * The shape check that happens on the developer's machine, and the body it
+ * builds.
+ *
+ * `--file` reads whatever path it is handed, and an agent that mistypes one
+ * would otherwise upload a `.env`, a source file, or a log to a service whose
+ * whole boundary is that it never receives those. Refusing here means the wrong
+ * file never leaves the machine, rather than leaving it and being refused.
+ *
+ * So this returns the exact object to send rather than a verdict on the file.
+ * Spreading the parsed file into the request was the same mistake in a quieter
+ * form: whatever else the file happened to carry travelled with it, and the
+ * strict schema on the other side is a refusal after the fact, not a boundary.
+ */
+export function readTeachBackFile(raw) {
+    if (Buffer.byteLength(raw, "utf8") > MAX_FILE_BYTES) {
+        return { ok: false, reason: "the file is larger than 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" };
+    }
+    const extra = unexpectedKeys(parsed, ALLOWED_TOP_LEVEL);
+    if (extra.length > 0) {
+        return {
+            ok: false,
+            reason: `it carries ${extra.join(", ")}, which a proposal does not have and this command will not send`,
+        };
+    }
+    const value = parsed;
+    const teachBack = value.teachBack;
+    if (teachBack === undefined || typeof teachBack !== "object" || Array.isArray(teachBack)) {
+        return { ok: false, reason: "it has no teachBack object" };
+    }
+    const extraTeachBack = unexpectedKeys(teachBack, ALLOWED_TEACH_BACK);
+    if (extraTeachBack.length > 0) {
+        return {
+            ok: false,
+            reason: `teachBack carries ${extraTeachBack.join(", ")}, which this command will not send`,
+        };
+    }
+    const meaning = teachBack.meaning;
+    if (meaning === undefined || typeof meaning !== "object" || Array.isArray(meaning)) {
+        return { ok: false, reason: "it has no teachBack.meaning" };
+    }
+    const missing = REQUIRED_MEANING_FIELDS.filter((field) => meaning[field] === undefined);
+    if (missing.length > 0) {
+        return { ok: false, reason: `teachBack.meaning is missing ${missing.join(", ")}` };
+    }
+    if (typeof value.explicitIntent !== "string" || value.explicitIntent.trim().length === 0) {
+        return { ok: false, reason: "it has no explicitIntent saying why this is being proposed" };
+    }
+    // Read from the file, never assumed. Every proposal this command ever filed
+    // was recorded at 1 because 1 was written here in the code, so the number an
+    // owner reads on the review page said nothing about this proposal: it said
+    // what the constant said. A file that will not state how sure its author was
+    // is refused rather than answered on their behalf.
+    const confidence = teachBack.confidence;
+    if (typeof confidence !== "number" || !Number.isFinite(confidence)) {
+        return {
+            ok: false,
+            reason: "teachBack.confidence is missing. Say how sure you are that this is the behavior the person meant, as a number from 0 to 1",
+        };
+    }
+    if (confidence < 0 || confidence > 1) {
+        return { ok: false, reason: "teachBack.confidence must be between 0 and 1" };
+    }
+    return {
+        ok: true,
+        value: {
+            explicitIntent: value.explicitIntent,
+            teachBack: {
+                meaning,
+                confidence,
+                ...(teachBack.unresolvedQuestions === undefined
+                    ? {}
+                    : { unresolvedQuestions: teachBack.unresolvedQuestions }),
+                ...(teachBack.proposedOwnerId === undefined
+                    ? {}
+                    : { proposedOwnerId: teachBack.proposedOwnerId }),
+            },
+        },
+    };
+}
+/**
+ * The repository a proposal is about, taken from the connection rather than from
+ * the file.
+ *
+ * A teach-back file names surfaces and labels; it has never named a repository
+ * id, because the setup route stamped one from the repository the request
+ * resolved. The connection is now what resolves it, so it stamps it: a file that
+ * carried some other repository's id cannot reach that repository, because this
+ * overwrites it and the server refuses a candidate whose scope does not match
+ * the principal's repository anyway.
+ */
+function scopedMeaning(meaning, repositoryId) {
+    const scope = meaning.scope;
+    if (scope === null || typeof scope !== "object" || Array.isArray(scope))
+        return meaning;
+    return { ...meaning, scope: { ...scope, repositoryId } };
+}
+/**
+ * Proposes one promise over this repository's own agent connection.
+ *
+ * It used to go over the delegated setup session, which lives for a bounded time
+ * and is meant for setting Balladeer up. That made proposing something a person
+ * could only do for a while after pairing: the credential expired, and a command
+ * whose whole job is "propose this" answered "run setup again". The connection
+ * this uses instead is the one setup issued for this repository, the same one
+ * the agent host forwards, and it does not expire.
+ *
+ * Nothing widens by moving: the call is `propose_promise` on the MCP endpoint,
+ * so it is authenticated as the agent principal, bound to that one repository,
+ * and refused everything except proposing. It lands as a candidate awaiting a
+ * named person's agreement, and nothing this command can do agrees to it.
+ */
+export async function runPropose(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 proposal file: balladeer propose --file <path>.", 4);
+    }
+    let raw;
+    try {
+        raw = readFileSync(options.file, "utf8");
+    }
+    catch {
+        return fail("teachback_unreadable", `I could not read ${options.file}.`, 4);
+    }
+    const parsed = readTeachBackFile(raw);
+    if (!parsed.ok) {
+        return fail("teachback_malformed", `${options.file} is not a proposal: ${parsed.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") {
+        // The repository being connected somewhere else is not this machine holding
+        // a credential, and a proposal runs over the one this machine holds. Said in
+        // its own sentence, before anything is sent, because the remedy is to
+        // connect this machine rather than to pair again: a setup session, however
+        // fresh, cannot carry a proposal.
+        if (selection.missingFor !== undefined) {
+            return fail("no_agent_credential_on_this_machine", `${noAgentCredentialSentence(selection.missingFor)} Nothing was sent.`, 4);
+        }
+        return fail("no_agent_connection", `${selection.reason} Run \`${commandLine(null, "setup")}\` in this repository first. Nothing was sent.`, 4);
+    }
+    const { agent } = selection;
+    const call = await callAgentTool(agent, "propose_promise", {
+        // A person or an agent ran this command against a file that says why. That
+        // is the explicit act the server requires; nothing here infers one.
+        explicitHumanAction: true,
+        source: "protect_behavior",
+        explicitIntent: parsed.value.explicitIntent,
+        meaning: scopedMeaning(parsed.value.teachBack.meaning, agent.repositoryId),
+        unresolvedQuestions: parsed.value.teachBack.unresolvedQuestions ?? [],
+        ...(parsed.value.teachBack.proposedOwnerId === undefined
+            ? {}
+            : { proposedOwnerId: parsed.value.teachBack.proposedOwnerId }),
+        confidence: parsed.value.teachBack.confidence,
+    });
+    switch (call.kind) {
+        case "endpoint_refused":
+            return fail("agent_endpoint_unsafe", `${call.reason} Nothing was sent.`, 4);
+        case "unreachable":
+            return fail("control_plane_unreachable", `Balladeer could not be reached at ${options.controlPlane}. Nothing was changed.`, 5);
+        case "client_too_old":
+            return fail("client_too_old", `This copy of the Balladeer command is too old for ${options.controlPlane}. Update it with: ${call.update}`, 3);
+        case "unauthorized":
+            return fail("agent_connection_revoked", `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. Run \`${commandLine(null, "setup")}\` here again, or issue a new connection at ${options.controlPlane}/setup. Nothing was recorded.`, 5);
+        case "tool_refusal":
+            return fail("propose_refused", `Balladeer refused this proposal: ${call.text}`, 5);
+        case "http":
+            return fail("propose_failed", `Balladeer answered ${call.status} to this proposal. Nothing was recorded.`, 5);
+        case "malformed":
+            return fail("propose_failed", "Balladeer could not record this proposal.", 5);
+        case "result":
+            break;
+    }
+    const candidateId = structuredString(call.structured, "id");
+    const status = structuredString(call.structured, "status");
+    if (candidateId === undefined) {
+        return fail("propose_failed", "Balladeer could not record this proposal.", 5);
+    }
+    if (status !== "pending_review") {
+        // The server matched something already on file rather than recording a new
+        // proposal, which is what the setup route used to answer as a conflict. It
+        // is reported as one here too: sending a person to agree to a record that
+        // was already decided is worse than saying nothing was recorded.
+        return fail("candidate_not_pending", `Balladeer matched an existing proposal, ${candidateId}, which is ${status ?? "in an unreported state"}. Nothing new was recorded.`, 5);
+    }
+    // The review link is built from the address this copy paired with. The tool
+    // answers with an id and no link at all, so there is nothing here a
+    // misconfigured public base URL could redirect.
+    const review = reviewLink(options.controlPlane, `candidates/${candidateId}`);
+    emit({ step: "promise", status: "proposed", candidateId, reviewUrl: review });
+    if (!options.json) {
+        options.write("Proposed. You will own it unless you named someone else; the owner reads it and clicks Agree, and nothing else can.\n");
+        options.write(`${review}\n`);
+        options.write(`Sent over ${agent.repository ?? "this repository"}'s Balladeer agent connection, which does not expire.\n`);
+    }
+    return 0;
+}

package/dist/commands/repositories.d.ts

@@ -0,0 +1,18 @@
+export type RepositoriesOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    write: (text: string) => void;
+}>;
+/**
+ * What this machine could add to Balladeer, and which of them are already in.
+ *
+ * It exists so the agent asking "which repositories shall I set up" has
+ * something to show. Setting one up is still `setup`, run in a checkout of it or
+ * named with `--repository`; this command changes nothing and sends nothing
+ * anywhere. The one network call it makes is to Balladeer, to find out which of
+ * these are already enrolled, and it is skipped entirely when no session is
+ * stored.
+ */
+export declare function runRepositories(options: RepositoriesOptions): Promise<number>;

package/dist/commands/repositories.js

@@ -0,0 +1,185 @@
+import { ClientTooOldError, TransportError, request } from "../client.js";
+import { ghAvailable, ghLogin, ghSignedIn, listVisibleRepositories } from "../gh.js";
+import { commandLine } from "../release.js";
+import { StoreError, findSession, readCredentials } from "../store.js";
+import { repositoryHint } from "../repository.js";
+import {} from "../wire.js";
+/** How many to offer. A list nobody reads to the end is a list nobody chooses from. */
+const LIMIT = 100;
+function emit(options, step) {
+    if (options.json)
+        options.write(`${JSON.stringify(step)}\n`);
+}
+function say(options, text) {
+    if (!options.json)
+        options.write(`${text}\n`);
+}
+/**
+ * What this machine could add to Balladeer, and which of them are already in.
+ *
+ * It exists so the agent asking "which repositories shall I set up" has
+ * something to show. Setting one up is still `setup`, run in a checkout of it or
+ * named with `--repository`; this command changes nothing and sends nothing
+ * anywhere. The one network call it makes is to Balladeer, to find out which of
+ * these are already enrolled, and it is skipped entirely when no session is
+ * stored.
+ */
+export async function runRepositories(options) {
+    const here = repositoryHint(options.cwd);
+    const known = here === "unknown/unknown" ? undefined : here;
+    if (!(await ghAvailable())) {
+        return withoutGh(options, known, "the GitHub CLI is not installed", "Install the GitHub CLI from https://cli.github.com, sign in with `gh auth login`, then run this command again to see the whole list.");
+    }
+    if (!(await ghSignedIn())) {
+        return withoutGh(options, known, "gh is installed but not signed in", "Run `gh auth login`, then run this command again to see the whole list.");
+    }
+    // The account's own repositories, and the organization this checkout belongs
+    // to. A Didero engineer sitting in one of their own repositories wants the
+    // other eleven, and those belong to the organization rather than to them.
+    const owners = new Set([undefined]);
+    const hereOwner = known?.split("/")[0];
+    if (hereOwner !== undefined)
+        owners.add(hereOwner);
+    const login = await ghLogin();
+    if (login !== undefined &&
+        hereOwner !== undefined &&
+        login.toLowerCase() === hereOwner.toLowerCase()) {
+        owners.delete(hereOwner);
+    }
+    const seen = new Map();
+    for (const owner of owners) {
+        for (const found of await listVisibleRepositories(owner, LIMIT)) {
+            if (!seen.has(found.repository.toLowerCase())) {
+                seen.set(found.repository.toLowerCase(), found.canWrite);
+            }
+        }
+    }
+    if (known !== undefined && !seen.has(known.toLowerCase()))
+        seen.set(known.toLowerCase(), true);
+    const enrolled = await enrolledNames(options);
+    const rows = [...seen.keys()]
+        .map((name) => ({
+        repository: name,
+        here: known !== undefined && name === known.toLowerCase(),
+        ...(enrolled === undefined ? {} : { enrolled: enrolled.has(name) }),
+    }))
+        // The one you are standing in first, then the rest alphabetically, so the
+        // default is the first thing read rather than something to hunt for.
+        .sort((left, right) => left.here === right.here
+        ? left.repository.localeCompare(right.repository)
+        : left.here
+            ? -1
+            : 1);
+    if (rows.length === 0) {
+        say(options, "Your GitHub account can see no repositories to add.");
+        emit(options, {
+            step: "repositories",
+            source: "none",
+            workspaceKnown: enrolled !== undefined,
+            repositories: [],
+        });
+        return 0;
+    }
+    report(options, rows, enrolled !== undefined);
+    emit(options, {
+        step: "repositories",
+        source: "gh",
+        workspaceKnown: enrolled !== undefined,
+        repositories: rows,
+    });
+    return 0;
+}
+/** The listing a person reads, and the one line that sets any of them up. */
+function report(options, rows, workspaceKnown) {
+    say(options, workspaceKnown
+        ? "Repositories your GitHub account can see. Ones already in Balladeer are marked."
+        : "Repositories your GitHub account can see. Nothing is stored for this Balladeer, so which of them are already added is unknown.");
+    say(options, "");
+    for (const row of rows) {
+        const marks = [
+            row.here ? "this directory" : undefined,
+            row.enrolled === true ? "already in Balladeer" : undefined,
+        ].filter((mark) => mark !== undefined);
+        say(options, `  ${row.repository}${marks.length === 0 ? "" : `  (${marks.join(", ")})`}`);
+    }
+    const addable = rows.filter((row) => row.enrolled !== true);
+    say(options, "");
+    if (addable.length === 0) {
+        say(options, "Every repository this machine can see is already in Balladeer.");
+        return;
+    }
+    say(options, "Add one, or several, with:");
+    say(options, `  ${commandLine(null, `setup ${addable
+        .slice(0, 2)
+        .map((row) => `--repository ${row.repository}`)
+        .join(" ")}`)}`);
+    say(options, "Connecting a repository's coding agent and its CI happens in a checkout of that repository, so run setup there for each one. Naming a repository from somewhere else adds it to the workspace and stops there, which is said again when it happens.");
+}
+/**
+ * Which repositories the workspace already holds, or nothing at all.
+ *
+ * Nothing rather than an empty set when there is no session or the read failed:
+ * an empty set would render every repository as addable, and an agent reading
+ * that would offer to add repositories the workspace already has.
+ */
+async function enrolledNames(options) {
+    let session;
+    try {
+        session = findSession(readCredentials(options.environment), options.controlPlane);
+    }
+    catch (error) {
+        if (!(error instanceof StoreError))
+            throw error;
+        return undefined;
+    }
+    if (session === undefined)
+        return undefined;
+    try {
+        const state = await request(options.controlPlane, {
+            method: "GET",
+            path: "/api/setup/v1/state",
+            bearer: session.token,
+        });
+        return new Set(state.repositories
+            .filter((repository) => repository.status === "active")
+            .map((repository) => repository.displayName.toLowerCase()));
+    }
+    catch (error) {
+        if (error instanceof ClientTooOldError || error instanceof TransportError)
+            return undefined;
+        return undefined;
+    }
+}
+/**
+ * The answer when `gh` cannot list anything.
+ *
+ * Still an answer rather than a refusal: this directory's own repository is a
+ * real thing an agent can offer, and telling somebody with no `gh` installed
+ * that there is nothing to add would be false.
+ */
+function withoutGh(options, here, reason, next) {
+    if (here === undefined) {
+        say(options, `I could not list your repositories: ${reason}.`);
+        say(options, `  This directory has no GitHub origin remote either, so I have nothing to offer.`);
+        say(options, `  Next: ${next}`);
+        emit(options, {
+            step: "repositories",
+            source: "none",
+            workspaceKnown: false,
+            repositories: [],
+            reason,
+        });
+        return 0;
+    }
+    say(options, `I could not list your repositories: ${reason}.`);
+    say(options, `  This directory's origin remote is ${here}, which is the one setup adds by default.`);
+    say(options, `  Next: ${next}`);
+    emit(options, {
+        step: "repositories",
+        source: "origin",
+        workspaceKnown: false,
+        repositories: [{ repository: here.toLowerCase(), here: true }],
+        reason,
+    });
+    return 0;
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,75 @@
+export type SetupOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    wait: boolean;
+    repo?: string;
+    createWorkspace?: string;
+    /**
+     * Every repository this run was told to set up, in the order they were named.
+     *
+     * One of them is this run's own: the steps after the enrollment write files
+     * and push a branch, and they can only do that to the working tree this
+     * process was started in. The rest are added to the workspace and nothing
+     * else, which is exactly what an agent enrolling a team's repositories from
+     * one checkout can honestly do from here, and the run says so per repository.
+     */
+    repositories?: readonly string[];
+    /**
+     * Repair the two files a previous setup wrote in this repository, and do
+     * nothing else. No pairing, no enrollment, no credential, no network: a
+     * stale install is repaired where it is, which may be a laptop that cannot
+     * reach the control plane at that moment.
+     */
+    refresh?: boolean;
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    write: (text: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => Date;
+}>;
+/** The bound the control plane's own name check holds, refused here so a name
+ * nobody could create never costs a pairing code. */
+export declare const CREATE_WORKSPACE_MAX_LENGTH = 120;
+/**
+ * Which repository this run acts on, and which it only adds.
+ *
+ * Every step after the enrollment acts on the working tree this process was
+ * started in: it writes `.mcp.json` and the conventions block there, and it
+ * cuts, commits and pushes the CI branch to that tree's own remote. So exactly
+ * one named repository can be this run's own, and it has to be the one this
+ * directory is a checkout of. Naming one repository while sitting in another
+ * would enroll one and change the other, and push a branch to a repository
+ * nobody named.
+ *
+ * A directory with no readable GitHub origin is not a disagreement: naming a
+ * repository is exactly how a person adds one from somewhere that is not a
+ * checkout of it, and every step below says what it could not do there.
+ */
+type Chosen = Readonly<{
+    kind: "chosen";
+    primary: string;
+    also: readonly string[];
+}> | Readonly<{
+    kind: "mismatch";
+    message: string;
+}>;
+export declare function chooseRepositories(named: readonly string[], cwd: string): Chosen;
+/**
+ * One run. It prints what it found, does what it can, and exits within seconds.
+ * Waiting is the person's choice, behind `--wait`, because an agent shell kills
+ * a command that blocks for minutes and the pairing would be lost with it.
+ */
+export declare function runSetup(options: SetupOptions): Promise<number>;
+/**
+ * Which invocation this repair writes, decided without asking anybody.
+ *
+ * A repair runs where the stale install is, and the server is not always
+ * reachable from there, so the two honest local sources are how this copy was
+ * itself obtained and what the file already says. A copy running out of a
+ * registry install writes the registry form. A copy running out of a checkout
+ * leaves a registry form alone rather than downgrading a published install to
+ * an absolute path on one person's laptop, and writes the checkout form only
+ * where the file was already a checkout form or had no entry at all.
+ */
+export declare function refreshPublishedForm(existing: unknown): string | null;
+export {};