balladeer 0.0.4 → 1.0.0

package/dist/store.d.ts

@@ -0,0 +1,98 @@
+import type { DelegatedScope } from "./wire.js";
+export declare class StoreError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type PendingPairing = Readonly<{
+    controlPlane: string;
+    pairingId: string;
+    userCode: string;
+    verifier: string;
+    verificationUri: string;
+    expiresAt: string;
+    startedAt: string;
+}>;
+export type StoredSession = Readonly<{
+    controlPlane: string;
+    sessionId: string;
+    token: string;
+    workspaceId: string;
+    workspaceName: string;
+    workspaceSlug: string;
+    /**
+     * The membership that approved this pairing. It is what lets `discover` name
+     * an owner on every promise it files without asking a person to look an id up.
+     * Optional because a store written by a copy of this command that predates the
+     * field has none, and an entry without one makes `discover` say so rather than
+     * guess at an owner.
+     */
+    membershipId?: string;
+    membershipDisplayName: string;
+    scopes: readonly DelegatedScope[];
+    expiresAt: string;
+}>;
+/**
+ * One repository-bound agent credential, written when setup issues it.
+ *
+ * `balladeer mcp` refuses an entry whose `mcpUrl` origin differs from its
+ * `controlPlane` origin, so a server response can never redirect this bearer to
+ * a host the person never paired with.
+ */
+export type StoredAgent = Readonly<{
+    controlPlane: string;
+    workspaceId: string;
+    /**
+     * The repository this credential reaches, by id and by the owner/name a person
+     * reads. The name is what lets `balladeer mcp` pick the credential belonging
+     * to the directory it was started in rather than whichever one happens to be
+     * stored first. It is absent only in a store written by a copy of this command
+     * that predates the field, and an entry without it simply never matches a
+     * directory, which is a refusal rather than a wrong answer.
+     */
+    repositoryId: string;
+    repository?: string;
+    connectionId: string;
+    mcpUrl: string;
+    token: string;
+}>;
+export type Credentials = {
+    version: 1;
+    pendingPairings: PendingPairing[];
+    sessions: StoredSession[];
+    agents: StoredAgent[];
+};
+export declare function configHome(environment?: NodeJS.ProcessEnv): string;
+export declare function credentialsPath(environment?: NodeJS.ProcessEnv): string;
+/**
+ * The credential must not land somewhere a commit would pick it up.
+ *
+ * An explicitly chosen location, or one under the current working directory, is
+ * refused outright the moment it sits in a work tree. The default
+ * `~/.config/balladeer` is only refused when git says the file would actually be
+ * tracked, because a great many developers keep their dotfiles in a repository
+ * and refusing all of them would brick setup for no gain.
+ */
+export declare function assertSafeStoreLocation(directory: string, environment?: NodeJS.ProcessEnv, cwd?: string): void;
+export declare function ensureStoreDirectory(environment?: NodeJS.ProcessEnv): string;
+export declare function readCredentials(environment?: NodeJS.ProcessEnv): Credentials;
+/**
+ * Atomic, and never through a path an attacker could have pre-planted: the
+ * temporary file is opened with `wx` (fail if it exists) under a random name,
+ * 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;
+/** 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. */
+export declare function putPendingPairing(credentials: Credentials, pending: PendingPairing): Credentials;
+export declare function findPendingPairing(credentials: Credentials, controlPlane: string): PendingPairing | undefined;
+export declare function dropPendingPairing(credentials: Credentials, controlPlane: string): Credentials;
+export declare function putSession(credentials: Credentials, session: StoredSession): Credentials;
+export declare function findSession(credentials: Credentials, controlPlane: string): StoredSession | undefined;
+export declare function dropSession(credentials: Credentials, controlPlane: string): Credentials;
+/**
+ * One agent credential per repository per control plane, newest wins. Keyed on
+ * both, because a workspace holds many repositories and each one's connection
+ * reaches exactly that repository.
+ */
+export declare function putAgent(credentials: Credentials, agent: StoredAgent): Credentials;

package/dist/store.js

