balladeer 1.0.16 → 1.0.18

package/dist/judge-hook.d.ts

@@ -1,20 +1,30 @@
 /**
- * Where a judge run starts: a coding host's PreToolUse hook, or git's own
- * pre-push hook.
+ * Where a judge run starts: a coding host's hook around a shell command, or
+ * git's own pre-push hook.
  *
- * The host hook fires on every shell command the agent runs, so the first job
- * is to say "not a push" and get out of the way in milliseconds. Only `git
- * push`, `gh pr create` and `gh pr merge` go further. The command is read the
- * way a shell reads it, so a push inside a quoted commit message is not a push
- * and `git stash push` is not one either.
+ * The host hook fires on every shell command the agent runs, twice: before it
+ * runs (PreToolUse) and after (PostToolUse). The first job each time is to say
+ * "not a push" and get out of the way in milliseconds. Only `git push`, `gh pr
+ * create` and `gh pr merge` go further. The command is read the way a shell
+ * reads it, so a push inside a quoted commit message is not a push and `git
+ * stash push` is not one either.
+ *
+ * Report mode judges after the push, so the push is never held and the check
+ * sees exactly what was pushed. Block mode judges before it, because a push
+ * can only be held before it runs.
  */
 export type HookHost = "claude" | "codex" | "git";
+/** The two host events the judge is installed on, in the order a command meets them. */
+export type HookEvent = "PreToolUse" | "PostToolUse";
+export declare const JUDGE_HOOK_EVENTS: readonly HookEvent[];
 export type HookInput = Readonly<{
     eventName?: string;
     toolName?: string;
     command?: string;
     cwd?: string;
     model?: string;
+    /** The host's session, from `session_id`, which both Claude Code and Codex send. */
+    sessionId?: string;
 }>;
 /** A coding host's hook payload, or nothing when the text is not one. */
 export declare function parseHookInput(text: string): HookInput | undefined;
@@ -26,17 +36,118 @@ export type PushedRef = Readonly<{
     remoteSha: string;
 }>;
 export declare function parsePrePushInput(text: string): PushedRef[];
+/** What separates or groups commands in a shell line. */
+export type ShellOperator = ";" | "&&" | "||" | "|" | "&" | "\n" | "(" | ")" | "`";
+/** One piece of a shell line: a simple command's words, or what comes between commands. */
+export type ShellPiece = Readonly<{
+    kind: "command";
+    words: readonly string[];
+}> | Readonly<{
+    kind: "operator";
+    operator: ShellOperator;
+}>;
 /**
- * The simple commands a shell line runs, as word lists.
+ * A shell line in the order a shell reads it: simple commands and the
+ * operators between them.
+ *
+ * Quotes and backslashes are honored, so quoted text stays one word. `;`,
+ * `&&`, `||`, `|`, `&`, newlines, parentheses and backquotes come between
+ * commands. A comment runs to the end of its line. A redirection (`>`, `2>&1`,
+ * `<file`, `&>log`) and its target are left out of the command's words.
  *
- * Quotes and backslashes are honored, so quoted text stays one word; `;`,
- * `&&`, `||`, `|`, `&`, newlines and parentheses end a command, so `npm test
- * && git push` is two commands and `$(git push)` is found. A comment runs to
- * the end of its line.
+ * A here-document (`<<WORD`, `<<'WORD'`, `<<"WORD"`, `<<-WORD`) is data: the
+ * lines after its command, up to a line that is exactly WORD (leading tabs
+ * removed for `<<-`), are not commands. A here-string's word (`<<<`) is data
+ * too. Two exceptions keep a push inside one from going unseen: text fed to a
+ * shell that reads its script from input (`bash <<EOF`, `cat <<EOF | sh`) is
+ * read as that script, and the `$(...)` and backquotes in a here-document
+ * whose delimiter is not quoted are read as the commands the shell runs while
+ * expanding it. Either is read as a subshell, after the pipeline it feeds. A
+ * here-document that never reaches its delimiter line is not taken as one, so
+ * the lines after it are still read as commands.
+ */
+export declare function scanShell(line: string, depth?: number): ShellPiece[];
+/**
+ * The simple commands a shell line runs, as word lists, in the order
+ * `scanShell` reads them: `npm test && git push` is two commands, `$(git
+ * push)` is found, and a here-document's text is not a command.
  */
 export declare function shellCommands(line: string): string[][];
