balladeer 1.0.15 → 1.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +2 -0
  2. package/dist/behavior-map-schema.d.ts +107 -0
  3. package/dist/behavior-map-schema.js +232 -0
  4. package/dist/cli.d.ts +6 -1
  5. package/dist/cli.js +74 -6
  6. package/dist/commands/guidance.d.ts +2 -1
  7. package/dist/commands/guidance.js +55 -0
  8. package/dist/commands/judge.d.ts +430 -0
  9. package/dist/commands/judge.js +1713 -0
  10. package/dist/commands/map.d.ts +164 -0
  11. package/dist/commands/map.js +838 -0
  12. package/dist/commands/mcp.js +2 -2
  13. package/dist/commands/offers.d.ts +265 -0
  14. package/dist/commands/offers.js +801 -0
  15. package/dist/commands/risk.d.ts +29 -0
  16. package/dist/commands/risk.js +133 -0
  17. package/dist/copy.d.ts +24 -1
  18. package/dist/copy.js +91 -0
  19. package/dist/guidance-hook.mjs +348 -94
  20. package/dist/headless-agent.d.ts +166 -0
  21. package/dist/headless-agent.js +416 -0
  22. package/dist/hook-trust.d.ts +41 -9
  23. package/dist/hook-trust.js +98 -16
  24. package/dist/judge-brief.d.ts +48 -0
  25. package/dist/judge-brief.js +102 -0
  26. package/dist/judge-hook.d.ts +258 -0
  27. package/dist/judge-hook.js +1278 -0
  28. package/dist/judge-said.d.ts +52 -0
  29. package/dist/judge-said.js +181 -0
  30. package/dist/map-brief.d.ts +16 -0
  31. package/dist/map-brief.js +41 -0
  32. package/dist/offer-brief.d.ts +95 -0
  33. package/dist/offer-brief.js +217 -0
  34. package/dist/owned-process.d.ts +65 -0
  35. package/dist/owned-process.js +146 -0
  36. package/dist/promise-meaning.d.ts +134 -0
  37. package/dist/promise-meaning.js +300 -0
  38. package/dist/relay.d.ts +71 -0
  39. package/dist/relay.js +193 -0
  40. package/dist/remove-earlier.js +4 -2
  41. package/dist/risk/contract.d.ts +145 -0
  42. package/dist/risk/contract.js +74 -0
  43. package/dist/risk/describe.d.ts +7 -0
  44. package/dist/risk/describe.js +45 -0
  45. package/dist/risk/diff.d.ts +26 -0
  46. package/dist/risk/diff.js +174 -0
  47. package/dist/risk/extract.d.ts +43 -0
  48. package/dist/risk/extract.js +336 -0
  49. package/dist/risk/git.d.ts +30 -0
  50. package/dist/risk/git.js +118 -0
  51. package/dist/risk/import-graph.d.ts +41 -0
  52. package/dist/risk/import-graph.js +487 -0
  53. package/dist/risk/index.d.ts +20 -0
  54. package/dist/risk/index.js +20 -0
  55. package/dist/risk/paths.d.ts +16 -0
  56. package/dist/risk/paths.js +73 -0
  57. package/dist/risk/pipeline.d.ts +47 -0
  58. package/dist/risk/pipeline.js +121 -0
  59. package/dist/risk/priors.d.ts +18 -0
  60. package/dist/risk/priors.js +86 -0
  61. package/dist/risk/resources.d.ts +56 -0
  62. package/dist/risk/resources.js +374 -0
  63. package/dist/risk/score.d.ts +95 -0
  64. package/dist/risk/score.js +552 -0
  65. package/dist/risk/symbols.d.ts +35 -0
  66. package/dist/risk/symbols.js +348 -0
  67. package/dist/risk/text.d.ts +43 -0
  68. package/dist/risk/text.js +277 -0
  69. package/dist/risk/validate.d.ts +19 -0
  70. package/dist/risk/validate.js +154 -0
  71. package/dist/scratch-worktree.d.ts +55 -0
  72. package/dist/scratch-worktree.js +160 -0
  73. package/dist/user-scope.d.ts +74 -3
  74. package/dist/user-scope.js +270 -9
  75. package/dist/wire.d.ts +52 -3
  76. package/dist/wire.js +2 -2
  77. package/package.json +1 -1