@@ -0,0 +1,225 @@
+import { execFileSync } from "node:child_process";
+import { closeSync, fchmodSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join, parse, resolve } from "node:path";
+export class StoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "StoreError";
+        this.code = code;
+    }
+}
+const EMPTY = { version: 1, pendingPairings: [], sessions: [], agents: [] };
+export function configHome(environment = process.env) {
+    const explicit = environment.BALLADEER_CONFIG_HOME?.trim();
+    if (explicit)
+        return resolve(explicit);
+    const xdg = environment.XDG_CONFIG_HOME?.trim();
+    if (xdg)
+        return resolve(join(xdg, "balladeer"));
+    return resolve(join(homedir(), ".config", "balladeer"));
+}
+export function credentialsPath(environment = process.env) {
+    return join(configHome(environment), "credentials.json");
+}
+function isTrackedByGit(directory, file) {
+    try {
+        execFileSync("git", ["-C", directory, "check-ignore", "--quiet", file], {
+            stdio: "ignore",
+        });
+        // Exit 0 means the path is ignored, so writing there would not be committed.
+        return false;
+    }
+    catch (error) {
+        const status = error.status;
+        // Exit 1 means "not ignored", which for a path inside a work tree means a
+        // commit would pick the credential up. Anything else (128, git absent) means
+        // we could not tell, and refusing on a guess would brick setup.
+        return status === 1;
+    }
+}
+function nearestGitDirectory(from) {
+    let current = resolve(from);
+    const { root } = parse(current);
+    for (;;) {
+        try {
+            lstatSync(join(current, ".git"));
+            return current;
+        }
+        catch {
+            // Keep walking.
+        }
+        if (current === root)
+            return undefined;
+        current = dirname(current);
+    }
+}
+/**
+ * The credential must not land somewhere a commit would pick it up.
+ *
+ * An explicitly chosen location, or one under the current working directory, is
+ * refused outright the moment it sits in a work tree. The default
+ * `~/.config/balladeer` is only refused when git says the file would actually be
+ * tracked, because a great many developers keep their dotfiles in a repository
+ * and refusing all of them would brick setup for no gain.
+ */
+export function assertSafeStoreLocation(directory, environment = process.env, cwd = process.cwd()) {
+    const worktree = nearestGitDirectory(directory);
+    if (!worktree)
+        return;
+    const explicit = Boolean(environment.BALLADEER_CONFIG_HOME?.trim());
+    const underCwd = resolve(directory).startsWith(`${resolve(cwd)}/`) || resolve(directory) === resolve(cwd);
+    if (explicit || underCwd || isTrackedByGit(worktree, join(directory, "credentials.json"))) {
+        throw new StoreError("credential_store_inside_git_worktree", `Balladeer will not write a credential inside a git work tree (${worktree}). Set BALLADEER_CONFIG_HOME to a directory outside every repository.`);
+    }
+}
+function assertPrivate(path, kind) {
+    const stats = lstatSync(path);
+    if (stats.isSymbolicLink()) {
+        throw new StoreError("credential_store_unsafe", `${path} is a symbolic link. Balladeer will not follow one to write a credential.`);
+    }
+    // Checked on every read and write, not only at creation: a store made private
+    // once but widened later is exactly as readable as one never protected.
+    if ((stats.mode & 0o077) !== 0) {
+        throw new StoreError("credential_store_unsafe", `${path} is readable by other users. Run: chmod ${kind === "directory" ? "700" : "600"} ${path}`);
+    }
+}
+export function ensureStoreDirectory(environment = process.env) {
+    const directory = configHome(environment);
+    assertSafeStoreLocation(directory, environment);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    assertPrivate(directory, "directory");
+    return directory;
+}
+export function readCredentials(environment = process.env) {
+    const path = credentialsPath(environment);
+    let raw;
+    try {
+        assertPrivate(path, "file");
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof StoreError)
+            throw error;
+        return { ...EMPTY, pendingPairings: [], sessions: [], agents: [] };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            version: 1,
+            pendingPairings: Array.isArray(parsed.pendingPairings) ? parsed.pendingPairings : [],
+            sessions: Array.isArray(parsed.sessions) ? parsed.sessions : [],
+            agents: Array.isArray(parsed.agents) ? parsed.agents : [],
+        };
+    }
+    catch {
+        throw new StoreError("credential_store_unreadable", `${path} is not valid JSON. Balladeer will not overwrite a file it cannot read.`);
+    }
+}
+/**
+ * Atomic, and never through a path an attacker could have pre-planted: the
+ * temporary file is opened with `wx` (fail if it exists) under a random name,
+ * its mode is set on the open descriptor, and it is flushed before the rename.
+ */
+export function writeCredentials(credentials, environment = process.env) {
+    const directory = ensureStoreDirectory(environment);
+    const path = join(directory, "credentials.json");
+    const temporary = join(directory, `.credentials.${randomBytes(8).toString("hex")}.tmp`);
+    let descriptor;
+    try {
+        descriptor = openSync(temporary, "wx", 0o600);
+        fchmodSync(descriptor, 0o600);
+        writeSync(descriptor, `${JSON.stringify(credentials, null, 2)}\n`);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        if (descriptor !== undefined) {
+            try {
+                closeSync(descriptor);
+            }
+            catch {
+                // Nothing further to do; the unlink below is the cleanup that matters.
+            }
+        }
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // The temporary file may never have been created.
+        }
+        if (error instanceof StoreError)
+            throw error;
+        throw new StoreError("credential_store_unwritable", `Balladeer could not write ${path}: ${error instanceof Error ? error.message : "unknown reason"}`);
+    }
+}
+/** Origins, not URL strings, so `https://host/../` cannot alias a stored entry. */
+export function normalizeControlPlane(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new StoreError("invalid_control_plane", `${value} is not a URL.`);
+    }
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
+        throw new StoreError("invalid_control_plane", `${value} is not https. Balladeer will not send a pairing secret over http.`);
+    }
+    return url.origin;
+}
+/** At most one pending pairing per control plane, newest wins. */
+export function putPendingPairing(credentials, pending) {
+    return {
+        ...credentials,
+        pendingPairings: [
+            ...credentials.pendingPairings.filter((entry) => entry.controlPlane !== pending.controlPlane),
+            pending,
+        ],
+    };
+}
+export function findPendingPairing(credentials, controlPlane) {
+    return credentials.pendingPairings.find((entry) => entry.controlPlane === controlPlane);
+}
+export function dropPendingPairing(credentials, controlPlane) {
+    return {
+        ...credentials,
+        pendingPairings: credentials.pendingPairings.filter((entry) => entry.controlPlane !== controlPlane),
+    };
+}
+export function putSession(credentials, session) {
+    return {
+        ...credentials,
+        sessions: [
+            ...credentials.sessions.filter((entry) => entry.controlPlane !== session.controlPlane),
+            session,
+        ],
+    };
+}
+export function findSession(credentials, controlPlane) {
+    return credentials.sessions.find((entry) => entry.controlPlane === controlPlane);
+}
+export function dropSession(credentials, controlPlane) {
+    return {
+        ...credentials,
+        sessions: credentials.sessions.filter((entry) => entry.controlPlane !== controlPlane),
+    };
+}
+/**
+ * One agent credential per repository per control plane, newest wins. Keyed on
+ * both, because a workspace holds many repositories and each one's connection
+ * reaches exactly that repository.
+ */
+export function putAgent(credentials, agent) {
+    return {
+        ...credentials,
+        agents: [
+            ...credentials.agents.filter((entry) => entry.controlPlane !== agent.controlPlane || entry.repositoryId !== agent.repositoryId),
+            agent,
+        ],
+    };
+}

