balladeer 1.0.15 → 1.0.17

package/dist/risk/validate.js

@@ -0,0 +1,154 @@
+import { PROMISE_ID } from "../behavior-map-schema.js";
+import { BANDS, CHANGE_EXTRACTION_SCHEMA_VERSION, DELTA_KINDS, FILE_STATUSES, INTENT_SOURCES, LANGUAGES, RESOURCE_CHANGES, RESOURCE_KINDS, RISK_REPORT_SCHEMA_VERSION, SIGNALS, SYMBOL_CHANGES, SYMBOL_EXTRACTORS, SYMBOL_KINDS, } from "./contract.js";
+const string = (max = 20_000) => (value, at, errors) => {
+    if (typeof value === "string" && value.length <= max)
+        return true;
+    errors.push(`${at} must be a string of at most ${max} characters`);
+    return false;
+};
+const pattern = (regex, description) => (value, at, errors) => {
+    if (typeof value === "string" && regex.test(value))
+        return true;
+    errors.push(`${at} must be ${description}`);
+    return false;
+};
+const oneOf = (values) => (value, at, errors) => {
+    if (typeof value === "string" && values.includes(value))
+        return true;
+    errors.push(`${at} must be one of ${values.join(", ")}`);
+    return false;
+};
+const number = (min, max, integer = false) => (value, at, errors) => {
+    if (typeof value === "number" &&
+        Number.isFinite(value) &&
+        value >= min &&
+        value <= max &&
+        (!integer || Number.isInteger(value)))
+        return true;
+    errors.push(`${at} must be ${integer ? "an integer" : "a number"} from ${min} to ${max}`);
+    return false;
+};
+const nullable = (check) => (value, at, errors) => value === null || check(value, at, errors);
+const boolean = (value, at, errors) => {
+    if (typeof value === "boolean")
+        return true;
+    errors.push(`${at} must be true or false`);
+    return false;
+};
+const listOf = (item) => (value, at, errors) => {
+    if (!Array.isArray(value)) {
+        errors.push(`${at} must be a list`);
+        return false;
+    }
+    let ok = true;
+    value.forEach((entry, index) => {
+        if (!item(entry, `${at}[${index}]`, errors))
+            ok = false;
+    });
+    return ok;
+};
+const record = (fields, optional = []) => (value, at, errors) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        errors.push(`${at} must be an object`);
+        return false;
+    }
+    const input = value;
+    const unknown = Object.keys(input).filter((key) => !(key in fields));
+    if (unknown.length > 0) {
+        errors.push(`${at} has fields the contract does not define: ${unknown.join(", ")}`);
+        return false;
+    }
+    let ok = true;
+    for (const [key, check] of Object.entries(fields)) {
+        if (!(key in input) || input[key] === undefined) {
+            if (optional.includes(key))
+                continue;
+            errors.push(`${at}.${key} is missing`);
+            ok = false;
+            continue;
+        }
+        if (!check(input[key], `${at}.${key}`, errors))
+            ok = false;
+    }
+    return ok;
+};
+const SHA = pattern(/^[0-9a-f]{40}$/, "a 40-character commit sha");
+const promiseId = pattern(PROMISE_ID, "a promise id");
+const count = number(0, Number.MAX_SAFE_INTEGER, true);
+const changedFile = record({
+    path: string(1024),
+    status: oneOf(FILE_STATUSES),
+    oldPath: nullable(string(1024)),
+    language: oneOf(LANGUAGES),
+    isTest: boolean,
+    hunks: listOf(record({ oldStart: count, oldLines: count, newStart: count, newLines: count })),
+    symbolsChanged: listOf(record({ name: string(512), kind: oneOf(SYMBOL_KINDS), change: oneOf(SYMBOL_CHANGES) })),
+    identifiersAdded: listOf(string(512)),
+    identifiersRemoved: listOf(string(512)),
+    resources: listOf(record({ kind: oneOf(RESOURCE_KINDS), name: string(600), change: oneOf(RESOURCE_CHANGES) })),
+    guardDeletions: listOf(record({ line: count, text: string(2000) })),
+    constantChanges: listOf(record({ name: string(512), from: string(2000), to: string(2000) })),
+    symbolExtractor: oneOf(SYMBOL_EXTRACTORS),
+}, ["symbolExtractor"]);
+const extraction = record({
+    schemaVersion: oneOf([CHANGE_EXTRACTION_SCHEMA_VERSION]),
+    base: SHA,
+    head: SHA,
+    files: listOf(changedFile),
+    deltas: listOf(record({ text: string(4000), files: listOf(string(1024)), kind: oneOf(DELTA_KINDS) })),
+    intent: record({ summary: string(), source: oneOf(INTENT_SOURCES) }),
+}, ["deltas", "intent"]);
+const unit = number(0, 1);
+const report = record({
+    schemaVersion: oneOf([RISK_REPORT_SCHEMA_VERSION]),
+    base: SHA,
+    head: SHA,
+    promises: listOf(record({
+        promiseId,
+        title: string(),
+        score: unit,
+        band: oneOf(BANDS),
+        reasons: listOf(record({
+            signal: oneOf(SIGNALS),
+            weight: unit,
+            evidence: record({
+                file: string(),
+                symbol: string(),
+                resource: string(),
+                delta: string(),
+                caseId: string(),
+                detail: string(),
+            }, ["caseId", "detail"]),
+        })),
+        features: record({
+            symbol_hit: unit,
+            graph_forward_distance: nullable(count),
+            graph_reverse_distance: nullable(count),
+            resource_overlap: unit,
+            linked_test_changed: unit,
+            sink_reach: unit,
+            delta_similarity: unit,
+            intent_clash: unit,
+            prior_break: count,
+            churn: unit,
+        }),
+    }, ["title"])),
+    baselines: record({
+        scope_only: listOf(promiseId),
+        import_closure: listOf(promiseId),
+        all: listOf(promiseId),
+        random: listOf(promiseId),
+    }),
+});
+function parse(check, value, name) {
+    const errors = [];
+    return check(value, name, errors) ? { ok: true, value: value } : { ok: false, errors };
+}
+/** A change extraction, checked against the contract. */
+export function parseChangeExtraction(value) {
+    return parse(extraction, value, "extraction");
+}
+/** A risk report, checked against the contract. */
+export function parseRiskReport(value) {
+    return parse(report, value, "report");
+}

