balladeer 0.0.4 → 1.0.0

package/dist/client.js

@@ -0,0 +1,114 @@
+import { noteServerVersion } from "./currency.js";
+import { commandLine } from "./release.js";
+import { CLIENT_HEADER, CLIENT_HEADER_VALUE } from "./wire.js";
+export class TransportError extends Error {
+    controlPlane;
+    constructor(controlPlane, reason) {
+        super(reason);
+        this.name = "TransportError";
+        this.controlPlane = controlPlane;
+    }
+}
+export class ClientTooOldError extends Error {
+    update;
+    controlPlane;
+    constructor(controlPlane, update) {
+        super(`This copy of balladeer is too old for ${controlPlane}. Run: ${update}`);
+        this.name = "ClientTooOldError";
+        this.controlPlane = controlPlane;
+        this.update = update;
+    }
+}
+export class RefusalError extends Error {
+    code;
+    status;
+    constructor(status, refusal) {
+        super(refusal.message ?? refusal.error);
+        this.name = "RefusalError";
+        this.code = refusal.error;
+        this.status = status;
+    }
+}
+/**
+ * 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: `https://localhost:8080/candidates/...`
+ * 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 function reviewLink(controlPlane, path) {
+    return new URL(path, ensureTrailing(controlPlane)).toString();
+}
+function ensureTrailing(controlPlane) {
+    return controlPlane.endsWith("/") ? controlPlane : `${controlPlane}/`;
+}
+/** Bounded, so a server's body can never become pages of terminal output. */
+function boundedReason(error) {
+    if (!(error instanceof Error))
+        return "unknown transport failure";
+    return error.message.trim().slice(0, 200) || error.name;
+}
+/**
+ * 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 async function request(controlPlane, options) {
+    const url = new URL(options.path, `${controlPlane}/`);
+    const headers = {
+        accept: "application/json",
+        [CLIENT_HEADER]: CLIENT_HEADER_VALUE,
+    };
+    if (options.body !== undefined)
+        headers["content-type"] = "application/json";
+    if (options.bearer)
+        headers.authorization = `Bearer ${options.bearer}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            method: options.method,
+            headers,
+            redirect: "manual",
+            signal: AbortSignal.timeout(options.timeoutMs ?? 20_000),
+            ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+        });
+    }
+    catch (error) {
+        throw new TransportError(controlPlane, boundedReason(error));
+    }
+    // Read before anything branches on the status, so a refusal teaches this copy
+    // that it is old just as a success does. A client whose call failed is the
+    // client most likely to be the one that needs updating.
+    noteServerVersion(response.headers);
+    if (response.status >= 300 && response.status < 400) {
+        throw new TransportError(controlPlane, `unexpected redirect (${response.status})`);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        payload = undefined;
+    }
+    if (response.status === 426) {
+        const refusal = (payload ?? {});
+        // The server's own remedy first, because it is the one that knows whether
+        // the package is published. A dist-tag would be the wrong fallback: it
+        // resolves to whatever the registry holds under that name today, which is
+        // not this program.
+        throw new ClientTooOldError(controlPlane, refusal.update ?? commandLine(null, "setup"));
+    }
+    if (!response.ok) {
+        const refusal = (payload ?? { error: `http_${response.status}` });
+        throw new RefusalError(response.status, refusal);
+    }
+    return payload;
+}

package/dist/commands/affected.d.ts

@@ -0,0 +1,22 @@
+export type AffectedOptions = Readonly<{
+    cwd: string;
+    json: boolean;
+    paths: readonly string[];
+    write: (text: string) => void;
+}>;
+/** The path as the map spells it: repository-relative, forward slashes. */
+export declare function normalizePath(root: string, cwd: string, given: string): string;
+/**
+ * Which promises a change touches, answered from the map and from nothing else.
+ *
+ * The point of answering here rather than asking Balladeer is that the question
+ * contains the answer's evidence: the file names of the change in front of the
+ * person. Sending them anywhere to find out which promises they touch would
+ * hand a vendor the shape of a repository it has promised never to see. So this
+ * reads one local file, and it says so.
+ *
+ * A stale row is still printed. The map's answer for a promise whose verifier
+ * has since changed is the last true thing anybody measured, and hiding it
+ * would leave a coder believing their change touches nothing.
+ */
+export declare function runAffected(options: AffectedOptions): Promise<number>;

