balladeer 0.0.5 → 1.0.1

package/dist/repository.js

@@ -0,0 +1,32 @@
+import { execFileSync } from "node:child_process";
+import { hostname } from "node:os";
+const REPOSITORY_HINT_PATTERN = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+const HOST_HINT_PATTERN = /^[A-Za-z0-9.-]{1,63}$/;
+/**
+ * The two display hints, and nothing else. They exist so a person can recognise
+ * their own pairing on the approval page, and the server refuses anything that
+ * is not the shape of an owner/name or a hostname, so a hint can never be
+ * written to read like Balladeer's own assertion.
+ */
+export function repositoryHint(cwd = process.cwd()) {
+    let remote;
+    try {
+        remote = execFileSync("git", ["-C", cwd, "remote", "get-url", "origin"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "unknown/unknown";
+    }
+    const match = /github\.com[:/]+([A-Za-z0-9._-]{1,39})\/([A-Za-z0-9._-]{1,100}?)(?:\.git)?$/.exec(remote);
+    if (!match)
+        return "unknown/unknown";
+    const hint = `${match[1]}/${match[2]}`;
+    return REPOSITORY_HINT_PATTERN.test(hint) ? hint : "unknown/unknown";
+}
+export function hostHint() {
+    const raw = hostname().split(".")[0] ?? "";
+    const cleaned = raw.replace(/[^A-Za-z0-9.-]/g, "").slice(0, 63);
+    return HOST_HINT_PATTERN.test(cleaned) ? cleaned : "unknown";
+}

package/dist/seals.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where a promise's sealed files live, and where the package that seals them
+ * lives. Both are fixed by the runner: `materials[].path` is refused unless it
+ * starts with `.continuity/promises/<promise-id>/`, and the sealed package is
+ * written to `.continuity/packages/<promise-id>.json`.
+ */
+export declare const PROMISE_TREE_ROOT = ".continuity/promises";
+export declare const PACKAGE_DIRECTORY = ".continuity/packages";
+/** How many sealed directories one report names before it says how many more. */
+export declare const SEALED_PATHS_SHOWN = 10;
+/**
+ * One promise's seal, as this checkout carries it.
+ *
+ * Everything here is read out of the customer's own sealed package file. None
+ * of it is a judgement about whether the seal still holds: that verdict comes
+ * from the pinned runner, which is the only thing entitled to give it.
+ */
+export type SealedPromise = Readonly<{
+    promiseId: string;
+    /** The directory whose every file the package digest-locks, with a trailing slash. */
+    sealedPath: string;
+    /** The sealed package file, repository-relative. */
+    packageFile: string;
+    title?: string;
+    owner?: string;
+    promiseUrl?: 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 seal, and refusing to say anything about the other
+ * promises because of it would be worse than leaving it out.
+ */
+export declare function sealedPromises(repositoryRoot: string): SealedPromise[];
+/**
+ * Which promise a changed path belongs to, or nothing when the path is
+ * ordinary source.
+ *
+ * Two paths belong to a promise: a file inside its sealed directory, whose
+ * bytes the package locks, and the sealed package itself, which is what a
+ * reseal rewrites. A change to either one is the change worth checking; every
+ * other path in a repository is somebody's ordinary work and this says so by
+ * answering nothing.
+ */
+export declare function promiseForPath(path: string): string | undefined;

package/dist/seals.js

@@ -0,0 +1,112 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Where a promise's sealed files live, and where the package that seals them
+ * lives. Both are fixed by the runner: `materials[].path` is refused unless it
+ * starts with `.continuity/promises/<promise-id>/`, and the sealed package is
+ * written to `.continuity/packages/<promise-id>.json`.
+ */
+export const PROMISE_TREE_ROOT = ".continuity/promises";
+export const PACKAGE_DIRECTORY = ".continuity/packages";
+/** How many sealed directories one report names before it says how many more. */
+export const SEALED_PATHS_SHOWN = 10;
+/** A promise id as the runner spells it. Anything else is not one of ours. */
+const PROMISE_ID = /^prom_[a-z0-9]{8,64}$/;
+function readableString(value, limit) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return undefined;
+    // Bounded, and stripped of anything that could reflow a terminal: this text
+    // came out of a file in the customer's repository and is about to be printed.
+    return trimmed.replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, limit);
+}
+/**
+ * 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 seal, and refusing to say anything about the other
+ * promises because of it would be worse than leaving it out.
+ */
+export function sealedPromises(repositoryRoot) {
+    let entries;
+    try {
+        entries = readdirSync(join(repositoryRoot, PACKAGE_DIRECTORY));
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith(".json"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(join(repositoryRoot, PACKAGE_DIRECTORY, entry), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const promise = parsed.promise;
+        const attribution = parsed.attribution;
+        const promiseId = typeof promise?.id === "string" ? promise.id : undefined;
+        if (promiseId === undefined || !PROMISE_ID.test(promiseId))
+            continue;
+        if (!Array.isArray(parsed.materials) || parsed.materials.length === 0)
+            continue;
+        found.push({
+            promiseId,
+            sealedPath: `${PROMISE_TREE_ROOT}/${promiseId}/`,
+            packageFile: `${PACKAGE_DIRECTORY}/${entry}`,
+            ...(readableString(promise?.title, 160) === undefined
+                ? {}
+                : { title: readableString(promise?.title, 160) }),
+            ...(readableString(attribution?.owner, 160) === undefined
+                ? {}
+                : { owner: readableString(attribution?.owner, 160) }),
+            ...(readableString(attribution?.promiseUrl, 300) === undefined
+                ? {}
+                : { promiseUrl: readableString(attribution?.promiseUrl, 300) }),
+        });
+    }
+    return found.sort((left, right) => left.promiseId.localeCompare(right.promiseId));
+}
+/**
+ * Which promise a changed path belongs to, or nothing when the path is
+ * ordinary source.
+ *
+ * Two paths belong to a promise: a file inside its sealed directory, whose
+ * bytes the package locks, and the sealed package itself, which is what a
+ * reseal rewrites. A change to either one is the change worth checking; every
+ * other path in a repository is somebody's ordinary work and this says so by
+ * answering nothing.
+ */
+export function promiseForPath(path) {
+    const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
+    const treePrefix = `${PROMISE_TREE_ROOT}/`;
+    const packagePrefix = `${PACKAGE_DIRECTORY}/`;
+    if (normalized.startsWith(treePrefix)) {
+        const rest = normalized.slice(treePrefix.length);
+        const slash = rest.indexOf("/");
+        // A file directly under the tree root belongs to no promise: the id is a
+        // directory, and something dropped beside those directories is not sealed.
+        if (slash > 0 && rest.length > slash + 1) {
+            const id = rest.slice(0, slash);
+            if (PROMISE_ID.test(id))
+                return id;
+        }
+        return undefined;
+    }
+    if (normalized.startsWith(packagePrefix)) {
+        const rest = normalized.slice(packagePrefix.length);
+        if (rest.endsWith(".json") && !rest.slice(0, -5).includes("/")) {
+            const id = rest.slice(0, -5);
+            if (PROMISE_ID.test(id))
+                return id;
+        }
+    }
+    return undefined;
+}

package/dist/session.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The id that ties what an agent was told to what it then wrote.
+ *
+ * A retrieval read happens before the commit exists, so nothing joins the two
+ * on its own. The agent's own working session is what spans them: it reads the
+ * index under this id, and writes the same id into the commit trailer. That is
+ * the whole mechanism, and it lives here rather than on the server because the
+ * server never sees a commit message.
+ *
+ * The id is opaque and says nothing about the work. It is not a secret either:
+ * it is written into commit messages, which is exactly where people will read
+ * it. What it must be is stable across one piece of work and different across
+ * two, which is what the marker file below is for.
+ */
+/**
+ * The shape of a session id, and the line that carries it into a commit.
+ *
+ * Written out here rather than imported. This command is published to npm on
+ * its own and depends on nothing, so the grammar it uses has to live inside it;
+ * a packaging test compares these three against the control plane's own
+ * definitions, so a drift fails here rather than as a token the server refuses
+ * out of a customer's commit message.
+ */
+export declare const AGENT_SESSION_ID_PATTERN: RegExp;
+/** The trailer key an agent writes into the commit or the pull-request body. */
+export declare const AGENT_SESSION_TRAILER = "Balladeer-Session";
+/** The exact line to paste, so every carrier spells the trailer one way. */
+export declare function agentSessionTrailerLine(sessionId: string): string;
+/**
+ * The session id a commit message or pull-request body carries, if it carries
+ * one this release would recognise.
+ *
+ * A body carrying two different session ids is refused rather than resolved:
+ * two answers to "which session wrote this" is not one answer, and guessing
+ * which of them to record would put an invented join in front of a number.
+ */
+export declare function readAgentSessionTrailer(text: string): string | undefined;
+/** Where the current session for a repository is remembered. */
+export declare const SESSION_FILE = "sessions.json";
+/**
+ * How long one session id stays current.
+ *
+ * A working session is a sitting, not a calendar day. Twelve hours is long
+ * enough that a morning's work and the commit that ends it share an id, and
+ * short enough that a machine left running overnight starts the next day's work
+ * under a new one rather than attributing tomorrow's commits to yesterday's
+ * reads. `--new` is the manual answer for anyone whose sitting ends earlier.
+ */
+export declare const SESSION_LIFETIME_MS: number;
+export type SessionMark = Readonly<{
+    /** Which repository this session belongs to, as the credential names it. */
+    repository: string;
+    sessionId: string;
+    startedAt: string;
+}>;
+type SessionFile = {
+    version: 1;
+    sessions: SessionMark[];
+};
+/** A fresh id: the prefix a person can recognise, and 128 bits of nothing else. */
+export declare function mintSessionId(): string;
+export declare function isSessionId(value: string): boolean;
+export declare function readSessionMarks(environment?: NodeJS.ProcessEnv): SessionFile;
+export type CurrentSession = Readonly<{
+    sessionId: string;
+    startedAt: string;
+    /** True when this call minted it, false when it was already current. */
+    minted: boolean;
+}>;
+/**
+ * The session id for this repository right now, minting one when there is none
+ * current.
+ *
+ * Reusing a live one is the point. An agent that asks twice in one sitting must
+ * get the same answer, or its reads and its commit end up under two ids and the
+ * join it exists to make is broken by the act of asking for it.
+ */
+export declare function currentSession(input: Readonly<{
+    repository: string;
+    now: string;
+    forceNew?: boolean;
+    environment?: NodeJS.ProcessEnv;
+}>): CurrentSession;
+export {};

package/dist/session.js

@@ -0,0 +1,135 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { assertSafeStoreLocation, configHome, writeStoreFile } from "./store.js";
+/**
+ * The id that ties what an agent was told to what it then wrote.
+ *
+ * A retrieval read happens before the commit exists, so nothing joins the two
+ * on its own. The agent's own working session is what spans them: it reads the
+ * index under this id, and writes the same id into the commit trailer. That is
+ * the whole mechanism, and it lives here rather than on the server because the
+ * server never sees a commit message.
+ *
+ * The id is opaque and says nothing about the work. It is not a secret either:
+ * it is written into commit messages, which is exactly where people will read
+ * it. What it must be is stable across one piece of work and different across
+ * two, which is what the marker file below is for.
+ */
+/**
+ * The shape of a session id, and the line that carries it into a commit.
+ *
+ * Written out here rather than imported. This command is published to npm on
+ * its own and depends on nothing, so the grammar it uses has to live inside it;
+ * a packaging test compares these three against the control plane's own
+ * definitions, so a drift fails here rather than as a token the server refuses
+ * out of a customer's commit message.
+ */
+export const AGENT_SESSION_ID_PATTERN = /^bs_[0-9a-f]{32}$/;
+/** The trailer key an agent writes into the commit or the pull-request body. */
+export const AGENT_SESSION_TRAILER = "Balladeer-Session";
+/** The exact line to paste, so every carrier spells the trailer one way. */
+export function agentSessionTrailerLine(sessionId) {
+    return `${AGENT_SESSION_TRAILER}: ${sessionId}`;
+}
+/**
+ * The session id a commit message or pull-request body carries, if it carries
+ * one this release would recognise.
+ *
+ * A body carrying two different session ids is refused rather than resolved:
+ * two answers to "which session wrote this" is not one answer, and guessing
+ * which of them to record would put an invented join in front of a number.
+ */
+export function readAgentSessionTrailer(text) {
+    const pattern = new RegExp(`^[ \\t]*${AGENT_SESSION_TRAILER}[ \\t]*:[ \\t]*(\\S+)[ \\t]*$`, "gim");
+    const found = new Set();
+    for (const match of text.matchAll(pattern)) {
+        const value = match[1];
+        if (value !== undefined && isSessionId(value))
+            found.add(value);
+    }
+    if (found.size !== 1)
+        return undefined;
+    return [...found][0];
+}
+/** Where the current session for a repository is remembered. */
+export const SESSION_FILE = "sessions.json";
+/**
+ * How long one session id stays current.
+ *
+ * A working session is a sitting, not a calendar day. Twelve hours is long
+ * enough that a morning's work and the commit that ends it share an id, and
+ * short enough that a machine left running overnight starts the next day's work
+ * under a new one rather than attributing tomorrow's commits to yesterday's
+ * reads. `--new` is the manual answer for anyone whose sitting ends earlier.
+ */
+export const SESSION_LIFETIME_MS = 12 * 60 * 60 * 1000;
+const EMPTY = { version: 1, sessions: [] };
+/** A fresh id: the prefix a person can recognise, and 128 bits of nothing else. */
+export function mintSessionId() {
+    return `bs_${randomBytes(16).toString("hex")}`;
+}
+export function isSessionId(value) {
+    return AGENT_SESSION_ID_PATTERN.test(value);
+}
+function sessionPath(environment) {
+    return join(configHome(environment), SESSION_FILE);
+}
+export function readSessionMarks(environment = process.env) {
+    let raw;
+    try {
+        raw = readFileSync(sessionPath(environment), "utf8");
+    }
+    catch {
+        return { version: 1, sessions: [] };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const sessions = Array.isArray(parsed.sessions) ? parsed.sessions : [];
+        // A marker whose id this build would not recognise is dropped rather than
+        // repaired. It can only have come from a copy of this command that spelled
+        // ids differently, and reusing one would put a token the server refuses
+        // into a commit message where nobody would ever look for the cause.
+        return { version: 1, sessions: sessions.filter((mark) => isSessionId(mark.sessionId)) };
+    }
+    catch {
+        return { ...EMPTY, sessions: [] };
+    }
+}
+function writeSessionMarks(file, environment) {
+    assertSafeStoreLocation(configHome(environment), environment);
+    writeStoreFile(SESSION_FILE, `${JSON.stringify(file, null, 2)}\n`, environment);
+}
+/**
+ * The session id for this repository right now, minting one when there is none
+ * current.
+ *
+ * Reusing a live one is the point. An agent that asks twice in one sitting must
+ * get the same answer, or its reads and its commit end up under two ids and the
+ * join it exists to make is broken by the act of asking for it.
+ */
+export function currentSession(input) {
+    const environment = input.environment ?? process.env;
+    const file = readSessionMarks(environment);
+    const existing = file.sessions.find((mark) => mark.repository === input.repository);
+    const age = existing === undefined ? undefined : Date.parse(input.now) - Date.parse(existing.startedAt);
+    const usable = existing !== undefined &&
+        input.forceNew !== true &&
+        age !== undefined &&
+        Number.isFinite(age) &&
+        age >= 0 &&
+        age < SESSION_LIFETIME_MS;
+    if (usable && existing !== undefined) {
+        return { sessionId: existing.sessionId, startedAt: existing.startedAt, minted: false };
+    }
+    const minted = {
+        repository: input.repository,
+        sessionId: mintSessionId(),
+        startedAt: input.now,
+    };
+    writeSessionMarks({
+        version: 1,
+        sessions: [...file.sessions.filter((mark) => mark.repository !== input.repository), minted],
+    }, environment);
+    return { sessionId: minted.sessionId, startedAt: minted.startedAt, minted: true };
+}

package/dist/store.d.ts

@@ -0,0 +1,108 @@
+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;
+/**
+ * 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. */
+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;