balladeer 0.0.5 → 1.0.1

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/session.d.ts

@@ -0,0 +1,35 @@
+export type SessionOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    /**
+     * Read the session out of the commit at HEAD and tell Balladeer which commit
+     * it wrote, instead of printing an id.
+     */
+    record: boolean;
+    /** Start a new session even though one is still current. */
+    fresh: boolean;
+    /** 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;
+    now?: string;
+    write: (text: string) => void;
+}>;
+/**
+ * The id that joins what an agent was told to what it then wrote.
+ *
+ * Retrieval happens before the commit exists, so nothing ties the two together
+ * on its own, and without the tie a red check on Tuesday cannot be read back
+ * against what Balladeer had said on Monday. The agent's own working session
+ * spans both: it reads the index under this id and writes the same id into the
+ * commit it produces.
+ *
+ * `balladeer session` prints the id and the exact line to write.
+ * `balladeer session --record` reads that line back out of the commit at HEAD
+ * and tells Balladeer which commit the session wrote. The commit message itself
+ * never leaves this machine: only the pair of a session id and a forty-
+ * character SHA is sent, and the SHA is a fact CI already reports.
+ */
+export declare function runSession(options: SessionOptions): Promise<number>;

package/dist/commands/session.js

@@ -0,0 +1,118 @@
+import { callAgentTool, noAgentCredentialSentence, selectAgent } from "../agent.js";
+import { headCommit } from "../git.js";
+import { repositoryHint } from "../repository.js";
+import { AGENT_SESSION_TRAILER, agentSessionTrailerLine, currentSession, readAgentSessionTrailer, } from "../session.js";
+import { StoreError, readCredentials } from "../store.js";
+import {} from "../wire.js";
+/**
+ * The id that joins what an agent was told to what it then wrote.
+ *
+ * Retrieval happens before the commit exists, so nothing ties the two together
+ * on its own, and without the tie a red check on Tuesday cannot be read back
+ * against what Balladeer had said on Monday. The agent's own working session
+ * spans both: it reads the index under this id and writes the same id into the
+ * commit it produces.
+ *
+ * `balladeer session` prints the id and the exact line to write.
+ * `balladeer session --record` reads that line back out of the commit at HEAD
+ * and tells Balladeer which commit the session wrote. The commit message itself
+ * never leaves this machine: only the pair of a session id and a forty-
+ * character SHA is sent, and the SHA is a fact CI already reports.
+ */
+export async function runSession(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);
+    if (selection.kind === "refused") {
+        const message = selection.missingFor === undefined
+            ? selection.reason
+            : noAgentCredentialSentence(selection.missingFor);
+        return fail("no_agent_credential_on_this_machine", message, 4);
+    }
+    const agent = selection.agent;
+    if (options.record)
+        return recordCommit(options, agent, emit, say, fail);
+    let session;
+    try {
+        session = currentSession({
+            repository: agent.repositoryId,
+            now: options.now ?? new Date().toISOString(),
+            ...(options.fresh ? { forceNew: true } : {}),
+            environment: options.environment,
+        });
+    }
+    catch (error) {
+        return fail(error instanceof StoreError ? error.code : "session_store_unwritable", error instanceof StoreError ? error.message : String(error), 4);
+    }
+    const trailer = agentSessionTrailerLine(session.sessionId);
+    emit({
+        step: "session",
+        sessionId: session.sessionId,
+        startedAt: session.startedAt,
+        minted: session.minted,
+        trailer,
+        changed: session.minted,
+    });
+    say(session.sessionId);
+    say("");
+    say(session.minted
+        ? "This is a new session. Pass it to every promise read you make in this repository."
+        : "This session is already open. Pass it to every promise read you make in this repository, and use --new to start a different one.");
+    say(`Then write this line into the commit or pull-request body you produce:`);
+    say("");
+    say(`    ${trailer}`);
+    say("");
+    say(`and run \`balladeer session --record\` once the commit exists, so a check that goes red on it can be read back against what you were told before you started. Balladeer is sent the session id and the commit SHA, and nothing else.`);
+    return 0;
+}
+async function recordCommit(options, agent, emit, say, fail) {
+    const head = await headCommit(options.cwd);
+    if (head === undefined) {
+        return fail("no_commit_here", "There is no commit to record: this directory is not a git checkout, or it has no commits yet.", 4);
+    }
+    const sessionId = readAgentSessionTrailer(head.message);
+    if (sessionId === undefined) {
+        // Said in full rather than as a code. The likeliest reader of this line is
+        // an agent that forgot the trailer, and the remedy is one line it can add
+        // to the commit it just made.
+        return fail("no_session_trailer", `The commit at HEAD carries no ${AGENT_SESSION_TRAILER} line this release recognises, so there is nothing to record. Add \`${AGENT_SESSION_TRAILER}: <the id balladeer session prints>\` to the commit message and run this again. A commit carrying two different session ids is refused rather than guessed at.`, 4);
+    }
+    const call = await callAgentTool(agent, "record_session_commit", {
+        session: sessionId,
+        commitSha: head.sha,
+    });
+    if (call.kind !== "result") {
+        return fail(call.kind === "tool_refusal" ? "refused" : call.kind, call.kind === "tool_refusal"
+            ? call.text
+            : `Balladeer could not record this commit (${call.kind}). Nothing was recorded, and running this again after the connection is back is safe: the same pair recorded twice is recorded once.`, 5);
+    }
+    emit({
+        step: "session_commit",
+        sessionId,
+        commitSha: head.sha,
+        changed: true,
+    });
+    say(`Recorded ${head.sha.slice(0, 12)} as written by this session.`);
+    return 0;
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,98 @@
+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;
+    /**
+     * Set up even though an earlier Balladeer is still installed on this machine.
+     *
+     * The check that stops this run is a warning about two programs claiming one
+     * name, not a safety property, so somebody who has decided to run both says so
+     * and this run carries on exactly as it would have.
+     */
+    force?: boolean;
+    /**
+     * Whether to also connect Claude desktop chat for this repository.
+     *
+     * Three states, because there are three answers and only two of them are a
+     * flag. `true` is `--claude-desktop`: connect it, and say out loud when this
+     * machine has no such app rather than skipping in silence. `false` is
+     * `--no-claude-desktop`: do not touch that file and do not mention it.
+     * Undefined is the ordinary run, which connects it where Claude desktop is
+     * installed and says nothing at all where it is not. Writing it by default is
+     * the same bargain `.mcp.json` already makes: the entry is additive, it
+     * carries no credential, it never replaces anybody else's server, and the
+     * people this is for write their plan in that chat before they open a coding
+     * agent at all.
+     */
+    claudeDesktop?: 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 {};