balladeer 1.0.0 → 1.0.2

package/dist/store.d.ts

@@ -1,7 +1,7 @@
 import type { DelegatedScope } from "./wire.js";
 export declare class StoreError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    constructor(code: string, message: string, options?: ErrorOptions);
 }
 export type PendingPairing = Readonly<{
     controlPlane: string;
@@ -81,6 +81,16 @@ export declare function readCredentials(environment?: NodeJS.ProcessEnv): Creden
  * its mode is set on the open descriptor, and it is flushed before the rename.
  */
 export declare function writeCredentials(credentials: Credentials, environment?: NodeJS.ProcessEnv): void;
+/**
+ * One private file in the store directory, written the same careful way the
+ * credential is.
+ *
+ * Pulled out of `writeCredentials` rather than copied beside it: the session
+ * marker written next to the credential is not a secret, but it is written into
+ * the same directory by the same command, and a second, sloppier writer there
+ * would be the one an attacker pre-plants a symlink for.
+ */
+export declare function writeStoreFile(fileName: string, contents: string, environment?: NodeJS.ProcessEnv): void;
 /** Origins, not URL strings, so `https://host/../` cannot alias a stored entry. */
 export declare function normalizeControlPlane(value: string): string;
 /** At most one pending pairing per control plane, newest wins. */

package/dist/store.js

@@ -5,8 +5,8 @@ import { homedir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
 export class StoreError extends Error {
     code;
-    constructor(code, message) {
-        super(message);
+    constructor(code, message, options) {
+        super(message, options);
         this.name = "StoreError";
         this.code = code;
     }
@@ -124,14 +124,26 @@ export function readCredentials(environment = process.env) {
  * its mode is set on the open descriptor, and it is flushed before the rename.
  */
 export function writeCredentials(credentials, environment = process.env) {
+    writeStoreFile("credentials.json", `${JSON.stringify(credentials, null, 2)}\n`, environment);
+}
+/**
+ * One private file in the store directory, written the same careful way the
+ * credential is.
+ *
+ * Pulled out of `writeCredentials` rather than copied beside it: the session
+ * marker written next to the credential is not a secret, but it is written into
+ * the same directory by the same command, and a second, sloppier writer there
+ * would be the one an attacker pre-plants a symlink for.
+ */
+export function writeStoreFile(fileName, contents, environment = process.env) {
     const directory = ensureStoreDirectory(environment);
-    const path = join(directory, "credentials.json");
-    const temporary = join(directory, `.credentials.${randomBytes(8).toString("hex")}.tmp`);
+    const path = join(directory, fileName);
+    const temporary = join(directory, `.${fileName}.${randomBytes(8).toString("hex")}.tmp`);
     let descriptor;
     try {
         descriptor = openSync(temporary, "wx", 0o600);
         fchmodSync(descriptor, 0o600);
-        writeSync(descriptor, `${JSON.stringify(credentials, null, 2)}\n`);
+        writeSync(descriptor, contents);
         fsyncSync(descriptor);
         closeSync(descriptor);
         descriptor = undefined;
@@ -154,7 +166,7 @@ export function writeCredentials(credentials, environment = process.env) {
         }
         if (error instanceof StoreError)
             throw error;
-        throw new StoreError("credential_store_unwritable", `Balladeer could not write ${path}: ${error instanceof Error ? error.message : "unknown reason"}`);
+        throw new StoreError("credential_store_unwritable", `Balladeer could not write ${path}: ${error instanceof Error ? error.message : "unknown reason"}`, { cause: error });
     }
 }
 /** Origins, not URL strings, so `https://host/../` cannot alias a stored entry. */

package/dist/wire.d.ts

@@ -5,9 +5,10 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export declare const CLI_VERSION = "1.0.0";
+export declare const CLI_VERSION = "1.0.2";
+export declare const CLI_INVOCATION = "npx -y balladeer@latest";
 export declare const CLIENT_HEADER = "x-balladeer-client";
-export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.0";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.2";
 export declare const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 export type DelegatedScope = "repository:enroll" | "agent:issue" | "ci:connect" | "workspace:invite" | "candidate:propose";
 export declare const DELEGATED_SCOPES: readonly DelegatedScope[];
@@ -108,6 +109,21 @@ export type SetupInvitationResponse = Readonly<{
 export type SetupCiRequest = Readonly<{
     eventClasses: readonly ("push" | "pull_request")[];
 }>;
+/**
+ * The GitHub login this machine's `gh` is signed in as.
+ *
+ * Sent so a run started by this person can be shown under their name instead of
+ * a handle nobody has learned. No token is sent, here or anywhere: the login is
+ * read from the GitHub CLI they already signed in to, and Balladeer stores it as
+ * something they said rather than something anyone checked. It grants nothing.
+ * An empty string clears it.
+ */
+export type SetupGithubLoginRequest = Readonly<{
+    login: string;
+}>;
+export type SetupGithubLoginResponse = Readonly<{
+    claimedLogin: string | null;
+}>;
 export type SetupRepositoryView = Readonly<{
     id: string;
     displayName: string;
@@ -193,9 +209,32 @@ export type SetupCandidateResponse = Readonly<{
     reviewUrl: string;
 }>;
 /** The step objects `--json` emits, one per line, and nothing else on stdout. */
+/**
+ * What a run did about Claude desktop chat, on the two steps that can touch it.
+ *
+ * Its own type because both `agent` and `refresh` report it and they must report
+ * it identically: an agent reading either step reads the same three fields.
+ */
+export type ClaudeDesktopStep = Readonly<{
+    status: "connected" | "current" | "absent" | "unsupported" | "refused";
+    key?: string;
+    path?: string;
+    reason?: string;
+}>;
 export type JsonStep = Readonly<{
     step: "explain";
     version: string;
+}> | Readonly<{
+    /**
+     * The GitHub login this machine was signed in as, handed over so a run
+     * this person starts can be shown under their name. `status` says what
+     * happened: `claimed` when it was recorded, `unavailable` when `gh` could
+     * not name a login, and `refused` when the control plane would not take
+     * it. None of the three stops setup.
+     */
+    step: "github_login";
+    status: "claimed" | "unavailable" | "refused";
+    login?: string;
 }> | Readonly<{
     step: "pair";
     status: "pending" | "paired" | "expired" | "denied";
@@ -210,7 +249,7 @@ export type JsonStep = Readonly<{
     scopes?: readonly DelegatedScope[];
 }> | Readonly<{
     step: "repository";
-    status: "added" | "already" | "blocked";
+    status: "added" | "already" | "not_connected" | "blocked";
     repository?: string;
     repositoryId?: string;
     defaultBranch?: string;
@@ -258,6 +297,15 @@ export type JsonStep = Readonly<{
     /** Present only where this command refused to change one of these files. */
     mcpConfig?: string;
     conventions?: string;
+    /**
+     * What happened to Claude desktop chat, present only where this run had
+     * something to say about it. `connected` and `current` carry the key this
+     * repository's server is named under and the file it was written to;
+     * `absent`, `unsupported` and `refused` carry the sentence saying why
+     * nothing was written, and are only ever reported where the flag asked for
+     * it or the file itself refused the merge.
+     */
+    claudeDesktop?: ClaudeDesktopStep;
 }> | Readonly<{
     step: "ci";
     /**
@@ -266,7 +314,7 @@ export type JsonStep = Readonly<{
      * moved, and the repository's own workflow file has not, so the proof is a
      * run on the new pin that has not happened yet.
      */
-    status: "identity_recorded" | "connected" | "release_upgraded" | "blocked";
+    status: "identity_recorded" | "connected" | "release_upgraded" | "not_changed" | "blocked";
     repositoryId?: string;
     pullRequestUrl?: string;
     validatedRunCount?: number;
@@ -276,6 +324,10 @@ export type JsonStep = Readonly<{
     /** The release this repository was moved onto, on a `release_upgraded` step. */
     attestorReleaseSha?: string;
     reason?: string;
+}> | Readonly<{
+    step: "warning";
+    code: "enforcement_unavailable";
+    message: string;
 }> | Readonly<{
     step: "promise";
     status: "proposed" | "agreed" | "none";
@@ -284,6 +336,20 @@ export type JsonStep = Readonly<{
     reviewUrl?: string;
     promiseUrl?: string;
 }>
+/**
+ * The one-time qualification setup, minted and written to disk.
+ *
+ * `supersededPackets` is the number of earlier packets this run invalidated,
+ * so a caller can tell an ordinary first preparation from a deliberate
+ * replacement without reading prose. It is zero on the ordinary case.
+ */
+ | Readonly<{
+    step: "qualification";
+    status: "prepared";
+    promiseId: string;
+    metadataPath: string;
+    supersededPackets: number;
+}>
 /**
  * A whole discovered catalog, filed in one run.
  *
@@ -482,6 +548,30 @@ export type JsonStep = Readonly<{
     changed: boolean;
     exitCode: number;
 }>
+/**
+ * The working session an agent reads and commits under.
+ *
+ * `minted` is the difference between "here is a new session" and "you already
+ * have one open": an agent that asked twice must reuse the second answer
+ * rather than treat it as a second session, or its reads and its commit end
+ * up under two ids and the join breaks by the act of asking for it.
+ */
+ | Readonly<{
+    step: "session";
+    sessionId: string;
+    startedAt: string;
+    minted: boolean;
+    /** The exact line to write into the commit or the pull-request body. */
+    trailer: string;
+    changed: boolean;
+}>
+/** One commit recorded as written by one session. */
+ | Readonly<{
+    step: "session_commit";
+    sessionId: string;
+    commitSha: string;
+    changed: boolean;
+}>
 /**
  * One invited address, one line, whatever happened to it.
  *
@@ -582,6 +672,7 @@ export type JsonStep = Readonly<{
     previousConventionsVersion?: number;
     reason?: string;
     message?: string;
+    claudeDesktop?: ClaudeDesktopStep;
 }> | Readonly<{
     step: "whoami";
     session: PairSessionSummary;

package/dist/wire.js

@@ -5,7 +5,8 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export const CLI_VERSION = "1.0.0";
+export const CLI_VERSION = "1.0.2";
+export const CLI_INVOCATION = "npx -y balladeer@latest";
 export const CLIENT_HEADER = "x-balladeer-client";
 export const CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;
 export const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "balladeer",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,