package/dist/commands/affected.js

@@ -0,0 +1,122 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { TOUCH_MAP_FILE, affectedPaths, readLocalPackages, readTouchMap, verifierDigest, } from "../touch-map.js";
+import {} from "../wire.js";
+import { promiseRoot } from "./touch-map.js";
+/** How many promises one path lists before the report says how many more. */
+const NAMED_LIMIT = 20;
+/** The path as the map spells it: repository-relative, forward slashes. */
+export function normalizePath(root, cwd, given) {
+    const absolute = isAbsolute(given) ? given : resolve(cwd, given);
+    const inside = relative(root, absolute);
+    if (inside === "" || inside.startsWith("..") || isAbsolute(inside))
+        return given.replace(/\\/g, "/").replace(/^\.\//, "");
+    return inside.split(sep).join("/");
+}
+/**
+ * Which promises a change touches, answered from the map and from nothing else.
+ *
+ * The point of answering here rather than asking Balladeer is that the question
+ * contains the answer's evidence: the file names of the change in front of the
+ * person. Sending them anywhere to find out which promises they touch would
+ * hand a vendor the shape of a repository it has promised never to see. So this
+ * reads one local file, and it says so.
+ *
+ * A stale row is still printed. The map's answer for a promise whose verifier
+ * has since changed is the last true thing anybody measured, and hiding it
+ * would leave a coder believing their change touches nothing.
+ */
+export async function runAffected(options) {
+    const emit = (step) => {
+        if (options.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    const say = (text) => {
+        if (!options.json)
+            options.write(`${text}\n`);
+    };
+    if (options.paths.length === 0) {
+        const message = "Name at least one path: balladeer affected src/orders/total.ts";
+        if (options.json)
+            emit({ step: "error", reason: "usage", message, changed: false, exitCode: 4 });
+        else
+            options.write(`${message}\n`);
+        return 4;
+    }
+    const root = await promiseRoot(options.cwd);
+    if (root === undefined) {
+        const message = "This is not a git repository and there are no promise packages here, so there is no map to read. Run it from inside your checkout.";
+        if (options.json)
+            emit({ step: "error", reason: "not_a_repository", message, changed: false, exitCode: 4 });
+        else
+            options.write(`${message}\n`);
+        return 4;
+    }
+    const reading = readTouchMap(root);
+    if (reading.kind !== "map") {
+        const message = reading.kind === "absent"
+            ? `There is no touch map in this checkout yet. Build one with: balladeer touch-map`
+            : `${TOUCH_MAP_FILE} could not be read as a touch map. Build it again with: balladeer touch-map`;
+        emit({ step: "affected", mapped: false, paths: [], changed: false });
+        say(message);
+        // Zero, because having no map is not a fault in the change somebody is
+        // making. A command that failed here would break every hook it was put in.
+        return 0;
+    }
+    const packages = readLocalPackages(root);
+    const details = new Map(packages.map((pkg) => [pkg.promiseId, pkg]));
+    const current = new Map(packages.map((pkg) => [pkg.promiseId, verifierDigest(root, pkg)]));
+    const paths = options.paths.map((given) => normalizePath(root, options.cwd, given));
+    const answers = affectedPaths(reading.map, paths, current, details);
+    const touched = answers.filter((answer) => answer.promises.length > 0);
+    const stale = answers.reduce((count, answer) => count + answer.promises.filter((promise) => promise.stale).length, 0);
+    emit({
+        step: "affected",
+        mapped: true,
+        generatedAt: reading.map.generatedAt,
+        ...(reading.map.truncated ? { truncated: true } : {}),
+        paths: answers.map((answer) => ({
+            path: answer.path,
+            promises: answer.promises.slice(0, NAMED_LIMIT).map((promise) => ({
+                promiseId: promise.promiseId,
+                stale: promise.stale,
+                ...(promise.title === undefined ? {} : { title: promise.title }),
+                ...(promise.claim === undefined ? {} : { claim: promise.claim }),
+            })),
+        })),
+        changed: false,
+    });
+    if (touched.length === 0) {
+        say(`No promise in this map ran any of those files. The map was built ${reading.map.generatedAt}; a promise sealed since then is not in it.`);
+        return 0;
+    }
+    for (const answer of answers) {
+        if (answer.promises.length === 0)
+            continue;
+        say(answer.path);
+        for (const promise of answer.promises.slice(0, NAMED_LIMIT)) {
+            say(`  ${promise.promiseId}${promise.title ? `: ${promise.title}` : ""}`);
+            if (promise.claim !== undefined)
+                say(`    ${promise.claim}`);
+            if (promise.stale)
+                say("    Stale: this promise's verifier has changed since the map was built.");
+        }
+        if (answer.promises.length > NAMED_LIMIT)
+            say(`  and ${answer.promises.length - NAMED_LIMIT} more, not listed here.`);
+    }
+    // Named and absent is an answer, and a silent omission is not. A person who
+    // listed four files and read two of them back cannot tell whether the other
+    // two are untouched or were dropped.
+    const untouched = answers.filter((answer) => answer.promises.length === 0);
+    if (untouched.length > 0) {
+        say("");
+        say(`No promise in this map ran: ${untouched.map((answer) => answer.path).join(", ")}`);
+    }
+    say("");
+    if (stale > 0) {
+        say(stale === 1
+            ? "One answer above is stale. Run balladeer touch-map to measure it again."
+            : `${stale} of those answers are stale. Run balladeer touch-map to measure them again.`);
+    }
+    say("This came from your own checkout. Balladeer was not asked, and was told nothing.");
+    return 0;
+}

package/dist/commands/check-seals.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Where the pinned runner sits once setup's instructions have been followed.
+ *
+ * Setup tells an agent to check the enrolled attestor release out beside the
+ * repository, at exactly the commit CI pins, and to run its prebuilt entry
+ * point. This command runs that same binary rather than deciding for itself
+ * whether a seal holds: the runner's answer is the one CI will give, and a
+ * second opinion computed here would eventually disagree with it.
+ */
+export declare const PINNED_RUNNER = "../balladeer-attestor/release/continuity-runner/cli.js";
+export type CheckSealsOptions = Readonly<{
+    cwd: string;
+    json: boolean;
+    /** Write the optional pre-push hook instead of checking anything. */
+    installHook: boolean;
+    /** Where the pinned runner is, when it is not in the usual place. */
+    runner?: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+}>;
+/**
+ * The one command a coder runs before they push, and the one they never notice
+ * when nothing is wrong.
+ *
+ * A seal is broken by an ordinary edit, and the person who breaks one almost
+ * never meant to. Finding out in CI costs the promise's owner an afternoon of
+ * qualifying it again; finding out here costs a `git checkout` of one file. So
+ * this says nothing at all when the change is ordinary, and when it is not it
+ * names the promise, the person who agreed it, and the page they agreed it on,
+ * because those are what the coder needs to decide whether to back the edit out
+ * or to finish the repair.
+ *
+ * It never decides for itself whether a seal holds. It works out which promises
+ * this push touches and asks the pinned runner about each one, so its verdict
+ * and the protected check's verdict come from the same program.
+ */
+export declare function runCheckSeals(options: CheckSealsOptions): Promise<number>;

package/dist/commands/check-seals.js

@@ -0,0 +1,289 @@
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { runCommand } from "../gh.js";
+import { repositoryRoot } from "../git.js";
+import { promiseForPath, sealedPromises } from "../seals.js";
+import {} from "../wire.js";
+/**
+ * Where the pinned runner sits once setup's instructions have been followed.
+ *
+ * Setup tells an agent to check the enrolled attestor release out beside the
+ * repository, at exactly the commit CI pins, and to run its prebuilt entry
+ * point. This command runs that same binary rather than deciding for itself
+ * whether a seal holds: the runner's answer is the one CI will give, and a
+ * second opinion computed here would eventually disagree with it.
+ */
+export const PINNED_RUNNER = "../balladeer-attestor/release/continuity-runner/cli.js";
+/** The exit code `run-one-target` uses for a broken seal, and only for that. */
+const SEAL_BROKEN_EXIT = 4;
+/** A verifier gets this long before the check gives up on it. */
+const RUNNER_TIMEOUT_MS = 120_000;
+/** How many broken seals are named before the report says how many more. */
+const NAMED_LIMIT = 20;
+/** How many of one promise's changed files are listed under it. */
+const CHANGED_SHOWN = 10;
+/**
+ * Every path this push would carry that the person has not pushed yet.
+ *
+ * Two questions, because a coder is in one of two states when this runs. Before
+ * the commit, the change is staged; after it, the change is committed and the
+ * remote has never seen it. Both are asked, and the union is what a push would
+ * take. Unstaged edits are deliberately not included: a file being edited right
+ * now is not a change anybody is pushing, and a check that went red on every
+ * keystroke would be turned off within the hour.
+ */
+async function pendingPaths(root) {
+    const paths = new Set();
+    const staged = await runCommand("git", ["-C", root, "diff", "--cached", "--name-only"]);
+    if (staged.ok)
+        for (const line of staged.stdout.split("\n"))
+            if (line.trim())
+                paths.add(line);
+    // `@{upstream}` names the branch this one pushes to. A branch that has never
+    // been pushed has none, and then every commit not on any remote is pending,
+    // which is what the second form answers.
+    const upstream = await runCommand("git", [
+        "-C",
+        root,
+        "rev-parse",
+        "--abbrev-ref",
+        "--symbolic-full-name",
+        "@{upstream}",
+    ]);
+    if (upstream.ok) {
+        const committed = await runCommand("git", [
+            "-C",
+            root,
+            "diff",
+            "--name-only",
+            `${upstream.stdout.trim()}...HEAD`,
+        ]);
+        if (committed.ok)
+            for (const line of committed.stdout.split("\n"))
+                if (line.trim())
+                    paths.add(line);
+        return [...paths].sort();
+    }
+    // No upstream: take every commit that sits on no remote branch at all.
+    const unpushed = await runCommand("git", [
+        "-C",
+        root,
+        "log",
+        "--format=%H",
+        "--branches",
+        "--not",
+        "--remotes",
+    ]);
+    const commits = unpushed.ok
+        ? unpushed.stdout.split("\n").filter((line) => line.trim() !== "")
+        : [];
+    const oldest = commits[commits.length - 1];
+    if (oldest !== undefined) {
+        const changed = await runCommand("git", [
+            "-C",
+            root,
+            "diff",
+            "--name-only",
+            `${oldest}^`,
+            "HEAD",
+        ]);
+        // A repository whose first commit is unpushed has no `^` to diff against,
+        // so everything it holds is what it would push.
+        const all = changed.ok
+            ? changed
+            : await runCommand("git", ["-C", root, "ls-tree", "-r", "--name-only", "HEAD"]);
+        if (all.ok)
+            for (const line of all.stdout.split("\n"))
+                if (line.trim())
+                    paths.add(line);
+    }
+    return [...paths].sort();
+}
+/**
+ * The one command a coder runs before they push, and the one they never notice
+ * when nothing is wrong.
+ *
+ * A seal is broken by an ordinary edit, and the person who breaks one almost
+ * never meant to. Finding out in CI costs the promise's owner an afternoon of
+ * qualifying it again; finding out here costs a `git checkout` of one file. So
+ * this says nothing at all when the change is ordinary, and when it is not it
+ * names the promise, the person who agreed it, and the page they agreed it on,
+ * because those are what the coder needs to decide whether to back the edit out
+ * or to finish the repair.
+ *
+ * It never decides for itself whether a seal holds. It works out which promises
+ * this push touches and asks the pinned runner about each one, so its verdict
+ * and the protected check's verdict come from the same program.
+ */
+export async function runCheckSeals(options) {
+    const emit = (step) => {
+        if (options.json)
+            options.write(`${JSON.stringify(step)}\n`);
+    };
+    const say = (text) => {
+        if (!options.json)
+            options.write(`${text}\n`);
+    };
+    const root = await repositoryRoot(options.cwd);
+    if (root === undefined) {
+        const message = "This is not a git repository, so there is no change to check. Run it from inside your checkout.";
+        if (options.json)
+            emit({ step: "error", reason: "not_a_repository", message, changed: false, exitCode: 4 });
+        else
+            options.write(`${message}\n`);
+        return 4;
+    }
+    if (options.installHook)
+        return installPrePushHook(root, options, emit, say);
+    const sealed = new Map(sealedPromises(root).map((promise) => [promise.promiseId, promise]));
+    if (sealed.size === 0)
+        return 0;
+    const paths = await pendingPaths(root);
+    const touched = new Map();
+    for (const path of paths) {
+        const promiseId = promiseForPath(path);
+        if (promiseId === undefined || !sealed.has(promiseId))
+            continue;
+        const changed = touched.get(promiseId) ?? [];
+        changed.push(path);
+        touched.set(promiseId, changed);
+    }
+    if (touched.size === 0)
+        return 0;
+    const runner = options.runner ?? PINNED_RUNNER;
+    // Resolved against the repository root, so the documented relative default
+    // and an absolute path a person passed both land where they mean.
+    const runnerPath = resolve(root, runner);
+    if (!existsSync(runnerPath)) {
+        // Loud, and still zero. Whether a seal holds is the pinned runner's answer
+        // and nobody else's, so with no runner here this has no verdict to give; it
+        // says which promises went unchecked rather than implying they are fine.
+        const names = [...touched.keys()].sort().join(", ");
+        const message = `This change touches sealed files for ${names}, and the pinned Balladeer runner is not at ` +
+            `${runner}, so nothing was checked. Check the enrolled attestor release out beside this ` +
+            `repository, or pass --runner with the path to its cli.js.`;
+        emit({ step: "error", reason: "runner_unavailable", message, changed: false, exitCode: 0 });
+        say(message);
+        return 0;
+    }
+    const head = await runCommand("git", ["-C", root, "rev-parse", "HEAD"]);
+    const sourceSha = head.ok ? head.stdout.trim() : "";
+    const broken = [];
+    for (const promiseId of [...touched.keys()].sort()) {
+        const promise = sealed.get(promiseId);
+        const answer = await runCommand(process.execPath, [runnerPath, "run-one-target", promise.packageFile], {
+            cwd: root,
+            timeoutMs: RUNNER_TIMEOUT_MS,
+            // The runner refuses to produce a result without an exact commit to
+            // attribute it to. This is a local question about the tree in front of
+            // it, so the commit it is standing on is the honest answer.
+            env: { ...options.environment, BALLADEER_SOURCE_SHA: sourceSha },
+        });
+        // Only a broken seal. A refuted behavior, a verifier that could not run, and
+        // a runner that fell over are all somebody's problem, and none of them is
+        // this command's: a check that blocked a push for any of them would be
+        // turned off, and then it would catch nothing at all.
+        if (answer.code !== SEAL_BROKEN_EXIT)
+            continue;
+        broken.push({ promise, changedPaths: (touched.get(promiseId) ?? []).slice(0, CHANGED_SHOWN) });
+    }
+    if (broken.length === 0)
+        return 0;
+    emit({
+        step: "seals",
+        broken: broken.length,
+        promises: broken.slice(0, NAMED_LIMIT).map((entry) => ({
+            promiseId: entry.promise.promiseId,
+            sealedPath: entry.promise.sealedPath,
+            ...(entry.promise.title === undefined ? {} : { title: entry.promise.title }),
+            ...(entry.promise.owner === undefined ? {} : { owner: entry.promise.owner }),
+            ...(entry.promise.promiseUrl === undefined ? {} : { promiseUrl: entry.promise.promiseUrl }),
+            changedPaths: [...entry.changedPaths],
+            resealWith: resealCommand(promiseFile(entry.promise), entry.promise, runner),
+        })),
+        changed: false,
+    });
+    say(broken.length === 1
+        ? "Pushing this would break one promise's seal."
+        : `Pushing this would break the seals of ${broken.length} promises.`);
+    for (const entry of broken.slice(0, NAMED_LIMIT)) {
+        say("");
+        say(`  ${entry.promise.promiseId}${entry.promise.title ? `: ${entry.promise.title}` : ""}`);
+        say(`    Sealed files: ${entry.promise.sealedPath}`);
+        if (entry.promise.owner !== undefined)
+            say(`    Agreed by: ${entry.promise.owner}`);
+        if (entry.promise.promiseUrl !== undefined)
+            say(`    Read it: ${entry.promise.promiseUrl}`);
+        for (const path of entry.changedPaths)
+            say(`    Changed here: ${path}`);
+    }
+    if (broken.length > NAMED_LIMIT) {
+        say("");
+        say(`  and ${broken.length - NAMED_LIMIT} more, not listed here.`);
+    }
+    say("");
+    say("If you did not mean to touch these files, put them back and push again. If you were repairing");
+    say("a verifier, the repair is not finished until the promise is sealed again with the pinned runner:");
+    say("");
+    for (const entry of broken.slice(0, NAMED_LIMIT)) {
+        say(`  ${resealCommand(promiseFile(entry.promise), entry.promise, runner)}`);
+    }
+    say("");
+    say("Then a named person qualifies the promise again before it protects anything.");
+    return 1;
+}
+/** The draft the reseal reads, which the scaffold wrote beside the package. */
+function promiseFile(promise) {
+    return `.continuity/drafts/${promise.promiseId}.json`;
+}
+/**
+ * The exact line that reseals one promise.
+ *
+ * The seal command refuses to overwrite an existing package on purpose, so the
+ * old one is removed in the same line rather than left for the coder to find
+ * out about from a refusal.
+ */
+function resealCommand(draftFile, promise, runner) {
+    return `rm ${promise.packageFile} && node ${runner} seal ${draftFile} ${promise.packageFile}`;
+}
+/**
+ * The optional hook, written only when somebody asks for it by name.
+ *
+ * Setup offers this and never installs it. A tool that writes into somebody's
+ * `.git/hooks` without being asked has taken over a file the person may already
+ * be using, and the first they would know of it is a push that stopped for a
+ * reason they cannot find.
+ */
+function installPrePushHook(root, options, emit, say) {
+    const hookPath = join(root, ".git", "hooks", "pre-push");
+    if (existsSync(hookPath)) {
+        const message = `${hookPath} already exists, so nothing was written. Add this line to it yourself if you ` +
+            "want the check: balladeer check-seals";
+        emit({ step: "error", reason: "hook_exists", message, changed: false, exitCode: 4 });
+        say(message);
+        return 4;
+    }
+    const script = [
+        "#!/bin/sh",
+        "# Installed by: balladeer check-seals --install-hook",
+        "# It stops a push that would break a promise's seal, and says nothing otherwise.",
+        "# Delete this file to remove it.",
+        "balladeer check-seals || exit 1",
+        "",
+    ].join("\n");
+    try {
+        mkdirSync(dirname(hookPath), { recursive: true });
+        writeFileSync(hookPath, script, { encoding: "utf8", flag: "wx" });
+        chmodSync(hookPath, 0o755);
+    }
+    catch (error) {
+        const message = `That hook could not be written: ${error instanceof Error ? error.message : String(error)}`;
+        emit({ step: "error", reason: "hook_unwritable", message, changed: false, exitCode: 4 });
+        say(message);
+        return 4;
+    }
+    emit({ step: "hook", path: ".git/hooks/pre-push", changed: true });
+    say("Written: .git/hooks/pre-push. Every push from this checkout now stops if it would break a promise's seal.");
+    say("Delete that file to remove it. It is yours, and Balladeer never rewrites it.");
+    return 0;
+}

package/dist/commands/discover.d.ts

@@ -0,0 +1,68 @@
+import { type TeachBackRequest } from "./propose.js";
+export type DiscoverOptions = Readonly<{
+    controlPlane: string;
+    json: boolean;
+    /** The catalog file: one object with a `promises` array. */
+    file?: string;
+    /** The repository whose connection to use, named as `owner/name`. */
+    repo?: string;
+    /** The repository whose connection to use, named by id, as `mcp` takes it. */
+    repository?: string;
+    /** The membership every promise is proposed as owned by, when it is not the paired one. */
+    owner?: string;
+    environment: NodeJS.ProcessEnv;
+    cwd: string;
+    write: (text: string) => void;
+}>;
+/**
+ * Ten promises at 64 KiB each, which is the per-promise cap `propose` already
+ * enforces. The whole file is measured before it is parsed, so a file nobody
+ * meant to hand this command is refused on its size rather than after a parser
+ * has walked it.
+ */
+export declare const MAX_PROMISES = 10;
+export type CatalogRead = Readonly<{
+    ok: true;
+    value: readonly TeachBackRequest[];
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+/**
+ * The shape check that happens on the developer's machine, for a whole catalog.
+ *
+ * It is `readTeachBackFile` run over every entry rather than a second, looser
+ * gate written beside it. That matters more here than it does for one proposal:
+ * this command exists because an agent has just walked a repository's tests,
+ * pull requests, documents and reverts, and everything it read while doing that
+ * is exactly what Balladeer promises never to receive. One entry that carries a
+ * path, a transcript, a diff, or a stray key it picked up on the way is refused
+ * here, before anything leaves the machine.
+ *
+ * So it returns the exact objects to send rather than a verdict on the file, and
+ * one bad entry refuses the whole catalog. Sending the good half of a file
+ * somebody has to fix anyway would leave a person a review page they cannot
+ * finish and a second run that duplicates what already landed.
+ */
+export declare function readCatalogFile(raw: string): CatalogRead;
+/**
+ * The one link that opens every promise this run filed.
+ *
+ * A person who has just been handed eight proposals should be handed one page,
+ * not eight. The ids travel in the query string because the batch is exactly
+ * these promises and nothing else: 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 batchReviewLink(controlPlane: string, candidateIds: readonly string[]): string;
+/**
+ * Files a whole discovered catalog over this repository's own agent connection,
+ * every promise owned by the person who ran setup, and hands back one link.
+ *
+ * The owner is named explicitly on every proposal rather than left to a server
+ * default. Who owns a promise decides who may agree to it, and a catalog of ten
+ * promises waiting on nobody is a catalog nobody can finish; naming the person
+ * who ran setup is the one honest answer this command can give without asking
+ * anyone anything.
+ */
+export declare function runDiscover(options: DiscoverOptions): Promise<number>;