+/** Where one push, pull request creation or merge in a shell line runs. */
+export type PushSite = Readonly<{
+    kind: "push" | "create" | "merge";
+    /** The absolute directory it runs in; absent when that cannot be told for certain. */
+    directory?: string;
+    /** The repository a pull request command names with `--repo`, `-R` or `GH_REPO`. */
+    repo?: string;
+}>;
+/**
+ * Every push, pull request creation and merge in a shell line, with the
+ * directory it runs in when that can be told for certain.
+ *
+ * Starting from `cwd`, each `cd` moves the line along in order, and a git
+ * command's own `-C` options apply to that command alone. A `cd` inside
+ * parentheses, backquotes or `$(...)` ends with them. Anything that makes the
+ * directory uncertain makes it unknown from there on rather than guessed: `cd`
+ * with no directory, `cd -`, a variable or pattern, `pushd` or `popd`, a `cd`
+ * in a pipeline or in the background, a `cd` inside `if`, a loop, `case` or a
+ * function, and a `cd` that ran only when an earlier command succeeded or
+ * failed, once the line goes past its `&&` chain. A shell's `-c` script starts
+ * where the shell does and moves nothing outside it.
+ */
+export declare function pushSites(line: string, cwd: string | undefined, depth?: number): PushSite[];
+/** Where a shell line's pushes run, when that is one directory that can be told for certain. */
+export type PushPlace = Readonly<{
+    known: true;
+    directory: string;
+    sites: readonly PushSite[];
+}> | Readonly<{
+    known: false;
+}>;
+/**
+ * The one directory a shell line's pushes run in, starting from `cwd`, or
+ * unknown when any of them cannot be told or they run in more than one.
+ */
+export declare function pushPlace(line: string, cwd: string): PushPlace;
+/**
+ * A repository as `owner/name` in lower case, from a remote URL or a `--repo`
+ * value: `https://github.com/o/r.git`, `git@github.com:o/r.git`,
+ * `ssh://git@host/o/r`, `HOST/o/r` or `o/r`. Nothing when there is no owner.
+ */
+export declare function repositoryName(reference: string): string | undefined;
+/** The repositories a checkout's remotes point at, from what `git remote -v` prints. */
+export declare function remoteRepositoryNames(listing: string): Set<string>;
 /** Whether a shell line pushes: `git push`, `gh pr create`, or `gh pr merge`, anywhere in it. */