@@ -0,0 +1,1278 @@
1
+ import { execFileSync } from "node:child_process";
2
+ import { randomBytes } from "node:crypto";
3
+ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
4
+ import { basename, dirname, isAbsolute, join, resolve } from "node:path";
5
+ import { runCommand } from "./gh.js";
6
+ import { resolveCommit } from "./scratch-worktree.js";
7
+ import { configHome } from "./store.js";
8
+ export const JUDGE_HOOK_EVENTS = ["PreToolUse", "PostToolUse"];
9
+ /** A session id as the hook keeps it: a bounded name, never a path or a sentence. */
10
+ const SESSION_ID = /^[A-Za-z0-9._:-]{1,128}$/;
11
+ /** A coding host's hook payload, or nothing when the text is not one. */
12
+ export function parseHookInput(text) {
13
+ let value;
14
+ try {
15
+ value = JSON.parse(text);
16
+ }
17
+ catch {
18
+ return undefined;
19
+ }
20
+ if (value === null || typeof value !== "object" || Array.isArray(value))
21
+ return undefined;
22
+ const input = value;
23
+ const toolInput = input.tool_input;
24
+ const command = commandText(toolInput?.command);
25
+ return {
26
+ ...(typeof input.hook_event_name === "string" ? { eventName: input.hook_event_name } : {}),
27
+ ...(typeof input.tool_name === "string" ? { toolName: input.tool_name } : {}),
28
+ ...(command === undefined ? {} : { command }),
29
+ ...(typeof input.cwd === "string" ? { cwd: input.cwd } : {}),
30
+ ...(typeof input.model === "string" ? { model: input.model } : {}),
31
+ ...(typeof input.session_id === "string" && SESSION_ID.test(input.session_id)
32
+ ? { sessionId: input.session_id }
33
+ : {}),
34
+ };
35
+ }
36
+ const SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh"]);
37
+ /** Codex can send a command as an argument vector; a shell's `-c` script is what runs. */
38
+ function commandText(value) {
39
+ if (typeof value === "string")
40
+ return value;
41
+ if (!Array.isArray(value) || !value.every((word) => typeof word === "string"))
42
+ return undefined;
43
+ const words = value;
44
+ if (words.length >= 3 && SHELLS.has(basename(words[0])) && /^-[a-z]*c[a-z]*$/.test(words[1]))
45
+ return words[2];
46
+ return words.join(" ");
47
+ }
48
+ const ZERO = /^0{40}$/;
49
+ export function parsePrePushInput(text) {
50
+ const refs = [];
51
+ for (const line of text.split("\n")) {
52
+ const [localRef, localSha, remoteRef, remoteSha] = line.trim().split(/\s+/);
53
+ if (!localRef || !localSha || !remoteRef || !remoteSha)
54
+ continue;
55
+ if (!/^[0-9a-f]{40}$/.test(localSha) || ZERO.test(localSha))
56
+ continue;
57
+ refs.push({ localRef, localSha, remoteRef, remoteSha });
58
+ }
59
+ return refs;
60
+ }
61
+ /** What ends a shell word outside quotes. */
62
+ const WORD_END = /[\s;&|()<>`]/;
63
+ /**
64
+ * One word read the way a shell reads it, starting at `from`: quotes and
65
+ * backslashes honored and removed. `quoted` says whether any part was quoted
66
+ * or escaped, which is what makes a here-document's text literal.
67
+ */
68
+ function readWord(line, from) {
69
+ let text = "";
70
+ let quoted = false;
71
+ let at = from;
72
+ while (at < line.length && !WORD_END.test(line[at])) {
73
+ const char = line[at];
74
+ if (char === "'") {
75
+ quoted = true;
76
+ const close = line.indexOf("'", at + 1);
77
+ const end = close < 0 ? line.length : close;
78
+ text += line.slice(at + 1, end);
79
+ at = end + 1;
80
+ }
81
+ else if (char === '"') {
82
+ quoted = true;
83
+ at += 1;
84
+ while (at < line.length && line[at] !== '"') {
85
+ if (line[at] === "\\" && at + 1 < line.length)
86
+ at += 1;
87
+ text += line[at];
88
+ at += 1;
89
+ }
90
+ at += 1;
91
+ }
92
+ else if (char === "\\") {
93
+ quoted = true;
94
+ if (at + 1 < line.length && line[at + 1] !== "\n")
95
+ text += line[at + 1];
96
+ at += 2;
97
+ }
98
+ else {
99
+ text += char;
100
+ at += 1;
101
+ }
102
+ }
103
+ return { text, end: Math.min(at, line.length), quoted };
104
+ }
105
+ function skipBlanks(line, from) {
106
+ let at = from;
107
+ while (at < line.length && (line[at] === " " || line[at] === "\t"))
108
+ at += 1;
109
+ return at;
110
+ }
111
+ /**
112
+ * Whether a command reads a script from its input: a shell given no `-c`
113
+ * script and no script file, as in `bash <<EOF` or `... | sh`.
114
+ */
115
+ function readsScriptFromInput(words) {
116
+ const run = program(words);
117
+ if (run.length === 0 || !SHELLS.has(basename(run[0])))
118
+ return false;
119
+ const args = run.slice(1);
120
+ if (args.some((word) => /^-[a-z]*c[a-z]*$/.test(word)))
121
+ return false;
122
+ const operand = args.findIndex((word) => !word.startsWith("-"));
123
+ return operand < 0 || args.slice(0, operand).includes("-s");
124
+ }
125
+ /**
126
+ * The command substitutions in a here-document whose delimiter is not quoted,
127
+ * `$(...)` and backquotes, which the shell runs while it reads the text. The
128
+ * rest of the text is data.
129
+ */
130
+ function substitutions(body) {
131
+ const found = [];
132
+ for (let at = 0; at < body.length; at += 1) {
133
+ const char = body[at];
134
+ if (char === "\\") {
135
+ at += 1;
136
+ }
137
+ else if (char === "$" && body[at + 1] === "(" && body[at + 2] !== "(") {
138
+ let depth = 1;
139
+ let end = at + 2;
140
+ while (end < body.length && depth > 0) {
141
+ if (body[end] === "(")
142
+ depth += 1;
143
+ else if (body[end] === ")")
144
+ depth -= 1;
145
+ if (depth > 0)
146
+ end += 1;
147
+ }
148
+ found.push(body.slice(at + 2, end));
149
+ at = end;
150
+ }
151
+ else if (char === "`") {
152
+ let end = at + 1;
153
+ while (end < body.length && body[end] !== "`")
154
+ end += body[end] === "\\" ? 2 : 1;
155
+ found.push(body.slice(at + 1, end));
156
+ at = end;
157
+ }
158
+ }
159
+ return found;
160
+ }
161
+ /**
162
+ * A shell line in the order a shell reads it: simple commands and the
163
+ * operators between them.
164
+ *
165
+ * Quotes and backslashes are honored, so quoted text stays one word. `;`,
166
+ * `&&`, `||`, `|`, `&`, newlines, parentheses and backquotes come between
167
+ * commands. A comment runs to the end of its line. A redirection (`>`, `2>&1`,
168
+ * `<file`, `&>log`) and its target are left out of the command's words.
169
+ *
170
+ * A here-document (`<<WORD`, `<<'WORD'`, `<<"WORD"`, `<<-WORD`) is data: the
171
+ * lines after its command, up to a line that is exactly WORD (leading tabs
172
+ * removed for `<<-`), are not commands. A here-string's word (`<<<`) is data
173
+ * too. Two exceptions keep a push inside one from going unseen: text fed to a
174
+ * shell that reads its script from input (`bash <<EOF`, `cat <<EOF | sh`) is
175
+ * read as that script, and the `$(...)` and backquotes in a here-document
176
+ * whose delimiter is not quoted are read as the commands the shell runs while
177
+ * expanding it. Either is read as a subshell, after the pipeline it feeds. A
178
+ * here-document that never reaches its delimiter line is not taken as one, so
179
+ * the lines after it are still read as commands.
180
+ */
181
+ export function scanShell(line, depth = 0) {
182
+ const pieces = [];
183
+ const fed = [];
184
+ const pending = [];
185
+ let words = [];
186
+ let word = "";
187
+ let inWord = false;
188
+ const endWord = () => {
189
+ if (inWord)
190
+ words.push(word);
191
+ word = "";
192
+ inWord = false;
193
+ };
194
+ const endCommand = () => {
195
+ endWord();
196
+ if (words.length > 0)
197
+ pieces.push({ kind: "command", words });
198
+ words = [];
199
+ };
200
+ const operator = (value) => {
201
+ endCommand();
202
+ pieces.push({ kind: "operator", operator: value });
203
+ };
204
+ /** The bodies of the here-documents waiting on the line that just ended, from `from`. */
205
+ const hereDocuments = (from) => {
206
+ let at = from;
207
+ while (pending.length > 0) {
208
+ const document = pending[0];
209
+ const lines = [];
210
+ let cursor = at;
211
+ let after = -1;
212
+ for (;;) {
213
+ const newline = line.indexOf("\n", cursor);
214
+ const stop = newline < 0 ? line.length : newline;
215
+ const text = document.stripTabs
216
+ ? line.slice(cursor, stop).replace(/^\t+/, "")
217
+ : line.slice(cursor, stop);
218
+ if (text === document.delimiter) {
219
+ after = newline < 0 ? line.length : newline + 1;
220
+ break;
221
+ }
222
+ lines.push(text);
223
+ if (newline < 0)
224
+ break;
225
+ cursor = newline + 1;
226
+ }
227
+ if (after < 0) {
228
+ // Never closed: read what follows as commands rather than hide it.
229
+ pending.length = 0;
230
+ break;
231
+ }
232
+ pending.shift();
233
+ fed.push({
234
+ index: document.index,
235
+ body: lines.join("\n"),
236
+ expands: document.expands,
237
+ order: fed.length,
238
+ });
239
+ at = after;
240
+ }
241
+ return at;
242
+ };
243
+ let at = 0;
244
+ while (at < line.length) {
245
+ const char = line[at];
246
+ const next = line[at + 1];
247
+ if (char === "'") {
248
+ const close = line.indexOf("'", at + 1);
249
+ const end = close < 0 ? line.length : close;
250
+ word += line.slice(at + 1, end);
251
+ inWord = true;
252
+ at = end + 1;
253
+ }
254
+ else if (char === '"') {
255
+ inWord = true;
256
+ at += 1;
257
+ while (at < line.length && line[at] !== '"') {
258
+ if (line[at] === "\\" && at + 1 < line.length)
259
+ at += 1;
260
+ word += line[at];
261
+ at += 1;
262
+ }
263
+ at += 1;
264
+ }
265
+ else if (char === "\\") {
266
+ // A backslash before a newline joins two lines and adds nothing.
267
+ if (next !== undefined && next !== "\n") {
268
+ word += next;
269
+ inWord = true;
270
+ }
271
+ at += 2;
272
+ }
273
+ else if (char === "#" && !inWord) {
274
+ const end = line.indexOf("\n", at);
275
+ at = end < 0 ? line.length : end;
276
+ }
277
+ else if (char === "\n") {
278
+ operator("\n");
279
+ at = hereDocuments(at + 1);
280
+ }
281
+ else if (/\s/.test(char)) {
282
+ endWord();
283
+ at += 1;
284
+ }
285
+ else if (char === "<" && next === "<" && line[at + 2] === "<") {
286
+ endWord();
287
+ const data = readWord(line, skipBlanks(line, at + 3));
288
+ fed.push({ index: pieces.length, body: data.text, expands: false, order: fed.length });
289
+ at = data.end;
290
+ }
291
+ else if (char === "<" && next === "<") {
292
+ endWord();
293
+ let from = at + 2;
294
+ const stripTabs = line[from] === "-";
295
+ if (stripTabs)
296
+ from += 1;
297
+ from = skipBlanks(line, from);
298
+ const delimiter = readWord(line, from);
299
+ if (delimiter.end > from)
300
+ pending.push({
301
+ delimiter: delimiter.text,
302
+ stripTabs,
303
+ expands: !delimiter.quoted,
304
+ index: pieces.length,
305
+ });
306
+ at = delimiter.end;
307
+ }
308
+ else if ((char === "<" || char === ">") && next === "(") {
309
+ // Process substitution: the parenthesis opens a command of its own.
310
+ endWord();
311
+ at += 1;
312
+ }
313
+ else if (char === "<" || char === ">" || (char === "&" && next === ">")) {
314
+ // A number written straight before the operator is the descriptor it redirects.
315
+ if (inWord && /^\d+$/.test(word)) {
316
+ word = "";
317
+ inWord = false;
318
+ }
319
+ else
320
+ endWord();
321
+ let from = at + (char === "&" ? 2 : 1);
322
+ if (line[from] === ">" || line[from] === "&" || line[from] === "|")
323
+ from += 1;
324
+ else if (char === "<" && line[from] === ">")
325
+ from += 1;
326
+ at = readWord(line, skipBlanks(line, from)).end;
327
+ }
328
+ else if (char === "&" && next === "&") {
329
+ operator("&&");
330
+ at += 2;
331
+ }
332
+ else if (char === "|" && next === "|") {
333
+ operator("||");
334
+ at += 2;
335
+ }
336
+ else if (char === "|") {
337
+ operator("|");
338
+ at += next === "&" ? 2 : 1;
339
+ }
340
+ else if (char === "&" || char === ";" || char === "(" || char === ")" || char === "`") {
341
+ operator(char);
342
+ at += 1;
343
+ }
344
+ else {
345
+ word += char;
346
+ inWord = true;
347
+ at += 1;
348
+ }
349
+ }
350
+ endCommand();
351
+ if (depth >= 3)
352
+ return pieces;
353
+ // Text read as commands goes in as a subshell after the pipeline it feeds,
354
+ // latest first so the earlier positions stay where they are.
355
+ const isPipe = (piece) => piece?.kind === "operator" && piece.operator === "|";
356
+ const placed = fed
357
+ .filter((entry) => pieces[entry.index]?.kind === "command")
358
+ .map((entry) => {
359
+ let start = entry.index;
360
+ let end = entry.index;
361
+ while (start >= 2 && isPipe(pieces[start - 1]) && pieces[start - 2]?.kind === "command")
362
+ start -= 2;
363
+ while (isPipe(pieces[end + 1]) && pieces[end + 2]?.kind === "command")
364
+ end += 2;
365
+ const pipeline = pieces
366
+ .slice(start, end + 1)
367
+ .flatMap((piece) => (piece.kind === "command" ? [piece.words] : []));
368
+ const scripts = pipeline.some(readsScriptFromInput)
369
+ ? [entry.body]
370
+ : entry.expands
371
+ ? substitutions(entry.body)
372
+ : [];
373
+ return { end, order: entry.order, scripts };
374
+ })
375
+ .sort((a, b) => b.end - a.end || b.order - a.order);
376
+ for (const { end, scripts } of placed) {
377
+ const inserted = scripts.flatMap((script) => [
378
+ { kind: "operator", operator: "(" },
379
+ ...scanShell(script, depth + 1),
380
+ { kind: "operator", operator: ")" },
381
+ ]);
382
+ pieces.splice(end + 1, 0, ...inserted);
383
+ }
384
+ return pieces;
385
+ }
386
+ /**
387
+ * The simple commands a shell line runs, as word lists, in the order
388
+ * `scanShell` reads them: `npm test && git push` is two commands, `$(git
389
+ * push)` is found, and a here-document's text is not a command.
390
+ */
391
+ export function shellCommands(line) {
392
+ return scanShell(line).flatMap((piece) => (piece.kind === "command" ? [[...piece.words]] : []));
393
+ }
394
+ /** Words that group commands or negate one; the command is what follows them. */
395
+ const GROUPING = new Set(["{", "}", "!"]);
396
+ /** Words after which a command runs only sometimes, repeatedly, or later. */
397
+ const BRANCHING = new Set([
398
+ "if",
399
+ "then",
400
+ "elif",
401
+ "else",
402
+ "fi",
403
+ "for",
404
+ "while",
405
+ "until",
406
+ "do",
407
+ "done",
408
+ "case",
409
+ "esac",
410
+ "select",
411
+ "function",
412
+ ]);
413
+ /**
414
+ * A directory a command names, taken from `from`, or nothing when it cannot
415
+ * be told for certain: a variable, a pattern, another user's home, or a
416
+ * starting point that is itself unknown.
417
+ */
418
+ function directoryFrom(from, named) {
419
+ if (from === undefined || named === "" || /[$`*?[]/.test(named))
420
+ return undefined;
421
+ let path = named;
422
+ if (path === "~" || path.startsWith("~/")) {
423
+ const home = process.env.HOME;
424
+ if (!home || !isAbsolute(home))
425
+ return undefined;
426
+ path = join(home, path.slice(1));
427
+ }
428
+ else if (path.startsWith("~"))
429
+ return undefined;
430
+ const joined = isAbsolute(path) ? join(path) : join(from, path);
431
+ return joined.length > 1 ? joined.replace(/\/+$/, "") : joined;
432
+ }
433
+ /** Where `cd` with these arguments goes. `cd`, `cd -` and `cd a b` cannot be told. */
434
+ function cdTarget(from, args) {
435
+ let at = 0;
436
+ while (at < args.length && /^-[LPe@]+$/.test(args[at]))
437
+ at += 1;
438
+ if (args[at] === "--")
439
+ at += 1;
440
+ const rest = args.slice(at);
441
+ if (rest.length !== 1 || rest[0] === "-")
442
+ return undefined;
443
+ return directoryFrom(from, rest[0]);
444
+ }
445
+ /** Where a git command runs after its `-C` options; `--git-dir` and `--work-tree` cannot be told. */
446
+ function gitDirectory(from, args) {
447
+ let here = from;
448
+ for (let at = 0; at < args.length; at += 1) {
449
+ const word = args[at];
450
+ if (/^--(git-dir|work-tree)(=|$)/.test(word))
451
+ return undefined;
452
+ if (word === "-C") {
453
+ const named = args[at + 1];
454
+ if (named === undefined)
455
+ return undefined;
456
+ if (named !== "")
457
+ here = directoryFrom(here, named);
458
+ at += 1;
459
+ }
460
+ else if (GIT_VALUE_OPTIONS.has(word))
461
+ at += 1;
462
+ else if (!word.startsWith("-"))
463
+ break;
464
+ }
465
+ return here;
466
+ }
467
+ /** `gh pr create` options that take the next word as their value. */
468
+ const GH_CREATE_VALUE_OPTIONS = new Set([
469
+ "-a",
470
+ "--assignee",
471
+ "-B",
472
+ "--base",
473
+ "-b",
474
+ "--body",
475
+ "-F",
476
+ "--body-file",
477
+ "-H",
478
+ "--head",
479
+ "-l",
480
+ "--label",
481
+ "-m",
482
+ "--milestone",
483
+ "-p",
484
+ "--project",
485
+ "-R",
486
+ "--repo",
487
+ "-r",
488
+ "--reviewer",
489
+ "-T",
490
+ "--template",
491
+ "-t",
492
+ "--title",
493
+ "--recover",
494
+ ]);
495
+ function createRepo(args) {
496
+ let repo;
497
+ for (let at = 0; at < args.length; at += 1) {
498
+ const word = args[at];
499
+ if (word === "--")
500
+ break;
501
+ if (word.startsWith("--repo="))
502
+ repo = word.slice("--repo=".length);
503
+ else if (GH_CREATE_VALUE_OPTIONS.has(word)) {
504
+ if (word === "-R" || word === "--repo")
505
+ repo = args[at + 1];
506
+ at += 1;
507
+ }
508
+ }
509
+ return repo;
510
+ }
511
+ /**
512
+ * Every push, pull request creation and merge in a shell line, with the
513
+ * directory it runs in when that can be told for certain.
514
+ *
515
+ * Starting from `cwd`, each `cd` moves the line along in order, and a git
516
+ * command's own `-C` options apply to that command alone. A `cd` inside
517
+ * parentheses, backquotes or `$(...)` ends with them. Anything that makes the
518
+ * directory uncertain makes it unknown from there on rather than guessed: `cd`
519
+ * with no directory, `cd -`, a variable or pattern, `pushd` or `popd`, a `cd`
520
+ * in a pipeline or in the background, a `cd` inside `if`, a loop, `case` or a
521
+ * function, and a `cd` that ran only when an earlier command succeeded or
522
+ * failed, once the line goes past its `&&` chain. A shell's `-c` script starts
523
+ * where the shell does and moves nothing outside it.
524
+ */
525
+ export function pushSites(line, cwd, depth = 0) {
526
+ const pieces = scanShell(line);
527
+ const sites = [];
528
+ const saved = [];
529
+ let here = cwd;
530
+ // Set after a `cd` that ran only when an earlier command succeeded or
531
+ // failed: it holds along its own `&&` chain and not past it.
532
+ let conditional = false;
533
+ let backquoted = false;
534
+ let branching = false;
535
+ const restore = () => {
536
+ const frame = saved.pop();
537
+ here = frame === undefined ? undefined : frame.here;
538
+ conditional = frame === undefined ? false : frame.conditional;
539
+ };
540
+ const operatorAt = (index) => {
541
+ const piece = pieces[index];
542
+ return piece?.kind === "operator" ? piece.operator : undefined;
543
+ };
544
+ for (let index = 0; index < pieces.length; index += 1) {
545
+ const piece = pieces[index];
546
+ if (piece.kind === "operator") {
547
+ const value = piece.operator;
548
+ if (value === "(") {
549
+ // `name()` defines a function, whose body runs later if at all.
550
+ if (operatorAt(index + 1) === ")")
551
+ branching = true;
552
+ saved.push({ here, conditional });
553
+ conditional = false;
554
+ }
555
+ else if (value === ")")
556
+ restore();
557
+ else if (value === "`") {
558
+ if (backquoted)
559
+ restore();
560
+ else {
561
+ saved.push({ here, conditional });
562
+ conditional = false;
563
+ }
564
+ backquoted = !backquoted;
565
+ }
566
+ else if (value !== "&&" && conditional) {
567
+ here = undefined;
568
+ conditional = false;
569
+ }
570
+ continue;
571
+ }
572
+ let start = 0;
573
+ while (start < piece.words.length) {
574
+ const word = piece.words[start];
575
+ if (BRANCHING.has(word))
576
+ branching = true;
577
+ else if (!GROUPING.has(word))
578
+ break;
579
+ start += 1;
580
+ }
581
+ const words = piece.words.slice(start);
582
+ const run = program(words);
583
+ if (run.length === 0)
584
+ continue;
585
+ const prefix = words.slice(0, words.length - run.length);
586
+ const name = basename(run[0]);
587
+ const before = operatorAt(index - 1);
588
+ const after = operatorAt(index + 1);
589
+ if (name === "cd") {
590
+ if (branching || before === "|" || after === "|" || after === "&")
591
+ here = undefined;
592
+ else {
593
+ here = cdTarget(here, run.slice(1));
594
+ if (before === "&&" || before === "||")
595
+ conditional = true;
596
+ }
597
+ }
598
+ else if (name === "pushd" || name === "popd")
599
+ here = undefined;
600
+ else if (name === "git" && gitSubcommand(run.slice(1)) === "push") {
601
+ const directory = prefix.some((word) => /^GIT_(DIR|WORK_TREE)=/.test(word))
602
+ ? undefined
603
+ : gitDirectory(here, run.slice(1));
604
+ sites.push({ kind: "push", ...(directory === undefined ? {} : { directory }) });
605
+ }
606
+ else if (name === "gh" && run[1] === "pr" && (run[2] === "create" || run[2] === "merge")) {
607
+ const named = (run[2] === "merge" ? mergeTarget(run.slice(3)).repo : createRepo(run.slice(3))) ??
608
+ prefix.find((word) => word.startsWith("GH_REPO="))?.slice("GH_REPO=".length);
609
+ const directory = named !== undefined && /[$`]/.test(named) ? undefined : here;
610
+ sites.push({
611
+ kind: run[2],
612
+ ...(directory === undefined ? {} : { directory }),
613
+ ...(named ? { repo: named } : {}),
614
+ });
615
+ }
616
+ else if (SHELLS.has(name) && depth < 3) {
617
+ const flag = run.findIndex((word, at) => at > 0 && /^-[a-z]*c[a-z]*$/.test(word));
618
+ const script = flag > 0 ? run[flag + 1] : undefined;
619
+ if (script !== undefined)
620
+ sites.push(...pushSites(script, here, depth + 1));
621
+ }
622
+ }
623
+ return sites;
624
+ }
625
+ /**
626
+ * The one directory a shell line's pushes run in, starting from `cwd`, or
627
+ * unknown when any of them cannot be told or they run in more than one.
628
+ */
629
+ export function pushPlace(line, cwd) {
630
+ const sites = pushSites(line, cwd);
631
+ if (sites.length === 0)
632
+ return { known: true, directory: cwd, sites };
633
+ const directories = new Set(sites.map((site) => site.directory));
634
+ const [directory] = directories;
635
+ if (directories.size !== 1 || directory === undefined)
636
+ return { known: false };
637
+ return { known: true, directory, sites };
638
+ }
639
+ /**
640
+ * A repository as `owner/name` in lower case, from a remote URL or a `--repo`
641
+ * value: `https://github.com/o/r.git`, `git@github.com:o/r.git`,
642
+ * `ssh://git@host/o/r`, `HOST/o/r` or `o/r`. Nothing when there is no owner.
643
+ */
644
+ export function repositoryName(reference) {
645
+ let path = reference.trim();
646
+ const url = /^[a-z][a-z0-9+.-]*:\/\/[^/]*(\/.*)?$/i.exec(path);
647
+ const scp = url === null ? /^(?:[^/@:\s]+@)?[^/:\s]+:(.*)$/.exec(path) : null;
648
+ if (url !== null)
649
+ path = url[1] ?? "";
650
+ else if (scp !== null)
651
+ path = scp[1] ?? "";
652
+ const segments = path
653
+ .replace(/\/+$/, "")
654
+ .replace(/\.git$/i, "")
655
+ .split("/")
656
+ .filter(Boolean);
657
+ return segments.length < 2 ? undefined : segments.slice(-2).join("/").toLowerCase();
658
+ }
659
+ /** The repositories a checkout's remotes point at, from what `git remote -v` prints. */
660
+ export function remoteRepositoryNames(listing) {
661
+ const names = new Set();
662
+ for (const line of listing.split("\n")) {
663
+ const url = line.trim().split(/\s+/)[1];
664
+ const name = url === undefined ? undefined : repositoryName(url);
665
+ if (name !== undefined)
666
+ names.add(name);
667
+ }
668
+ return names;
669
+ }
670
+ const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
671
+ const WRAPPERS = new Set(["env", "command", "exec", "time", "nohup", "nice", "sudo", "builtin"]);
672
+ /** The command's words with leading assignments and wrappers like `env` and `sudo` removed. */
673
+ function program(words) {
674
+ let at = 0;
675
+ while (at < words.length) {
676
+ const word = words[at];
677
+ if (ASSIGNMENT.test(word))
678
+ at += 1;
679
+ else if (WRAPPERS.has(basename(word))) {
680
+ at += 1;
681
+ while (at < words.length && (words[at].startsWith("-") || ASSIGNMENT.test(words[at])))
682
+ at += 1;
683
+ }
684
+ else
685
+ break;
686
+ }
687
+ return words.slice(at);
688
+ }
689
+ /** git's global options that take the next word as their value. */
690
+ const GIT_VALUE_OPTIONS = new Set([
691
+ "-C",
692
+ "-c",
693
+ "--git-dir",
694
+ "--work-tree",
695
+ "--namespace",
696
+ "--super-prefix",
697
+ "--config-env",
698
+ ]);
699
+ function gitSubcommand(args) {
700
+ for (let at = 0; at < args.length; at += 1) {
701
+ const word = args[at];
702
+ if (GIT_VALUE_OPTIONS.has(word)) {
703
+ at += 1;
704
+ continue;
705
+ }
706
+ if (word.startsWith("-"))
707
+ continue;
708
+ return word;
709
+ }
710
+ return undefined;
711
+ }
712
+ /**
713
+ * The commands in a shell line that matter to the judge, in the order they
714
+ * run: pushes, pull requests created or merged, and commits. A shell's `-c`
715
+ * script is read in place, a few levels deep.
716
+ */
717
+ function steps(line, depth = 0) {
718
+ const found = [];
719
+ for (const words of shellCommands(line)) {
720
+ const run = program(words);
721
+ if (run.length === 0)
722
+ continue;
723
+ const name = basename(run[0]);
724
+ if (name === "git") {
725
+ const subcommand = gitSubcommand(run.slice(1));
726
+ if (subcommand === "push" || subcommand === "commit")
727
+ found.push({ kind: subcommand, args: [] });
728
+ }
729
+ else if (name === "gh" && run[1] === "pr" && (run[2] === "create" || run[2] === "merge"))
730
+ found.push({ kind: run[2], args: run.slice(3) });
731
+ else if (SHELLS.has(name) && depth < 3) {
732
+ const flag = run.findIndex((word, index) => index > 0 && /^-[a-z]*c[a-z]*$/.test(word));
733
+ const script = flag > 0 ? run[flag + 1] : undefined;
734
+ if (script !== undefined)
735
+ found.push(...steps(script, depth + 1));
736
+ }
737
+ }
738
+ return found;
739
+ }
740
+ /** Whether a shell line pushes: `git push`, `gh pr create`, or `gh pr merge`, anywhere in it. */
741
+ export function isPushCommand(line) {
742
+ return steps(line).some((step) => step.kind !== "commit");
743
+ }
744
+ /**
745
+ * Whether a shell line sends this checkout's commits: a `git push`, or a `gh pr
746
+ * create`, which pushes the branch it opens a pull request for. A line whose
747
+ * only push is `gh pr merge` sends none; that pull request's commits were on
748
+ * the remote before the line ran.
749
+ */
750
+ export function sendsCommits(line) {
751
+ return steps(line).some((step) => step.kind === "push" || step.kind === "create");
752
+ }
753
+ /**
754
+ * git commands that make a commit or move the branch to one: what a check run
755
+ * before the shell line cannot see, because it does not exist yet.
756
+ */
757
+ const COMMIT_MAKING = new Set(["commit", "merge", "cherry-pick", "revert", "am", "rebase", "pull"]);
758
+ /** Flags with which those commands make no commit: they stop, or only pretend. */
759
+ const MAKES_NO_COMMIT = new Set(["--abort", "--quit", "--dry-run"]);
760
+ /** The simple commands a shell line runs, in order, with those inside `bash -c` and the like in place. */
761
+ function commandsInOrder(line, depth = 0) {
762
+ const out = [];
763
+ for (const words of shellCommands(line)) {
764
+ const run = program(words);
765
+ if (run.length === 0)
766
+ continue;
767
+ if (SHELLS.has(basename(run[0])) && depth < 3) {
768
+ const flag = run.findIndex((word, index) => index > 0 && /^-[a-z]*c[a-z]*$/.test(word));
769
+ const script = flag > 0 ? run[flag + 1] : undefined;
770
+ if (script !== undefined) {
771
+ out.push(...commandsInOrder(script, depth + 1));
772
+ continue;
773
+ }
774
+ }
775
+ out.push(run);
776
+ }
777
+ return out;
778
+ }
779
+ /**
780
+ * The first command in the line that makes a commit before it pushes, as
781
+ * `git <subcommand>`, or nothing.
782
+ *
783
+ * A host's PreToolUse hook sees the checkout before the line runs, so in
784
+ * `git commit -am x && git push` the check judges the code as it was before
785
+ * the commit, and the commit the push carries is one it never saw. Only a
786
+ * commit made before the push matters: one made after it is not in what was
787
+ * pushed, and `gh pr merge` merges a pull request's head, not this checkout's.
788
+ */
789
+ export function commitBeforePush(line) {
790
+ let found;
791
+ for (const run of commandsInOrder(line)) {
792
+ const name = basename(run[0]);
793
+ if (name === "gh" && run[1] === "pr" && run[2] === "create")
794
+ return found;
795
+ if (name !== "git")
796
+ continue;
797
+ const subcommand = gitSubcommand(run.slice(1));
798
+ if (subcommand === "push")
799
+ return found;
800
+ if (found === undefined &&
801
+ subcommand !== undefined &&
802
+ COMMIT_MAKING.has(subcommand) &&
803
+ !run.some((word) => MAKES_NO_COMMIT.has(word)))
804
+ found = `git ${subcommand}`;
805
+ }
806
+ return undefined;
807
+ }
808
+ /** `gh pr merge` options that take the next word as their value. */
809
+ const GH_MERGE_VALUE_OPTIONS = new Set([
810
+ "-A",
811
+ "--author-email",
812
+ "-b",
813
+ "--body",
814
+ "-F",
815
+ "--body-file",
816
+ "--match-head-commit",
817
+ "-t",
818
+ "--subject",
819
+ "-R",
820
+ "--repo",
821
+ ]);
822
+ function mergeTarget(args) {
823
+ let selector;
824
+ let repo;
825
+ for (let at = 0; at < args.length; at += 1) {
826
+ const word = args[at];
827
+ if (word === "--") {
828
+ selector ??= args[at + 1];
829
+ break;
830
+ }
831
+ if (word.startsWith("--") && word.includes("=")) {
832
+ if (word.startsWith("--repo="))
833
+ repo = word.slice("--repo=".length);
834
+ continue;
835
+ }
836
+ if (GH_MERGE_VALUE_OPTIONS.has(word)) {
837
+ if (word === "-R" || word === "--repo")
838
+ repo = args[at + 1];
839
+ at += 1;
840
+ continue;
841
+ }
842
+ if (word.startsWith("-"))
843
+ continue;
844
+ selector ??= word;
845
+ }
846
+ return { ...(selector ? { selector } : {}), ...(repo ? { repo } : {}) };
847
+ }
848
+ /** Every `gh pr merge` in a shell line, with the pull request and repository it names. */
849
+ export function mergeTargets(line) {
850
+ return steps(line)
851
+ .filter((step) => step.kind === "merge")
852
+ .map((step) => mergeTarget(step.args));
853
+ }
854
+ /**
855
+ * What the host is told. In report mode the lines reach the agent as context
856
+ * and the push goes ahead; a block is exit 2 with the reason, which both hosts
857
+ * treat as a refusal of that one command. Claude Code also gets the reason as
858
+ * `permissionDecision: "deny"`, which it prefers to stderr; Codex is given the
859
+ * stderr form its documentation names. After the command ran (PostToolUse)
860
+ * there is nothing left to hold, so the lines are only ever context, named for
861
+ * the event that asked.
862
+ */
863
+ export function hookResponse(host, outcome) {
864
+ const text = outcome.lines.join("\n");
865
+ const event = outcome.event ?? "PreToolUse";
866
+ if (outcome.block && event === "PreToolUse") {
867
+ if (host === "claude")
868
+ return {
869
+ stdout: `${JSON.stringify({
870
+ hookSpecificOutput: {
871
+ hookEventName: "PreToolUse",
872
+ permissionDecision: "deny",
873
+ permissionDecisionReason: text,
874
+ },
875
+ })}\n`,
876
+ stderr: `${text}\n`,
877
+ exitCode: 2,
878
+ };
879
+ return { stdout: "", stderr: `${text}\n`, exitCode: 2 };
880
+ }
881
+ if (outcome.lines.length === 0)
882
+ return { stdout: "", stderr: "", exitCode: 0 };
883
+ if (host === "git")
884
+ return { stdout: `${text}\n`, stderr: "", exitCode: 0 };
885
+ return {
886
+ stdout: `${JSON.stringify({
887
+ hookSpecificOutput: { hookEventName: event, additionalContext: text },
888
+ })}\n`,
889
+ stderr: "",
890
+ exitCode: 0,
891
+ };
892
+ }
893
+ /** The status line both hosts show while the hook runs, and the mark of the entry this command owns. */
894
+ export const JUDGE_HOOK_MARKER = "Balladeer judge";
895
+ export const JUDGE_HOOK_TIMEOUT_SECONDS = 900;
896
+ /**
897
+ * The most a judge budget may be when the command runs from a host's hook.
898
+ *
899
+ * Claude Code documents that a hook reaching its own timeout lets the command
900
+ * run, and Codex documents no rule; so a budget longer than the hook's timeout
901
+ * would let a push through with no verdict and no line saying so, which is the
902
+ * one thing block mode exists to prevent. Login checks and the risk ranking can
903
+ * spend about ninety seconds before the budget starts, so the cap sits well
904
+ * under the hook timeout. The hook canary of 29 September 2026 found the gap.
905
+ */
906
+ export const HOOK_BUDGET_CAP_SECONDS = 600;
907
+ export const GIT_HOOK_MARKER = "# Installed by: balladeer judge --install-hook git";
908
+ /** The budget a run may spend: as configured, except from a hook, where the host's timeout rules. */
909
+ export function effectiveBudgetSeconds(configured, fromHook) {
910
+ return fromHook ? Math.min(configured, HOOK_BUDGET_CAP_SECONDS) : configured;
911
+ }
912
+ export function judgeHookCommand(host) {
913
+ return `balladeer judge --hook ${host}`;
914
+ }
915
+ function expectedEntry(host) {
916
+ return {
917
+ matcher: "Bash",
918
+ hooks: [
919
+ {
920
+ type: "command",
921
+ command: judgeHookCommand(host),
922
+ timeout: JUDGE_HOOK_TIMEOUT_SECONDS,
923
+ statusMessage: JUDGE_HOOK_MARKER,
924
+ },
925
+ ],
926
+ };
927
+ }
928
+ export const GIT_PRE_PUSH_SCRIPT = [
929
+ "#!/bin/sh",
930
+ GIT_HOOK_MARKER,
931
+ "# It judges the promises this push could break, on this machine's own coding agent login.",
932
+ "# In block mode it stops a push whose break was reproduced both ways. Delete this file to remove it.",
933
+ "command -v balladeer >/dev/null 2>&1 || exit 0",
934
+ "balladeer judge --hook git",
935
+ "",
936
+ ].join("\n");
937
+ function readOwnFile(path) {
938
+ if (!existsSync(path)) {
939
+ try {
940
+ lstatSync(path);
941
+ }
942
+ catch {
943
+ return undefined;
944
+ }
945
+ throw new Error(`${path} is a link to nothing`);
946
+ }
947
+ const stat = lstatSync(path);
948
+ if (!stat.isFile() || stat.isSymbolicLink())
949
+ throw new Error(`${path} is not a regular file`);
950
+ if (stat.size > 1024 * 1024)
951
+ throw new Error(`${path} is larger than this command edits`);
952
+ return readFileSync(path, "utf8");
953
+ }
954
+ function writeAtomically(path, content, mode) {
955
+ mkdirSync(dirname(path), { recursive: true });
956
+ const temporary = join(dirname(path), `.balladeer-judge-${randomBytes(6).toString("hex")}.tmp`);
957
+ writeFileSync(temporary, content, { flag: "wx", mode });
958
+ try {
959
+ renameSync(temporary, path);
960
+ }
961
+ catch (error) {
962
+ try {
963
+ unlinkSync(temporary);
964
+ }
965
+ catch {
966
+ /* Already gone. */
967
+ }
968
+ throw error;
969
+ }
970
+ }
971
+ /** The hook file the installer writes for a host, relative to the repository root. */
972
+ export function judgeHookFile(host) {
973
+ return host === "claude" ? ".claude/settings.json" : ".codex/hooks.json";
974
+ }
975
+ /** Whether one row of a hook event's list is an entry this command owns: a handler carries the marker. */
976
+ function ownsRow(row) {
977
+ const handlers = row?.hooks;
978
+ return Array.isArray(handlers)
979
+ ? handlers.some((handler) => handler?.statusMessage === JUDGE_HOOK_MARKER)
980
+ : false;
981
+ }
982
+ /**
983
+ * Whether the hook file the installer writes has this command's entry for one
984
+ * event. It reads the file rather than guessing, so a checkout installed by an
985
+ * earlier release, which wrote only the PreToolUse entry, is told apart from a
986
+ * current one. Anything unreadable counts as no entry.
987
+ */
988
+ export function hasJudgeEntry(root, host, event) {
989
+ try {
990
+ const text = readOwnFile(join(root, judgeHookFile(host)));
991
+ if (text === undefined)
992
+ return false;
993
+ const rows = JSON.parse(text)?.hooks?.[event];
994
+ return Array.isArray(rows) && rows.some(ownsRow);
995
+ }
996
+ catch {
997
+ return false;
998
+ }
999
+ }
1000
+ /**
1001
+ * Whether this checkout has the push check's own project entry for a host,
1002
+ * under either event. Where it does, that entry owns the check in this
1003
+ * checkout and the one setup writes at the host's user scope stands aside, so
1004
+ * a push is judged once. Either event counts: a checkout an earlier release
1005
+ * installed has only the entry before the push, and it keeps judging there.
1006
+ */
1007
+ export function hasProjectJudgeHook(root, host) {
1008
+ return JUDGE_HOOK_EVENTS.some((event) => hasJudgeEntry(root, host, event));
1009
+ }
1010
+ /**
1011
+ * The checkout that holds a folder, found by walking up to its `.git` entry (a
1012
+ * directory, or a file in a worktree). No process is started, so a folder that
1013
+ * is not in a checkout at all is known in well under a millisecond.
1014
+ */
1015
+ export function checkoutRoot(start) {
1016
+ let directory = resolve(start);
1017
+ for (;;) {
1018
+ if (existsSync(join(directory, ".git")))
1019
+ return directory;
1020
+ const parent = dirname(directory);
1021
+ if (parent === directory)
1022
+ return undefined;
1023
+ directory = parent;
1024
+ }
1025
+ }
1026
+ /**
1027
+ * The push check's switch for this laptop, in Balladeer's own config home.
1028
+ * Absent means on. Written only by `balladeer judge --push-check off`, and
1029
+ * read by the user-scope entry on each push, so turning it off takes effect in
1030
+ * sessions that are already open.
1031
+ */
1032
+ export const PUSH_CHECK_SETTING_FILE = "push-check.json";
1033
+ export function pushCheckSettingPath(environment) {
1034
+ return join(configHome(environment), PUSH_CHECK_SETTING_FILE);
1035
+ }
1036
+ /** True only when this laptop's switch says off; anything unreadable leaves it on. */
1037
+ export function pushCheckOff(environment) {
1038
+ try {
1039
+ const parsed = JSON.parse(readFileSync(pushCheckSettingPath(environment), "utf8"));
1040
+ return parsed?.on === false;
1041
+ }
1042
+ catch {
1043
+ return false;
1044
+ }
1045
+ }
1046
+ /** Turn the user-scope push check off or back on for this laptop. */
1047
+ export function setPushCheck(environment, on) {
1048
+ const path = pushCheckSettingPath(environment);
1049
+ if (on) {
1050
+ rmSync(path, { force: true });
1051
+ return;
1052
+ }
1053
+ mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
1054
+ writeFileSync(path, `${JSON.stringify({ on: false })}\n`, { mode: 0o600 });
1055
+ }
1056
+ /**
1057
+ * The PreToolUse and PostToolUse entries in a host's JSON hook file, each
1058
+ * added once. Both run the same command; the judge reads which event called it
1059
+ * from the host's input (`hook_event_name`).
1060
+ *
1061
+ * The entry this command owns is the one whose handler carries the marker. A
1062
+ * second run finds both and changes nothing, byte for byte; a file written by
1063
+ * an earlier release, with only the PreToolUse entry, gains the PostToolUse
1064
+ * one. An owned entry that somebody edited is left alone and reported, and
1065
+ * nothing in the file is written, the same rule the guidance installer
1066
+ * follows: it is theirs now, and silently putting it back would undo a
1067
+ * decision somebody made on purpose.
1068
+ */
1069
+ function installJsonHook(root, host) {
1070
+ const relativePath = judgeHookFile(host);
1071
+ const path = join(root, relativePath);
1072
+ try {
1073
+ const before = readOwnFile(path);
1074
+ const document = before === undefined ? {} : JSON.parse(before);
1075
+ if (document === null || typeof document !== "object" || Array.isArray(document))
1076
+ return {
1077
+ target: host,
1078
+ path: relativePath,
1079
+ status: "refused",
1080
+ reason: `${relativePath} is not a JSON object`,
1081
+ };
1082
+ const settings = document;
1083
+ const hooks = settings.hooks === undefined ? {} : settings.hooks;
1084
+ if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks))
1085
+ return {
1086
+ target: host,
1087
+ path: relativePath,
1088
+ status: "refused",
1089
+ reason: `hooks in ${relativePath} is not an object`,
1090
+ };
1091
+ const events = hooks;
1092
+ const expected = expectedEntry(host);
1093
+ const missing = [];
1094
+ for (const event of JUDGE_HOOK_EVENTS) {
1095
+ const rows = events[event] === undefined ? [] : events[event];
1096
+ if (!Array.isArray(rows))
1097
+ return {
1098
+ target: host,
1099
+ path: relativePath,
1100
+ status: "refused",
1101
+ reason: `hooks.${event} in ${relativePath} is not a list`,
1102
+ };
1103
+ const own = rows.filter(ownsRow);
1104
+ if (own.length === 1 && JSON.stringify(own[0]) === JSON.stringify(expected))
1105
+ continue;
1106
+ if (own.length > 0)
1107
+ return {
1108
+ target: host,
1109
+ path: relativePath,
1110
+ status: "refused",
1111
+ reason: `${relativePath} already has a Balladeer judge entry under ${event} that was edited by hand, so the file was left as it is. Remove it to have this command write the current ones.`,
1112
+ };
1113
+ missing.push(event);
1114
+ }
1115
+ if (missing.length === 0)
1116
+ return { target: host, path: relativePath, status: "unchanged" };
1117
+ for (const event of missing)
1118
+ events[event] = [...(events[event] ?? []), expected];
1119
+ settings.hooks = events;
1120
+ const mode = before === undefined ? 0o644 : lstatSync(path).mode & 0o777;
1121
+ writeAtomically(path, `${JSON.stringify(settings, null, 2)}\n`, mode);
1122
+ return { target: host, path: relativePath, status: "written" };
1123
+ }
1124
+ catch (error) {
1125
+ return {
1126
+ target: host,
1127
+ path: relativePath,
1128
+ status: "refused",
1129
+ reason: error instanceof SyntaxError
1130
+ ? `${relativePath} is not valid JSON`
1131
+ : error instanceof Error
1132
+ ? error.message
1133
+ : String(error),
1134
+ };
1135
+ }
1136
+ }
1137
+ /** Where git looks for hooks in this checkout, which is not `.git/hooks` in a worktree. */
1138
+ export function gitHooksDirectory(root) {
1139
+ try {
1140
+ const answer = execFileSync("git", ["-C", root, "rev-parse", "--git-path", "hooks"], {
1141
+ encoding: "utf8",
1142
+ stdio: ["ignore", "pipe", "ignore"],
1143
+ timeout: 5000,
1144
+ }).trim();
1145
+ if (answer)
1146
+ return isAbsolute(answer) ? answer : join(root, answer);
1147
+ }
1148
+ catch {
1149
+ /* Fall through to the ordinary place. */
1150
+ }
1151
+ return join(root, ".git", "hooks");
1152
+ }
1153
+ function installGitHook(root) {
1154
+ const directory = gitHooksDirectory(root);
1155
+ const path = join(directory, "pre-push");
1156
+ const shown = path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
1157
+ try {
1158
+ const before = readOwnFile(path);
1159
+ if (before === GIT_PRE_PUSH_SCRIPT)
1160
+ return { target: "git", path: shown, status: "unchanged" };
1161
+ if (before !== undefined)
1162
+ return {
1163
+ target: "git",
1164
+ path: shown,
1165
+ status: "refused",
1166
+ reason: before.includes(GIT_HOOK_MARKER)
1167
+ ? `${shown} was installed by this command and edited since, so it was left as it is.`
1168
+ : `${shown} already exists and is not Balladeer's, so nothing was written. Add this line to it yourself: balladeer judge --hook git`,
1169
+ };
1170
+ writeAtomically(path, GIT_PRE_PUSH_SCRIPT, 0o755);
1171
+ chmodSync(path, 0o755);
1172
+ return { target: "git", path: shown, status: "written" };
1173
+ }
1174
+ catch (error) {
1175
+ return {
1176
+ target: "git",
1177
+ path: shown,
1178
+ status: "refused",
1179
+ reason: error instanceof Error ? error.message : String(error),
1180
+ };
1181
+ }
1182
+ }
1183
+ /** Install the judge hook for one host. Running it twice changes nothing the second time. */
1184
+ export function installJudgeHook(root, target) {
1185
+ return target === "git" ? installGitHook(root) : installJsonHook(root, target);
1186
+ }
1187
+ const SHA = /^[0-9a-f]{40}$/;
1188
+ /**
1189
+ * Whether a commit is on a remote now: reachable from a remote-tracking ref,
1190
+ * or else the tip of a branch some remote reports.
1191
+ *
1192
+ * `git push`, `git push origin HEAD:branch` and the push `gh pr create` makes
1193
+ * all move the remote-tracking ref of what they pushed, so the first check is
1194
+ * local and immediate. The second is there because a push can land without
1195
+ * that ref moving: Codex's workspace sandbox keeps `.git` read-only, so its
1196
+ * pushes reach the remote and then fail to update `refs/remotes/...` (hook
1197
+ * canary, 29 September 2026). Asking each remote for its branch tips settles
1198
+ * it without fetching anything, and a push that failed leaves its commit on
1199
+ * neither.
1200
+ */
1201
+ export async function pushLanded(root, sha) {
1202
+ const local = await runCommand("git", [
1203
+ "-C",
1204
+ root,
1205
+ "for-each-ref",
1206
+ "--contains",
1207
+ sha,
1208
+ "--count=1",
1209
+ "--format=%(refname)",
1210
+ "refs/remotes",
1211
+ ], { timeoutMs: 30_000 });
1212
+ if (local.ok && local.stdout.trim() !== "")
1213
+ return true;
1214
+ const remotes = await runCommand("git", ["-C", root, "remote"]);
1215
+ if (!remotes.ok)
1216
+ return false;
1217
+ const names = remotes.stdout
1218
+ .split("\n")
1219
+ .map((name) => name.trim())
1220
+ .filter(Boolean);
1221
+ for (const remote of names.slice(0, 5)) {
1222
+ const listed = await runCommand("git", ["-C", root, "ls-remote", "--heads", remote], {
1223
+ timeoutMs: 20_000,
1224
+ env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
1225
+ });
1226
+ if (listed.ok && listed.stdout.split("\n").some((line) => line.startsWith(`${sha}\t`)))
1227
+ return true;
1228
+ }
1229
+ return false;
1230
+ }
1231
+ /**
1232
+ * Where the remote default branch stood before this push, when this push is
1233
+ * what moved it to `head`; otherwise nothing, and the ordinary fork-point rule
1234
+ * applies.
1235
+ *
1236
+ * Judged after a push straight to the default branch, the fork point with that
1237
+ * branch's remote-tracking ref is `head` itself, so the change would shrink to
1238
+ * its last commit. git records the push in the ref's reflog ("update by
1239
+ * push"), and the entry before it is where the branch stood.
1240
+ */
1241
+ export async function baseBeforePush(root, head) {
1242
+ const names = [];
1243
+ const remoteHead = await runCommand("git", [
1244
+ "-C",
1245
+ root,
1246
+ "rev-parse",
1247
+ "--abbrev-ref",
1248
+ "origin/HEAD",
1249
+ ]);
1250
+ const named = remoteHead.stdout.trim();
1251
+ if (remoteHead.ok && named && named !== "origin/HEAD")
1252
+ names.push(named);
1253
+ names.push("origin/main", "origin/master");
1254
+ for (const name of new Set(names)) {
1255
+ if ((await resolveCommit(root, name)) !== head)
1256
+ continue;
1257
+ const log = await runCommand("git", [
1258
+ "-C",
1259
+ root,
1260
+ "reflog",
1261
+ "show",
1262
+ "--format=%H %gs",
1263
+ "-n",
1264
+ "2",
1265
+ name,
1266
+ ]);
1267
+ const [latest, earlier] = log.ok ? log.stdout.trim().split("\n") : [];
1268
+ if (!latest?.startsWith(`${head} update by push`) || earlier === undefined)
1269
+ return undefined;
1270
+ const previous = earlier.split(" ")[0] ?? "";
1271
+ if (!SHA.test(previous) || previous === head)
1272
+ return undefined;
1273
+ const fork = await runCommand("git", ["-C", root, "merge-base", head, previous]);
1274
+ const sha = fork.stdout.trim();
1275
+ return fork.ok && SHA.test(sha) && sha !== head ? sha : undefined;
1276
+ }
1277
+ return undefined;
1278
+ }