package/dist/scratch-worktree.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Disposable checkouts of one commit, for an agent to read and run things in.
+ *
+ * A map builder and a judge each work in a detached `git worktree` of the
+ * commit they are about, made under the system temp directory and removed
+ * afterwards. Whatever the agent writes there, a scratch test, a build output,
+ * an edit it should not have made, goes with the directory, and the person's
+ * own checkout is never the one being changed. Nothing here fetches: the
+ * commit has to be in the repository already, which it is for a change being
+ * pushed.
+ */
+export type ScratchWorktree = Readonly<{
+    path: string;
+    sha: string;
+    remove: () => Promise<void>;
+}>;
+export declare function resolveCommit(root: string, ref: string): Promise<string | undefined>;
+export declare function addScratchWorktree(root: string, ref: string, label: string, scratch?: string): Promise<{
+    ok: true;
+    worktree: ScratchWorktree;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** Synchronous, for a process that is being stopped: remove what this process made. */
+export declare function removeLiveWorktreesNow(): void;
+/**
+ * The installed dependencies a fresh worktree lacks, linked from the checkout.
+ *
+ * A new worktree holds only tracked files, so it has no `node_modules` and a
+ * test run in it fails before it reaches the behavior. Each `node_modules`
+ * beside a tracked `package.json` in the person's checkout, and a `.venv` at
+ * the top, is linked into the same place in the worktree. Linked, not copied:
+ * the link is removed with the worktree and the dependencies are never touched.
+ */
+export declare function shareDependencies(root: string, worktree: string): Promise<number>;
+export type CarriedFile = Readonly<{
+    path: string;
+    sha256: string;
+}>;
+/**
+ * Files an agent added in one worktree, so a command it wrote can run in another.
+ *
+ * A judge that proves a break usually writes a new test. Its reproduction is
+ * then run in a clean checkout of the base commit, where that test does not
+ * exist, so the new files travel with it: untracked, not ignored, regular, and
+ * small. Edits to tracked files do not travel, and the judge brief says to put
+ * a reproduction in a new file for that reason.
+ */
+export declare function newFiles(worktree: string): Promise<CarriedFile[]>;
+/**
+ * Copy files from one directory into another at the same relative paths, and
+ * return the ones copied. A path that would land outside `to` is skipped.
+ */
+export declare function carryFiles(from: string, to: string, files: readonly CarriedFile[]): CarriedFile[];

package/dist/scratch-worktree.js

@@ -0,0 +1,160 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { runCommand } from "./gh.js";
+/** Every worktree this process made and has not removed, for a signal handler to clear. */
+const live = new Map();
+export async function resolveCommit(root, ref) {
+    const answer = await runCommand("git", ["-C", root, "rev-parse", "--verify", `${ref}^{commit}`]);
+    const sha = answer.stdout.trim();
+    return answer.ok && /^[0-9a-f]{40}$/.test(sha) ? sha : undefined;
+}
+export async function addScratchWorktree(root, ref, label, scratch) {
+    const sha = await resolveCommit(root, ref);
+    if (sha === undefined)
+        return { ok: false, reason: `${ref} is not a commit in this repository` };
+    const parent = realpathSync(mkdtempSync(join(scratch ?? tmpdir(), `balladeer-${label.replace(/[^A-Za-z0-9_-]/g, "-")}-`)));
+    const path = join(parent, "tree");
+    const added = await runCommand("git", ["-C", root, "worktree", "add", "--detach", "--quiet", path, sha], { timeoutMs: 120_000 });
+    if (!added.ok) {
+        rmSync(parent, { recursive: true, force: true });
+        return {
+            ok: false,
+            reason: `a scratch checkout of ${sha.slice(0, 12)} could not be made: ${added.stderr}`,
+        };
+    }
+    live.set(path, root);
+    return {
+        ok: true,
+        worktree: {
+            path,
+            sha,
+            remove: async () => {
+                await runCommand("git", ["-C", root, "worktree", "remove", "--force", path], {
+                    timeoutMs: 60_000,
+                });
+                rmSync(parent, { recursive: true, force: true });
+                await runCommand("git", ["-C", root, "worktree", "prune"]);
+                live.delete(path);
+            },
+        },
+    };
+}
+/** Synchronous, for a process that is being stopped: remove what this process made. */
+export function removeLiveWorktreesNow() {
+    for (const [path, root] of live) {
+        try {
+            execFileSync("git", ["-C", root, "worktree", "remove", "--force", path], {
+                stdio: "ignore",
+                timeout: 20_000,
+            });
+        }
+        catch {
+            /* The directory removal below still clears the files. */
+        }
+        rmSync(dirname(path), { recursive: true, force: true });
+        live.delete(path);
+    }
+}
+/**
+ * The installed dependencies a fresh worktree lacks, linked from the checkout.
+ *
+ * A new worktree holds only tracked files, so it has no `node_modules` and a
+ * test run in it fails before it reaches the behavior. Each `node_modules`
+ * beside a tracked `package.json` in the person's checkout, and a `.venv` at
+ * the top, is linked into the same place in the worktree. Linked, not copied:
+ * the link is removed with the worktree and the dependencies are never touched.
+ */
+export async function shareDependencies(root, worktree) {
+    const listed = await runCommand("git", [
+        "-C",
+        root,
+        "ls-files",
+        "--",
+        "package.json",
+        "*/package.json",
+        "*/*/package.json",
+    ]);
+    const directories = new Set(["."]);
+    if (listed.ok)
+        for (const line of listed.stdout.split("\n"))
+            if (line.trim())
+                directories.add(dirname(line.trim()));
+    let linked = 0;
+    const link = (relativePath) => {
+        const source = join(root, relativePath);
+        const target = join(worktree, relativePath);
+        if (!existsSync(source) || existsSync(target) || !existsSync(dirname(target)))
+            return;
+        try {
+            symlinkSync(source, target, "dir");
+            linked += 1;
+        }
+        catch {
+            /* A test that needs it will say so. */
+        }
+    };
+    for (const directory of directories)
+        link(join(directory, "node_modules"));
+    link(".venv");
+    return linked;
+}
+/**
+ * Files an agent added in one worktree, so a command it wrote can run in another.
+ *
+ * A judge that proves a break usually writes a new test. Its reproduction is
+ * then run in a clean checkout of the base commit, where that test does not
+ * exist, so the new files travel with it: untracked, not ignored, regular, and
+ * small. Edits to tracked files do not travel, and the judge brief says to put
+ * a reproduction in a new file for that reason.
+ */
+export async function newFiles(worktree) {
+    const listed = await runCommand("git", [
+        "-C",
+        worktree,
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+        "-z",
+    ]);
+    if (!listed.ok)
+        return [];
+    const files = [];
+    for (const path of listed.stdout.split("\0")) {
+        if (!path || files.length >= 200)
+            continue;
+        const absolute = join(worktree, path);
+        try {
+            const stat = lstatSync(absolute);
+            if (!stat.isFile() || stat.size > 1024 * 1024)
+                continue;
+            files.push({
+                path,
+                sha256: createHash("sha256").update(readFileSync(absolute)).digest("hex"),
+            });
+        }
+        catch {
+            /* Gone between the listing and the read. */
+        }
+    }
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Copy files from one directory into another at the same relative paths, and
+ * return the ones copied. A path that would land outside `to` is skipped.
+ */
+export function carryFiles(from, to, files) {
+    const carried = [];
+    for (const file of files) {
+        const target = resolve(to, file.path);
+        const inside = relative(to, target);
+        if (inside.startsWith("..") || inside === "" || isAbsolute(inside))
+            continue;
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(join(from, file.path), target);
+        carried.push(file);
+    }
+    return carried;
+}

package/dist/user-scope.d.ts

@@ -15,6 +15,59 @@
  * shape, never by trust in the name.
  */
 export declare const USER_SCOPE_OWNER = "Balladeer current guidance (user scope, loader 1)";
+/**
+ * The push check at user scope. Robert, 30 September 2026: setup turns it on
+ * for everyone, where it writes Balladeer's other hooks, report-only unless a
+ * repository says block, so it runs in every connected repository and every
+ * worktree with no step per repository. Two entries on matcher `Bash`, the
+ * same pair `balladeer judge --install-hook` writes into a checkout: after the
+ * command, where report mode judges, and before it, where block mode does.
+ *
+ * Its own mark, apart from the guidance hooks' and from the project entry's
+ * `Balladeer judge`, so each is recognised, replaced and removed only by
+ * itself. The relay note and the push check both sit under PostToolUse.
+ */
+export declare const USER_SCOPE_PUSH_CHECK_OWNER = "Balladeer push check (user scope)";
+/**
+ * The push check runs on every shell command an agent runs, twice, so it is
+ * written only where the command starts in milliseconds: the installed command
+ * by path, or this checkout's own entry file. The `npx` form costs npm's own
+ * start and a registry lookup each time, which would slow every command the
+ * agent runs, so a laptop on it gets no push check until the command installs.
+ */
+export declare function pushCheckInstallable(published: boolean, installed?: string): boolean;
+/** Where the push check stands on this laptop after setup wrote the user scope. */
+export type PushCheckState = "on" | "off" | "unavailable";
+export declare function pushCheckState(environment: NodeJS.ProcessEnv, published: boolean, installed?: string): PushCheckState;
+/** Setup's one line about the push check. */
+export declare function pushCheckSetupLine(state: PushCheckState): string;
+/**
+ * What the push check's entry asks grep before Node starts: whether the
+ * payload's `"command"`, read as JSON (a string, or a list of words as Codex
+ * can send it), so much as mentions `push`, `create` or `merge`. Every line
+ * the judge reads as a push (`git push`, `gh pr create`, `gh pr merge`) spells
+ * one of them out, so none is dropped, and a folder or an output that says
+ * "push" wakes nothing. A word split by quotes (`pu''sh`) is the one spelling
+ * the judge reads as a push and this does not.
+ */
+export declare const PUSH_CHECK_FILTER = "\"command\" *: *(\\[( *\"([^\"\\\\]|\\\\.)*\" *,)* *)?\"([^\"\\\\]|\\\\.)*(push|create|merge)";
+/**
+ * The push check's entry as the host runs it. It runs on every shell command
+ * an agent runs, before and after, so a POSIX shell looks first and starts
+ * Node only for a command that could push: a few milliseconds on anything
+ * else instead of Node's start (measured 30 September 2026: 4 to 6 ms against
+ * 45 to 90). Both hosts run a hook's command through a shell (Codex checked
+ * natively the same day). Only grep's plain "no match" ends it there: a grep
+ * that cannot run lets the command through, so a laptop without one pays
+ * Node's start and loses nothing. `awaiting` is a file that exists while
+ * Codex has yet to run the entry; every command goes through while it does,
+ * so that first run is noted without waiting for a push. Windows gets the
+ * plain command: there is no /bin/sh to count on.
+ */
+export declare function pushCheckCommand(host: UserScopeHost, published: boolean, installed?: string, options?: Readonly<{
+    awaiting?: string;
+    platform?: NodeJS.Platform;
+}>): string;
 /** Every tool of the server named `balladeer`, in Claude Code's permission rule form. */
 export declare const USER_SCOPE_ALLOW_RULE = "mcp__balladeer__*";
 export type UserScopeHost = "claude" | "codex";
@@ -52,12 +105,28 @@ export declare function isOurUserEntry(entry: unknown): boolean;
  */
 export declare function isInstalledCommandPath(command: string): boolean;
 /** `~/.claude/settings.json` carries user-scope hooks. */
-export declare function mergeClaudeUserHooks(home: string, published: boolean, installed?: string): UserScopeWrite;
-/** What a person has to do once in Codex, which no command can do for them. */
-export declare const CODEX_HOOK_APPROVAL = "Codex: type /hooks in a Codex session and trust Balladeer's three hooks. Codex skips a hook until you have trusted it, so until then Codex has Balladeer's tools and none of its session-start guidance or updates.";
+export declare function mergeClaudeUserHooks(home: string, published: boolean, installed?: string, platform?: NodeJS.Platform): UserScopeWrite;
+/**
+ * What a person has to do once in Codex, which no command can do for them,
+ * counting the hooks this run gave Codex: the guidance hooks, and the push
+ * check's two where it was written.
+ */
+export declare function codexHookApproval(pushCheck: boolean): string;
 /** `~/.codex/config.toml` carries both the server and the hooks for Codex, in
  * one fenced block this command owns end to end. */
 export declare function mergeCodexUserConfig(home: string, published: boolean, installed?: string): UserScopeWrite;
+/**
+ * The push check's two entries in `~/.codex/config.toml`, in a fenced block of
+ * their own after Balladeer's other one, so the guidance block and this one are
+ * each written, replaced and removed only by themselves, and Codex's trust in
+ * the one says nothing about the other. TOML lets a later block add to
+ * `[[hooks.PostToolUse]]`, and Codex 0.144.5 reads the file that results
+ * (checked 30 September 2026 with `codex mcp list` on a file of this shape).
+ */
+export declare function mergeCodexPushCheck(home: string, published: boolean, installed?: string, options?: Readonly<{
+    awaiting?: string;
+    platform?: NodeJS.Platform;
+}>): UserScopeWrite;
 /** A copy of this command running out of a source checkout registers the
  * checkout; any installed or npx copy registers the published package. */
 export declare function runningFromCheckout(entry?: string): boolean;
@@ -72,4 +141,6 @@ export declare function installUserScope(options: {
     home?: string;
     /** The durable command's absolute path, when one is installed. */
     installed?: string;
+    /** The clock the Codex trust marks are stamped with. */
+    now?: () => number;
 }): UserScopeWrite[];