balladeer 0.0.4 → 1.0.0

package/dist/wire.d.ts

@@ -0,0 +1,588 @@
+/**
+ * The request and response shapes this command sends and receives, inlined.
+ *
+ * They are written out here rather than imported so the published package has no
+ * 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 CLIENT_HEADER = "x-balladeer-client";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.0";
+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[];
+/** The verifier digest the server accepts, and the form the store writes. */
+export declare const VERIFIER_DIGEST_PREFIX = "sha256:";
+export type PairStartRequest = Readonly<{
+    verifierDigest: string;
+    repositoryHint: string;
+    hostHint: string;
+}>;
+export type PairStartResponse = Readonly<{
+    pairingId: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresAt: string;
+    pollIntervalSeconds: number;
+}>;
+export type PairSessionSummary = Readonly<{
+    sessionId: string;
+    workspaceId: string;
+    workspaceName: string;
+    workspaceSlug: string;
+    /**
+     * The membership that approved this session. `discover` names it as the
+     * proposed owner of every promise it files, because the person who ran setup
+     * is the person the catalog is waiting on. Absent from a server too old to
+     * send it, which is a refusal to guess rather than a wrong owner.
+     */
+    membershipId?: string;
+    membershipDisplayName: string;
+    role: string;
+    scopes: readonly DelegatedScope[];
+    scopeMeanings: readonly string[];
+    expiresAt: string;
+}>;
+export type PairPollResponse = Readonly<{
+    status: "pending";
+    pollIntervalSeconds: number;
+}> | Readonly<{
+    status: "claimed";
+    token: string;
+    session: PairSessionSummary;
+}>;
+export type PairRefusal = Readonly<{
+    error: string;
+    message?: string;
+    minimum?: string;
+    blessed?: string;
+    update?: string;
+}>;
+/**
+ * The setup API, inlined the same way and for the same reason.
+ *
+ * A contract test compares these field names against `@balladeer/contracts`, so
+ * the published package still carries no runtime dependency while a change to
+ * either side that the other did not follow fails the build.
+ */
+export type SetupRepositoryRequest = Readonly<{
+    repository: string;
+    githubRepositoryId: string;
+    githubOwnerId: string;
+    defaultBranch: string;
+}>;
+export type SetupAgentRequest = Readonly<{
+    label?: string;
+    rotate?: boolean;
+}>;
+/**
+ * One teammate invited. The workspace is absent because the session decides it:
+ * a command cannot invite anybody into a workspace its approver is not in.
+ */
+export type SetupInvitationRequest = Readonly<{
+    email: string;
+    requestedRole: "admin" | "contributor" | "viewer";
+}>;
+/**
+ * What the server answers once the email has actually gone.
+ *
+ * The address comes back as the server recorded it rather than as it was typed,
+ * so the confirmation a person reads names the address the invitation went to.
+ * `expiresAt` is null where the deadline could not be read back; the invitation
+ * was still sent, and reporting a guessed date would be worse than reporting
+ * none.
+ */
+export type SetupInvitationResponse = Readonly<{
+    email: string;
+    requestedRole: "admin" | "contributor" | "viewer";
+    status: "sent";
+    workspaceName: string;
+    expiresAt: string | null;
+}>;
+/**
+ * Only the event classes. The GitHub owner id and the caller workflow reference
+ * decide whose signed runs count, so the server derives both from the
+ * enrollment and this command never names either.
+ */
+export type SetupCiRequest = Readonly<{
+    eventClasses: readonly ("push" | "pull_request")[];
+}>;
+export type SetupRepositoryView = Readonly<{
+    id: string;
+    displayName: string;
+    defaultBranch: string;
+    status: "enrolling" | "active" | "revoked";
+    githubRepositoryId: string | null;
+    githubOwnerId: string | null;
+    agentConfigured: boolean;
+    agentConnectionId: string | null;
+    ciIdentityRecorded: boolean;
+    ciConfigured: boolean;
+    ciValidatedRunCount: number;
+    ciFirstValidatedAt: string | null;
+    ciLastValidatedAt: string | null;
+    eventClasses: readonly string[];
+    ciAttestorReleaseId: string | null;
+    /**
+     * The release this repository was moved off and whose runs are still
+     * accepted, and null when the enrollment names only its current release.
+     * Publication moves the enrollment; this is the pin the repository's own
+     * workflow file may still carry.
+     */
+    ciSupersededAttestorReleaseId: string | null;
+    /** That release's commit, which is the pin the workflow file is leaving. */
+    ciSupersededAttestorReleaseSha: string | null;
+    /**
+     * Candidates still waiting for a named person, and the newest of them. One a
+     * person has already accepted, merged, or rejected is in neither, so this
+     * command can never send someone back to the browser to agree to something
+     * that is already agreed or was refused.
+     */
+    candidateCount: number;
+    latestCandidateId: string | null;
+    promiseCount: number;
+    /** The promise this repository's first agreement produced, once one exists. */
+    firstPromiseId: string | null;
+}>;
+/**
+ * How the server says this command should be invoked.
+ *
+ * `publishedVersion` is null until the package is actually on the registry, and
+ * `command` is the invocation to print: the pinned registry form once it is,
+ * and the checkout form until then.
+ */
+export type SetupClientRelease = Readonly<{
+    publishedVersion: string | null;
+    command: string;
+}>;
+export type SetupStateResponse = Readonly<{
+    workspace: Readonly<{
+        id: string;
+        name: string;
+        slug: string;
+    }>;
+    repositories: readonly SetupRepositoryView[];
+    client: SetupClientRelease;
+}>;
+export type CallerWorkflowResponse = Readonly<{
+    workspaceLocator: string;
+    defaultBranch: string;
+    workflowPath: string;
+    workflowYaml: string;
+    attestorWorkflowRef: string;
+    attestorSha: string;
+    attestationOrigin: string;
+    variables: readonly Readonly<{
+        name: string;
+        value: string;
+    }>[];
+}>;
+export type AgentPacketResponse = Readonly<{
+    connectionId: string;
+    repositoryId: string;
+    scopes: readonly string[];
+    token: string;
+    mcpUrl: string;
+    configuration: unknown;
+    instructions: readonly string[];
+}>;
+export type SetupCandidateResponse = Readonly<{
+    candidateId: string;
+    repositoryId: string;
+    reviewUrl: string;
+}>;
+/** The step objects `--json` emits, one per line, and nothing else on stdout. */
+export type JsonStep = Readonly<{
+    step: "explain";
+    version: string;
+}> | Readonly<{
+    step: "pair";
+    status: "pending" | "paired" | "expired" | "denied";
+    userCode?: string;
+    verificationUri?: string;
+    expiresAt?: string;
+    workspace?: Readonly<{
+        id: string;
+        name: string;
+        slug: string;
+    }>;
+    scopes?: readonly DelegatedScope[];
+}> | Readonly<{
+    step: "repository";
+    status: "added" | "already" | "blocked";
+    repository?: string;
+    repositoryId?: string;
+    defaultBranch?: string;
+    /**
+     * Present only where this run filled in the GitHub owner id of a
+     * repository that was added without one. It is the id now recorded, so an
+     * agent reading these lines can see that step 4 became possible here.
+     */
+    githubOwnerIdRecorded?: string;
+    reason?: string;
+}> | Readonly<{
+    step: "agent";
+    /**
+     * `connected` is reported only where Balladeer answered a real call over
+     * the credential this step issued. `unproven` is the connection existing
+     * and that call not having succeeded: the credential is stored and the
+     * files are written, and a caller must not report it as working.
+     * `already` is this machine holding a credential for this repository
+     * before the run started, which is the only reading of "already" that
+     * means the tools will work here.
+     */
+    status: "connected" | "unproven" | "already" | "blocked";
+    repositoryId?: string;
+    connectionId?: string;
+    /**
+     * True where this machine holds a credential for the repository once the
+     * step is over. A caller reads this rather than inferring a working
+     * machine from the repository being connected: the two are different
+     * facts, and only this one says the tools can run from here.
+     */
+    storedHere?: boolean;
+    /**
+     * True where the repository already had a live connection issued
+     * elsewhere and this run issued a further one for this machine. The
+     * existing connection is untouched; connections coexist and each is
+     * revoked on its own.
+     */
+    alreadyConnectedElsewhere?: boolean;
+    files?: readonly string[];
+    reason?: string;
+    /** The tool call that proved the connection, on a `connected` step. */
+    provedBy?: string;
+    /** What the person or agent does next, on an `unproven` step. */
+    nextAction?: string;
+    /** Present only where this command refused to change one of these files. */
+    mcpConfig?: string;
+    conventions?: string;
+}> | Readonly<{
+    step: "ci";
+    /**
+     * `release_upgraded` is this repository having been moved onto a newer
+     * Balladeer release. It is deliberately not `connected`: the enrollment has
+     * 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";
+    repositoryId?: string;
+    pullRequestUrl?: string;
+    validatedRunCount?: number;
+    firstValidatedAt?: string;
+    /** The workflow is already on the default branch, so there was nothing to commit. */
+    workflowInstalled?: boolean;
+    /** The release this repository was moved onto, on a `release_upgraded` step. */
+    attestorReleaseSha?: string;
+    reason?: string;
+}> | Readonly<{
+    step: "promise";
+    status: "proposed" | "agreed" | "none";
+    candidateId?: string;
+    promiseId?: string;
+    reviewUrl?: string;
+    promiseUrl?: string;
+}>
+/**
+ * A whole discovered catalog, filed in one run.
+ *
+ * `proposed` and `requested` are separate numbers on purpose: an agent that
+ * read only the count would report eight promises filed from a file of ten.
+ * `reviewUrl` is the one page that opens every promise this run filed, and it
+ * is absent when nothing was filed rather than pointing at an empty page.
+ */
+ | Readonly<{
+    step: "discovery";
+    status: "proposed" | "partial";
+    proposed: number;
+    requested: number;
+    /** The membership every promise in this run was proposed as owned by. */
+    ownerId: string;
+    candidateIds: readonly string[];
+    reviewUrl?: string;
+    /**
+     * Promises the run never tried, because a connection-level failure would
+     * have answered every one of them the same way. Present only when the run
+     * stopped early, so a caller can tell "refused" from "not attempted".
+     */
+    notAttempted?: number;
+    failures?: readonly Readonly<{
+        promise: number;
+        reason: string;
+        message: string;
+    }>[];
+}>
+/**
+ * This repository, read over its own agent connection rather than over a setup
+ * session. It is the step that answers "is Balladeer working here" long after
+ * the setup session that issued the connection has gone.
+ */
+ | Readonly<{
+    step: "connection";
+    status: "agent";
+    repositoryId: string;
+    repository?: string;
+    /** False when the repository has no current attestor release enrolled. */
+    enrolled: boolean;
+    /** How many active members may be named as a promise's proposed owner. */
+    memberCount: number;
+}>
+/**
+ * Something about this repository that a person should look at, observed on
+ * this machine rather than reported by Balladeer.
+ *
+ * Today there is one: a promise naming a path this checkout does not have,
+ * which is what a rename leaves behind. Balladeer cannot see it, because it
+ * holds no token for the repository and reads no file. `considered` and
+ * `total` are separate because the run is bounded: a caller has to be able to
+ * tell "nothing is missing" from "nothing is missing in the part I read".
+ */
+ | Readonly<{
+    step: "attention";
+    reason: "scope_marker_missing";
+    observed: number;
+    considered: number;
+    total: number;
+    stoppedEarly: boolean;
+    promises: readonly Readonly<{
+        promiseId: string;
+        missing: readonly string[];
+    }>[];
+}>
+/**
+ * One promise, read by id, and whether it is currently holding.
+ *
+ * This is what the copyable line on a broken promise sends an agent to, so it
+ * carries exactly the three facts a repair starts from: the commit the failing
+ * run checked, the bounded reason it could not report green, and the cases in
+ * the agreed meaning that run was checking. A promise that is holding says so
+ * and carries none of them.
+ */
+ | Readonly<{
+    step: "promise";
+    status: "holding" | "not_holding" | "unreadable";
+    promiseId: string;
+    title?: string;
+    protectionPosture?: string;
+    promiseUrl?: string;
+    ownerName?: string;
+    /** `refuted` is the caught regression; `unknown` is the check not deciding. */
+    kind?: "refuted" | "unknown";
+    sourceSha?: string;
+    reasonCode?: string;
+    refutedCaseIds?: readonly string[];
+    refutedCaseNote?: string;
+    observedAt?: string;
+    message?: string;
+}>
+/**
+ * The workspace-wide view, named as unavailable rather than reported as empty.
+ * Only a live setup session can read every repository, so a caller is told
+ * which view it did not get and why.
+ */
+ | Readonly<{
+    step: "workspace";
+    status: "unavailable";
+    reason: string;
+    message: string;
+}>
+/**
+ * The four receipts, each true on its own and each with an explicit not-yet
+ * form. Never one rolled-up "done": a person reading this has to be able to
+ * tell what was set up from what a named person still has to agree to.
+ */
+ | Readonly<{
+    step: "receipt";
+    setup: Readonly<{
+        complete: boolean;
+        sentence: string;
+    }>;
+    /**
+     * `reviewUrl` is a candidate a person still has to read, and `promiseUrl`
+     * is one they have agreed to. Never both, and never one under the other's
+     * name: a caller that followed `reviewUrl` to an already-agreed promise
+     * would send its person to agree to it a second time.
+     */
+    firstPromise: Readonly<{
+        complete: boolean;
+        sentence: string;
+        reviewUrl?: string;
+        promiseUrl?: string;
+    }>;
+    protection: Readonly<{
+        complete: boolean;
+        sentence: string;
+    }>;
+    /**
+     * Which credential keeps working once this run is over. Setting Balladeer
+     * up needs a session that ends; proposing and reporting from then on run
+     * over each repository's agent connection, which does not.
+     */
+    connection: Readonly<{
+        complete: boolean;
+        sentence: string;
+    }>;
+    repositories: readonly Readonly<{
+        repository: string;
+        agent: string;
+        ci: string;
+    }>[];
+}>
+/**
+ * Which promises this checkout seals, and which of them a pending change
+ * would break the seal of.
+ *
+ * `broken` is the count that matters and `promises` is the bounded list a
+ * person or an agent acts on. The reseal line travels with each row because
+ * the alternative is an agent assembling one from a path it half remembers.
+ */
+ | Readonly<{
+    step: "seals";
+    broken: number;
+    promises: readonly Readonly<{
+        promiseId: string;
+        sealedPath: string;
+        title?: string;
+        owner?: string;
+        promiseUrl?: string;
+        changedPaths: readonly string[];
+        resealWith: string;
+    }>[];
+    changed: boolean;
+}>
+/** The sealed directories this checkout carries, listed before anybody edits one. */
+ | Readonly<{
+    step: "sealed_paths";
+    total: number;
+    shown: readonly Readonly<{
+        promiseId: string;
+        sealedPath: string;
+        title?: string;
+    }>[];
+}>
+/** The optional pre-push hook, written only when somebody asked for it by name. */
+ | Readonly<{
+    step: "hook";
+    path: string;
+    changed: boolean;
+}>
+/**
+ * Every way this command can fail, in the shape a caller can branch on.
+ *
+ * `--json` is the mode an agent picks, and an agent that receives a bare exit
+ * code cannot tell a person what went wrong or whether the run left anything
+ * behind. `reason` is the bounded code, `message` is the same sentence a person
+ * would have read, and `changed` says whether this run altered anything.
+ */
+ | Readonly<{
+    step: "error";
+    reason: string;
+    message: string;
+    changed: boolean;
+    exitCode: number;
+}>
+/**
+ * One invited address, one line, whatever happened to it.
+ *
+ * A run that invites four people emits four of these, because a caller has to
+ * be able to tell a person which of the four emails went. Never one rolled-up
+ * status: three sent and one refused is not "partly done", it is three people
+ * who will get an email and one who will not.
+ */
+ | Readonly<{
+    step: "invitation";
+    status: "sent" | "refused";
+    email: string;
+    role: "admin" | "contributor" | "viewer";
+    workspace?: string;
+    expiresAt?: string | null;
+    reason?: string;
+    message?: string;
+}>
+/**
+ * What this machine can see and could add, so an agent has something to offer
+ * rather than asking a person to type repository names from memory.
+ *
+ * `enrolled` is read from the workspace, and absent entirely when no setup
+ * session could read it: a listing that quietly showed every repository as not
+ * enrolled would invite an agent to add the ones already there.
+ */
+ | Readonly<{
+    step: "repositories";
+    /** Where the names came from: the GitHub CLI, or this checkout's origin. */
+    source: "gh" | "origin" | "none";
+    workspaceKnown: boolean;
+    repositories: readonly Readonly<{
+        repository: string;
+        /** True for the repository this directory's origin remote names. */
+        here: boolean;
+        enrolled?: boolean;
+    }>[];
+    reason?: string;
+}>
+/**
+ * What the touch map now holds, after measuring this checkout's verifiers.
+ *
+ * `bytes` is here because the map is a file a person keeps, and `changed`
+ * because a second run over an unchanged repository rewrites nothing. Neither
+ * this step nor the file it describes ever leaves the machine: the map names
+ * a customer's own files, which Balladeer promises never to receive.
+ */
+ | Readonly<{
+    step: "touch_map";
+    promises: number;
+    files: number;
+    /** Promises whose verifier could not be measured, so nothing is mapped to them. */
+    unmapped: number;
+    bytes: number;
+    changed: boolean;
+    /** Present only when a size cap cut the map, so a short map is never read as complete. */
+    truncated?: true;
+}>
+/**
+ * Which promises the named paths touch, read out of the local map.
+ *
+ * `mapped` false is the answer when there is no map to read, and it is not an
+ * error: a repository nobody has measured yet has no answer to give, and a
+ * caller that treated that as a failure would break the hook it sits in.
+ * `stale` on a row says the verifier has changed since the map was built, so
+ * the answer is the last measured one rather than a current one.
+ */
+ | Readonly<{
+    step: "affected";
+    mapped: boolean;
+    generatedAt?: string;
+    truncated?: true;
+    paths: readonly Readonly<{
+        path: string;
+        promises: readonly Readonly<{
+            promiseId: string;
+            stale: boolean;
+            title?: string;
+            claim?: string;
+        }>[];
+    }>[];
+    changed: boolean;
+}>
+/**
+ * What `setup --refresh` rewrote, and what it left alone.
+ *
+ * `current` is the honest answer for a repository whose files already say the
+ * right thing, and it is not the same as `updated`: an agent that reported a
+ * repair on a run that changed nothing would be telling a person their stale
+ * install was fixed.
+ */
+ | Readonly<{
+    step: "refresh";
+    status: "updated" | "current" | "blocked";
+    repositoryId?: string;
+    files: readonly string[];
+    conventionsVersion?: number;
+    previousConventionsVersion?: number;
+    reason?: string;
+    message?: string;
+}> | Readonly<{
+    step: "whoami";
+    session: PairSessionSummary;
+}>;