package/dist/touch-map.d.ts

@@ -0,0 +1,241 @@
+/**
+ * The touch map: which files each promise's verifier actually executed.
+ *
+ * A promise's scope surfaces are what somebody wrote down when they agreed it.
+ * They are a guess about which files matter, they age, and nobody rewrites them
+ * when a module moves. What a verifier executed is not a guess: it is the file
+ * list V8 recorded while the check ran. So an agent asking "which promises does
+ * this change touch" gets an answer measured from the repository in front of it
+ * rather than one somebody typed months ago.
+ *
+ * Two rules hold the whole feature up, and both are structural rather than
+ * remembered. The map is written under `.continuity/` and nothing in this
+ * command sends it anywhere: it names a customer's file tree, which is the one
+ * thing Balladeer promises never to receive. And every entry carries the digest
+ * of the verifier that produced it, so a map computed against a verifier that
+ * has since changed reads as stale rather than as fact.
+ */
+/** The directory a repository keeps its promises, packages and map in. */
+export declare const CONTINUITY_DIRECTORY = ".continuity";
+/** Where a promise's sealed files live. Everything under it is the verifier itself. */
+export declare const PROMISE_TREE_ROOT = ".continuity/promises";
+/** Where the sealed packages live, one JSON file per promise. */
+export declare const PACKAGE_DIRECTORY = ".continuity/packages";
+/** Where the scaffold leaves the readable draft each package was sealed from. */
+export declare const DRAFT_DIRECTORY = ".continuity/drafts";
+/** The map itself, beside the packages it was computed from. */
+export declare const TOUCH_MAP_FILE = ".continuity/touch-map.json";
+/** The document's own version, so a reader can refuse one it does not understand. */
+export declare const TOUCH_MAP_SCHEMA = "balladeer-touch-map/v1";
+/**
+ * What one map may hold.
+ *
+ * A repository with a thousand promises and a hundred thousand files would
+ * otherwise write a document nothing can open. The caps are stated in the
+ * document when they bite, because a map that quietly stopped early would be
+ * read as "nothing else is touched", which is the one thing it must never say
+ * by accident.
+ */
+export declare const TOUCH_MAP_LIMITS: {
+    /** Files one map names. */
+    readonly files: 5000;
+    /** Promises listed under one file. */
+    readonly promisesPerFile: 50;
+    /** Characters of one repository-relative path. */
+    readonly path: 400;
+    /** Characters of one promise's claim, as `affected` prints it. */
+    readonly claim: 200;
+};
+/** How a verifier is invoked, as the sealed package declares it. */
+export type VerifierTarget = Readonly<{
+    executable: string;
+    args: readonly string[];
+    cwd?: string;
+    timeoutMs?: number;
+}>;
+/** One promise, as this checkout's sealed package file carries it. */
+export type LocalPackage = Readonly<{
+    promiseId: string;
+    /** The sealed package file, repository-relative. */
+    packageFile: string;
+    target: VerifierTarget;
+    /** Every file the package digest-locks, repository-relative. */
+    materialPaths: readonly string[];
+    title?: string;
+    claim?: string;
+}>;
+/** Why a promise's verifier produced no coverage, in a word a caller can branch on. */
+export type UnmappedReason = "no_verifier_target" | "unsupported_executable" | "cwd_outside_repository" | "did_not_run" | "timed_out" | "no_coverage";
+/** One promise this run could not map, and why. */
+export type UnmappedPromise = Readonly<{
+    promiseId: string;
+    reason: UnmappedReason;
+    /** One sentence a person can act on. Never a page of the verifier's output. */
+    detail: string;
+}>;
+/** One promise's claim on one file: it executed it, under this verifier. */
+export type TouchEntry = Readonly<{
+    promiseId: string;
+    verifierDigest: string;
+}>;
+export type TouchMapFile = Readonly<{
+    path: string;
+    promises: readonly TouchEntry[];
+}>;
+export type TouchMapPromise = Readonly<{
+    promiseId: string;
+    verifierDigest: string;
+    /** How many files this promise's verifier executed, before any cap. */
+    files: number;
+}>;
+export type TouchMap = Readonly<{
+    schemaVersion: typeof TOUCH_MAP_SCHEMA;
+    generatedAt: string;
+    /** True when a cap cut something, so nothing reads a short map as a complete one. */
+    truncated: boolean;
+    promises: readonly TouchMapPromise[];
+    files: readonly TouchMapFile[];
+    unmapped: readonly UnmappedPromise[];
+}>;
+/**
+ * The first sentence of a stored outcome, never crossing a paragraph break.
+ *
+ * The same rule the promise index uses, written out rather than imported: this
+ * package is published with no dependency of its own, and `affected` prints a
+ * claim from a file on the customer's disk with no server in the conversation.
+ */
+export declare function firstSentence(value: string): string;
+/**
+ * Every promise this checkout has a sealed package for, in id order.
+ *
+ * It reads the package files and nothing else, so it works with no network, no
+ * credential, and no runner checkout. A file that is not a readable sealed
+ * package is skipped rather than reported: a half-written draft in that
+ * directory is not a promise, and refusing to map the other promises because of
+ * it would be worse than leaving it out.
+ *
+ * The claim is read from the draft the scaffold leaves beside the package when
+ * there is one, because that is the readable copy a person edits, and from the
+ * package itself when there is not.
+ */
+export declare function readLocalPackages(root: string): LocalPackage[];
+/** JSON with its object keys in sorted order, so the same input digests the same. */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * The digest a map entry was computed under.
+ *
+ * It covers exactly what decides which files a verifier executes: how the
+ * verifier is invoked, and the bytes of every file the package locks. It is
+ * taken from the files on disk rather than from the digests the package
+ * declares, so both ways a verifier can change move it: a reseal, and an edit
+ * nobody has sealed yet.
+ *
+ * It is deliberately not the package digest. That moves when somebody fixes a
+ * typo in the promise's title, and a map that read stale after a wording change
+ * would be rebuilt so often that nobody would trust the word.
+ */
+export declare function verifierDigest(root: string, pkg: LocalPackage): string;
+/** A path in the map's own spelling: repository-relative, forward slashes. */
+export declare function repositoryPath(root: string, absolute: string): string | undefined;
+/**
+ * Whether a file this verifier executed belongs in the map.
+ *
+ * The promise tree is out, because those files are the verifier: a map that
+ * said "this promise touches its own verifier" would answer every question with
+ * itself. Installed dependencies are out too. They are executed by everything,
+ * they are nobody's change, and a map that carried them would be mostly
+ * `node_modules` and would blow the size cap before it reached the first file
+ * anybody edits.
+ */
+export declare function mappablePath(path: string): boolean;
+/**
+ * The repository files one coverage document says were executed, before any
+ * exclusion.
+ *
+ * V8 records every script the process loaded, including Node's own internals
+ * and anything outside this repository. A script counts as executed when any of
+ * its ranges ran at least once, which is true of a module the verifier merely
+ * imported: importing it runs its top level, and a verifier that imports a file
+ * has read the behavior in it.
+ *
+ * The promise's own tree is still in this answer, because it is what proves the
+ * verifier ran at all. `mappablePath` is what takes it back out before anything
+ * is written down.
+ */
+export declare function executedPaths(root: string, document: unknown): string[];
+/** Every coverage document V8 left in one directory, unparsed ones skipped. */
+export declare function readCoverageDirectory(directory: string): unknown[];
+/** One promise's measured result: the files it executed, under one digest. */
+export type PromiseCoverage = Readonly<{
+    promiseId: string;
+    verifierDigest: string;
+    paths: readonly string[];
+}>;
+/**
+ * The map document, assembled from what each verifier executed.
+ *
+ * Ordering is total and by name at every level, so two runs over an unchanged
+ * repository produce the same bytes and a diff shows a behavior change rather
+ * than a shuffle.
+ */
+export declare function buildTouchMap(input: {
+    generatedAt: string;
+    covered: readonly PromiseCoverage[];
+    unmapped: readonly UnmappedPromise[];
+}): TouchMap;
+/** The document as it is written: two-space JSON with a trailing newline. */
+export declare function serializeTouchMap(map: TouchMap): string;
+/** The same document with the timestamp removed, which is what "unchanged" means. */
+export declare function touchMapBody(map: TouchMap): string;
+export type TouchMapReading = Readonly<{
+    kind: "absent";
+}> | Readonly<{
+    kind: "unreadable";
+}> | Readonly<{
+    kind: "map";
+    map: TouchMap;
+}>;
+/** The map this checkout holds, or why there is nothing to read. */
+export declare function readTouchMap(root: string): TouchMapReading;
+/** One promise a path is mapped to, and whether the map still describes it. */
+export type AffectedPromise = Readonly<{
+    promiseId: string;
+    /** True when the verifier has changed since the map was built. */
+    stale: boolean;
+    title?: string;
+    claim?: string;
+}>;
+export type AffectedPath = Readonly<{
+    path: string;
+    promises: readonly AffectedPromise[];
+}>;
+/**
+ * Which promises a set of paths touches, and which of those answers have aged.
+ *
+ * Staleness is per entry rather than per map. A repository where one verifier
+ * was repaired this morning still has a true answer for every other promise in
+ * it, and marking the whole map stale would throw those away.
+ */
+export declare function affectedPaths(map: TouchMap, paths: readonly string[], currentDigests: ReadonlyMap<string, string>, details: ReadonlyMap<string, LocalPackage>): AffectedPath[];
+/**
+ * The environment a verifier is measured in.
+ *
+ * The same closed allow-list the pinned runner gives a verifier, plus the two
+ * variables this measurement needs: where V8 writes coverage, and where a
+ * native-protocol verifier writes its verdict. It is an allow-list rather than
+ * a subtraction so a control-plane token, a cloud credential, or anything else
+ * this terminal happens to hold cannot reach a customer's verifier because
+ * somebody forgot to name it.
+ */
+export declare function touchMapEnvironment(environment: Record<string, string | undefined>, coverageDirectory: string, resultPath?: string): Record<string, string>;
+/**
+ * Whether this release can measure a verifier invoked that way.
+ *
+ * Node only, for now. Coverage is collected by the runtime executing the
+ * verifier, so every language needs its own collector, and a command that
+ * guessed would map a Python verifier to nothing and call it an empty answer.
+ * The others are named as unmapped instead, which is a thing a person can read.
+ */
+export declare function measurableWithNode(target: VerifierTarget): boolean;
+/** The working directory a verifier runs in, or nothing when it leaves the repository. */
+export declare function verifierCwd(root: string, target: VerifierTarget): string | undefined;