balladeer 1.0.14 → 1.0.16

package/dist/commands/offers.d.ts

@@ -0,0 +1,265 @@
+import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient } from "../headless-agent.js";
+import type { HookHost } from "../judge-hook.js";
+import { OFFER_BRIEF_REVISION, OFFER_QUESTION, type BoundedDiff, type ExistingPromise } from "../offer-brief.js";
+import { type PromiseDocument, type PromiseReader } from "../promise-meaning.js";
+/**
+ * `balladeer offers`: the rules a change establishes that no promise records,
+ * for the person pushing it to be offered in that same session.
+ *
+ * It reads and reports. It stores nothing, records nothing and proposes
+ * nothing: a rule becomes a proposal only when the person says yes to the
+ * question each offer carries, in the session this hands its findings to, and
+ * that session records it. No offer outlives the session it was made in.
+ */
+export declare const OFFERS_SCHEMA_VERSION = "balladeer-offers/v1";
+/** The most existing promises read through the connection for one reading. */
+export declare const MAX_EXISTING_PROMISES = 200;
+/** How long `balladeer offers` gives the reader by hand, unless told otherwise. */
+export declare const DEFAULT_OFFER_TIMEOUT_SECONDS = 240;
+/**
+ * What the pushing session is told to do with the offers, stated once after
+ * them. It asks for the offers to be shown word for word because the first
+ * Codex canary's agent, told only to "offer these", answered that no hook
+ * message had appeared: in four sessions it surfaced them once, and with this
+ * wording three times in three.
+ */
+export declare const OFFER_INSTRUCTIONS: string;
+export type OfferEvidence = Readonly<{
+    file: string;
+    shows: string;
+}>;
+/** A rule found in the change, in the shape both `offers` and `held` carry. */
+export type FoundRule = Readonly<{
+    rule: string;
+    beneficiary: string;
+    trigger: string;
+    passingExample: string;
+    failingExample: string;
+    evidence: readonly OfferEvidence[];
+    statedBy: "commit" | "test" | "code";
+    confidence: "high" | "medium";
+}>;
+/** A rule handed to the pushing session, with the exact question it asks. */
+export type Offer = FoundRule & Readonly<{
+    question: typeof OFFER_QUESTION;
+}>;
+export type CoveredRule = Readonly<{
+    promiseId: string;
+    rule: string;
+}>;
+export type ExistingSource = "connection" | "directory" | "checkout" | "none";
+export type OffersResult = Readonly<{
+    schemaVersion: typeof OFFERS_SCHEMA_VERSION;
+    brief: typeof OFFER_BRIEF_REVISION;
+    base: string;
+    head: string;
+    offers: readonly Offer[];
+    held: readonly FoundRule[];
+    covered: readonly CoveredRule[];
+    existing: Readonly<{
+        known: boolean;
+        count: number;
+        source: ExistingSource;
+    }>;
+    notes: string;
+    agent: Readonly<{
+        client: HeadlessClient;
+        model: string;
+        durationMs: number;
+        inputTokens: number;
+        outputTokens: number;
+    }>;
+}>;
+/**
+ * Keeps what is well formed and whose evidence names a file the change
+ * touches, in the reader's own order. The first three are offered, each with
+ * the question; the rest are held, in the same shape without it. Covered
+ * rules must name a promise the reader was given, and there are none when the
+ * existing promises could not be read.
+ */
+export declare function readOfferAnswer(answer: Record<string, unknown> | undefined, input: Readonly<{
+    changedFiles: readonly string[];
+    existingIds: ReadonlySet<string>;
+    existingKnown: boolean;
+}>): {
+    offers: Offer[];
+    held: FoundRule[];
+    covered: CoveredRule[];
+    notes: string;
+};
+/**
+ * The lines handed to the pushing session, through the hook and as the
+ * command's `question`: each rule, what shows it, and the exact question; then
+ * what the session may do with them, stated once. Nothing when there is no
+ * offer, so a push with nothing to offer hears nothing about it.
+ */
+export declare function offerLines(result: OffersResult): string[];
+/**
+ * What a person reads at a terminal: one line per offer, what an existing
+ * promise already covers and which, and one sentence saying nothing was
+ * recorded. The git pre-push hook prints the same, since whoever ran git
+ * reads it.
+ */
+export declare function personLines(result: OffersResult, options?: Readonly<{
+    directory?: string;
+    quietWhenEmpty?: boolean;
+}>): string[];
+export type ExistingRead = Readonly<{
+    known: boolean;
+    source: ExistingSource;
+    promises: readonly ExistingPromise[];
+    notes: readonly string[];
+}>;
+/** One promise as the reader is told it: title, outcome, who, when, and what it forbids. */
+export declare function existingFromDocument(document: PromiseDocument): ExistingPromise;
+/**
+ * Every promise in a directory of promise files, or in one file.
+ *
+ * Each `*.json` holds one promise in `get_promise`'s shape or a sealed
+ * package's, read with `readPromiseFile`, or an object with a `promises` array
+ * of them, which is how the evaluation's promise sets are laid out. A file
+ * holding neither is skipped and named.
+ */
+export declare function readPromisesDirectory(path: string): {
+    ok: true;
+    promises: PromiseDocument[];
+    skipped: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Every agreed promise through the connection: the ids with `list_promises`,
+ * page after page, then each meaning with `get_promise`, which the reader
+ * always marks unattended. Any read that fails fails the whole source, so a
+ * partial list is never presented as the repository's promises.
+ */
+export declare function readThroughConnection(reader: PromiseReader): Promise<{
+    ok: true;
+    promises: PromiseDocument[];
+    capped: boolean;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** The promises this checkout holds: sealed packages first, then behavior-map excerpts. */
+export declare function readCheckoutPromises(root: string): ExistingPromise[];
+/**
+ * The promises already recorded, from the first source that answers: a
+ * directory named by the caller; else this repository's agent connection;
+ * else what the checkout holds. A connection that is missing or fails in any
+ * read falls through to the checkout, and the notes say why.
+ */
+export declare function readExistingPromises(input: Readonly<{
+    root: string;
+    /** Promises already read from `--promises-dir`. */
+    directory?: readonly PromiseDocument[];
+    /** Undefined: find this repository's connection. Null: there is none. */
+    reader?: PromiseReader | null;
+    environment: NodeJS.ProcessEnv;
+    controlPlane: string;
+}>): Promise<ExistingRead>;
+/** `git diff --no-color <base> <head>`, bounded as the prompt carries it. */
+export declare function readChangeDiff(root: string, base: string, head: string): Promise<BoundedDiff>;
+/** The change's commit messages, oldest first, with trailers that carry an address removed. */
+export declare function readCommitMessages(root: string, base: string, head: string): Promise<string>;
+export type OfferReadInput = Readonly<{
+    root: string;
+    base: string;
+    head: string;
+    files: readonly string[];
+    existing: ExistingRead;
+    client: HeadlessClient | "auto";
+    prefer?: HeadlessClient;
+    timeoutMs: number;
+    environment: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+}>;
+export type OfferReading = Readonly<{
+    ok: true;
+    result: OffersResult;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+    message: string;
+}>;
+/** Read one change for rules no promise records. Never throws for the agent or the machine. */
+export declare function readOffers(input: OfferReadInput): Promise<OfferReading>;
+/**
+ * Whether a change repairs something, read from what its author wrote: a
+ * commit whose subject is a fix, a hotfix or a revert by the usual convention,
+ * or says in words that it fixes, restores or reverts, or names a regression.
+ *
+ * The first measurement (29 September 2026, 24 real regressions) is why this
+ * is the default gate. Read at the fix, a change offered the rule that had
+ * broken in 20 cases of 24, and as its first offer in 18. Read at the change
+ * that first built the behavior, it offered that rule in 3 of 23, while
+ * offering two rules or more on almost every feature. A repair is where a rule
+ * has just shown what losing it costs; everywhere else the reader is mostly
+ * guessing which of many rules will matter, and the person is asked too often.
+ * No model is asked: the subject line is what the author said.
+ */
+export declare function isRepairChange(messages: string): boolean;
+/** The first `max` offers stay offers; the rest join what was held, without their question. */
+export declare function limitOffers(result: OffersResult, max: number): OffersResult;
+/**
+ * The same reading, for the push hook: the change is already identified, and
+ * what comes back is the lines the pushing session or person is handed. Any
+ * failure, a missing login or a reading still running at the deadline is no
+ * lines at all: finding rules never holds or fails a push.
+ */
+export declare function offersForPush(input: Readonly<{
+    root: string;
+    base: string;
+    head: string;
+    files: readonly string[];
+    host: HookHost;
+    environment: NodeJS.ProcessEnv;
+    controlPlane: string;
+    client: HeadlessClient | "auto";
+    /** When the hook's budget ends, as a time in milliseconds. */
+    deadline: number;
+    signal: AbortSignal;
+    /** Which pushes are read. Absent reads every change, as the command by hand does. */
+    policy?: "fixes" | "all";
+    /** How many offers are handed over. Absent hands over every offer read. */
+    max?: number;
+    reader?: PromiseReader | null;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    now?: () => number;
+}>): Promise<string[]>;
+export type OffersArguments = Readonly<{
+    base?: string;
+    head?: string;
+    json: boolean;
+    repo?: string;
+    promisesDir?: string;
+    client: HeadlessClient | "auto";
+    timeoutSeconds: number;
+}>;
+export declare const OFFERS_USAGE = "  npx -y balladeer@latest offers [--base <ref>] [--head <ref>] [--json] [--repo <root>]\n                  [--promises-dir <dir>] [--client auto|claude|codex] [--timeout <seconds>]\n      Read this change for rules it establishes that no promise records yet,\n      on your own Claude Code or Codex login, and list at most three, each with\n      the files in the change that show it. It records nothing and stores\n      nothing: to keep one, ask your coding agent to record it as a promise for\n      your review. The promises already recorded come from --promises-dir,\n      else this repository's Balladeer connection, else the promises sealed or\n      mapped in this checkout. The change runs from the fork point with the\n      remote default branch to HEAD unless named. --json prints the result.\n";
+export declare function parseOffersArguments(argv: readonly string[]): OffersArguments;
+export type OffersDependencies = Readonly<{
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    /** Null means "no connection", without trying to find one. */
+    reader?: PromiseReader | null;
+}>;
+export type OffersRunOptions = Readonly<{
+    args: OffersArguments;
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    controlPlane: string;
+    write: (text: string) => void;
+    error: (text: string) => void;
+    deps?: OffersDependencies;
+}>;
+/** `balladeer offers`, from arguments already parsed. */
+export declare function runOffers(options: OffersRunOptions): Promise<number>;
+/** `balladeer offers ...` from raw arguments, as `cli.ts` hands them over. */
+export declare function offersCommand(argv: readonly string[], io: Readonly<{
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+}>): Promise<number>;