package/dist/wire.js

@@ -0,0 +1,20 @@
+/**
+ * The request and response shapes this command sends and receives, inlined.
+ *
+ * They are written out here rather than imported so the published package has no
+ * 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 CLIENT_HEADER = "x-balladeer-client";
+export const CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;
+export const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
+export const DELEGATED_SCOPES = [
+    "repository:enroll",
+    "agent:issue",
+    "ci:connect",
+    "workspace:invite",
+    "candidate:propose",
+];
+/** The verifier digest the server accepts, and the form the store writes. */
+export const VERIFIER_DIGEST_PREFIX = "sha256:";

package/package.json

@@ -1,21 +1,30 @@
 {
   "name": "balladeer",
-  "version": "0.0.4",
-  "description": "Installer for the Balladeer client (decision memory for engineering teams and their AI agents): downloads the sha256-verified client from get.balladeer.ai and installs it globally.",
-  "license": "SEE LICENSE IN LICENSE",
-  "homepage": "https://balladeer.ai",
-  "engines": {
-    "node": ">=20"
+  "version": "1.0.0",
+  "description": "Set up Balladeer from your terminal, or from a coding agent's.",
+  "license": "Apache-2.0",
+  "private": false,
+  "//": "repository and homepage are deliberately absent: the source repository is private, and a registry page linking somewhere a reader cannot open is worse than one that links nowhere. Add both when the repository is public, and delete this note when you do.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
   },
   "bin": {
-    "balladeer": "bin/balladeer.js"
+    "balladeer": "dist/cli.js"
   },
   "files": [
-    "bin",
+    "dist",
     "LICENSE",
     "README.md"
   ],
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
   }
 }