balladeer 1.0.14 → 1.0.16

package/dist/commands/map.d.ts

@@ -0,0 +1,120 @@
+import { type BehaviorMap } from "../behavior-map-schema.js";
+import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
+import { type PromiseDocument, type PromiseReader } from "../promise-meaning.js";
+/** Tools a map builder or a judge may use, and the ones refused whatever else is allowed. */
+export declare const AGENT_TOOLS: readonly ["Read", "Grep", "Glob", "Bash"];
+export declare const REFUSED_TOOL_RULES: readonly ["Bash(git push:*)", "Bash(gh:*)"];
+export type MapArguments = Readonly<{
+    promiseId?: string;
+    all: boolean;
+    check: boolean;
+    stale: boolean;
+    fromFile?: string;
+    repo?: string;
+    out?: string;
+    client: HeadlessClient | "auto";
+    timeoutMs: number;
+    json: boolean;
+    repository?: string;
+    controlPlane: string;
+}>;
+export declare const MAP_USAGE = "  npx -y balladeer@latest map <promise id> | --all | --check | --stale\n                [--from-file <promise.json>] [--repo <root>] [--out <dir>]\n                [--client auto|claude|codex] [--timeout <seconds>] [--json]\n      Build a behavior map for a promise with your own coding agent: where its\n      behavior starts, the code on its path, what it depends on, the tests that\n      exercise it and where each failing case would show. The agent works in a\n      throwaway read-only checkout, on the Claude Code or Codex login already on\n      this machine, and the map is written to .continuity/behavior-maps/<id>.json\n      for your team to commit. It never leaves this machine. --all maps every\n      agreed promise; --check reports maps whose code or meaning has moved\n      (exit 1 when any has) and --stale prints just their ids, both without a\n      model. --from-file reads the promise from a file instead of Balladeer.\n";
+export declare function parseMapArguments(argv: readonly string[]): MapArguments;
+export type MapDependencies = Readonly<{
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    /** `null` means "no connection", without looking for one. */
+    reader?: PromiseReader | null;
+    now?: () => Date;
+    login?: LoginCheck;
+}>;
+export type BuildMapInput = Readonly<{
+    root: string;
+    promise: PromiseDocument;
+    client: HeadlessClient | "auto";
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    prefer?: HeadlessClient;
+    login?: LoginCheck;
+    scratch?: string;
+    now?: () => Date;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+}>;
+export type BuildMapResult = Readonly<{
+    ok: true;
+    map: BehaviorMap;
+    agent: HeadlessAgentResult;
+    dropped: string[];
+    /** Closed-list fields the agent filled with a word the contract does not have, read as the nearest allowed one. */
+    coerced: string[];
+}> | Readonly<{
+    ok: false;
+    reason: string;
+    agent?: HeadlessAgentResult;
+    errors?: string[];
+}>;
+/**
+ * One promise's behavior map, built by the person's own agent from the code at
+ * HEAD, in a disposable checkout, and checked against the contract before it is
+ * returned. Nothing is written here; the caller decides where the map goes.
+ */
+export declare function buildBehaviorMap(input: BuildMapInput): Promise<BuildMapResult>;
+export declare function agentFailure(agent: HeadlessAgentResult): string;
+/**
+ * The agent's answer made into a map: the runner's own fields filled in, paths
+ * made repository-relative, and every entry whose file does not exist at the
+ * mapped commit dropped and named, because a map pointing at nothing reads as
+ * stale forever. The meaning excerpt is taken from the promise itself rather
+ * than from the agent's copy, so a transcription slip cannot change it.
+ */
+export declare function mapFromAgent(json: Record<string, unknown>, context: Readonly<{
+    promise: PromiseDocument;
+    sha: string;
+    client: HeadlessClient;
+    model: string;
+    at: string;
+    tree: string;
+}>): {
+    map: unknown;
+    dropped: string[];
+    coerced: string[];
+};
+export type Staleness = Readonly<{
+    stale: boolean;
+    reasons: string[];
+    /** False when no current digest was available, so meaning drift is unanswered. */
+    digestChecked: boolean;
+}>;
+/**
+ * Whether a map still points at real code, answered without a model.
+ *
+ * Stale when a mapped symbol is no longer in its file (a plain search for its
+ * name, the way a person would grep for it), when a mapped file is gone, or,
+ * when the current digest is known, when the promise's meaning has moved on
+ * since the map was built.
+ */
+export declare function mapStaleness(root: string, map: BehaviorMap, currentDigest?: string): Staleness;
+export type StoredMap = Readonly<{
+    promiseId: string;
+    path: string;
+    map?: BehaviorMap;
+    errors?: string[];
+}>;
+/** Every map in a directory, read and checked; an unreadable one is listed with why. */
+export declare function readBehaviorMaps(directory: string): StoredMap[];
+export declare function readBehaviorMap(root: string, promiseId: string): BehaviorMap | undefined;
+export type MapOptions = Readonly<{
+    args: MapArguments;
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    deps?: MapDependencies;
+}>;
+/** `balladeer map`, from arguments already parsed. */
+export declare function runMap(options: MapOptions): Promise<number>;
+/** `balladeer map ...` from raw arguments, as `cli.ts` hands them over. */
+export declare function mapCommand(argv: readonly string[], io: Readonly<{
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+}>): Promise<number>;