balladeer 0.0.5 → 1.0.1

package/dist/cli.js

@@ -0,0 +1,531 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runAffected } from "./commands/affected.js";
+import { runCheckSeals } from "./commands/check-seals.js";
+import { runDiscover } from "./commands/discover.js";
+import { runExplain } from "./commands/explain.js";
+import { parseRole, runInvite } from "./commands/invite.js";
+import { runMcp } from "./commands/mcp.js";
+import { runPrepare } from "./commands/prepare.js";
+import { runPropose } from "./commands/propose.js";
+import { runRepositories } from "./commands/repositories.js";
+import { CREATE_WORKSPACE_MAX_LENGTH, runSetup } from "./commands/setup.js";
+import { runSession } from "./commands/session.js";
+import { runStatus } from "./commands/status.js";
+import { runTouchMap } from "./commands/touch-map.js";
+import { runWhoami } from "./commands/whoami.js";
+import { updateNotice } from "./currency.js";
+import { StoreError, normalizeControlPlane } from "./store.js";
+import { CLI_VERSION, DEFAULT_CONTROL_PLANE } from "./wire.js";
+const USAGE = `balladeer ${CLI_VERSION}
+
+  balladeer setup [--repository owner/name]... [--json] [--wait] [--control-plane <url>]
+                  [--create-workspace <name>] [--refresh] [--force]
+                  [--claude-desktop | --no-claude-desktop]
+      Pair this session, add this repository, connect this coding agent and CI,
+      and report what a person still has to do. Name --repository more than once
+      to add other repositories to the same workspace; each of those is added and
+      nothing more, because connecting an agent and CI happens in a checkout.
+      --create-workspace carries a name to the approval page, where a person
+      signs in and creates the workspace themselves; this command never creates
+      one.
+      --refresh does one thing and talks to nobody: it rewrites this
+      repository's balladeer entry in .mcp.json, its Balladeer instructions
+      block and its Claude desktop chat entry to the current form, leaves every
+      other entry in those files alone, and prints what it changed. Run it when
+      Balladeer says a newer version is available.
+      --force sets up even though an earlier Balladeer is still installed on
+      this machine. Without it, a run that finds the older client's machine-wide
+      MCP entry or session hook stops and says to remove it first.
+      Claude desktop chat is connected too, under a key named for this
+      repository, wherever the app is installed. --claude-desktop asks for it by
+      name, so a machine with no Claude desktop on it says so instead of
+      skipping quietly; --no-claude-desktop leaves that file alone entirely.
+      Quit and reopen the app afterwards: it reads its configuration at startup.
+
+  balladeer repositories [--json] [--control-plane <url>]
+      List the repositories this machine's GitHub account can see, marking the
+      one you are standing in and the ones Balladeer already has.
+
+  balladeer invite <email>... [--role contributor|viewer|administrator] [--json]
+      Invite teammates into this workspace by email, and say per address whether
+      the invitation went. Inviting is an administrator's act.
+
+  balladeer status [<promise id>] [--repo owner/name] [--repository <uuid>] [--json]
+                   [--control-plane <url>]
+      Report this repository over its agent connection, and every repository in
+      the workspace when a setup session is still live. Named with a promise id,
+      report that one promise instead: whether it is holding, and if it is not,
+      the commit the failing run checked, the bounded reason, and the cases in
+      the agreed meaning that run was checking. That is the form the line on a
+      broken promise tells a person to run first.
+
+  balladeer propose --file <path> [--repo owner/name] [--repository <uuid>] [--json]
+      Propose one promise from a proposal file, over this repository's agent
+      connection. A named person still agrees to it.
+
+  balladeer prepare <promise id> [--again] [--repo owner/name] [--repository <uuid>]
+                    [--json] [--control-plane <url>]
+      Prepare the one-time qualification setup for a promise whose meaning is
+      agreed and which nothing is checking yet, and write it to
+      .continuity/qualification/<promise id>.json, which is where the sealed run
+      reads it. No sign-off and no code: agreeing the meaning was the person's
+      act, and building the check that proves it is yours. Then build the
+      verifier, seal it, and push to the default branch; protection starts by
+      itself when that run qualifies. It is one-time, so while nobody has
+      published against the packet already prepared this refuses and says who
+      prepared it and when. --again prepares a replacement and invalidates that
+      earlier packet: a run publishing its identities afterwards is refused.
+
+  balladeer discover --file <path> [--repo owner/name] [--repository <uuid>]
+                     [--owner <membership id>] [--json]
+      Propose a whole discovered catalog, up to ten promises from one file, each
+      owned by whoever paired this machine, and print one link that opens all of
+      them. A named person still agrees to every one.
+
+  balladeer check-seals [--json] [--runner <path>] [--install-hook]
+      Say whether what you are about to push would break a promise's seal. It
+      prints nothing and exits 0 when it would not, and names the promise, its
+      owner, its page and the line that seals it again when it would. It runs
+      offline, over the runner this repository is pinned to. --install-hook
+      writes .git/hooks/pre-push so every push asks first; nothing installs it
+      for you, and deleting that file removes it.
+
+  balladeer touch-map [--json]
+      Run this repository's promise verifiers under coverage and write down
+      which files each one actually executed, to .continuity/touch-map.json.
+      It runs offline and the map stays on this machine: Balladeer is never
+      sent it. Node verifiers only in this release.
+
+  balladeer affected <paths...> [--json]
+      Say which promises the named files touch, out of that map, marking any
+      answer whose verifier has changed since the map was built. It reads one
+      local file and contacts nothing.
+
+  balladeer session [--new] [--record] [--repo owner/name] [--repository <uuid>] [--json]
+                    [--control-plane <url>]
+      Print the id for this piece of work, and the one line to write into the
+      commit it produces. Pass the id to every promise read you make, so a check
+      that goes red later can be read back against what Balladeer told you
+      before you started. --new starts a different session; --record reads the
+      Balladeer-Session line out of the commit at HEAD and tells Balladeer which
+      commit this session wrote. Your commit message never leaves this machine:
+      only the session id and the commit SHA are sent.
+
+  balladeer explain [--control-plane <url>]
+      Print, word for word, what Balladeer can and cannot see, where to watch
+      your promises, and what leaving costs.
+
+  balladeer whoami [--json] [--control-plane <url>]
+      Report the stored setup session's workspace, role, scopes, and expiry.
+
+  balladeer agent rotate [--control-plane <url>]
+      Replace this repository's agent credential. A setup session cannot do this,
+      because rotating revokes the connections the repository already has.
+
+  balladeer mcp [--repository <uuid>] [--control-plane <url>]
+      Forward one MCP session over stdio using this repository's agent connection.
+
+Exit codes: 0 progress reported truthfully, 2 pairing expired or denied or already
+claimed, 3 this copy is too old for the server, 4 usage or credential store problem,
+5 transport or server failure, 6 an earlier Balladeer is still installed on this
+machine and nothing was changed.
+`;
+const SUBCOMMANDS = { agent: ["rotate"] };
+export function parseArguments(argv) {
+    const args = [...argv];
+    const command = args.shift() ?? "help";
+    let subcommand;
+    if (SUBCOMMANDS[command] !== undefined) {
+        subcommand = args.shift();
+        if (subcommand === undefined || !SUBCOMMANDS[command].includes(subcommand)) {
+            throw new StoreError("usage", `${command} needs one of: ${SUBCOMMANDS[command].join(", ")}.`);
+        }
+    }
+    let json = false;
+    let wait = false;
+    let refresh = false;
+    let force = false;
+    let claudeDesktop;
+    let installHook = false;
+    let fresh = false;
+    let record = false;
+    let again = false;
+    let runner;
+    let controlPlane;
+    let repo;
+    let file;
+    let owner;
+    let createWorkspace;
+    let role;
+    const repositories = [];
+    const positional = [];
+    const NEEDS = {
+        "--control-plane": "a URL",
+        "--repo": "an owner/name",
+        "--file": "a path",
+        "--repository": "a repository, as owner/name for setup or as an id elsewhere",
+        "--owner": "a membership id",
+        "--create-workspace": "a workspace name",
+        "--role": "contributor, viewer, or administrator",
+        "--runner": "a path to the pinned runner's cli.js",
+    };
+    const value = (flag, inline) => {
+        const next = inline ?? args.shift();
+        if (!next)
+            throw new StoreError("usage", `${flag} needs ${NEEDS[flag] ?? "a value"}.`);
+        return next;
+    };
+    while (args.length > 0) {
+        const flag = args.shift();
+        if (!flag.startsWith("--")) {
+            positional.push(flag);
+            continue;
+        }
+        const [name, ...rest] = flag.split("=");
+        const inline = rest.length > 0 ? rest.join("=") : undefined;
+        if (name === "--json")
+            json = true;
+        else if (name === "--again")
+            again = true;
+        else if (name === "--install-hook")
+            installHook = true;
+        else if (name === "--new")
+            fresh = true;
+        else if (name === "--record")
+            record = true;
+        else if (name === "--runner")
+            runner = value("--runner", inline);
+        else if (name === "--wait")
+            wait = true;
+        else if (name === "--refresh")
+            refresh = true;
+        else if (name === "--force")
+            force = true;
+        else if (name === "--claude-desktop")
+            claudeDesktop = true;
+        else if (name === "--no-claude-desktop")
+            claudeDesktop = false;
+        else if (name === "--control-plane")
+            controlPlane = value("--control-plane", inline);
+        else if (name === "--repo")
+            repo = value("--repo", inline);
+        else if (name === "--file")
+            file = value("--file", inline);
+        else if (name === "--repository")
+            repositories.push(value("--repository", inline));
+        else if (name === "--owner")
+            owner = value("--owner", inline);
+        else if (name === "--role")
+            role = value("--role", inline);
+        else if (name === "--create-workspace") {
+            createWorkspace = value("--create-workspace", inline).trim();
+            if (createWorkspace.length === 0 || createWorkspace.length > CREATE_WORKSPACE_MAX_LENGTH) {
+                throw new StoreError("usage", `--create-workspace needs a workspace name of 1 to ${CREATE_WORKSPACE_MAX_LENGTH} characters.`);
+            }
+        }
+        else
+            throw new StoreError("usage", `Unknown option ${flag}.`);
+    }
+    // `invite` is the one command that takes a bare word, and the words it takes
+    // are email addresses. Anywhere else a bare word is a mistyped flag or a
+    // value that lost its flag, and it was refused before this loop learned to
+    // collect them, so it is refused here rather than ignored.
+    // `affected` is the other one, and the words it takes are paths in the change
+    // in front of the person. `prepare` and `status` each take exactly one bare
+    // word, the promise id a person copied off a promise page, which is the form
+    // both of those commands are told to people and to agents in.
+    // `--again` invalidates a packet somebody may be halfway through using, so it
+    // belongs to the one command that mints one. Accepted silently elsewhere, it
+    // would read as a general "do it anyway" flag.
+    if (again && command !== "prepare") {
+        throw new StoreError("usage", "--again belongs to prepare: run `balladeer prepare <promise id> --again`.");
+    }
+    if (positional.length > 0 &&
+        command !== "invite" &&
+        command !== "affected" &&
+        command !== "prepare" &&
+        command !== "status") {
+        throw new StoreError("usage", `${command} takes no bare arguments: ${positional.join(", ")}.`);
+    }
+    // `--repository` names one repository everywhere but `setup`, where it names
+    // as many as a person wants to add. A second one anywhere else is refused
+    // rather than resolved to the last: silently acting on one of two repositories
+    // somebody named is worse than saying no.
+    // `--refresh` repairs the files setup writes, so it belongs to setup and to
+    // nothing else. Accepting it silently elsewhere would let somebody run
+    // `status --refresh`, see no error, and believe their install was repaired.
+    if (refresh && command !== "setup") {
+        throw new StoreError("usage", "--refresh belongs to setup: run `balladeer setup --refresh`.");
+    }
+    // `--force` says one thing only: set up alongside an earlier Balladeer. Taken
+    // silently by another command it would read as a general "do it anyway" flag,
+    // which is exactly what nothing else here offers.
+    if (force && command !== "setup") {
+        throw new StoreError("usage", "--force belongs to setup: run `balladeer setup --force`.");
+    }
+    // Connecting a chat client is something setup does, so the flag belongs to
+    // setup. Accepted silently on `status`, it would let somebody believe they had
+    // connected Claude desktop when nothing had written a line.
+    if (claudeDesktop !== undefined && command !== "setup") {
+        throw new StoreError("usage", "--claude-desktop belongs to setup: run `balladeer setup --claude-desktop`.");
+    }
+    if (command !== "setup" && repositories.length > 1) {
+        throw new StoreError("usage", `${command} acts on one repository. Name --repository once, or run it again for the other.`);
+    }
+    const chosen = controlPlane ?? process.env.BALLADEER_CONTROL_PLANE?.trim() ?? DEFAULT_CONTROL_PLANE;
+    return {
+        command,
+        subcommand,
+        json,
+        wait,
+        refresh,
+        force,
+        claudeDesktop,
+        repo,
+        file,
+        repository: repositories[0],
+        repositories,
+        owner,
+        installHook,
+        fresh,
+        record,
+        again,
+        runner,
+        createWorkspace,
+        positional,
+        role,
+        controlPlane: normalizeControlPlane(chosen),
+    };
+}
+export async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArguments(argv);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`);
+        return 4;
+    }
+    const write = (text) => void process.stdout.write(text);
+    const code = await dispatch(parsed, write);
+    // Said once, at the end, on stderr: an agent reading `--json` gets its steps
+    // on stdout unchanged, and a person reading a terminal gets the one line that
+    // says this copy is behind. It is a nag and never a failure, so it does not
+    // touch the exit code.
+    const notice = updateNotice();
+    if (notice !== undefined)
+        process.stderr.write(`${notice}\n`);
+    return code;
+}
+async function dispatch(parsed, write) {
+    switch (parsed.command) {
+        case "explain":
+            return runExplain(write, parsed.controlPlane);
+        case "setup":
+            return runSetup({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                wait: parsed.wait,
+                refresh: parsed.refresh,
+                force: parsed.force,
+                ...(parsed.claudeDesktop === undefined ? {} : { claudeDesktop: parsed.claudeDesktop }),
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                repositories: parsed.repositories,
+                ...(parsed.createWorkspace === undefined
+                    ? {}
+                    : { createWorkspace: parsed.createWorkspace }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "repositories":
+            return runRepositories({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "invite": {
+            const role = parseRole(parsed.role);
+            if (role === undefined) {
+                process.stderr.write(`--role takes contributor, viewer, or administrator. It was given "${parsed.role}".\n`);
+                return 4;
+            }
+            return runInvite({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                emails: parsed.positional,
+                role,
+                environment: process.env,
+                write,
+            });
+        }
+        case "check-seals":
+            return runCheckSeals({
+                json: parsed.json,
+                installHook: parsed.installHook,
+                ...(parsed.runner === undefined ? {} : { runner: parsed.runner }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "touch-map":
+            return runTouchMap({
+                json: parsed.json,
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "session":
+            return runSession({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                record: parsed.record,
+                fresh: parsed.fresh,
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                ...(parsed.repository === undefined ? {} : { repository: parsed.repository }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "affected":
+            return runAffected({
+                json: parsed.json,
+                paths: parsed.positional,
+                cwd: process.cwd(),
+                write,
+            });
+        case "status": {
+            // At most one. Two ids on one line is a mistake, and answering for the
+            // first of them silently would report a promise nobody asked about.
+            if (parsed.positional.length > 1) {
+                process.stderr.write("status reads one promise id at a time.\n");
+                return 4;
+            }
+            const promiseId = parsed.positional[0];
+            return runStatus({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                ...(promiseId === undefined ? {} : { promiseId }),
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                ...(parsed.repository === undefined ? {} : { repository: parsed.repository }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        }
+        case "prepare": {
+            // One id, and one only. Preparing two packets from one line would mint
+            // two one-time identities and write two files, and reporting the first
+            // silently would leave the second promise unprepared with nobody told.
+            if (parsed.positional.length !== 1) {
+                process.stderr.write("prepare reads one promise id: balladeer prepare <promise id> [--again].\n");
+                return 4;
+            }
+            return runPrepare({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                promiseId: parsed.positional[0],
+                again: parsed.again,
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                ...(parsed.repository === undefined ? {} : { repository: parsed.repository }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        }
+        case "propose":
+            return runPropose({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                ...(parsed.file === undefined ? {} : { file: parsed.file }),
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                ...(parsed.repository === undefined ? {} : { repository: parsed.repository }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "discover":
+            return runDiscover({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                ...(parsed.file === undefined ? {} : { file: parsed.file }),
+                ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
+                ...(parsed.repository === undefined ? {} : { repository: parsed.repository }),
+                ...(parsed.owner === undefined ? {} : { owner: parsed.owner }),
+                environment: process.env,
+                cwd: process.cwd(),
+                write,
+            });
+        case "agent":
+            // Rotating revokes every live connection for the repository, which is
+            // removal. The approval page tells a person their setup session cannot
+            // remove anything, so this command says the same rather than trying and
+            // relaying a server refusal the person cannot act on.
+            process.stderr.write("A setup session cannot rotate an agent connection: rotating revokes the connections this repository already has, and a setup session may not remove anything.\n" +
+                `Rotate it in Balladeer under workspace settings at ${parsed.controlPlane}/settings.\n`);
+            return 4;
+        case "whoami":
+            return runWhoami({
+                controlPlane: parsed.controlPlane,
+                json: parsed.json,
+                environment: process.env,
+                write,
+            });
+        case "mcp":
+            return runMcp({
+                controlPlane: parsed.controlPlane,
+                ...(parsed.repository === undefined ? {} : { repositoryId: parsed.repository }),
+                environment: process.env,
+                cwd: process.cwd(),
+                stdin: process.stdin,
+                write,
+                error: (text) => void process.stderr.write(text),
+            });
+        case "help":
+        case "--help":
+        case "-h":
+            write(USAGE);
+            return 0;
+        case "--version":
+        case "-v":
+            write(`${CLI_VERSION}\n`);
+            return 0;
+        default:
+            process.stderr.write(`Unknown command "${parsed.command}".\n\n${USAGE}`);
+            return 4;
+    }
+}
+/**
+ * The real file behind a path, following symlinks.
+ *
+ * `npx` and every global install run this program through a
+ * `node_modules/.bin/balladeer` symlink, so `process.argv[1]` is the link and
+ * not the file Node loaded. `resolve` does not follow a link, so comparing
+ * resolved paths made the guard below false for every customer: the process
+ * exited 0 having printed nothing, and only a checkout running
+ * `node dist/cli.js` ever saw the program run at all.
+ *
+ * A path that cannot be read back falls through to the resolved form rather
+ * than throwing, because a guard that decides whether the program runs must
+ * never be the thing that stops it.
+ */
+function programPath(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+// Only when this file is the program, so a test may import `main` without the
+// import itself running a command.
+const entry = process.argv[1];
+if (entry !== undefined && programPath(fileURLToPath(import.meta.url)) === programPath(entry)) {
+    process.exitCode = await main(process.argv.slice(2));
+}

package/dist/client.d.ts

@@ -0,0 +1,66 @@
+import { type PairRefusal } from "./wire.js";
+export declare class TransportError extends Error {
+    readonly controlPlane: string;
+    constructor(controlPlane: string, reason: string);
+}
+export declare class ClientTooOldError extends Error {
+    readonly update: string;
+    readonly controlPlane: string;
+    constructor(controlPlane: string, update: string);
+}
+export declare class RefusalError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(status: number, refusal: PairRefusal);
+}
+/**
+ * A link this command prints, always built from the address it paired with.
+ *
+ * Behind a platform proxy a server can resolve a link against the machine it is
+ * running on rather than against the address customers use, and the first
+ * production `propose` printed exactly that: a review link on `localhost:8080`
+ * as the place to go and agree. A command that prints such a link is worse than
+ * one that prints none, because the person tries it.
+ *
+ * So no link a server sends is ever printed. The proposal path answers with an
+ * identifier and this builds the address, which is why there is no parameter
+ * here for a server's own link to arrive through.
+ */
+export declare function reviewLink(controlPlane: string, path: string): string;
+/**
+ * The one place this command decides where a person reads a proposal.
+ *
+ * Every review address this command prints, in a receipt, in a discovery run,
+ * or in its JSON, is built here, so the address is one edit rather than a hunt
+ * and a printed link cannot fall behind the page it names. It matches the
+ * server's own `proposal-links` helper: the page is `/proposals`, and
+ * the retired address redirects to it permanently, so a link an older copy of
+ * this command already printed still lands on it.
+ */
+export declare function proposalReviewLink(controlPlane: string, proposalId: string): string;
+/** The address the whole waiting inbox is read on. */
+export declare function proposalInboxLink(controlPlane: string): string;
+/**
+ * One link that opens exactly the proposals named, and nothing else.
+ *
+ * The ids travel in the query string because the batch is exactly these
+ * promises: 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 declare function batchProposalReviewLink(controlPlane: string, proposalIds: readonly string[]): string;
+export type RequestOptions = Readonly<{
+    method: "GET" | "POST";
+    path: string;
+    body?: unknown;
+    bearer?: string;
+    timeoutMs?: number;
+}>;
+/**
+ * The one place this command talks to a network.
+ *
+ * `redirect: "manual"` so no redirect can carry a bearer to a host the person
+ * never paired with, and the 426 handshake is decoded here so every caller gets
+ * the same actionable refusal rather than a status code.
+ */
+export declare function request<T>(controlPlane: string, options: RequestOptions): Promise<T>;