-export declare function isPushCommand(line: string, depth?: number): boolean;
+export declare function isPushCommand(line: string): boolean;
+/**
+ * Whether a shell line sends this checkout's commits: a `git push`, or a `gh pr
+ * create`, which pushes the branch it opens a pull request for. A line whose
+ * only push is `gh pr merge` sends none; that pull request's commits were on
+ * the remote before the line ran.
+ */
+export declare function sendsCommits(line: string): boolean;
+/**
+ * The first command in the line that makes a commit before it pushes, as
+ * `git <subcommand>`, or nothing.
+ *
+ * A host's PreToolUse hook sees the checkout before the line runs, so in
+ * `git commit -am x && git push` the check judges the code as it was before
+ * the commit, and the commit the push carries is one it never saw. Only a
+ * commit made before the push matters: one made after it is not in what was
+ * pushed, and `gh pr merge` merges a pull request's head, not this checkout's.
+ */
+export declare function commitBeforePush(line: string): string | undefined;
+/**
+ * What a `gh pr merge` names. Neither field means the current branch's pull
+ * request, which is the change in this checkout; either one can name a pull
+ * request whose change is somewhere else entirely.
+ */
+export type MergeTarget = Readonly<{
+    selector?: string;
+    repo?: string;
+}>;
+/** Every `gh pr merge` in a shell line, with the pull request and repository it names. */
+export declare function mergeTargets(line: string): MergeTarget[];
 export type HookResponse = Readonly<{
     stdout: string;
     stderr: string;
@@ -47,11 +158,14 @@ export type HookResponse = Readonly<{
  * and the push goes ahead; a block is exit 2 with the reason, which both hosts
  * treat as a refusal of that one command. Claude Code also gets the reason as
  * `permissionDecision: "deny"`, which it prefers to stderr; Codex is given the
- * stderr form its documentation names.
+ * stderr form its documentation names. After the command ran (PostToolUse)
+ * there is nothing left to hold, so the lines are only ever context, named for
+ * the event that asked.
  */
 export declare function hookResponse(host: HookHost, outcome: Readonly<{
     block: boolean;
     lines: readonly string[];
+    event?: HookEvent;
 }>): HookResponse;
 /** The status line both hosts show while the hook runs, and the mark of the entry this command owns. */
 export declare const JUDGE_HOOK_MARKER = "Balladeer judge";
@@ -78,7 +192,67 @@ export type HookInstallResult = Readonly<{
     status: "written" | "unchanged" | "refused";
     reason?: string;
 }>;
+/** The hook file the installer writes for a host, relative to the repository root. */
+export declare function judgeHookFile(host: "claude" | "codex"): string;
+/**
+ * Whether the hook file the installer writes has this command's entry for one
+ * event. It reads the file rather than guessing, so a checkout installed by an
+ * earlier release, which wrote only the PreToolUse entry, is told apart from a
+ * current one. Anything unreadable counts as no entry.
+ */
+export declare function hasJudgeEntry(root: string, host: "claude" | "codex", event: HookEvent): boolean;
+/**
+ * Whether this checkout has the push check's own project entry for a host,
+ * under either event. Where it does, that entry owns the check in this
+ * checkout and the one setup writes at the host's user scope stands aside, so
+ * a push is judged once. Either event counts: a checkout an earlier release
+ * installed has only the entry before the push, and it keeps judging there.
+ */
+export declare function hasProjectJudgeHook(root: string, host: "claude" | "codex"): boolean;
+/**
+ * The checkout that holds a folder, found by walking up to its `.git` entry (a
+ * directory, or a file in a worktree). No process is started, so a folder that
+ * is not in a checkout at all is known in well under a millisecond.
+ */
+export declare function checkoutRoot(start: string): string | undefined;
+/**
+ * The push check's switch for this laptop, in Balladeer's own config home.
+ * Absent means on. Written only by `balladeer judge --push-check off`, and
+ * read by the user-scope entry on each push, so turning it off takes effect in
+ * sessions that are already open.
+ */
+export declare const PUSH_CHECK_SETTING_FILE = "push-check.json";
+export declare function pushCheckSettingPath(environment: NodeJS.ProcessEnv): string;
+/** True only when this laptop's switch says off; anything unreadable leaves it on. */
+export declare function pushCheckOff(environment: NodeJS.ProcessEnv): boolean;
+/** Turn the user-scope push check off or back on for this laptop. */
+export declare function setPushCheck(environment: NodeJS.ProcessEnv, on: boolean): void;
 /** Where git looks for hooks in this checkout, which is not `.git/hooks` in a worktree. */
 export declare function gitHooksDirectory(root: string): string;
 /** Install the judge hook for one host. Running it twice changes nothing the second time. */
 export declare function installJudgeHook(root: string, target: HookHost): HookInstallResult;
+/**
+ * Whether a commit is on a remote now: reachable from a remote-tracking ref,
+ * or else the tip of a branch some remote reports.
+ *
+ * `git push`, `git push origin HEAD:branch` and the push `gh pr create` makes
+ * all move the remote-tracking ref of what they pushed, so the first check is
+ * local and immediate. The second is there because a push can land without
+ * that ref moving: Codex's workspace sandbox keeps `.git` read-only, so its
+ * pushes reach the remote and then fail to update `refs/remotes/...` (hook
+ * canary, 29 September 2026). Asking each remote for its branch tips settles
+ * it without fetching anything, and a push that failed leaves its commit on
+ * neither.
+ */
+export declare function pushLanded(root: string, sha: string): Promise<boolean>;
+/**
+ * Where the remote default branch stood before this push, when this push is
+ * what moved it to `head`; otherwise nothing, and the ordinary fork-point rule
+ * applies.
+ *
+ * Judged after a push straight to the default branch, the fork point with that
+ * branch's remote-tracking ref is `head` itself, so the change would shrink to
+ * its last commit. git records the push in the ref's reflog ("update by
+ * push"), and the entry before it is where the branch stood.
+ */
+export declare function baseBeforePush(root: string, head: string): Promise<string | undefined>;