yadflow 4.9.0 → 4.11.0

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 (155) hide show
  1. package/CHANGELOG.md +184 -0
  2. package/README.md +15 -5
  3. package/bin/commands.mjs +11 -1
  4. package/bin/yad.mjs +203 -14
  5. package/cli/agent-guard-worker.mjs +13 -0
  6. package/cli/agent-guard.mjs +1797 -73
  7. package/cli/agent-rules.mjs +64 -5
  8. package/cli/argv-flags.mjs +2 -2
  9. package/cli/brain/vendor/LICENSE-graphology-library.txt +21 -0
  10. package/cli/brain/vendor/LICENSE-graphology.txt +21 -0
  11. package/cli/brain/vendor/LICENSE-sigma.txt +12 -0
  12. package/cli/brain/vendor/graphology-library.min.js +2 -0
  13. package/cli/brain/vendor/graphology.umd.min.js +2 -0
  14. package/cli/brain/vendor/sigma.min.js +1369 -0
  15. package/cli/brain/view/app.js +382 -0
  16. package/cli/brain/view/index.html +63 -0
  17. package/cli/brain/view/live.css +228 -0
  18. package/cli/brain/view/live.html +110 -0
  19. package/cli/brain/view/live.js +884 -0
  20. package/cli/brain/view/style.css +141 -0
  21. package/cli/brain-about.mjs +206 -0
  22. package/cli/brain-activity.mjs +285 -0
  23. package/cli/brain-skills.mjs +118 -0
  24. package/cli/brain-vendor.mjs +71 -0
  25. package/cli/brain-view.mjs +344 -0
  26. package/cli/brain.mjs +810 -0
  27. package/cli/ci-check.mjs +48 -4
  28. package/cli/codeowners-command.mjs +72 -6
  29. package/cli/commit.mjs +17 -3
  30. package/cli/docs.mjs +2 -0
  31. package/cli/doctor.mjs +151 -25
  32. package/cli/epic-state.mjs +186 -4
  33. package/cli/epic.mjs +26 -10
  34. package/cli/errors.mjs +2 -1
  35. package/cli/find-product.mjs +69 -15
  36. package/cli/fold.mjs +31 -6
  37. package/cli/foundation-publish.mjs +256 -0
  38. package/cli/gate.mjs +29 -3
  39. package/cli/git-read.mjs +38 -0
  40. package/cli/guard-stream.mjs +409 -0
  41. package/cli/guide.mjs +3 -1
  42. package/cli/hook.mjs +102 -9
  43. package/cli/issue-links.mjs +61 -0
  44. package/cli/issues-act.mjs +371 -0
  45. package/cli/issues-write.mjs +441 -0
  46. package/cli/issues.mjs +513 -0
  47. package/cli/lib.mjs +37 -2
  48. package/cli/lifecycle.mjs +7 -0
  49. package/cli/local-page.mjs +138 -0
  50. package/cli/machine.mjs +1 -1
  51. package/cli/manifest.mjs +59 -3
  52. package/cli/map/view/app.js +712 -0
  53. package/cli/map/view/index.html +50 -0
  54. package/cli/map/view/style.css +142 -0
  55. package/cli/map-view.mjs +186 -0
  56. package/cli/map.mjs +637 -0
  57. package/cli/members.mjs +9 -15
  58. package/cli/next.mjs +1 -1
  59. package/cli/openpr.mjs +26 -6
  60. package/cli/plan.mjs +127 -0
  61. package/cli/platform.mjs +159 -4
  62. package/cli/product-index.mjs +1 -1
  63. package/cli/protection.mjs +53 -3
  64. package/cli/reconcile.mjs +9 -3
  65. package/cli/report.mjs +9 -3
  66. package/cli/reports-dir.mjs +391 -0
  67. package/cli/reports.mjs +65 -0
  68. package/cli/run-checks.mjs +15 -4
  69. package/cli/scan.mjs +314 -0
  70. package/cli/setup.mjs +42 -8
  71. package/cli/standup.mjs +120 -78
  72. package/cli/status.mjs +6 -5
  73. package/cli/story-frames.mjs +17 -6
  74. package/cli/test-agents-file.mjs +985 -12
  75. package/cli/test-brain-activity.mjs +753 -0
  76. package/cli/test-brain-view.mjs +381 -0
  77. package/cli/test-brain.mjs +795 -0
  78. package/cli/test-build.mjs +25 -0
  79. package/cli/test-ci-check.mjs +469 -10
  80. package/cli/test-guide.mjs +218 -0
  81. package/cli/test-machine.mjs +59 -0
  82. package/cli/test-map.mjs +615 -0
  83. package/cli/test-node.mjs +15 -0
  84. package/cli/test-reports.mjs +382 -0
  85. package/cli/test-run-checks.mjs +21 -0
  86. package/cli/test-setup-agent.mjs +14 -0
  87. package/cli/test-story-frames.mjs +74 -4
  88. package/cli/test-worktree.mjs +24 -3
  89. package/cli/toolbox-connect.mjs +259 -0
  90. package/cli/toolbox.mjs +187 -12
  91. package/cli/update-commit.mjs +101 -9
  92. package/cli/usage.mjs +8 -4
  93. package/package.json +12 -4
  94. package/skills/sdlc/config.yaml +1 -1
  95. package/skills/sdlc/module-help.csv +3 -1
  96. package/skills/yad-analysis/SKILL.md +4 -0
  97. package/skills/yad-architecture/SKILL.md +22 -4
  98. package/skills/yad-backfill/SKILL.md +4 -0
  99. package/skills/yad-change/SKILL.md +7 -1
  100. package/skills/yad-change/references/triage.md +2 -0
  101. package/skills/yad-checks/SKILL.md +15 -7
  102. package/skills/yad-checks/references/check-gates.md +70 -35
  103. package/skills/yad-checks/templates/checks/build-test-lint.sh +7 -0
  104. package/skills/yad-checks/templates/checks/install-deps.sh +6 -0
  105. package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
  106. package/skills/yad-checks/templates/checks/package-manager.sh +42 -0
  107. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  108. package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
  109. package/skills/yad-checks/templates/github/yad-checks.yml +358 -69
  110. package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
  111. package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
  112. package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
  113. package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
  114. package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
  115. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +80 -20
  116. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
  117. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
  118. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
  119. package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
  120. package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
  121. package/skills/yad-checks/templates/hooks/yad-activity.mjs +238 -0
  122. package/skills/yad-commit/SKILL.md +3 -1
  123. package/skills/yad-connect-design/SKILL.md +42 -10
  124. package/skills/yad-connect-design/references/design-context.md +35 -5
  125. package/skills/yad-connect-design/references/design-registry.md +3 -3
  126. package/skills/yad-connect-learning/SKILL.md +12 -2
  127. package/skills/yad-connect-repos/SKILL.md +18 -0
  128. package/skills/yad-connect-testing/SKILL.md +22 -5
  129. package/skills/yad-connect-testing/references/testing-context.md +1 -1
  130. package/skills/yad-discovery/SKILL.md +11 -0
  131. package/skills/yad-discovery/references/foundation-schema.md +11 -0
  132. package/skills/yad-docs/templates/app/package-lock.json +18 -10
  133. package/skills/yad-docs/templates/app/package.json +6 -1
  134. package/skills/yad-epic/SKILL.md +7 -0
  135. package/skills/yad-epic/references/state-schema.md +50 -1
  136. package/skills/yad-guide/SKILL.md +8 -4
  137. package/skills/yad-implement/SKILL.md +117 -4
  138. package/skills/yad-implement/references/implement-conventions.md +2 -1
  139. package/skills/yad-issues/SKILL.md +54 -0
  140. package/skills/yad-learn/SKILL.md +4 -0
  141. package/skills/yad-open-pr/SKILL.md +6 -0
  142. package/skills/yad-pr-template/SKILL.md +2 -1
  143. package/skills/yad-pr-template/templates/checks/pr-template.sh +8 -4
  144. package/skills/yad-pr-template/templates/checks/pr-title.sh +42 -6
  145. package/skills/yad-product-bridge/references/bridge.md +28 -0
  146. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
  147. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
  148. package/skills/yad-run/SKILL.md +5 -0
  149. package/skills/yad-scan/SKILL.md +51 -0
  150. package/skills/yad-spec/SKILL.md +32 -2
  151. package/skills/yad-stories/SKILL.md +22 -4
  152. package/skills/yad-stories/references/story-schema.md +1 -1
  153. package/skills/yad-test-cases/SKILL.md +18 -2
  154. package/skills/yad-ui/SKILL.md +43 -8
  155. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
@@ -12,16 +12,69 @@
12
12
  // The refusal says what to do instead: ask the person to run it themselves (`! <command>` in Claude Code).
13
13
  //
14
14
  // A SPEED BUMP, NOT PROOF. It reads the command line the agent sends, so a command hidden in a script, an
15
- // alias or `eval` is not seen; Codex has no hooks at all. What proves an approval is the platform (and CI's
15
+ // alias, or an `eval` of a value known only when the line runs is not seen; Codex has no hooks at all. What proves an approval is the platform (and CI's
16
16
  // ledger guard). The rules in AGENTS.md are what the agent follows; this catches the plain mistake.
17
17
  //
18
18
  // FAIL-OPEN, like the ledger guard: a payload it cannot read, or no command in it, is allowed.
19
- import { classify } from './agent-rules.mjs';
19
+ import fs from 'node:fs';
20
+ import path from 'node:path';
21
+ import { streamGuard, zshDiffers } from './guard-stream.mjs';
22
+ import { fileURLToPath } from 'node:url';
23
+ import { classify, readAllowList } from './agent-rules.mjs';
20
24
  import { VALUE_FLAGS, LIST_FLAGS } from './argv-flags.mjs';
21
25
 
22
26
  // A heredoc's `<<` and its end word: bare (`EOF`), quoted (`'EOF'`, `"EOF"`, `E"OF"`) or escaped (`\EOF`). Any
23
- // quote or `\` in the word makes the text plain text, as bash reads it: nothing in it runs.
24
- const HEREDOC = /^<<(-?)[ \t]*((?:\\.|'[^'\n]*'|"[^"\n]*"|[A-Za-z0-9_.-])+)/;
27
+ // quote or `\` in the word makes the text plain text, as bash reads it: nothing in it runs. The word is every
28
+ // character the shell reads as one word (#492): anything but a space, a tab, a newline or `; & | ( ) < >` — so
29
+ // `EOF#`, `EOF+` and a CR (`EOF\r`, from a line written with CRLF) are part of it. Sticky, matched in place
30
+ // (`heredocAt`): slicing the rest of the line for each `<<` made a long line take quadratic time.
31
+ const HEREDOC = /<<(-?)[ \t]*((?:\\.|'[^'\n]*'|"[^"\n]*"|[^ \t\n;&|()<>'"\\])+)/y;
32
+ // An end word holding `$` or a backtick is read as no heredoc (#492 review): inside `bash -c "…"` the outer shell
33
+ // expands it first (`EOF$x` becomes `EOF`), so where it ends cannot be known here, and the lines after it are
34
+ // judged as commands instead.
35
+ // It is still a redirect (`<<"E$x" gh pr merge 1` runs gh), so the `<<word` is read past either way: only no
36
+ // heredoc is recorded for it (`expands`).
37
+ const heredocAt = (line, i) => { HEREDOC.lastIndex = i; const m = HEREDOC.exec(line); if (m) m.expands = /[$`]/.test(m[2]); return m; };
38
+
39
+ // A `$'…'` string from `from` (just past `$'`): its text with the escapes bash applies, and the index of its closing
40
+ // quote (or the end). `\'` is a quote in it, so it does not end the string.
41
+ const ANSI = { n: '\n', t: '\t', r: '\r', a: '\x07', b: '\b', e: '\x1b', E: '\x1b', f: '\f', v: '\v', '\\': '\\', "'": "'", '"': '"', '?': '?' };
42
+ function ansiC(line, from) {
43
+ let text = '';
44
+ let i = from;
45
+ for (; i < line.length && line[i] !== "'"; i++) {
46
+ if (line[i] !== '\\' || i + 1 >= line.length) { text += line[i]; continue; }
47
+ const c = line[i + 1];
48
+ let m;
49
+ if (c in ANSI) { text += ANSI[c]; i++; } else if ((m = /^x([0-9A-Fa-f]{1,2})/.exec(line.slice(i + 1, i + 4)))) { text += String.fromCharCode(parseInt(m[1], 16)); i += m[0].length; } else if ((m = /^[0-7]{1,3}/.exec(line.slice(i + 1, i + 4)))) { text += String.fromCharCode(parseInt(m[0], 8)); i += m[0].length; } else if ((m = /^u([0-9A-Fa-f]{1,4})/.exec(line.slice(i + 1, i + 6)))) { text += String.fromCharCode(parseInt(m[1], 16)); i += m[0].length; } else { text += `\\${c}`; i++; }
50
+ }
51
+ return { text, end: i };
52
+ }
53
+
54
+ // Where each line of `text` starts, by its exact text and by its text with leading tabs removed (`<<-`), so a
55
+ // heredoc's end line is found by a binary search, not by scanning on: a line of many heredocs with different
56
+ // end words is read in near-linear time (#492). `endAfter` gives the index just past the first line at or
57
+ // after `at` that reads `word`, or -1.
58
+ function lineIndex(text) {
59
+ const exact = new Map(), stripped = new Map();
60
+ for (let at = 0; at <= text.length;) {
61
+ const eol = text.indexOf('\n', at);
62
+ const t = text.slice(at, eol < 0 ? text.length : eol);
63
+ for (const [map, k] of [[exact, t], [stripped, t.replace(/^\t+/, '')]]) { const list = map.get(k); if (list) list.push(at); else map.set(k, [at]); }
64
+ at = eol < 0 ? text.length + 1 : eol + 1;
65
+ }
66
+ return {
67
+ endAfter(word, tabs, at) {
68
+ const list = (tabs ? stripped : exact).get(word);
69
+ if (!list) return -1;
70
+ let lo = 0, hi = list.length;
71
+ while (lo < hi) { const mid = (lo + hi) >> 1; if (list[mid] < at) lo = mid + 1; else hi = mid; }
72
+ if (lo === list.length) return -1;
73
+ const eol = text.indexOf('\n', list[lo]);
74
+ return eol < 0 ? text.length + 1 : eol + 1;
75
+ },
76
+ };
77
+ }
25
78
  const heredocOf = (m) => ({ word: m[2].replace(/\\(.)|['"]/g, '$1'), tabs: m[1] === '-', quoted: /['"\\]/.test(m[2]) });
26
79
 
27
80
  // One command line split into its simple commands: on `;`, `&`, `&&`, `||`, `|` and newlines, outside
@@ -33,43 +86,192 @@ const heredocOf = (m) => ({ word: m[2].replace(/\\(.)|['"]/g, '$1'), tabs: m[1]
33
86
  // (`$(…)` or backticks, outside single quotes) stays inside its word, and its text is also kept in
34
87
  // `parts.subs`, so the caller judges the command it runs: `r=$(yad gate approve …)` runs an approval. Quotes
35
88
  // inside it are its own (`"$(cat <<'EOF' … EOF)"` holds any `"` in the heredoc's text).
36
- export function shellParts(line) {
89
+ // `mode` picks the reading where bash and zsh decide by context the reader does not track (#492): `literalExpanding`
90
+ // reads an end word holding `$` or a backtick as a heredoc ending at that literal word (else: no heredoc), and
91
+ // `hashAfterParen` reads a `#` right after `(` or `)` as a comment (else: text). agentGuardDecision judges both.
92
+ // Which shell's redirect reading this is (#518): 'bash' or 'zsh', or '' for main's. Its own field, never the `$(…)`
93
+ // end rule (`mode.ends`): judgeReadings crosses the two, so main's redirect reading runs under every end rule.
94
+ const shellOf = (mode) => mode?.redir ?? '';
95
+ export function shellParts(rawLine, mode = {}) {
96
+ // The private-use characters that shield quoted braces (below) cannot come from the line itself: a typed one
97
+ // would turn into a real `{` when a carried command is re-read (`bash -c "gh pr {merge,\uE000} 5"`).
98
+ const line = rawLine.replace(/[\uE000-\uE002]/g, '\uFFFD');
37
99
  const parts = [];
38
- // Not enumerable: `parts` reads as the plain list of parts it always was.
100
+ // Not enumerable: `parts` reads as the plain list of parts it always was. `bodies` and `herestrings` (#495) are
101
+ // the text a part's heredocs and here-strings feed it, by part index: a shell reading them runs them.
39
102
  Object.defineProperty(parts, 'subs', { value: [] });
103
+ Object.defineProperty(parts, 'bodies', { value: [] });
104
+ Object.defineProperty(parts, 'herestrings', { value: [] });
40
105
  let words = [];
41
106
  let word = '';
42
107
  let inWord = false;
43
108
  let quote = null;
44
109
  const heredocs = [];
45
- const endWord = () => { if (inWord) words.push(word); word = ''; inWord = false; };
46
- const endPart = () => { endWord(); if (words.length) parts.push(words); words = []; };
110
+ // A redirect's target is not a word of the command (#495): `gh >x pr merge 5` runs `gh pr merge 5`.
111
+ let dropWord = false;
112
+ let hereString = false;
113
+ // Which words hold an unquoted `{` (#495): only those are brace-expanded, as the shell does — quoted JSON is not.
114
+ Object.defineProperty(parts, 'braced', { value: [] });
115
+ // Which parts read the previous part's output through a pipe (`|`, `|&`), by index.
116
+ Object.defineProperty(parts, 'piped', { value: new Set() });
117
+ // Words whose backslashes in double quotes the shell keeps (#498), by part: their kept spelling.
118
+ Object.defineProperty(parts, 'posix', { value: [] });
119
+ let partPosix = null;
120
+ // Text that reaches a shell (#498, rows 1, 2, 8), by part: `procsubs` (a `<(…)`, `>(…)` or zsh `=(…)`, with the
121
+ // words before it and its inner parts), `subst` (each word's `$(…)` and backtick spans, for the words their
122
+ // printed text makes), `writes` (`>`, `>>` targets) and `reads` (`<` targets).
123
+ Object.defineProperty(parts, 'procsubs', { value: [] });
124
+ Object.defineProperty(parts, 'subst', { value: [] });
125
+ Object.defineProperty(parts, 'writes', { value: [] });
126
+ Object.defineProperty(parts, 'reads', { value: [] });
127
+ Object.defineProperty(parts, 'pipedWrites', { value: [] });
128
+ Object.defineProperty(parts, 'groups', { value: [] });
129
+ const braceGroups = [];
130
+ let closedGroup = null;
131
+ let partSubst = null;
132
+ const wordSubs = [];
133
+ let partWrites = null;
134
+ let partReads = null;
135
+ // The redirect whose target is the next word: `{op, fd}`, and the one before it when that one's target is
136
+ // still to come (`bash < <(…)`: the process substitution is the target of a `<`).
137
+ let redirect = null;
138
+ let redirectBefore = null;
139
+ // One entry per open `(`: `{proc, cases}`, `proc` set for a process substitution; `cases` counts the `case`
140
+ // commands open inside it, whose pattern `)` closes nothing (#498 review: `bash <(case x in x) …;; esac)`).
141
+ const parens = [];
142
+ // The process substitution just closed, while the command it belongs to goes on (`bash < <(a) < <(b)`).
143
+ let afterProc = null;
144
+ const wordKeep = [];
145
+ let orAt = -1;
146
+ let realMarks = null;
147
+ let wordBraced = false;
148
+ // A word with no quote or escape in it: only such a `case` or `esac` is the reserved word.
149
+ let wordPlain = true;
150
+ // The word after a bare `>&` (#498 review): `>&f` and `>& f` write the file f, as `&>f` does. The word stays a
151
+ // word of the command, as main reads it.
152
+ let afterDup = null;
153
+ let partBraced = null;
154
+ const endWord = () => {
155
+ if (inWord) {
156
+ // A here-string is the command's input, not one of its words (`x=<<<1 git commit …` runs git).
157
+ // The kept spelling is built in one pass (#498 review: a rebuild per backslash was quadratic).
158
+ let kept = null;
159
+ if (wordKeep.length) {
160
+ kept = '';
161
+ let from = 0;
162
+ for (const at of wordKeep) { kept += `${word.slice(from, at)}\\`; from = at; }
163
+ kept = unshieldBraces(kept + word.slice(from));
164
+ }
165
+ const subs = wordSubs.length ? { word, subs: wordSubs.slice() } : null;
166
+ if (hereString) {
167
+ parts.herestrings.push({ part: parts.length, text: unshieldBraces(word), subst: subs });
168
+ // A shell fed the here-string reads the kept backslashes too (#498 review).
169
+ if (kept !== null) parts.herestrings.push({ part: parts.length, text: kept });
170
+ } else if (!dropWord) {
171
+ words.push(unshieldBraces(word));
172
+ const top = parens.at(-1);
173
+ if (top && wordPlain && (words.length === 1 || CASE_LEAD.has(words[words.length - 2]))) {
174
+ const wd = words[words.length - 1];
175
+ // `esac` only as a command's first word: after `then` it may be an argument (`echo then esac`).
176
+ if (wd === 'case') top.cases++; else if (wd === 'esac' && top.cases && words.length === 1) top.cases--;
177
+ }
178
+ if (afterDup?.write) {
179
+ const wd = words[words.length - 1];
180
+ if (!/[$`]/.test(word) && !DEVICE.test(wd)) (partWrites ??= []).push({ target: wd, append: false });
181
+ }
182
+ if (wordBraced) (partBraced ??= new Map()).set(words.length - 1, word);
183
+ if (kept !== null) (partPosix ??= new Map()).set(words.length - 1, kept);
184
+ if (subs) (partSubst ??= new Map()).set(words.length - 1, subs);
185
+ } else if (redirect && !/[$`]/.test(word)) {
186
+ // A redirect's target (#498, row 8): a file written (only by the output a shell would write, fd 1) or read.
187
+ const target = unshieldBraces(word);
188
+ if (!DEVICE.test(target)) {
189
+ if (redirect.op === '<') (partReads ??= []).push(target);
190
+ else if (redirect.op !== '<>' && (redirect.fd === '' || redirect.fd === '1')) (partWrites ??= []).push({ target, append: redirect.op.endsWith('>>') });
191
+ }
192
+ }
193
+ }
194
+ wordBraced = false;
195
+ wordKeep.length = 0;
196
+ wordSubs.length = 0;
197
+ wordPlain = true;
198
+ if (inWord) afterDup = null;
199
+ // Reset only once the target (or the here-string) was read: a space before it ends no word.
200
+ if (inWord) { dropWord = false; hereString = false; redirect = null; redirectBefore = null; }
201
+ word = ''; inWord = false;
202
+ };
203
+ const endPart = () => {
204
+ endWord(); dropWord = false; hereString = false; redirect = null; redirectBefore = null;
205
+ afterDup = null;
206
+ if (words[0] === '{') braceGroups.push(parts.length);
207
+ if (words[0] === '}' && braceGroups.length) {
208
+ // A copy: main's own `parts.writes` holds `partWrites`, and the group's list must never change it (#532 review 1).
209
+ parts.groups.push({ from: braceGroups.pop(), to: parts.length, writes: [...(partWrites ?? [])], brace: true });
210
+ }
211
+ if (words.length) { parts.braced.push(partBraced); parts.posix.push(partPosix); parts.subst.push(partSubst); parts.writes.push(partWrites); parts.reads.push(partReads); parts.push(words); }
212
+ // A redirect alone after a pipe: zsh writes what it is piped to the file (`echo … | > f`), as `cat > f` would.
213
+ else if (partWrites && parts.length && parts.piped.has(parts.length)) parts.pipedWrites.push({ after: parts.length - 1, writes: partWrites });
214
+ // Only the redirect-only part straight after a `( … )` writes that subshell's output (`( … ) > f`); any later
215
+ // part is another command, so the record is cleared at every part's end (#532 review 1).
216
+ if (!words.length && partWrites && closedGroup) closedGroup.writes.push(...partWrites);
217
+ closedGroup = null;
218
+ words = []; partBraced = null; partPosix = null; partSubst = null; partWrites = null; partReads = null;
219
+ };
47
220
  // Where the heredocs opened on this line end: the index just past the last one's end line, or -1 when an end
48
221
  // line never comes. The text of one whose end word is not quoted (`<<EOF`, not `<<'EOF'`) still runs its
49
222
  // `$(…)` and backticks, so those go to `parts.subs`.
223
+ // The end line must match exactly: `EOF\r` ends only a heredoc whose word is `EOF\r`, as in bash and zsh (a
224
+ // shell that drops CRs is the other reading, judged by agentGuardDecision). A heredoc whose end line never
225
+ // comes is ended by the shell at the end of the input, and an unquoted one still runs its `$(…)` there: those
226
+ // are judged too, as the rest of the line is also read as commands.
227
+ let index = null;
228
+ let restFrom = -1;
229
+ let restBody = false;
50
230
  const heredocsEnd = (from) => {
231
+ index ??= lineIndex(line);
51
232
  let at = from;
52
233
  const bodies = [];
53
234
  for (const h of heredocs) {
54
235
  const start = at;
55
- for (;;) {
56
- if (at > line.length) return -1;
57
- const eol = line.indexOf('\n', at);
58
- const text = line.slice(at, eol < 0 ? line.length : eol).replace(/\r$/, '');
59
- const lineStart = at;
60
- at = eol < 0 ? line.length + 1 : eol + 1;
61
- if ((h.tabs ? text.replace(/^\t+/, '') : text) === h.word) { if (!h.quoted) bodies.push(line.slice(start, lineStart)); break; }
236
+ const next = index.endAfter(h.word, h.tabs, at);
237
+ if (next >= 0) parts.bodies.push({ part: h.part, text: line.slice(start, line.lastIndexOf('\n', next - 2) + 1 || start) });
238
+ if (next < 0) {
239
+ // `bash+` (#516): its text is the rest of the input, what a `cat` of it prints, as in
240
+ // `eval "$(cat <<'E'⏎git p)ush -f"`, where bash 3.2 ends the `$(…)` at the `)` and runs `git p` joined to
241
+ // `ush -f`. Only in that reading: in the others, a text here kept the `$(…)` from being judged as commands.
242
+ // Once, as below: each later heredoc's text is inside it (one per heredoc was quadratic, review round 3).
243
+ if (mode.ends === 'bash+' && !restBody) { restBody = true; parts.bodies.push({ part: h.part, text: line.slice(start) }); }
244
+ // Once is enough: a later heredoc that never ends starts further on, inside text already judged.
245
+ if (restFrom < 0 && heredocs.some((x) => !x.quoted)) { restFrom = from; const subs = substitutionsIn(line.slice(from), mode); if (subs.tooComplex) parts.tooComplex = true; for (const x of subs) parts.subs.push(x); }
246
+ return -1;
62
247
  }
248
+ if (!h.quoted) bodies.push(line.slice(start, line.lastIndexOf('\n', next - 2) + 1 || start));
249
+ at = next;
63
250
  }
64
- for (const body of bodies) parts.subs.push(...substitutionsIn(body));
251
+ // A loop, not a spread: a body of 124,000 `$(` overflowed the stack with `push(...)` (#492 review).
252
+ for (const body of bodies) { const subs = substitutionsIn(body, mode); if (subs.tooComplex) parts.tooComplex = true; for (const x of subs) parts.subs.push(x); }
65
253
  return at;
66
254
  };
67
255
  for (let i = 0; i < line.length; i++) {
68
256
  const ch = line[i];
69
257
  // A command substitution, unquoted or in double quotes (single quotes keep it as text).
70
258
  if (quote !== '\'' && ((ch === '$' && line[i + 1] === '(') || ch === '`')) {
71
- const end = ch === '`' ? backtickEnd(line, i + 1) : substitutionEnd(line, i + 2);
72
- parts.subs.push(ch === '`' ? line.slice(i + 1, end).replace(/\\`/g, '`') : line.slice(i + 2, end));
259
+ const end = ch === '`' ? backtickEnd(line, i + 1) : substitutionEnd(line, i + 2, () => (index ??= lineIndex(line)), mode);
260
+ // Past the budget for `case` words or the deadline (#498): refused, not read on.
261
+ if (end < 0) { parts.tooComplex = true; break; }
262
+ const subText = ch === '`' ? line.slice(i + 1, end).replace(/\\`/g, '`') : line.slice(i + 2, end);
263
+ parts.subs.push(subText);
264
+ // A `case` in it: its `x)` closes no `$(` to the shell (#495), so the text up to the line's last `)` is
265
+ // judged too. Only refuses more.
266
+ // The marks are found once per line, so this costs no scan per `$(` (#498 review: it was quadratic).
267
+ if (ch === '$' && markWithin((realMarks ??= marksOf(line)).cases, i + 2, end)) {
268
+ const eol = firstAtOrAfter(realMarks.newlines, i);
269
+ const stop = eol < 0 ? line.length : eol;
270
+ const last = line.lastIndexOf(')', stop - 1);
271
+ if (last > end) parts.subs.push(line.slice(i + 2, last));
272
+ }
273
+ // Where it sits in the word, for the words its printed text makes (#498, row 2).
274
+ wordSubs.push({ at: word.length, len: end + 1 - i, text: subText, quoted: quote === '"' });
73
275
  word += line.slice(i, end + 1); inWord = true;
74
276
  i = end;
75
277
  continue;
@@ -77,20 +279,31 @@ export function shellParts(line) {
77
279
  if (quote) {
78
280
  if (ch === quote) quote = null;
79
281
  else if (ch === '\\' && quote === '"' && line[i + 1] === '\n') i++;
80
- else if (ch === '\\' && quote === '"' && i + 1 < line.length) word += line[++i];
81
- else word += ch;
282
+ else if (ch === '\\' && quote === '"' && i + 1 < line.length) {
283
+ // In double quotes the shell keeps the backslash unless `$`, a backtick, `"`, `\\` or a newline follows
284
+ // (#498): a line re-read by `bash -c` or `eval` sees it. Kept as an extra spelling of the word.
285
+ if (!'$`"\\\n'.includes(line[i + 1])) wordKeep.push(word.length);
286
+ word += shieldBrace(line[++i]);
287
+ }
288
+ else word += shieldBrace(ch);
82
289
  continue;
83
290
  }
84
- if (ch === '\'' || ch === '"') { quote = ch; inWord = true; continue; }
291
+ // `$'…'` is read with its escapes (`\'` is a quote in it, #495); `$"…"` is a double-quoted string.
292
+ if (ch === '$' && line[i + 1] === '\'') { wordPlain = false; const r = ansiC(line, i + 2); word += [...r.text].map(shieldBrace).join(''); inWord = true; i = r.end; continue; }
293
+ if (ch === '$' && line[i + 1] === '"') { continue; }
294
+ if (ch === '\'' || ch === '"') { quote = ch; inWord = true; wordPlain = false; continue; }
85
295
  if (ch === '\\' && line[i + 1] === '\n') { i++; continue; }
86
- if (ch === '\\' && line[i + 1] === '\r' && line[i + 2] === '\n') { i += 2; continue; }
87
- if (ch === '\\' && i + 1 < line.length) { word += line[++i]; inWord = true; continue; }
88
- if (ch === '#' && !inWord) { while (i + 1 < line.length && line[i + 1] !== '\n') i++; continue; }
89
- if (ch === '<' && line[i + 1] === '<' && line[i + 2] === '<') { endWord(); i += 2; continue; }
296
+ // `\` + CR + LF is NOT a line join: bash and zsh read an escaped CR, then run the next line as its own
297
+ // command. So it falls through to the escape below (the CR is a character of the word), and the LF ends the part.
298
+ if (ch === '\\' && i + 1 < line.length) { word += shieldBrace(line[++i]); inWord = true; wordPlain = false; continue; }
299
+ // A `#` starts a comment only where a word starts after a space, a tab, a newline, `;`, `&` or `|` (or at the
300
+ // start): right after `(` or `)` it is text to zsh's globs and to bash's `[[ =~ ]]` (#492 review).
301
+ if (ch === '#' && !inWord && (i === 0 || (mode.hashAfterParen ? /[ \t\n;&|()]/ : /[ \t\n;&|]/).test(line[i - 1])) && !(mode.hashAfterBar && line[i - 1] === '|')) { while (i + 1 < line.length && line[i + 1] !== '\n') i++; continue; }
302
+ if (ch === '<' && line[i + 1] === '<' && line[i + 2] === '<') { endWord(); hereString = true; i += 2; continue; }
90
303
  if (ch === '<' && line[i + 1] === '<') {
91
304
  // A heredoc: its delimiter, bare or quoted, with `<<-` stripping leading tabs from the lines.
92
- const m = HEREDOC.exec(line.slice(i));
93
- if (m) { heredocs.push(heredocOf(m)); endWord(); i += m[0].length - 1; continue; }
305
+ const m = heredocAt(line, i);
306
+ if (m) { if (!m.expands || mode.literalExpanding) heredocs.push({ ...heredocOf(m), part: parts.length }); endWord(); i += m[0].length - 1; continue; }
94
307
  }
95
308
  if (ch === '\n' && heredocs.length) {
96
309
  endPart();
@@ -100,21 +313,178 @@ export function shellParts(line) {
100
313
  if (at >= 0) i = at - 1 - 1;
101
314
  continue;
102
315
  }
103
- if (ch === '\n' || ch === ';' || ch === '&' || ch === '|') { endPart(); continue; }
104
- if (ch === ' ' || ch === '\t' || ch === '\r') { endWord(); continue; }
316
+ // A redirect (#495): `[n]>`, `>>`, `>|`, `&>`, `&>>`, `<`, `<>`, `[n]>&n`, `[n]<&n`, `>&-`. Its operator and its
317
+ // target are not words of the command, and the `&` in it splits nothing (`git push origin main 2>&1 --force`
318
+ // pushes with --force). A `(` right after it is a process substitution: the part break below reads it.
319
+ // zsh's numeric glob (`<->`, `<1-9>`) is one word, not two redirects (#495 review): judged both ways.
320
+ if (mode.numericGlob && ch === '<') {
321
+ const g = /^<[0-9]*-[0-9]*>/.exec(line.slice(i, i + 24));
322
+ if (g) { word += g[0]; inWord = true; i += g[0].length - 1; continue; }
323
+ }
324
+ if ((ch === '>' || ch === '<') || (ch === '&' && line[i + 1] === '>')) {
325
+ let fd = '';
326
+ if (inWord && /^[0-9]+$/.test(word)) { fd = word; word = ''; inWord = false; wordKeep.length = 0; wordSubs.length = 0; } else endWord();
327
+ let j = i + (ch === '&' ? 2 : 1);
328
+ if (line[j] === '>' || line[j] === '|' || (ch === '<' && line[j] === '>')) j++;
329
+ // #518: zsh's `>!`, `>>!`, `&>!`, `&>>!` and `>>|` write the file, as `>|` does (the `!` or `|` is the operator's).
330
+ // After `>|` or `&>|` a `!` is the target's (zsh writes the file `!`), not the operator's (review 1).
331
+ if (shellOf(mode) === 'zsh' && ch !== '<' && ((line[j] === '!' && line[j - 1] !== '|') || (line[j] === '|' && line[j - 1] === '>'))) j++;
332
+ // `>&n` and `>&-` copy or close a file descriptor, read as before; a bare `>&` before a word writes it.
333
+ if (line[j] === '&') {
334
+ j++;
335
+ // #518: how bash 3.2 and zsh read the word after `>&` / `<&` (blanks allowed before it), each in its own mode;
336
+ // main's reading below stays as it was. Both: digits alone copy a descriptor.
337
+ // bash: an unquoted `-` closes it, and what follows is a word of the command (`>&--n` and `>& --n` pass
338
+ // `-n`; `>&--{n,x}` passes `-n -x`); digits and `-` move one; any other word after `>&` is a file
339
+ // written, as `&>` writes it (`>&1--n`, `>&p`).
340
+ // zsh: `-` alone closes, `p` alone is the coprocess; any other word after `>&` is a file written, the whole
341
+ // word (`>&--n` writes `--n`, `>&1-` writes `1-`); `>&|` and `>&!` write the next word, as `&>|` does.
342
+ const shell = shellOf(mode);
343
+ if (shell) {
344
+ const into = ch !== '<';
345
+ if (shell === 'zsh' && into && (line[j] === '|' || line[j] === '!')) {
346
+ redirectBefore = dropWord ? redirect : null;
347
+ redirect = { op: '>', fd: fd || '1' };
348
+ dropWord = true;
349
+ i = j;
350
+ continue;
351
+ }
352
+ let k = j;
353
+ while (line[k] === ' ' || line[k] === '\t') k++;
354
+ const ends = (at) => at >= line.length || /[\s;&|<>()]/.test(line[at]);
355
+ const digits = /^[0-9]*/.exec(line.slice(k, k + 24))[0];
356
+ if (k < line.length && !ends(k)) {
357
+ if (digits && ends(k + digits.length)) { i = k + digits.length - 1; continue; }
358
+ if (shell === 'bash' && digits && line[k + digits.length] === '-' && ends(k + digits.length + 1)) { i = k + digits.length; continue; }
359
+ if (line[k] === '-' && (shell === 'bash' || ends(k + 1))) {
360
+ // bash reads the `-` as a token of its own, so a `#` right after it starts a comment (review 1).
361
+ if (shell === 'bash' && line[k + 1] === '#') { i = k + 1; while (i + 1 < line.length && line[i + 1] !== '\n') i++; continue; }
362
+ i = k;
363
+ continue;
364
+ }
365
+ if (shell === 'zsh' && line[k] === 'p' && ends(k + 1)) { i = k; continue; }
366
+ redirectBefore = dropWord ? redirect : null;
367
+ redirect = { op: into ? '>' : '<', fd: into ? (fd || '1') : fd };
368
+ dropWord = true;
369
+ i = k - 1;
370
+ continue;
371
+ }
372
+ }
373
+ const from = j;
374
+ while (j < line.length && /[0-9-]/.test(line[j])) j++;
375
+ if (j === from) afterDup = { write: ch !== '<' && (fd === '' || fd === '1') };
376
+ i = j - 1;
377
+ continue;
378
+ }
379
+ redirectBefore = dropWord ? redirect : null;
380
+ redirect = { op: line.slice(i, j).replace(/[|!]/g, ''), fd: ch === '&' ? '1' : fd };
381
+ dropWord = true;
382
+ i = j - 1;
383
+ continue;
384
+ }
385
+ // `(` and `)` end a part too (#492): `<(cmd)`, `>(cmd)`, `f(){ cmd; }` and `case x in x) cmd;;` run `cmd`.
386
+ if (ch === '\n' || ch === ';' || ch === '&' || ch === '|' || ch === '(' || ch === ')') {
387
+ const prevProc = afterProc;
388
+ afterProc = null;
389
+ if (ch === '(') {
390
+ // A process substitution (#498, row 1): `<(…)` or `>(…)` (the `<` read as a redirect just before), or
391
+ // zsh's `=(…)` (a word that is just `=`). The words before it are its owner's (with those before an
392
+ // earlier one the same command holds), and the word it makes stands at `position` (the `=` word
393
+ // itself, which stays a word of the part as written).
394
+ const zshEq = inWord && word === '=' && !wordSubs.length;
395
+ const isProc = zshEq || (dropWord && redirect && (line[i - 1] === '<' || line[i - 1] === '>'));
396
+ // Carried only while short: a shell's script word comes before its first few words end (a carry with no
397
+ // bound grew with every `<(…)` on a long line, #498 review).
398
+ // Past the bound, the first owner's first words are kept and the substitution is judged whenever they
399
+ // start a shell (`maybe`): only refuses more.
400
+ const carry = prevProc && prevProc.owner.length + words.length < 64;
401
+ const owner = !isProc ? null : carry ? [...prevProc.owner, ...(prevProc.viaStdin ? [] : ['\0']), ...words] : prevProc ? prevProc.owner.slice(0, 64) : words.slice();
402
+ const viaStdin = !zshEq && redirectBefore?.op === '<';
403
+ endPart();
404
+ parens.push({ from: parts.length, proc: owner && owner.length ? { owner, position: owner.length, viaStdin, maybe: !!prevProc && !carry, sourceFrom: i + 1, from: parts.length } : null, cases: 0 });
405
+ continue;
406
+ }
407
+ endPart();
408
+ if (ch === ')' && !parens.at(-1)?.cases) {
409
+ const top = parens.pop();
410
+ const p = top?.proc;
411
+ if (top && !p) { closedGroup = { from: top.from, to: parts.length, writes: [] }; parts.groups.push(closedGroup); }
412
+ // A held `)` before already recorded this substitution: its record now runs to this, the real close.
413
+ if (p && top.held) { top.held.to = parts.length; top.held.text = line.slice(p.sourceFrom, i); afterProc = p; } else if (p) { parts.procsubs.push({ ...p, to: parts.length, text: line.slice(p.sourceFrom, i) }); afterProc = p; }
414
+ // A redirect-only part straight after it is its command's (`cat <(…) > f`): kept in `after`, which only the
415
+ // output pass reads (#532 review 2).
416
+ const rec = p && (top.held ?? parts.procsubs.at(-1));
417
+ if (rec) closedGroup = { writes: (rec.after ??= []) };
418
+ } else if (ch === ')' && parens.at(-1)?.held) {
419
+ // One record per substitution, run on to each later held `)` (#498 review: a `case` the reader took
420
+ // for the reserved word may hold every one).
421
+ parens.at(-1).held.to = parts.length;
422
+ } else if (ch === ')' && parens.at(-1)?.proc) {
423
+ // A `)` read as a `case` pattern's: it may close the process substitution after all (a `case` the reader
424
+ // took for the reserved word), so that reading is judged too.
425
+ const rec = { ...parens.at(-1).proc, to: parts.length };
426
+ parts.procsubs.push(rec);
427
+ parens.at(-1).held = rec;
428
+ }
429
+ if (ch === '|') {
430
+ // The second `|` of `||` is known by where the first one was, not by the raw text before it (`\||bash`).
431
+ if (line[i + 1] === '|' && orAt !== i) orAt = i + 1;
432
+ else if (orAt !== i) parts.piped.add(parts.length);
433
+ }
434
+ continue;
435
+ }
436
+ // A CR is a character of the word, as bash and zsh read it (#492): `x\r#` is one word, so its `#` starts no
437
+ // comment. A shell that drops CRs is the other reading, judged by agentGuardDecision.
438
+ if (ch === ' ' || ch === '\t') { endWord(); continue; }
439
+ if (ch === '{') wordBraced = true;
105
440
  word += ch; inWord = true;
106
441
  }
107
442
  endPart();
108
443
  return parts;
109
444
  }
110
445
 
446
+ // Where the word `case` and each newline stand in a line, in order: found once per line, so each `$(` asks by a
447
+ // binary search whether its text holds a `case`, never by a scan (a scan per `$(` was quadratic, #498 review).
448
+ function marksOf(line) {
449
+ const cases = [], newlines = [];
450
+ for (const m of line.matchAll(/\bcase\b|\n/g)) (m[0] === '\n' ? newlines : cases).push(m.index);
451
+ return { cases, newlines };
452
+ }
453
+ // The first index in `sorted` at or after `from`, or -1.
454
+ function firstAtOrAfter(sorted, from) {
455
+ let lo = 0, hi = sorted.length;
456
+ while (lo < hi) { const mid = (lo + hi) >> 1; if (sorted[mid] < from) lo = mid + 1; else hi = mid; }
457
+ return lo < sorted.length ? sorted[lo] : -1;
458
+ }
459
+ function markWithin(marks, from, to) {
460
+ const at = firstAtOrAfter(marks, from);
461
+ return at >= 0 && at < to;
462
+ }
463
+
111
464
  // Where the `$(` whose text starts at `from` closes: the index of its `)`, or the end of the line when it never
112
465
  // closes. Quotes, nested `(…)` and a heredoc's text inside it are its own, so a `)` in them does not close it.
113
- function substitutionEnd(line, from) {
466
+ // `getIndex` gives the line index of `line`, built once per text and shared by every `$(` in it (#492 review: one
467
+ // per call made many `$(…)` holding heredocs take quadratic time).
468
+ function substitutionEnd(line, from, getIndex, mode = {}) {
114
469
  let depth = 1;
115
470
  let quote = null;
116
471
  const heredocs = [];
117
- for (let i = from; i < line.length; i++) {
472
+ // `mode.ends` (#498), the end rule of the whole reading. Unset: main's. `bash`: `$'…'` is skipped with its
473
+ // escapes (`\'` does not end it), a `#` comment and backticks are skipped, and a `case` is text, as bash 3.2
474
+ // reads them. `zsh`: `$'…'` and comments the same, and a `case <word> in` makes its `x)` patterns close
475
+ // nothing, as zsh reads them. Each is a reading of its own, never mixed in one.
476
+ // `bash+` and `zsh+` (#516) add the rarer forms each shell takes, as readings beside `bash` and `zsh`, so main's
477
+ // readings stay as they were and a line is only ever refused more: `bash+` reads a heredoc's text as code;
478
+ // `zsh+` takes a `case` word in backticks, a comment or `;` before `in`, `case x { … }`, and `esac` in more spots.
479
+ const shell = mode.ends?.replace('+', '');
480
+ const rare = !!mode.ends?.endsWith('+');
481
+ const ansi = shell === 'bash' || shell === 'zsh';
482
+ // One entry per open `case`, and (`zsh+`) per `{ … }` group opened inside one; `at` is the depth of the
483
+ // innermost `case`, whose `x)` patterns close nothing.
484
+ const cases = [];
485
+ // `mode.until`: scan no further (a bound on a `case` word).
486
+ const stop = Math.min(line.length, mode.until ?? Infinity);
487
+ for (let i = from; i < stop; i++) {
118
488
  const ch = line[i];
119
489
  if (quote) {
120
490
  if (ch === quote) quote = null;
@@ -122,44 +492,138 @@ function substitutionEnd(line, from) {
122
492
  continue;
123
493
  }
124
494
  if (ch === '\\') { i++; continue; }
495
+ if (ansi && ch === '$' && line[i + 1] === '\'') {
496
+ let j = i + 2;
497
+ while (j < stop && line[j] !== '\'') j += line[j] === '\\' ? 2 : 1;
498
+ i = j;
499
+ continue;
500
+ }
501
+ // Both shells read a `#` that starts a word as a comment to the end of the line: a `)` in it closes nothing
502
+ // (#498 review round 6). Not `$#`, `${#x}` or `16#ff`, where it starts no word. bash 3.2 starts one only after
503
+ // a blank or a newline (`;#` is no comment to it); zsh after `;`, `&`, `|`, `(` and `)` too (round 7).
504
+ if (ansi && ch === '#' && (i === from || (shell === 'bash' ? /[ \t\n]/ : /[\s;&|()]/).test(line[i - 1]))) {
505
+ const nl = line.indexOf('\n', i);
506
+ if (nl < 0 || nl >= stop) return line.length;
507
+ i = nl - 1;
508
+ continue;
509
+ }
510
+ // bash 3.2 reads backticks inside `$(…)` as nested: a `)` in them closes nothing (zsh does not).
511
+ if (shell === 'bash' && ch === '`') { i = backtickEnd(line, i + 1); continue; }
512
+ if (shell === 'zsh' && (ch === 'c' || ch === 'e' || (rare && (ch === '{' || ch === '}'))) && (i === from || /[\s;&|(]/.test(line[i - 1]) || (rare && line[i - 1] === ')' && ch !== 'c' && ch !== 'e'))) {
513
+ const top = cases[cases.length - 1];
514
+ if (ch === 'c' && line.startsWith('case', i)) {
515
+ const at = caseInEnd(line, i, getIndex, rare);
516
+ // What a `case` word costs is charged to one budget per reading: past it, the command is refused.
517
+ if ((caseLeft.n -= caseScanned) < 0 || Date.now() > deadline) return -2;
518
+ if (at >= 0) { cases.push({ at: depth, braces: line[at - 1] === '{' }); i = at - 1; continue; }
519
+ }
520
+ // `esac` ends a case only where a command starts: `echo esac` is a word (#498 review). `zsh+`: also right
521
+ // after `}`, `esac`, `]]`, `!` or the case's `in` (#516).
522
+ if (ch === 'e' && top && !top.group && /^esac(?![^\s;&|()<>])/.test(line.slice(i, i + 5)) && (rare ? zshReservedAt : commandStart)(line, i, from)) { cases.pop(); i += 3; continue; }
523
+ if (rare && top && /^.(?![^\s;&|()<>])/.test(line.slice(i, i + 2))) {
524
+ // zsh reads a `}` word as the end of the open `{` anywhere, `echo }` too (#516); a `{` opens a group only
525
+ // where a command starts, and its `}` is never read as the end of the case.
526
+ if (ch === '}' && (top.group || top.braces)) { cases.pop(); continue; }
527
+ if (ch === '{' && zshReservedAt(line, i, from)) { cases.push({ at: top.at, group: true }); continue; }
528
+ }
529
+ }
125
530
  if (ch === '\'' || ch === '"') { quote = ch; continue; }
126
- if (ch === '<' && line[i + 1] === '<' && line[i + 2] !== '<') {
127
- const m = HEREDOC.exec(line.slice(i));
128
- if (m) { heredocs.push(heredocOf(m)); i += m[0].length - 1; continue; }
531
+ // `bash+`: bash 3.2 reads a heredoc's text inside `$(…)` as code (#516), so a `)` or a quote in it counts.
532
+ if (ch === '<' && line[i + 1] === '<' && line[i + 2] !== '<' && mode.ends !== 'bash+') {
533
+ const m = heredocAt(line, i);
534
+ if (m) { if (!m.expands || mode.literalExpanding) heredocs.push(heredocOf(m)); i += m[0].length - 1; continue; }
129
535
  }
130
536
  if (ch === '\n' && heredocs.length) {
131
537
  // Skip each heredoc's text to its end line; one that never ends is not a heredoc.
538
+ const index = getIndex();
132
539
  let at = i + 1;
133
540
  let found = true;
134
541
  for (const h of heredocs) {
135
- for (;;) {
136
- if (at > line.length) { found = false; break; }
137
- const eol = line.indexOf('\n', at);
138
- const text = line.slice(at, eol < 0 ? line.length : eol).replace(/\r$/, '');
139
- at = eol < 0 ? line.length + 1 : eol + 1;
140
- if ((h.tabs ? text.replace(/^\t+/, '') : text) === h.word) break;
141
- }
142
- if (!found) break;
542
+ const next = index.endAfter(h.word, h.tabs, at);
543
+ if (next < 0) { found = false; break; }
544
+ at = next;
143
545
  }
144
546
  heredocs.length = 0;
145
547
  if (found) i = at - 2;
146
548
  continue;
147
549
  }
148
550
  if (ch === '(') depth++;
551
+ else if (ch === ')' && cases.length && depth === cases[cases.length - 1].at) continue;
149
552
  else if (ch === ')' && --depth === 0) return i;
150
553
  }
151
554
  return line.length;
152
555
  }
153
556
 
557
+ // After the `case` at `i`, the index just past its `in`, or -1 (#498 review): the word between may be quoted,
558
+ // escaped, a `$(…)` or a `${…}`, and `in` may follow a newline.
559
+ const CASE_WORD = 4096;
560
+ // How far the last caseInEnd scanned, charged by its caller to one budget per reading.
561
+ let caseScanned = 0;
562
+ function caseInEnd(line, i, getIndex, rare = false) {
563
+ const limit = Math.min(line.length, i + CASE_WORD);
564
+ let j = i + 4;
565
+ const done = (at) => { caseScanned = Math.min(Math.max(j, i + 4), limit) - i; return at; };
566
+ if (line[j] !== ' ' && line[j] !== '\t') return done(-1);
567
+ while (j < limit && (line[j] === ' ' || line[j] === '\t')) j++;
568
+ const start = j;
569
+ for (; j < limit && !/[\s;&|()<>]/.test(line[j]); j++) {
570
+ const c = line[j];
571
+ if (c === '\\') j++;
572
+ // zsh takes a word in backticks (#516).
573
+ else if (rare && c === '`') { j = backtickEnd(line, j + 1); if (j >= limit) return done(-1); }
574
+ else if (c === '\'') { j++; while (j < limit && line[j] !== '\'') j++; if (j >= limit) return done(-1); }
575
+ else if (c === '"') { j++; while (j < limit && line[j] !== '"') j += line[j] === '\\' ? 2 : 1; if (j >= limit) return done(-1); }
576
+ // The default scan, never the shells' own: that one reads a `case` here again, and the two calling each other
577
+ // doubled the time at each `case $(` (#498 review round 2).
578
+ else if (c === '$' && line[j + 1] === '(') { j = substitutionEnd(line, j + 2, getIndex, { until: limit }); if (j >= limit) return done(-1); }
579
+ else if (c === '$' && line[j + 1] === '{') {
580
+ let d = 0;
581
+ for (; j < limit; j++) { if (line[j] === '{') d++; else if (line[j] === '}' && --d === 0) break; }
582
+ if (j >= limit) return done(-1);
583
+ }
584
+ }
585
+ if (j === start || j >= limit) return done(-1);
586
+ // `zsh+` (#516): zsh also takes `;` and `#` comments before `in` (a `#` starts one only after a blank), and its
587
+ // other form, `case x { … }` (the index just past its `{`).
588
+ for (;;) {
589
+ while (j < limit && (rare ? /[\s;]/ : /\s/).test(line[j])) j++;
590
+ if (!rare || j >= limit || line[j] !== '#') break;
591
+ while (j < limit && line[j] !== '\n') j++;
592
+ }
593
+ if (rare && j < limit && line[j] === '{' && /\s/.test(line[j - 1])) return done(j + 1);
594
+ return done(/^in(?![^\s;&|()<>])/.test(line.slice(j, j + 3)) ? j + 2 : -1);
595
+ }
596
+ // Whether a command starts at `i`: only blanks between it and `from`, or a `;`, `&`, `)` or newline (not `|` or
597
+ // `(`: in `case x in a|esac)` the `esac` is a pattern).
598
+ function commandStart(line, i, from) {
599
+ let k = i - 1;
600
+ while (k >= from && (line[k] === ' ' || line[k] === '\t')) k--;
601
+ return k < from || /[;&)\n]/.test(line[k]);
602
+ }
603
+ // Whether zsh reads a reserved word (`esac`, `{`) at `i` (#516): only blanks between it and `from`, or after a
604
+ // `;`, `&`, `)` or newline (not `|` or `(`: in `case x in a|esac)` the `esac` is a pattern), or right after a
605
+ // `}`, `esac`, `]]`, `!` or `in` word.
606
+ function zshReservedAt(line, i, from) {
607
+ let k = i - 1;
608
+ while (k >= from && (line[k] === ' ' || line[k] === '\t')) k--;
609
+ if (k < from || /[;&)\n]/.test(line[k])) return true;
610
+ let w = k;
611
+ while (w >= from && !/[\s;&|()<>]/.test(line[w])) w--;
612
+ return ['}', 'esac', ']]', '!', 'in'].includes(line.slice(w + 1, k + 1));
613
+ }
614
+
154
615
  // The commands of every `$(…)` and backticks in a heredoc's text, where quotes are plain characters and `\`
155
616
  // keeps the next one as text.
156
- function substitutionsIn(text) {
617
+ function substitutionsIn(text, mode = {}) {
157
618
  const out = [];
619
+ let index = null;
620
+ const getIndex = () => (index ??= lineIndex(text));
158
621
  for (let i = 0; i < text.length; i++) {
159
622
  const ch = text[i];
160
623
  if (ch === '\\') { i++; continue; }
161
624
  if ((ch === '$' && text[i + 1] === '(') || ch === '`') {
162
- const end = ch === '`' ? backtickEnd(text, i + 1) : substitutionEnd(text, i + 2);
625
+ const end = ch === '`' ? backtickEnd(text, i + 1) : substitutionEnd(text, i + 2, getIndex, { ends: mode.ends });
626
+ if (end < 0) { out.tooComplex = true; break; }
163
627
  out.push(ch === '`' ? text.slice(i + 1, end).replace(/\\`/g, '`') : text.slice(i + 2, end));
164
628
  i = end;
165
629
  }
@@ -180,7 +644,9 @@ function backtickEnd(line, from) {
180
644
  // `command`, `exec`, `time`, `nohup`, `nice`, `timeout` with its duration, the shell's own words (`then`, `do`,
181
645
  // `else`, `{`, `!`), `xargs`, `stdbuf`, `watch`, and a `(` stuck to the front of the first word. The options of a prefix are skipped with
182
646
  // it, and the value of one that takes a value (`sudo -u <user>`, `nice -n <n>`, `env -u <name>`).
183
- const PREFIXES = new Set(['env', 'sudo', 'command', 'exec', 'time', 'nohup', 'nice', 'xargs', 'stdbuf', 'watch', 'then', 'do', 'else', 'elif', 'if', 'while', 'until', '{', '!']);
647
+ // #495 adds `builtin`, zsh's `noglob` and `nocorrect`, `coproc [NAME]`, `function NAME` and `exec -a NAME`.
648
+ const PREFIXES = new Set(['env', 'sudo', 'command', 'exec', 'time', 'nohup', 'nice', 'xargs', 'stdbuf', 'watch', 'then', 'do', 'else', 'elif', 'if', 'while', 'until', '{', '!',
649
+ 'builtin', 'noglob', 'nocorrect', 'coproc', 'function']);
184
650
  const PREFIX_VALUE_OPTIONS = new Set(['-u', '-g', '-n', '-C', '-h', '-U', '-r', '-t', '-s', '-k', '-o', '--user', '--group', '--signal',
185
651
  '--kill-after', '--unset', '--chdir', '--adjustment', '--output']);
186
652
  // A prefix whose letters mean something else (`xargs -r` and `-t` take no value, `sudo -E` none either) reads
@@ -191,14 +657,22 @@ const PREFIX_OWN_VALUE_OPTIONS = {
191
657
  '--max-procs', '--delimiter', '--arg-file', '--eof']),
192
658
  stdbuf: new Set(['-i', '-o', '-e', '--input', '--output', '--error']),
193
659
  watch: new Set(['-n', '--interval']),
660
+ exec: new Set(['-a']),
194
661
  };
195
662
  const stripPrefix = (words) => {
663
+ // The common case, a plain first word, in one look (it is called many times per part).
664
+ const w0 = words[0];
665
+ if (w0 && !w0.includes('=') && w0 !== 'function' && w0 !== 'coproc' && w0 !== 'timeout' && !PREFIXES.has(w0) && w0[0] !== '(' && w0[0] !== '{') return words.slice();
196
666
  const w = words.slice();
197
- if (w.length && w[0].startsWith('(')) w[0] = w[0].replace(/^\(+/, '');
667
+ // A `(` or a `{` stuck to the first word (zsh reads `{gh pr merge 5;}` as a group).
668
+ if (w.length && /^[({]/.test(w[0])) w[0] = w[0].replace(/^[({]+/, '');
198
669
  let i = 0;
199
670
  for (;;) {
200
671
  while (i < w.length && w[i] === '') i++;
201
672
  if (i < w.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(w[i])) { i++; continue; }
673
+ // `function NAME`, and `coproc NAME {` (a name only before a `{`): the name is not the command.
674
+ if (i < w.length && w[i] === 'function') { i += 2; continue; }
675
+ if (i < w.length && w[i] === 'coproc' && w[i + 2] === '{') { i += 2; continue; }
202
676
  if (i < w.length && (PREFIXES.has(w[i]) || w[i] === 'timeout')) {
203
677
  const isTimeout = w[i] === 'timeout';
204
678
  const own = PREFIX_OWN_VALUE_OPTIONS[w[i]];
@@ -211,7 +685,8 @@ const stripPrefix = (words) => {
211
685
  return w.slice(i);
212
686
  }
213
687
  };
214
- const programOf = (word) => word.split(/[\\/]/).pop().replace(/\.(exe|cmd)$/i, '');
688
+ // A word with no path and no extension is its own program (the common case, without two regexes).
689
+ const programOf = (word) => (typeof word === 'string' && !/[\\/.]/.test(word) ? word : word.split(/[\\/]/).pop().replace(/\.(exe|cmd)$/i, ''));
215
690
 
216
691
  // How package runners start a program. `npx [-y] yadflow[@v] …` or `npx yad …` (and pnpx, bunx), `npx -p
217
692
  // yadflow yad …`, `npm [opts] exec|x yadflow|yad -- …`, `pnpm [opts] exec|dlx …`, `pnpm yad …`, `yarn [opts]
@@ -268,13 +743,160 @@ function runnerOf(w) {
268
743
  // The command line a shell runs from its `-c` argument (`bash -c "yad gate approve …"`), or null. A package
269
744
  // runner's `-c`/`--call` before its program is one too (`npx -c '<line>'`, `npm exec -c '<line>'`), and
270
745
  // `pnpm exec|dlx -c` runs the rest of its words as a shell line. A program's own `-c` (`vitest -c x`) is not.
746
+ const SHELLS = ['bash', 'sh', 'zsh', 'dash', 'ksh'];
747
+ // The device files a redirect writes to or reads from that are not files the line can run (#498, row 8).
748
+ // The words after which a word starts a command, for `case` and `esac` (#498 review).
749
+ // Commands that only print their words: a file read past its limits there is printed, not run.
750
+ const PRINTERS = new Set(['echo', 'printf', 'print', 'cat']);
751
+ const CASE_LEAD = new Set(['then', 'do', 'else', 'elif', '{', '!', 'time', 'if', 'while', 'until']);
752
+ const DEVICE = /^\/dev\/(null|stdin|stdout|stderr|tty|zero|fd\/[0-9]+)$/;
753
+ // A shell reading its script from its input, not from a file: no `-c`, and either no plain word, or `-s` among its
754
+ // options (the words after are `$1…`), or the first plain word is the input itself (`-`, `/dev/stdin`,
755
+ // `/dev/fd/0`, `/proc/self/fd/0`); `source` / `.` of the input too. `--rcfile` / `--init-file` take a value.
756
+ const STDIN_FILES = /^(-|\/dev\/stdin|\/dev\/fd\/0|\/proc\/self\/fd\/0)$/;
757
+ function bareShell(w) {
758
+ if (!w.length) return false;
759
+ const prog = programOf(w[0]);
760
+ if ((prog === 'source' || prog === '.') && STDIN_FILES.test(w[1] ?? '')) return true;
761
+ if (!SHELLS.includes(prog) || shellC(w) !== null) return false;
762
+ for (let k = 1; k < w.length; k++) {
763
+ if (w[k] === '--') return k + 1 >= w.length || STDIN_FILES.test(w[k + 1]);
764
+ if (/^--(rcfile|init-file|emulate)$/.test(w[k])) { k++; continue; }
765
+ if (/^-[A-Za-z]*s[A-Za-z]*$/.test(w[k])) return true;
766
+ // A cluster holding `o` or `O` takes the next word as its value (`-euo pipefail`).
767
+ if (/^[-+][A-Za-z]*[oO][A-Za-z]*$/.test(w[k])) { k++; continue; }
768
+ if (/^[-+]/.test(w[k]) && w[k] !== '-') continue;
769
+ // A word that may expand to nothing (`bash $NOPE`, `"$@"`): the next one decides.
770
+ if (/[$`]/.test(w[k])) continue;
771
+ return STDIN_FILES.test(w[k]);
772
+ }
773
+ return true;
774
+ }
775
+ // Where a shell's script file is among its words (#498, rows 1, 8): the first plain word after its options, as
776
+ // bareShell reads them, or 1 for `source` and `.`; -1 when there is none, or the shell runs `-c` or reads `-s`.
777
+ function scriptAt(w) {
778
+ if (!w.length) return -1;
779
+ const prog = programOf(w[0]);
780
+ if (prog === 'source' || prog === '.') { const k = w[1] === '--' ? 2 : 1; return w.length > k ? k : -1; }
781
+ if (!SHELLS.includes(prog) || shellC(w) !== null) return -1;
782
+ for (let k = 1; k < w.length; k++) {
783
+ if (w[k] === '--') return k + 1 < w.length ? k + 1 : -1;
784
+ if (/^--(rcfile|init-file|emulate)$/.test(w[k])) { k++; continue; }
785
+ if (/^-[A-Za-z]*s[A-Za-z]*$/.test(w[k])) return -1;
786
+ if (/^[-+][A-Za-z]*[oO][A-Za-z]*$/.test(w[k])) { k++; continue; }
787
+ if (/^[-+]/.test(w[k]) && w[k] !== '-') continue;
788
+ return k;
789
+ }
790
+ return -1;
791
+ }
792
+ // A quoted or escaped `{`, `}` or `,` is text to the shell, not brace syntax: the reader carries it as a private-use
793
+ // character until the word's expansion is done (`git commit -m {'}',-n}` is a list of `}` and `-n`).
794
+ const QUOTED_BRACE = { '{': '\uE000', '}': '\uE001', ',': '\uE002' };
795
+ const shieldBrace = (c) => QUOTED_BRACE[c] ?? c;
796
+ const unshieldBraces = (x) => (/[\uE000-\uE002]/.test(x) ? x.replace(/\uE000/g, '{').replace(/\uE001/g, '}').replace(/\uE002/g, ',') : x);
797
+ // A word's brace expansion, as the shell makes it: every alternative of each list, lists side by side multiplied,
798
+ // lists inside lists expanded, `{x..y}` sequences (any one character, as zsh allows: `{-..-}` is `-`). A number
799
+ // sequence stands for one word, since digits spell no flag. Null when the word is too long to expand (over
800
+ // BRACE_WORD characters with a `{`) or would make more than BRACE_CAP words: the line is refused. The length bound
801
+ // keeps every scan here small, so nesting and long lists cannot make it slow (#495 review).
802
+ const BRACE_CAP = 64;
803
+ const BRACE_WORD = 4096;
804
+ // `bash` (#498): bash closes a list only at a `}` after one of its commas, or where its body is a sequence; a
805
+ // `}` before that is text (`{x},merge}` is `x}` and `merge`), and a `{` that never closes is passed over. zsh
806
+ // reads the first `}` as the close, the default.
807
+ const SEQUENCE = /^(-?\d+|.)\.\.(-?\d+|.)(?:\.\.-?\d+)?$/s;
808
+ // Bash's rule may scan from each `{` to the end of its word: past this many characters scanned for one word, the
809
+ // word is not judged (refused), so a long word of `{x}` cannot cost a scan per brace (#498 review).
810
+ const BASH_BRACE_SCAN = 65536;
811
+ function braceExpand(x, budget = { left: BRACE_CAP }, opts = {}) {
812
+ if (x.length > BRACE_WORD || Date.now() > deadline) return null;
813
+ // Nothing to expand: no scan of its braces, whatever their nesting.
814
+ if (!x.includes(',') && !x.includes('..')) return --budget.left < 0 ? null : [x];
815
+ const lastSep = Math.max(x.lastIndexOf(','), x.lastIndexOf('..'));
816
+ for (let i = x.indexOf('{'); i >= 0 && i < lastSep; i = x.indexOf('{', i + 1)) {
817
+ if (Date.now() > deadline) return null;
818
+ let depth = 0, close = -1;
819
+ const commas = [];
820
+ for (let j = i; j < x.length; j++) {
821
+ if (x[j] === '{') depth++;
822
+ else if (x[j] === '}') {
823
+ if (opts.bash && depth === 1 && !commas.length && !(j - i - 1 <= 64 && SEQUENCE.test(x.slice(i + 1, j)))) continue;
824
+ depth--; if (depth === 0) { close = j; break; }
825
+ } else if (x[j] === ',' && depth === 1) commas.push(j);
826
+ }
827
+ if (opts.bash && (budget.scanned = (budget.scanned ?? 0) + (close < 0 ? x.length : close) - i) > BASH_BRACE_SCAN) return null;
828
+ if (close < 0) { if (opts.bash) continue; break; }
829
+ const body = x.slice(i + 1, close), pre = x.slice(0, i), post = x.slice(close + 1);
830
+ let alts = null;
831
+ if (commas.length) {
832
+ alts = [];
833
+ let from = i + 1;
834
+ for (const c of [...commas, close]) { alts.push(x.slice(from, c)); from = c + 1; }
835
+ } else {
836
+ const m = SEQUENCE.exec(body);
837
+ if (m) {
838
+ const num = /^-?\d+$/.test(m[1]) && /^-?\d+$/.test(m[2]);
839
+ if (num) alts = [m[1]];
840
+ else if (m[1].length === 1 && m[2].length === 1) {
841
+ const a = m[1].charCodeAt(0), b = m[2].charCodeAt(0);
842
+ if (Math.abs(b - a) + 1 > BRACE_CAP) return null;
843
+ alts = [];
844
+ for (let k = a; a <= b ? k <= b : k >= b; k += a <= b ? 1 : -1) alts.push(String.fromCharCode(k));
845
+ }
846
+ }
847
+ }
848
+ if (!alts) continue;
849
+ const out = [];
850
+ for (const alt of alts) {
851
+ const more = braceExpand(pre + alt + post, budget, opts);
852
+ if (!more) return null;
853
+ for (const y of more) out.push(y);
854
+ }
855
+ return out;
856
+ }
857
+ // A finished word: only these count against the cap.
858
+ return --budget.left < 0 ? null : [x];
859
+ }
860
+ // A word's `$(…)`, backticks and `${…}` with their braces and commas shielded (#498): to bash and zsh a brace
861
+ // list does not see into them (`{$(echo '}'),-n}` is `$(echo '}')` and `-n`).
862
+ function shieldExpansions(raw, mode = {}) {
863
+ let out = '';
864
+ let index = null;
865
+ for (let k = 0; k < raw.length; k++) {
866
+ const ch = raw[k];
867
+ let end = -1;
868
+ if (ch === '$' && raw[k + 1] === '(') { end = substitutionEnd(raw, k + 2, () => (index ??= lineIndex(raw)), { ends: mode.ends }); if (end < 0) return null; }
869
+ else if (ch === '`') end = backtickEnd(raw, k + 1);
870
+ else if (ch === '$' && raw[k + 1] === '{') {
871
+ let d = 0;
872
+ for (let j = k + 1; j < raw.length; j++) { if (raw[j] === '{') d++; else if (raw[j] === '}' && --d === 0) { end = j; break; } }
873
+ if (end < 0) end = raw.length;
874
+ }
875
+ if (end < 0) { out += ch; continue; }
876
+ out += [...raw.slice(k, end + 1)].map(shieldBrace).join('');
877
+ k = end;
878
+ }
879
+ return out;
880
+ }
881
+ // A word quoted for a shell line, so a carried command re-read as a line keeps its words (`find -exec sh -c '…'`).
882
+ const shq = (x) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(x) ? x : `'${x.replace(/'/g, "'\\''")}'`);
271
883
  function shellC(words) {
272
884
  const w = stripPrefix(words);
273
885
  if (!w.length) return null;
274
886
  const prog = programOf(w[0]);
275
- if (['bash', 'sh', 'zsh', 'dash', 'ksh'].includes(prog)) {
887
+ if (SHELLS.includes(prog)) {
276
888
  const c = w.findIndex((x, n) => n > 0 && /^-[A-Za-z]*c[A-Za-z]*$/.test(x));
277
- return c > 0 && c + 1 < w.length ? w[c + 1] : null;
889
+ if (c < 0) return null;
890
+ // The line is the first word after the options that follow `-c` (#495): `bash -c -- "…"`, `bash -c -x "…"`,
891
+ // and `-o NAME` / `-O NAME`, which take a value.
892
+ let k = c + 1;
893
+ while (k < w.length) {
894
+ if (w[k] === '--' || w[k] === '-') { k++; break; }
895
+ if (/^[-+][oO]$/.test(w[k])) { k += 2; continue; }
896
+ if (/^[-+][A-Za-z]+$/.test(w[k])) { k++; continue; }
897
+ break;
898
+ }
899
+ return k < w.length ? w[k] : null;
278
900
  }
279
901
  const r = runnerOf(w);
280
902
  if (!r) return null;
@@ -298,6 +920,59 @@ function shellC(words) {
298
920
  return null;
299
921
  }
300
922
 
923
+ // Every command line a part carries and runs (#495): a shell's `-c` line (`shellC`); `env -S "<line>"`; each
924
+ // `find … -exec|-execdir|-ok|-okdir <cmd…> ;|+`; a `git -c alias.NAME=VALUE … NAME …` (a `!VALUE` is a shell
925
+ // line, any other VALUE runs as `git VALUE …`); and `eval <args>`, joined.
926
+ function innerLines(part) {
927
+ const out = [];
928
+ const c = shellC(part);
929
+ if (c !== null) out.push(c);
930
+ const lead = part.slice(0, part.length - stripPrefix(part).length);
931
+ const envAt = lead.lastIndexOf('env') >= 0 ? lead.indexOf('env') : (part[0] === 'env' ? 0 : -1);
932
+ if (envAt >= 0) {
933
+ for (let i = envAt + 1; i < part.length; i++) {
934
+ const a = part[i];
935
+ if (a === '-S' || a === '--split-string') { out.push([part[i + 1] ?? '', ...part.slice(i + 2)].join(' ')); break; }
936
+ const m = /^(?:-S|--split-string=)(.+)$/.exec(a);
937
+ if (m) { out.push([m[1], ...part.slice(i + 1)].join(' ')); break; }
938
+ // `env`'s options that take a value come before `-S` too (`env -u X -S "…"`).
939
+ if (['-u', '--unset', '-C', '--chdir', '-a', '--argv0'].includes(a)) { i++; continue; }
940
+ if (!a.startsWith('-') && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(a)) break;
941
+ }
942
+ }
943
+ const w = stripPrefix(part);
944
+ const prog = w.length ? programOf(w[0]) : '';
945
+ if (prog === 'find') {
946
+ for (let i = 1; i < w.length; i++) {
947
+ if (!/^-(exec|execdir|ok|okdir)$/.test(w[i])) continue;
948
+ let j = i + 1;
949
+ while (j < w.length && w[j] !== ';' && w[j] !== '+') j++;
950
+ out.push(w.slice(i + 1, j).map(shq).join(' '));
951
+ i = j;
952
+ }
953
+ }
954
+ if (prog === 'git') {
955
+ const alias = new Map();
956
+ let i = 1;
957
+ while (i < w.length && w[i].startsWith('-')) {
958
+ const m = w[i] === '-c' ? /^alias\.([^=]+)=(.*)$/s.exec(w[i + 1] ?? '') : null;
959
+ if (m) alias.set(m[1].toLowerCase(), m[2]);
960
+ i += GIT_VALUE_OPTIONS.has(w[i]) ? 2 : 1;
961
+ }
962
+ // Aliases may name aliases (`-c alias.a=b -c alias.b='push --force' a`): followed a few steps.
963
+ let rest = w.slice(i);
964
+ for (let step = 0; step < 5 && rest.length; step++) {
965
+ const value = alias.get(rest[0].toLowerCase());
966
+ if (value === undefined) break;
967
+ if (value.startsWith('!')) { out.push([value.slice(1), ...rest.slice(1).map(shq)].join(' ')); break; }
968
+ out.push(['git', value, ...rest.slice(1).map(shq)].join(' '));
969
+ rest = [...value.split(/\s+/).filter(Boolean), ...rest.slice(1)];
970
+ }
971
+ }
972
+ if (prog === 'eval') out.push(w.slice(1).join(' '));
973
+ return out;
974
+ }
975
+
301
976
  // The yad argv after the program, or null when the part does not run yad: `yad …` (any path, `yad.mjs` too),
302
977
  // yadflow's `yad` through a package runner (`runnerOf`), or `node [options] …/yad.mjs …`.
303
978
  function yadArgs(words) {
@@ -461,39 +1136,774 @@ function platformApproval(words) {
461
1136
  }
462
1137
 
463
1138
  // The verdict for one shell command line: `{allow: true}` or `{allow: false, message}`.
464
- export function agentGuardDecision(line, depth = 0) {
465
- if (typeof line !== 'string' || !line.trim()) return { allow: true };
466
- const parts = shellParts(line);
467
- // The commands a `$(…)` or backticks run are judged too (a few levels deep at most).
468
- if (depth < 3) {
469
- for (const sub of parts.subs) {
470
- const v = agentGuardDecision(sub, depth + 1);
1139
+ // Bash and zsh read a CR as a character of a word; a shell that drops CRs (Git Bash with `igncr`) does not, and
1140
+ // reads `\` + CR + LF as a line join. Refuse under either reading (#353, #492): a line holding a CR is judged
1141
+ // again with every CR removed, at every depth, since a `bash -c` string built from quoted pieces holds one only
1142
+ // once its quotes are gone. A line too long to judge in a hook's time is refused, never let through.
1143
+ export const MAX_JUDGED = 1_000_000;
1144
+ // Every reading costs time, so the whole judgement has a budget: past it the line is refused, as a line too long
1145
+ // is — a hook that runs out its harness's time lets the command through (#492).
1146
+ // (agentGuardPreapproval asks again for an allowed line, so a hook can spend it twice: about 10 s at worst, well
1147
+ // under a harness's hook timeout. Each reading is linear, so a 1 MB line costs well under a second per reading.)
1148
+ export const JUDGE_BUDGET_MS = 5000;
1149
+ let deadline = Infinity;
1150
+ // How many characters of `case` words one reading may scan (#498 review round 2).
1151
+ const CASE_SCAN = 1 << 20;
1152
+ const caseLeft = { n: Infinity };
1153
+ // How many characters of readings one reading of the command may build: the joins of what parts print, and the
1154
+ // words a `$(…)` is read into (#498 review: each `$(…)` reading paired with a long one, or many joins each under
1155
+ // a per-join cap, ran the hook out of memory before the 5 s cut-off, and a crashed hook lets the command run).
1156
+ // Past it, the line is refused. A 900,000-character commit message through `printf … | cat | cat` builds about 40
1157
+ // times its length.
1158
+ const BUILT_CHARS = 64 * 1_000_000;
1159
+ const built = { n: 0 };
1160
+ const TOO_MANY_READINGS = { allow: false, message: 'yad agent guard: this command has too many `case` words inside `$(…)` to judge. Run it as separate commands.' };
1161
+ const OUT_OF_TIME = { allow: false, message: 'yad agent guard: this command took too long to judge. Run it as separate commands.' };
1162
+ // The files a reading of the command writes (#498, row 8): each path's texts, every one ever written (a write
1163
+ // that may not run must not hide an earlier one), plus the text a run of `>>` writes in all. One map per reading
1164
+ // of the top-level command, shared by every line it carries, so `echo … > f; bash -c 'bash f'` is seen.
1165
+ // `seen` logs each read as [path, the file's version then]; `appends` counts `>>` writes. A pass whose reads all
1166
+ // saw the final version, with no `>>`, would be judged the same again, so it is not (see judgeLine).
1167
+ const files = { map: new Map(), judged: 0, writes: 0, version: 0, seen: [], appends: 0 };
1168
+ const resetFiles = () => { files.map = new Map(); files.judged = 0; files.writes = 0; files.version = 0; files.seen = []; files.appends = 0; };
1169
+ const TOO_MUCH_WRITTEN = { allow: false, message: 'yad agent guard: this command runs files it writes too many times, or too much text, to judge. Run it as separate commands.' };
1170
+ // `ends`: the end rule the reading this line came from uses (#498); a `$(…)` inside a line is read by the same
1171
+ // shell. Unset for a line read afresh (the top line, or what `bash -c` or `eval` runs). `redir` likewise (#518): the
1172
+ // redirect reading of the reading this `$(…)` came from — '' for main's, 'bash' or 'zsh' — or null to read afresh.
1173
+ export function agentGuardDecision(line, depth = 0, ends = undefined, redir = null) {
1174
+ if (typeof line === 'string' && line.length > MAX_JUDGED) {
1175
+ return { allow: false, message: `yad agent guard: this command is too long to judge (${line.length} characters, more than ${MAX_JUDGED}). Write what it carries to a file with your editor, or run it as separate commands.` };
1176
+ }
1177
+ if (depth > 0) return judgeReadings(line, depth, ends, redir);
1178
+ deadline = Date.now() + JUDGE_BUDGET_MS;
1179
+ caseLeft.n = CASE_SCAN;
1180
+ built.n = 0;
1181
+ resetFiles();
1182
+ // A reading of what a command writes or prints also stops at the deadline, and says "too much written": past
1183
+ // the deadline, the refusal says what stopped it — the time (#535 CI: a slow runner got the wrong reason).
1184
+ const timed = (d) => (d === TOO_MUCH_WRITTEN && Date.now() > deadline ? OUT_OF_TIME : d);
1185
+ try {
1186
+ return timed(judgeReadings(line, depth));
1187
+ } catch (e) {
1188
+ if (e?.code === 'YAD_GUARD_OUTPUT_LIMIT') return timed(TOO_MUCH_WRITTEN);
1189
+ if (e?.code === 'YAD_GUARD_TOO_DEEP') return TOO_DEEP;
1190
+ if (e?.code === 'YAD_GUARD_TOO_MANY_PROCSUBS') return TOO_MANY_PROCSUBS;
1191
+ if (e?.code === 'YAD_GUARD_BLOCKS_DEEP') return { allow: false, message: 'yad agent guard: this command nests `if`, `for`, `while` or `( … )` blocks too deep to judge. Run it as separate commands.' };
1192
+ // A line the reader cannot judge is refused, never let through: the payload was read, so this is a bug here.
1193
+ return { allow: false, message: `yad agent guard: this command could not be judged (${e?.message ?? e}). Run it as separate commands, and report it with \`yad report\`.` };
1194
+ } finally {
1195
+ deadline = Infinity;
1196
+ caseLeft.n = Infinity;
1197
+ built.n = 0;
1198
+ resetFiles();
1199
+ }
1200
+ }
1201
+ // Where the first heredoc whose end word expands (`<<E$x`, `<<"E\`x\`"`) opens, or -1: read from the actual matches,
1202
+ // one `<<` at a time, so it is linear (a regex over the line backtracked: quadratic on a run of `<<`).
1203
+ function firstExpandingHeredoc(text) {
1204
+ for (let i = text.indexOf('<<'); i >= 0; i = text.indexOf('<<', i + 2)) {
1205
+ const m = heredocAt(text, i);
1206
+ if (m?.expands) return i;
1207
+ }
1208
+ return -1;
1209
+ }
1210
+ // Every reading the shells may make of the line: as written; with CRs dropped (a CR-dropping shell); with every
1211
+ // `\` + newline join made, CRs dropped first (a `$\<LF>(`, an end word split by a join: `EO\<LF>F`); and, where
1212
+ // the line has the context the reader does not track, each mode of shellParts. Refused if any reading refuses.
1213
+ function judgeReadings(line, depth, ends, inherited = null) {
1214
+ if (typeof line !== 'string') return { allow: true };
1215
+ // The end rules of `$(…)` (#498): main's, bash 3.2's and zsh's (see substitutionEnd).
1216
+ // A line inside a `$(…)` keeps its reading's rule; a fresh one gets each rule that can differ here.
1217
+ const rules = ends !== undefined ? [ends] : [''];
1218
+ if (ends === undefined && line.includes('$(')) {
1219
+ const ansi = line.includes('$\'') || line.includes('#');
1220
+ if (ansi || line.includes('`')) rules.push('bash');
1221
+ if (ansi || /\bcase\b/.test(line)) rules.push('zsh');
1222
+ // #516: the rarer forms, as readings of their own beside main's (see substitutionEnd).
1223
+ if (line.includes('<<')) rules.push('bash+');
1224
+ if (/\bcase\b/.test(line)) rules.push('zsh+');
1225
+ }
1226
+ const texts = [line];
1227
+ if (line.includes('\r')) texts.push(line.replace(/\r/g, ''));
1228
+ if (/\\\r?\n/.test(line)) texts.push(line.replace(/\r/g, '').replace(/\\\n/g, ''));
1229
+ // #518: how bash and zsh read the word after `>&` / `<&`, and zsh's `>!`, `>>!`, `>>|` and `>&|` (see shellParts).
1230
+ // A dimension of its own, crossed with every end rule above: main's redirect reading stays under each of them, and
1231
+ // these only add readings (review 1 — tied to the end rule, they replaced main's under bash's and zsh's). Only
1232
+ // where some text of the line has one: a descriptor number written right after `>&` (`2>&1`) reads the same in
1233
+ // every shell, so the common lines are read once. A blank before the number (`>& 1`) does not (review 1). A `-`
1234
+ // after `>&` brings them in even where it only closes (`2>&-`): bash's comment after it (`>&-#`) needs it.
1235
+ // `>|!` needs no zsh trigger: main's reading already writes the file `!` there, as zsh does.
1236
+ // A line inside a `$(…)` keeps its reading's shell (review 2), as it keeps its end rule: read again by every shell
1237
+ // at every level, a nested line was read 3 times more per level, and in shells the outer reading is not.
1238
+ const redirs = [undefined];
1239
+ if (inherited !== null) redirs[0] = inherited || undefined;
1240
+ else if (texts.some((t) => /[<>]&[ \t]*(?:[^\s0-9;&|<>()]|[0-9]+[^\s0-9;&|<>()])|[<>]&[ \t]+[0-9]/.test(t))) redirs.push('bash', 'zsh');
1241
+ else if (texts.some((t) => />>?!|>>\||>&[|!]/.test(t))) redirs.push('zsh');
1242
+ const expandsAt = firstExpandingHeredoc(line);
1243
+ const flags = [];
1244
+ if (expandsAt >= 0) flags.push('literalExpanding');
1245
+ if (/[()]#/.test(line)) flags.push('hashAfterParen');
1246
+ // A `#` right after `|` is a comment in command position, text in `[[ =~ ]]` (#495).
1247
+ if (/\|#/.test(line)) flags.push('hashAfterBar');
1248
+ if (/<[0-9]*-[0-9]*>/.test(line)) flags.push('numericGlob');
1249
+ // Every combination of the readings that apply (at most 16).
1250
+ const flagModes = [{}];
1251
+ for (const f of flags) for (const m of flagModes.slice()) flagModes.push({ ...m, [f]: true });
1252
+ const modes = [];
1253
+ // The rarer readings (#516) take only the two `#` flags, `)#` and `|#`: a `#'` right after a `)` or `|` on an
1254
+ // earlier line otherwise hides the forms they read (review rounds 2 and 3). Each is one more pass over the whole line, and with every flag and text
1255
+ // too they doubled the time on a long line.
1256
+ const rareModes = [{}];
1257
+ for (const f of ['hashAfterParen', 'hashAfterBar']) if (flags.includes(f)) for (const m of rareModes.slice()) rareModes.push({ ...m, [f]: true });
1258
+ // #518: each shell's redirect reading is crossed with every end rule, the rarer ones too; main's (no `redir`) stays
1259
+ // under all of them.
1260
+ for (const redir of redirs) for (const rule of rules) for (const m of rule.endsWith('+') ? rareModes : flagModes) modes.push(redir ? { ...m, ends: rule, redir } : { ...m, ends: rule });
1261
+ // The rarer readings are bash 3.2's and zsh's, and neither drops a CR (Git Bash, which can, is bash 4 or later): the
1262
+ // line as written, and with its `\` + newline joins made.
1263
+ const rareTexts = /\\\n/.test(line) ? [line, line.replace(/\\\n/g, '')] : [line];
1264
+ for (const mode of modes) {
1265
+ for (const text of mode.ends?.endsWith('+') ? rareTexts : texts) {
1266
+ // Each reading of the command gets its own budget for `case` words (#498).
1267
+ if (depth === 0) { caseLeft.n = CASE_SCAN; built.n = 0; resetFiles(); }
1268
+ const v = judgeLine(text, depth, mode);
471
1269
  if (!v.allow) return v;
1270
+ if (depth === 0) {
1271
+ const api = {
1272
+ // Each output parse gets its own case scan.
1273
+ shellParts: (s, m) => { const saved = caseLeft.n; caseLeft.n = CASE_SCAN; try { return shellParts(s, m); } finally { caseLeft.n = saved; } },
1274
+ stripPrefix, programOf, bareShell, scriptAt, innerLines,
1275
+ judge: (t) => agentGuardDecision(t, 1),
1276
+ charge: (n) => { if ((built.n += n) > BUILT_CHARS || Date.now() > deadline) throw Object.assign(new Error('output reading budget exceeded'), { code: 'YAD_GUARD_OUTPUT_LIMIT' }); } };
1277
+ // Read as bash prints, then as zsh prints when the two may differ (escapes, zsh's `echo -`). Each pass
1278
+ // gets its own text budget, as each reading does: charged on top of what judgeLine just built, a long
1279
+ // text through a few `tee` stages was refused where main allows it (#532 review 11). The deadline is shared.
1280
+ for (const zsh of zshDiffers(text) ? [false, true] : [false]) {
1281
+ built.n = 0;
1282
+ const extra = streamGuard(text, mode, api, zsh);
1283
+ if (!extra.allow) return extra;
1284
+ }
1285
+ }
472
1286
  }
473
1287
  }
474
- for (const part of parts) {
475
- // `bash -c "<line>"`: the line it runs is judged too (a few levels deep at most).
476
- const inner = shellC(part);
477
- if (inner !== null && depth < 3) {
478
- const v = agentGuardDecision(inner, depth + 1);
479
- if (!v.allow) return v;
1288
+ // An end word that expands can end the heredoc on any line, whatever the variable holds (`bash -c "cat <<E$x …"`
1289
+ // with an empty $x ends at `E`): each line is judged on its own too, so the command after it is seen wherever
1290
+ // the heredoc ends. Only refuses more.
1291
+ if (expandsAt >= 0) {
1292
+ for (const text of texts) {
1293
+ const from = firstExpandingHeredoc(text);
1294
+ for (const one of text.slice(from < 0 ? 0 : from).split('\n')) {
1295
+ for (const redir of redirs) for (const rule of rules) {
1296
+ if (depth === 0) { caseLeft.n = CASE_SCAN; built.n = 0; resetFiles(); }
1297
+ const v = judgeLine(one, depth, redir ? { ends: rule, redir } : { ends: rule });
1298
+ if (!v.allow) return v;
1299
+ }
1300
+ }
480
1301
  }
481
- const args = yadArgs(part);
482
- if (args) {
483
- const { words, flags, help } = yadWords(args);
484
- if (!help && classify(words, flags) === 'human-only') {
485
- return { allow: false, message: `yad agent guard: \`yad ${words.join(' ')}${flags.includes('manual') ? ' --manual' : ''}\` is the person's to run, never the agent's (an approval, a gate comment or advance or reopen, or a commit past the ledger guard). Ask the person to run it themselves — in Claude Code they type it with \`!\` in front — then confirm by reading (\`yad gate status\` / \`yad guide --json\`).` };
1302
+ }
1303
+ return { allow: true };
1304
+ }
1305
+ // The four refusals for one part's words.
1306
+ function partVerdict(part) {
1307
+ const args = yadArgs(part);
1308
+ if (args) {
1309
+ const { words, flags, help } = yadWords(args);
1310
+ if (!help && classify(words, flags) === 'human-only') {
1311
+ return { allow: false, message: `yad agent guard: \`yad ${words.join(' ')}${flags.includes('manual') ? ' --manual' : ''}\` is the person's to run, never the agent's (an approval, a gate comment or advance or reopen, or a commit past the ledger guard). Ask the person to run it themselves — in Claude Code they type it with \`!\` in front — then confirm by reading (\`yad gate status\` / \`yad guide --json\`).` };
1312
+ }
1313
+ }
1314
+ if (platformApproval(part)) {
1315
+ return { allow: false, message: 'yad agent guard: approving or merging a PR/MR is the person\'s, never the agent\'s (the yadflow rules), even when your login could. Give the person the link and the exact steps, wait, then confirm by reading (`yad gate status` / `yad guide --json`).' };
1316
+ }
1317
+ if (hookSkip(part)) {
1318
+ return { allow: false, message: 'yad agent guard: skipping the git hooks (`--no-verify`, `-n`, `YAD_HOOK_DISABLE`, `core.hooksPath`) is the person\'s, never the agent\'s (the yadflow rules): it is the door past the ledger guard. When a hook refuses a commit, follow its message; if the commit must go through, the person runs `yad commit --manual --reason "<why>"` themselves (`!` in front in Claude Code).' };
1319
+ }
1320
+ if (forcePush(part)) {
1321
+ return { allow: false, message: 'yad agent guard: a force push is never the agent\'s (the yadflow rules). Tell the person why the push was refused and what a force push would overwrite; if it is needed, they run it themselves.' };
1322
+ }
1323
+ return { allow: true };
1324
+ }
1325
+ const TOO_MANY_BRACES = { allow: false, message: 'yad agent guard: this command\'s brace lists expand to too many words, or a word with them is too long, to judge. Write the words out, quote them, or run it as separate commands.' };
1326
+ const TOO_DEEP = { allow: false, message: 'yad agent guard: this command nests `$(…)`, backticks or `bash -c` too deep to judge. Run it as separate commands.' };
1327
+ // Text that reaches a shell (#498, rows 1, 2, 8). A path as the shell finds it again: `./f` and `d/../f` are `f`.
1328
+ const normPath = (p) => path.posix.normalize(p).replace(/^(?:\.\/+)+/, '');
1329
+ // At most this many texts are kept for one file; running a file with more is refused, and so is reading one
1330
+ // into anything a shell then runs.
1331
+ const FILE_TEXTS = 64;
1332
+ // What a read of a file past these limits gives: a text that refuses the line once a shell would run it, so a
1333
+ // file only printed (`cat notes.md`) is not refused for its size (#498 review).
1334
+ const OVER = '\0yad-guard-too-much-written\0';
1335
+ // Every text a file may hold when it is read (each write, and each reading of the whole run of `>>`), or null
1336
+ // when it holds too many, or too much text was read from files in all (each read is judged again, so this keeps
1337
+ // it linear).
1338
+ function fileTexts(p) {
1339
+ const key = normPath(p);
1340
+ const f = files.map.get(key);
1341
+ files.seen.push([key, f ? f.v : 0]);
1342
+ if (!f) return [];
1343
+ if (f.over || f.texts.size > FILE_TEXTS) return null;
1344
+ const out = [...f.texts];
1345
+ for (const a of f.all ?? []) if (!f.texts.has(a)) out.push(a);
1346
+ for (const t of out) if ((files.judged += t.length) > MAX_JUDGED) return null;
1347
+ // #518: the readings with no newline after a write that printed none are kept APART (`out.glued`), never in
1348
+ // the list: readings are paired by their place, and one put among them moves the pairs main makes (review 1).
1349
+ const glued = [];
1350
+ for (const a of [...(f.allOpen ?? []), ...(f.gluedTexts ?? [])]) if (!f.texts.has(a) && !glued.includes(a)) glued.push(a);
1351
+ for (const t of glued) if ((files.judged += t.length) > MAX_JUDGED) return null;
1352
+ if (glued.length) out.glued = glued;
1353
+ // The file's last write ended with no newline, so what is read after it runs on into its last line.
1354
+ if (f.open) out.open = true;
1355
+ return out;
1356
+ }
1357
+ // A write of `texts` (the readings of what a part prints) to a file: added to its texts, never replacing one.
1358
+ // `all` holds the readings of the whole file, should every write before have run: `>>` joins each reading of
1359
+ // what was there with each new one (side by side, as zipJoin does).
1360
+ function writeFile(target, texts, append) {
1361
+ files.writes++;
1362
+ const key = normPath(target);
1363
+ let f = files.map.get(key);
1364
+ if (!f) files.map.set(key, (f = { texts: new Set(), all: null, allOpen: null, gluedTexts: null, open: false, over: false, v: 0 }));
1365
+ if (append) files.appends++;
1366
+ const size = f.texts.size;
1367
+ const oldAll = f.all;
1368
+ const oldAllOpen = f.allOpen;
1369
+ const wasOver = f.over;
1370
+ const wasOpen = f.open;
1371
+ const gluedSize = f.gluedTexts?.size ?? 0;
1372
+ for (const t of texts) if (t !== '') f.texts.add(t);
1373
+ for (const t of texts.glued ?? []) if (t !== '' && !f.texts.has(t)) (f.gluedTexts ??= new Set()).add(t);
1374
+ // Joined one by one, not through zipJoin's reduce, so a long run of `>>` stays linear (#498 review).
1375
+ // #518: `allOpen` is the same run read with no newline after a write that printed none (`printf 'gh pr ' > f;
1376
+ // echo merge 1 >> f`), beside `all`, which keeps the newline reading. One list beside the other: linear too.
1377
+ if (append) {
1378
+ if (texts.length) {
1379
+ const old = f.all;
1380
+ if (old === null) { f.all = texts.slice(); f.allOpen = texts.glued?.length ? [...texts.glued, ...texts] : null; } else {
1381
+ const prior = f.allOpen ?? old;
1382
+ // The run kept apart also takes the new write's own readings kept apart (a `printf` format with its escapes
1383
+ // made), first, so they meet the first reading of what is there: this run pairs with nothing else, so the
1384
+ // order moves no reading main pairs.
1385
+ const next = texts.glued?.length ? [...texts.glued, ...texts] : texts;
1386
+ const n = Math.max(old.length, texts.length);
1387
+ const m = Math.max(prior.length, next.length);
1388
+ const glued = f.open || f.allOpen !== null || next !== texts;
1389
+ f.all = [];
1390
+ f.allOpen = glued ? [] : null;
1391
+ for (let j = 0; j < n; j++) f.all.push(`${old[Math.min(j, old.length - 1)]}\n${texts[Math.min(j, texts.length - 1)]}`);
1392
+ if (glued) for (let j = 0; j < m; j++) f.allOpen.push(`${prior[Math.min(j, prior.length - 1)]}${f.open ? '' : '\n'}${next[Math.min(j, next.length - 1)]}`);
486
1393
  }
1394
+ f.open = !!texts.open;
487
1395
  }
488
- if (platformApproval(part)) {
489
- return { allow: false, message: 'yad agent guard: approving or merging a PR/MR is the person\'s, never the agent\'s (the yadflow rules), even when your login could. Give the person the link and the exact steps, wait, then confirm by reading (`yad gate status` / `yad guide --json`).' };
1396
+ } else {
1397
+ for (const a of f.all ?? []) if (a !== '') f.texts.add(a);
1398
+ for (const a of f.allOpen ?? []) if (a !== '' && !f.texts.has(a)) (f.gluedTexts ??= new Set()).add(a);
1399
+ f.all = texts.length ? texts.slice() : null;
1400
+ f.allOpen = texts.glued?.length ? [...texts.glued, ...texts] : null;
1401
+ f.open = !!(texts.length && texts.open);
1402
+ }
1403
+ if ((f.all && (f.all.length > FILE_TEXTS || f.all.some((a) => a.length > MAX_JUDGED))) || (f.allOpen && (f.allOpen.length > FILE_TEXTS || f.allOpen.some((a) => a.length > MAX_JUDGED))) || (f.gluedTexts?.size ?? 0) > FILE_TEXTS) { f.all = null; f.allOpen = null; f.gluedTexts = null; f.over = true; }
1404
+ // A new version only when a read would now give something else.
1405
+ const same = (a, b) => a === b || (a !== null && b !== null && a.length === b.length && a.every((x, j) => x === b[j]));
1406
+ if (f.v === 0 || f.texts.size !== size || (f.gluedTexts?.size ?? 0) !== gluedSize || !same(oldAll, f.all) || !same(oldAllOpen, f.allOpen) || f.over !== wasOver || f.open !== wasOpen) f.v = ++files.version;
1407
+ }
1408
+ // The text each part is fed (its heredocs and here-strings), grouped once by part. A here-string's `$(…)` is also
1409
+ // read with its printed text in place (#498, row 2), one level deep: `bash <<< "$(echo '…; gh pr merge 5')"`.
1410
+ function fedOf(parts, mode, deep) {
1411
+ const fed = new Map();
1412
+ const add = (n, t) => { if (!fed.has(n)) fed.set(n, []); fed.get(n).push(t); };
1413
+ for (const x of parts.bodies) add(x.part, x.text);
1414
+ for (const x of parts.herestrings) {
1415
+ add(x.part, x.text);
1416
+ if (deep && x.subst) {
1417
+ const s = spellWord(x.subst, mode, true);
1418
+ if (s === null) return null;
1419
+ for (const ws of s) add(x.part, ws.join(' '));
1420
+ // Kept apart (`fed.apart`), as spellWord keeps them: `fed` heads printedOf's paired list (#518 review 2).
1421
+ for (const ws of s.glued ?? []) { fed.apart ??= new Map(); if (!fed.apart.has(x.part)) fed.apart.set(x.part, []); fed.apart.get(x.part).push(ws.join(' ')); }
1422
+ }
1423
+ }
1424
+ return fed;
1425
+ }
1426
+ // What part `n` prints, read from each of its spellings `lists` (words with the prefix stripped): the text it is
1427
+ // fed, `echo`'s words, `printf`'s two readings, and every text a `cat <file>` may hold (#498, row 8), with the
1428
+ // files of one `cat` also joined. `input` is what it reads from a pipe or a `<` file, which `cat` (with no file,
1429
+ // or `-`) and `tee` print. A file read past its limits gives OVER; null when its joins are too long (see zipJoin).
1430
+ function printedOf(fed, n, lists, input = []) {
1431
+ const out = [];
1432
+ const add = (...xs) => { for (const x of xs) { if ((built.n += x.length + 64) > BUILT_CHARS) throw Object.assign(new Error('output reading budget exceeded'), { code: 'YAD_GUARD_OUTPUT_LIMIT' }); out.push(x); } };
1433
+ for (const x of fed.get(n) ?? []) add(x);
1434
+ // #518: readings kept APART from the list (`out.glued`): those with no newline where a text printed none, and a
1435
+ // `printf` format with its escapes made. In the list they would move the pairs the joins make by place (review 1).
1436
+ const apart = [];
1437
+ for (const pw of lists) {
1438
+ if (!pw.length) continue;
1439
+ const prog = programOf(pw[0]);
1440
+ // Only `echo`'s leading options are options: `echo git commit -n` prints the `-n` (#498 review). zsh's `-`
1441
+ // (and `print`'s `--`) ends them and is not printed; `print -f` takes a format, as printf does.
1442
+ if (prog === 'echo' || prog === 'print') {
1443
+ let k = 1;
1444
+ let format = false;
1445
+ while (k < pw.length && (prog === 'echo' ? /^-[neE]+$/ : /^-[A-Za-z]+$/).test(pw[k])) { if (prog === 'print' && pw[k].includes('f')) format = true; if (pw[k].includes('n')) out.open = true; k++; }
1446
+ add(pw.slice(k).join(' '));
1447
+ // `\c` ends the output with no newline (zsh's echo always reads it, bash's with -e); `print -f` adds none, as printf.
1448
+ if (pw.slice(k).some((x) => x.includes('\\c')) || (format && !endsInNewline(pw[k] ?? ''))) out.open = true;
1449
+ // And its text with the escapes made (zsh's echo makes them, bash's with -e), apart.
1450
+ const made = printfEscapes(pw.slice(k).join(' '));
1451
+ if (made !== pw.slice(k).join(' ')) apart.push(made);
1452
+ // And main's reading, every `-n`/`-e`/`-E` word dropped wherever it stands: judged on its own, as main
1453
+ // judged it, and kept out of the joins (in the list, it moved the readings the joins pair, #498 review).
1454
+ if (prog === 'echo') (out.alone ??= []).push(pw.slice(1).filter((x) => !/^-[neE]+$/.test(x)).join(' '));
1455
+ if (pw[k] === '-' || (prog === 'print' && pw[k] === '--') || format) add(pw.slice(k + 1).join(' '));
1456
+ }
1457
+ // `printf` prints its format and its words; also its words after the format (`--` ends its options).
1458
+ if (prog === 'printf') {
1459
+ const f = pw[1] === '--' ? 2 : 1;
1460
+ add(pw.slice(1).join(' '), pw.slice(f).join(' '), pw.slice(f + 1).join(' '));
1461
+ // #518: a format that does not end in a newline prints none (`printf 'gh pr '`, `printf '%s' x`): what is
1462
+ // printed next runs on into the same line. Unknown counts as none; the newline reading is kept as well.
1463
+ if (!endsInNewline(pw[f] ?? '') || /(?:^|[^\\])(?:\\\\)*\\c/.test(pw[f] ?? '')) out.open = true;
1464
+ // And the format with its escapes made (`printf 'git push --force\n'` prints a line a shell runs), apart.
1465
+ const made = printfEscapes(pw.slice(f).join(' '));
1466
+ if (made !== pw.slice(f).join(' ')) apart.push(made);
1467
+ }
1468
+ if (prog === 'cat' || prog === 'tee') {
1469
+ // A word read past its limits stays, even as an option (`cat -$(cat f)` may be `cat -- h`, #498 review).
1470
+ const args = pw.slice(1).filter((a) => !a.startsWith('-') || a === '-' || (prog === 'cat' && a.includes(OVER)));
1471
+ if (prog === 'tee' || !args.length || args.includes('-')) { for (const x of input) add(x); for (const x of input.glued ?? []) apart.push(x); if (input.open) out.open = true; }
1472
+ if (prog === 'cat') {
1473
+ const per = [];
1474
+ for (const a of args) {
1475
+ if (a === '-') continue;
1476
+ // A file name read past its limits (`cat $(cat f)`): the file it names is unknown, so is what it prints
1477
+ // (#498 review: it read as no file, and `cat $(cat f) | bash` was let through).
1478
+ // Each file word costs a lookup and a list, counted too (#498 review: many words, each read again per reading).
1479
+ if ((built.n += 64 + a.length) > BUILT_CHARS) return null;
1480
+ if (a.includes(OVER)) { fileTexts(a); per.push([OVER]); continue; }
1481
+ const t = fileTexts(a);
1482
+ per.push(t === null ? [OVER] : t.length ? t : ['']);
1483
+ }
1484
+ // Every reading, empty ones too: the joins pair readings by their place, so dropping one moves the rest
1485
+ // (#498 review). Their memory is bounded by BUILT_CHARS.
1486
+ for (const t of per) { for (const x of t) add(x); for (const x of t.glued ?? []) apart.push(x); }
1487
+ if (per.length > 1) { const z = zipJoin(per); if (z === null) return null; for (const x of z) add(x); for (const x of z.glued ?? []) apart.push(x); }
1488
+ if (per.length && per[per.length - 1].open) out.open = true;
1489
+ }
490
1490
  }
491
- if (hookSkip(part)) {
492
- return { allow: false, message: 'yad agent guard: skipping the git hooks (`--no-verify`, `-n`, `YAD_HOOK_DISABLE`, `core.hooksPath`) is the person\'s, never the agent\'s (the yadflow rules): it is the door past the ledger guard. When a hook refuses a commit, follow its message; if the commit must go through, the person runs `yad commit --manual --reason "<why>"` themselves (`!` in front in Claude Code).' };
1491
+ }
1492
+ for (const t of fed.apart?.get(n) ?? []) apart.push(t);
1493
+ // What its spellings kept apart print (#518 review 2): read the same way, every reading of it kept apart.
1494
+ if (lists.glued?.length) {
1495
+ const more = printedOf(new Map(), n, lists.glued, input);
1496
+ if (more === null) return null;
1497
+ for (const t of more) apart.push(t);
1498
+ for (const t of more.glued ?? []) apart.push(t);
1499
+ if (more.open) out.open = true;
1500
+ }
1501
+ if (apart.length) out.glued = apart;
1502
+ return out;
1503
+ }
1504
+ // Does a printf format (or `print -f`'s) end in a newline: a real one, or `\n` after an even run of backslashes
1505
+ // (`\\n` prints a backslash and an n).
1506
+ const endsInNewline = (f) => f.endsWith('\n') || /(?:^|[^\\])(?:\\\\)*\\n$/.test(f);
1507
+ // A printf format's escapes made, as printf makes them: `\n`, `\t`, `\\`, and `\c` (nothing after it is printed).
1508
+ const printfEscapes = (s) => s.replace(/\\([ntc\\])/g, (_, e) => ({ n: '\n', t: '\t', c: '\0', '\\': '\\' }[e])).replace(/\0[\s\S]*$/, '');
1509
+ // Readings side by side: the j-th joins each list's j-th reading (its last, once it has no more) by newlines, as
1510
+ // their output is, so every reading is in one of them and the count stays the longest list's. Built from pieces,
1511
+ // one join each, so a long `cat f f f …` stays linear (#498 review). Null once the line's BUILT_CHARS are
1512
+ // spent: the line is refused. Never a text in place of the readings: a check that does not look for it would
1513
+ // let them through.
1514
+ // #518: a list marked `open` printed no newline at its end, so its text runs on into the next one's. Each such join
1515
+ // is also made with nothing between them, as more readings after the newline ones, which are always kept — one
1516
+ // more string per reading, so it stays linear. The mark is on the list, never in the text.
1517
+ // What a part prints that is piped on to the next part is that part's input, not text of its own beside it: its
1518
+ // missing newline is not glued to the next text (#518 review 1: `printf 'gh pr ' | cat; echo merge 1`).
1519
+ const producedFor = (outs, pipedOn) => (pipedOn && outs.open ? Object.assign(outs.slice(), outs.glued ? { glued: outs.glued } : {}) : outs);
1520
+ function zipCore(per, glue) {
1521
+ let n = 0;
1522
+ for (const p of per) n = Math.max(n, p.length);
1523
+ const out = [];
1524
+ for (let j = 0; j < n; j++) {
1525
+ const pieces = [];
1526
+ for (let q = 0; q < per.length; q++) {
1527
+ if ((q & 4095) === 0 && Date.now() > deadline) return [OVER];
1528
+ const x = per[q][Math.min(j, per[q].length - 1)];
1529
+ if ((built.n += x.length + 1) > BUILT_CHARS) return null;
1530
+ if (q) pieces.push(glue && per[q - 1].open ? '' : '\n');
1531
+ pieces.push(x);
493
1532
  }
494
- if (forcePush(part)) {
495
- return { allow: false, message: 'yad agent guard: a force push is never the agent\'s (the yadflow rules). Tell the person why the push was refused and what a force push would overwrite; if it is needed, they run it themselves.' };
1533
+ out.push(pieces.join(''));
1534
+ }
1535
+ return out;
1536
+ }
1537
+ // The readings joined, as before, in the list; the joins with no newline after an open text (and those made with
1538
+ // each list's own no-newline readings) kept APART in `.glued`, never in the list, where they would move the pairs a
1539
+ // later join or a word's spelling makes by place (#518 review 1). At most two more strings per reading: linear.
1540
+ function zipJoin(per) {
1541
+ const out = zipCore(per, false);
1542
+ if (out === null || (out.length === 1 && out[0] === OVER)) return out;
1543
+ const glued = [];
1544
+ const withOwn = per.some((p) => p.glued?.length);
1545
+ if (per.slice(0, -1).some((p) => p.open) || withOwn) {
1546
+ const g = zipCore(per, true);
1547
+ if (g === null) return null;
1548
+ const has = new Set(out);
1549
+ for (const x of g) if (!has.has(x)) glued.push(x);
1550
+ }
1551
+ if (withOwn) {
1552
+ const g = zipCore(per.map((p) => (p.glued?.length ? Object.assign(p.glued.slice(), { open: p.open }) : p)), true);
1553
+ if (g === null) return null;
1554
+ for (const x of g) glued.push(x);
1555
+ }
1556
+ if (glued.length) out.glued = glued;
1557
+ if (per.length && per[per.length - 1].open) out.open = true;
1558
+ return out;
1559
+ }
1560
+ // The readings of what a `$(…)` prints, when its text says (#498, row 2): `$(<f)`, and the `echo`, `printf`,
1561
+ // `cat` and heredoc text of its parts, in order, trailing newlines dropped. One level: a `$(…)` inside is not
1562
+ // read. `['']` when nothing it prints is known, null when a file read holds too much.
1563
+ function subOutputs(text, mode) {
1564
+ const m = /^\s*<\s*([^\s;&|<>()$`'"\\]+)\s*$/.exec(text);
1565
+ if (m) { const t = fileTexts(m[1]); return t === null ? [OVER] : (t.length ? t : Object.assign([''], t.glued ? { glued: t.glued } : {})); }
1566
+ if (!/echo|printf|print|cat|<</.test(text.replace(/[\\'"]/g, ''))) return [''];
1567
+ // What a `$(…)` prints is read by the reading's shell too (review 2: `$(echo gh >& 1 pr merge 5)` runs the merge).
1568
+ const sp = shellParts(text, { ends: mode.ends, redir: mode.redir });
1569
+ if (sp.tooComplex) return [''];
1570
+ const fed = fedOf(sp, mode, false);
1571
+ const per = [];
1572
+ let prev = [];
1573
+ for (let k = 0; k < sp.length; k++) {
1574
+ if (Date.now() > deadline) return [OVER];
1575
+ const t = printedOf(fed, k, spellingsOf(sp, k, null), sp.piped.has(k) ? prev : []);
1576
+ if (t === null) return null;
1577
+ if (t.length) per.push(producedFor(t, sp.piped.has(k + 1)));
1578
+ prev = t;
1579
+ }
1580
+ const z = zipJoin(per);
1581
+ if (z === null) return null;
1582
+ const out = z.map((x) => x.replace(/\n+$/, ''));
1583
+ // Kept apart, as zipJoin keeps them (#518 review 1): spellWord reads them in a pass of their own.
1584
+ const apart = [...(z.glued ?? []), ...per.flatMap((p) => p.glued ?? [])].map((x) => x.replace(/\n+$/, ''));
1585
+ const res = out.length ? out : [''];
1586
+ if (apart.length) res.glued = apart;
1587
+ return res;
1588
+ }
1589
+ // A word with each `$(…)` replaced by a reading of what it prints, as the shell makes it: split on blanks into
1590
+ // words outside double quotes (an empty one drops out), kept whole inside them. One list of words per reading,
1591
+ // or null when a file read holds too much.
1592
+ function spellWord(entry, mode, noSplit = false) {
1593
+ const outs = [];
1594
+ for (const s of entry.subs) { const o = subOutputs(s.text, mode); if (o === null) return null; outs.push(o); }
1595
+ const res = spellPass(entry, outs, noSplit);
1596
+ // #518: the readings a `$(…)` prints that are kept apart, in a pass of their own after main's, so they move none
1597
+ // of the pairs main's pass makes by place (review 1).
1598
+ // Returned apart (`res.glued`), never in `res`, which its callers pair by place too (review 2).
1599
+ if (res !== null && outs.some((o) => o.glued?.length)) {
1600
+ const more = spellPass(entry, outs.map((o) => (o.glued?.length ? o.glued : o)), noSplit);
1601
+ if (more === null) return null;
1602
+ if (more.length) res.glued = more;
1603
+ }
1604
+ return res;
1605
+ }
1606
+ function spellPass(entry, outs, noSplit) {
1607
+ let n = 1;
1608
+ for (const o of outs) n = Math.max(n, o.length);
1609
+ const res = [];
1610
+ for (let j = 0; j < n; j++) {
1611
+ const ws = [];
1612
+ let cur = '';
1613
+ let from = 0;
1614
+ let kept = false;
1615
+ entry.subs.forEach((s, q) => {
1616
+ cur += entry.word.slice(from, s.at);
1617
+ const text = outs[q][Math.min(j, outs[q].length - 1)];
1618
+ built.n += text.length + s.at - from;
1619
+ if (s.quoted || noSplit) { cur += text; kept = true; } else {
1620
+ const toks = text.split(/[ \t\n]+/);
1621
+ cur += toks[0];
1622
+ for (let t = 1; t < toks.length; t++) { if (cur !== '') ws.push(cur); cur = toks[t]; }
1623
+ }
1624
+ from = s.at + s.len;
1625
+ });
1626
+ cur += entry.word.slice(from);
1627
+ if (cur !== '' || kept) ws.push(cur);
1628
+ if (built.n > BUILT_CHARS) return null;
1629
+ res.push(ws.map(unshieldBraces));
1630
+ }
1631
+ return res;
1632
+ }
1633
+ // A part's spellings, prefix stripped: as written, and with the backslashes double quotes keep (#498). `subst`
1634
+ // adds the spellings with each `$(…)` read for what it prints.
1635
+ function spellingsOf(parts, n, subst) {
1636
+ const part = parts[n];
1637
+ const out = [stripPrefix(part)];
1638
+ const posix = parts.posix[n];
1639
+ if (posix) { const kept = part.slice(); for (const [k, v] of posix) kept[k] = v; out.push(stripPrefix(kept)); }
1640
+ if (subst) for (const s of subst) out.push(stripPrefix(s));
1641
+ // The spellings kept apart (#518 review 2): printedOf reads them into its own readings kept apart.
1642
+ if (subst?.glued?.length) out.glued = subst.glued.map(stripPrefix);
1643
+ return out;
1644
+ }
1645
+ // The spellings of part `n` with each `$(…)` read for what it prints (#498, row 2), whole parts with the prefix;
1646
+ // null when a file read holds too much. Only the words with a `$(…)` change.
1647
+ function substituted(parts, n, mode) {
1648
+ const subst = parts.subst[n];
1649
+ if (!subst) return [];
1650
+ const part = parts[n];
1651
+ const alts = new Map();
1652
+ let m = 0;
1653
+ for (const [k, e] of subst) {
1654
+ const a = spellWord(e, mode);
1655
+ if (a === null) return null;
1656
+ alts.set(k, a); m = Math.max(m, a.length);
1657
+ }
1658
+ const pass = (pick, count) => {
1659
+ const res = [];
1660
+ for (let j = 0; j < count; j++) {
1661
+ if (Date.now() > deadline) return null;
1662
+ const ws = [];
1663
+ for (let k = 0; k < part.length; k++) {
1664
+ const a = pick(k);
1665
+ // Every word is copied once per reading, so each is counted (#498 review).
1666
+ if (!a) { built.n += part[k].length + 1; ws.push(part[k]); continue; }
1667
+ for (const x of a[Math.min(j, a.length - 1)]) { built.n += x.length + 1; ws.push(x); }
1668
+ }
1669
+ if (built.n > BUILT_CHARS) return null;
1670
+ res.push(ws);
496
1671
  }
1672
+ return res;
1673
+ };
1674
+ const out = pass((k) => alts.get(k), m);
1675
+ if (out === null) return null;
1676
+ // #518 review 2: the spellings each word's `$(…)` gives apart (spellWord's `.glued`), in a pass of their own and
1677
+ // returned apart (`out.glued`): in `out` they would move the spellings printedOf pairs by place.
1678
+ if ([...alts.values()].some((a) => a.glued?.length)) {
1679
+ let m2 = 0;
1680
+ for (const a of alts.values()) m2 = Math.max(m2, (a.glued?.length ? a.glued : a).length);
1681
+ const more = pass((k) => { const a = alts.get(k); return a && (a.glued?.length ? a.glued : a); }, m2);
1682
+ if (more === null) return null;
1683
+ if (more.length) out.glued = more;
1684
+ }
1685
+ return out;
1686
+ }
1687
+ function judgeLine(line, depth, mode = {}) {
1688
+ if (typeof line !== 'string' || !line.trim()) return { allow: true };
1689
+ if (Date.now() > deadline) return OUT_OF_TIME;
1690
+ const parts = shellParts(line, mode);
1691
+ if (parts.tooComplex) return Date.now() > deadline ? OUT_OF_TIME : TOO_MANY_READINGS;
1692
+ // The commands a `$(…)` or backticks run are judged too, three levels deep; one deeper is refused (#492).
1693
+ if (parts.subs.length && depth >= 3) return TOO_DEEP;
1694
+ // At most twice, when the first pass writes a file (#498 review): a `$(…)` is judged before the parts that write, and a
1695
+ // loop or a function may run a file a later part writes (`g(){ bash f; }; echo … > f; g`). The second pass
1696
+ // judges it all again with the files the first one saw. Only refuses more.
1697
+ // Each pass reads the files on its own budget (#498 review: the second read halved it).
1698
+ // A second pass is needed only when a read in the first saw a file a later write changed, or a `>>` ran (a
1699
+ // second append joins the text again); otherwise it would judge the same texts again (#498 CI: twice at every
1700
+ // level made `x=$(echo a > f; bash f);` repeated pass the 5 s cut-off on a slower machine).
1701
+ const judgedBefore = files.judged;
1702
+ for (let pass = 0; pass < 2; pass++) {
1703
+ files.judged = judgedBefore;
1704
+ const writesBefore = files.writes;
1705
+ const seenFrom = files.seen.length;
1706
+ const appendsBefore = files.appends;
1707
+ const v = judgeParts(parts, depth, mode);
1708
+ if (!v.allow || files.writes === writesBefore) return v;
1709
+ if (files.appends === appendsBefore && !files.seen.slice(seenFrom).some(([k, ver]) => (files.map.get(k)?.v ?? 0) !== ver)) return v;
1710
+ }
1711
+ return { allow: true };
1712
+ }
1713
+ // Each process substitution's inner parts are walked once per owner; nested ones walk them again, so past this
1714
+ // many in all for one line the line is refused, not read on (#498 review: nested `bash <(` was quadratic).
1715
+ const PROCSUB_WALK = 200000;
1716
+ const TOO_MANY_PROCSUBS = { allow: false, message: 'yad agent guard: this command nests too many process substitutions (`<(…)`) to judge. Run it as separate commands.' };
1717
+ function judgeParts(parts, depth, mode) {
1718
+ for (const sub of parts.subs) {
1719
+ const v = agentGuardDecision(sub, depth + 1, mode.ends ?? '', mode.redir ?? '');
1720
+ if (!v.allow) return v;
1721
+ }
1722
+ // The text each part is fed, grouped once by part (a loop over every body for every part was quadratic).
1723
+ const fed = fedOf(parts, mode, true);
1724
+ if (fed === null) return TOO_MUCH_WRITTEN;
1725
+ const printed = [];
1726
+ const printedPer = [];
1727
+ // The process substitutions each part owns (#498, row 1), and what the part before this one printed (`tee`).
1728
+ const procsubs = new Map();
1729
+ for (const p of parts.procsubs) { if (!procsubs.has(p.from - 1)) procsubs.set(p.from - 1, []); procsubs.get(p.from - 1).push(p); }
1730
+ const pipedWrites = new Map();
1731
+ for (const p of parts.pipedWrites) { if (!pipedWrites.has(p.after)) pipedWrites.set(p.after, []); for (const wr of p.writes) pipedWrites.get(p.after).push(wr); }
1732
+ let before = [];
1733
+ let walked = 0;
1734
+ for (let n = 0; n < parts.length; n++) {
1735
+ const part = parts[n];
1736
+ // Every way the shell may read this part's words (#495): as written; with a command word that expands
1737
+ // (`$(echo gh)`, `${x:-gh}`, `=gh`, `$SHELL`) dropped (it may be empty) or as each guarded program or a
1738
+ // shell; and with its unquoted brace lists expanded, with the empty words kept (zsh) and dropped (bash).
1739
+ if (Date.now() > deadline) return OUT_OF_TIME;
1740
+ const w = stripPrefix(part);
1741
+ const variants = [part];
1742
+ // The backslashes kept in double quotes (#498): what `bash -c` and `eval` re-read.
1743
+ const posix = parts.posix[n];
1744
+ if (posix) { const kept = part.slice(); for (const [k, v] of posix) kept[k] = v; variants.push(kept); }
1745
+ const braced = parts.braced[n];
1746
+ if (braced) {
1747
+ // Four readings: the first-`}` rule with the empty words kept (zsh) and dropped (bash), as before; then with
1748
+ // `$(…)`, backticks and `${…}` opaque, by the first-`}` rule with empty words kept (zsh) and by bash's own
1749
+ // rule with them dropped (#498). Duplicates are judged once.
1750
+ const readings = [{}, { drop: true }, { shield: true }, { shield: true, bash: true, drop: true }];
1751
+ const seen = new Set();
1752
+ for (const r of readings) {
1753
+ const out = [];
1754
+ let added = 0;
1755
+ for (let k = 0; k < part.length; k++) {
1756
+ if (!braced.has(k)) { out.push(part[k]); continue; }
1757
+ const raw = r.shield ? shieldExpansions(braced.get(k), mode) : braced.get(k);
1758
+ const e = raw === null ? null : braceExpand(raw, { left: BRACE_CAP }, { bash: r.bash });
1759
+ if (!e || (added += e.length - 1) > 4 * BRACE_CAP) return Date.now() > deadline ? OUT_OF_TIME : TOO_MANY_BRACES;
1760
+ // Only an expansion's empty words are dropped, as bash does; a quoted `''` is a word.
1761
+ for (const y of e) if (!(r.drop && y === '')) out.push(unshieldBraces(y));
1762
+ }
1763
+ const key = JSON.stringify(out);
1764
+ if (!seen.has(key)) { seen.add(key); variants.push(out); }
1765
+ }
1766
+ }
1767
+ // Every reading so far is one a real shell makes; the ones below are not. Each `$(…)` read for what it prints
1768
+ // (#498, row 2): `bash -c "$(cat <<'EOF' … EOF)"` runs the heredoc's text. Then the command-word guesses.
1769
+ const real = variants.length;
1770
+ const subst = substituted(parts, n, mode);
1771
+ if (subst === null) return TOO_MUCH_WRITTEN;
1772
+ // A file read past its limits whose text is the command (`$(<f)`): refused, as a shell would run it.
1773
+ // A file read past its limits, in a word of a command that is not a printer (`gh $(<f)`): refused.
1774
+ // The spellings kept apart (#518 review 2) are judged too: `variants` pairs nothing by place.
1775
+ for (const s of [...subst, ...(subst.glued ?? [])]) {
1776
+ const sw = stripPrefix(s);
1777
+ if (sw.length && (sw[0].includes(OVER) || (!PRINTERS.has(programOf(sw[0])) && sw.some((x) => x.includes(OVER))))) return TOO_MUCH_WRITTEN;
1778
+ variants.push(s);
1779
+ }
1780
+ for (const base of variants.slice()) {
1781
+ const bw = stripPrefix(base);
1782
+ const raw = base[base.length - bw.length] ?? '';
1783
+ if (bw.length && (/[$`]/.test(raw) || /^=[A-Za-z]/.test(raw))) {
1784
+ const bl = base.slice(0, base.length - bw.length);
1785
+ // Six copies of the words, counted like every other reading built (#498 review).
1786
+ let size = 0;
1787
+ for (const x of base) size += x.length + 1;
1788
+ if ((built.n += 6 * size) > BUILT_CHARS || Date.now() > deadline) return TOO_MUCH_WRITTEN;
1789
+ variants.push([...bl, ...bw.slice(1)], ...['gh', 'glab', 'git', 'yad', 'bash'].map((prog) => [...bl, prog, ...bw.slice(1)]));
1790
+ }
1791
+ }
1792
+ // The lines each variant carries (`bash -c`, `env -S`, `find -exec`, a git alias, `eval`) are judged too, as deep;
1793
+ // one deeper is refused. A shell that reads its input runs what it is fed: its own heredoc or here-string, and
1794
+ // any text an earlier part prints (a pipe, `tee`, a `cat <<EOF` body), each judged once, by the first shell.
1795
+ const carried = [];
1796
+ let readsInput = false;
1797
+ for (const vw of variants) for (const t of innerLines(vw)) carried.push(t);
1798
+ // A real shell (as written, or brace-expanded) takes all the text printed before it: through a pipe, a group
1799
+ // (`{ echo …; } | bash`), or a file it reads back. A command word only guessed to be a shell needs a real pipe:
1800
+ // otherwise any `$x` line after a docs heredoc would be judged as running it.
1801
+ let realShell = false;
1802
+ variants.forEach((vw, k) => { if (bareShell(stripPrefix(vw))) { readsInput = true; if (k < real) realShell = true; } });
1803
+ if (readsInput) {
1804
+ for (const t of fed.get(n) ?? []) carried.push(t);
1805
+ // Each text, and the texts of the parts before joined as their output is (`{ printf 'gh pr '; echo merge 5; }
1806
+ // | bash`, #498 review).
1807
+ if (realShell || parts.piped.has(n)) {
1808
+ for (const t of printed) carried.push(t);
1809
+ // Also joined by newlines, as their output is: a quote one text opens, a later one closes.
1810
+ if (printedPer.length > 1) { const z = zipJoin(printedPer); if (z === null) return TOO_MUCH_WRITTEN; for (const t of z) carried.push(t); for (const t of z.glued ?? []) carried.push(t); }
1811
+ printed.length = 0; printedPer.length = 0;
1812
+ }
1813
+ }
1814
+ // A process substitution this part runs as its script, or reads as its input (#498, row 1): what its parts
1815
+ // print, in order (`bash <(echo …)`, `source <(…)`, `bash < <(…)`, zsh's `=(…)`).
1816
+ // A command word that expands is also read as a shell (`$SHELL <(…)`), as for the part's own words.
1817
+ for (const p of procsubs.get(n) ?? []) {
1818
+ const owners = [p.owner];
1819
+ const ow0 = stripPrefix(p.owner);
1820
+ if (ow0.length && (/[$`]/.test(ow0[0]) || /^=[A-Za-z]/.test(ow0[0]))) owners.push([...p.owner.slice(0, p.owner.length - ow0.length), 'bash', ...ow0.slice(1)]);
1821
+ const maybeShell = p.maybe && (SHELLS.includes(programOf(ow0[0] ?? '')) || ['source', '.'].includes(programOf(ow0[0] ?? '')));
1822
+ const runs = maybeShell || owners.some((o) => {
1823
+ const ow = [...o, '\0'];
1824
+ const sw = stripPrefix(ow);
1825
+ return scriptAt(sw) === p.position - (ow.length - sw.length) || (p.viaStdin && bareShell(stripPrefix(o)));
1826
+ });
1827
+ if (!runs) continue;
1828
+ if ((walked += p.to - p.from) > PROCSUB_WALK) return TOO_MANY_PROCSUBS;
1829
+ const per = [];
1830
+ let prev = [];
1831
+ for (let k = p.from; k < p.to; k++) {
1832
+ if (Date.now() > deadline) return OUT_OF_TIME;
1833
+ const t = printedOf(fed, k, spellingsOf(parts, k, null), parts.piped.has(k) ? prev : []);
1834
+ if (t === null) return TOO_MUCH_WRITTEN;
1835
+ if (t.length) per.push(producedFor(t, parts.piped.has(k + 1) && k + 1 < p.to));
1836
+ prev = t;
1837
+ }
1838
+ const z = zipJoin(per);
1839
+ if (z === null) return TOO_MUCH_WRITTEN;
1840
+ for (const t of z) carried.push(t);
1841
+ for (const t of z.glued ?? []) carried.push(t);
1842
+ }
1843
+ // A file written earlier on the line (#498, row 8), run as a shell's script, through `source` or `.`, as a
1844
+ // program by its path (`./f`), or read by a shell through `<`: each text it may hold.
1845
+ const runs = new Set();
1846
+ for (const vw of variants) {
1847
+ const sw = stripPrefix(vw);
1848
+ if (!sw.length) continue;
1849
+ const k = scriptAt(sw);
1850
+ if (k >= 0) { runs.add(sw[k]); if (/[$`]/.test(sw[k]) && k + 1 < sw.length) runs.add(sw[k + 1]); }
1851
+ if (sw[0].includes('/')) runs.add(sw[0]);
1852
+ if (bareShell(sw)) for (const r of parts.reads[n] ?? []) runs.add(r);
1853
+ }
1854
+ for (const f of runs) {
1855
+ const t = fileTexts(f);
1856
+ if (t === null) return TOO_MUCH_WRITTEN;
1857
+ for (const x of t) carried.push(x);
1858
+ for (const x of t.glued ?? []) carried.push(x);
1859
+ }
1860
+ if (carried.length && depth >= 3) return TOO_DEEP;
1861
+ for (const inner of carried) {
1862
+ // A file read past its limits, run by a shell (#498, row 8).
1863
+ if (inner.includes(OVER)) return TOO_MUCH_WRITTEN;
1864
+ const v = agentGuardDecision(inner, depth + 1);
1865
+ if (!v.allow) return v;
1866
+ }
1867
+ for (const vw of variants) {
1868
+ const v = partVerdict(vw);
1869
+ if (!v.allow) return v;
1870
+ }
1871
+ // What this part prints or is fed, for a shell later on the line: as written, with the backslashes double
1872
+ // quotes keep (#498 review: `echo "\\'; …" | bash`), and with each `$(…)` read for what it prints.
1873
+ // `cat` and `tee` print what they read from a pipe or a `<` file too.
1874
+ const prog = w.length ? programOf(w[0]) : '';
1875
+ // What it reads keeps its no-newline mark and its readings kept apart (#518 review 1: `printf 'gh pr ' | tee f`).
1876
+ const input = parts.piped.has(n) ? Object.assign(before.slice(), before.open ? { open: true } : {}, before.glued ? { glued: before.glued.slice() } : {}) : [];
1877
+ if (prog === 'cat' || prog === 'tee') {
1878
+ for (const r of parts.reads[n] ?? []) {
1879
+ const t = fileTexts(r);
1880
+ if (t === null) { input.push(OVER); continue; }
1881
+ for (const x of t) input.push(x);
1882
+ if (t.glued) (input.glued ??= []).push(...t.glued);
1883
+ if (t.open) input.open = true;
1884
+ }
1885
+ }
1886
+ const outs = printedOf(fed, n, spellingsOf(parts, n, subst), input);
1887
+ if (outs === null) return TOO_MUCH_WRITTEN;
1888
+ for (const t of outs) printed.push(t);
1889
+ for (const t of outs.alone ?? []) printed.push(t);
1890
+ for (const t of outs.glued ?? []) printed.push(t);
1891
+ if (outs.length) printedPer.push(producedFor(outs, parts.piped.has(n + 1)));
1892
+ // The files it writes (#498, row 8): its output through `>` or `>>` (with what it is piped, which a filter
1893
+ // like `cat` or `sort` passes on), and, for `tee`, its file words.
1894
+ const passes = parts.piped.has(n) && prog !== 'cat' && prog !== 'tee';
1895
+ const written = passes ? [...outs, ...before] : outs;
1896
+ // A filter passes on what it is piped, and so its missing newline (`printf 'gh pr ' | tr a a > f`).
1897
+ if (passes) { if (outs.open || before.open) written.open = true; const g = [...(outs.glued ?? []), ...(before.glued ?? [])]; if (g.length) written.glued = g; }
1898
+ // Each file once per part (`>&f >&f …` wrote the part's text once per redirect, #498 review).
1899
+ const once = new Set();
1900
+ for (const wr of parts.writes[n] ?? []) { const key = `${wr.append}:${wr.target}`; if (!once.has(key)) { once.add(key); writeFile(wr.target, written, wr.append); } }
1901
+ for (const wr of pipedWrites.get(n) ?? []) writeFile(wr.target, outs, wr.append);
1902
+ if (prog === 'tee') {
1903
+ const append = w.slice(1).some((x) => x === '--append' || /^-[A-Za-z]*a/.test(x));
1904
+ for (const a of w.slice(1)) if (!a.startsWith('-')) writeFile(a, outs, append);
1905
+ }
1906
+ before = outs;
497
1907
  }
498
1908
  return { allow: true };
499
1909
  }
@@ -509,3 +1919,317 @@ export function payloadCommand(payload) {
509
1919
 
510
1920
  // Cursor's payload names its event; Claude Code's says `PreToolUse`.
511
1921
  export const isCursorPayload = (payload) => payload?.hook_event_name === 'beforeShellExecution' || typeof payload?.cursor_version === 'string';
1922
+
1923
+ // ---------------------------------------------------------------------------------------------------------------
1924
+ // PRE-APPROVAL (E167, issue #353). The other half of the guard: a command line it can SEE only reads runs with no
1925
+ // permission prompt. Claude Code's allow rules match the start of a command, so `Bash(gh api:*)` would also pass
1926
+ // `gh api -X DELETE …`; this reads each word instead. It answers "allow" only when EVERY part of the line is one of
1927
+ // the reads below, written in a form it knows; anything else gets no answer, which is the prompt the person had
1928
+ // before. So a mistake here, or a hook that fails, costs a prompt, never a write. A team's own `deny` and `ask`
1929
+ // rules still win over a hook's "allow" (Claude Code's rule), and `YAD_NO_PREAPPROVE=1` turns this half off.
1930
+ //
1931
+ // Never pre-approved, whatever the form: a secret, token, variable, key or webhook (the person's, HUMAN_ONLY_ACTS
1932
+ // in cli/agent-rules.mjs), GraphQL (a mutation rides the same call as a query), any API call that is not a GET, a
1933
+ // file written or a file read from outside the project, a `$(…)`, a `bash -c`, an env prefix, and any program not
1934
+ // named here. What it lists is printed by `yad setup` and given to agents by `yad guide --json`.
1935
+ export const PREAPPROVED = Object.freeze({
1936
+ api: 'gh api / glab api: a GET (no -X other than GET, no fields, no --input, --hostname or --cache, only an Accept header), not graphql, and no secrets, secure files, variables, tokens, keys, hooks, e-mails, triggers, integrations, services, credentials, Terraform state, schedules, CI logs, traces or artifacts, admin settings (application) or user in the path, with or without a .json-style suffix',
1937
+ git: 'git log, status, diff, show, rev-parse, ls-files, blame (no git option before them; no --output, --ext-diff, --textconv, --no-index, --contents, --show-signature or a shortening of one, no %G in a format, git diff paths inside the project; git still runs what its own config names, such as an external diff or fsmonitor)',
1938
+ jq: 'jq (a filter on the line, never from a file; no env, $ENV, import or include in it; files inside the project)',
1939
+ filters: 'head, tail, wc, grep (not -R), cut, uniq, tr, cat (files inside the project)',
1940
+ yad: 'the read-only yad commands of the settings allow list',
1941
+ gates: 'the read-only gates in checks/ (spec-link, contract-check, commit-message, lineage-check, epic-open, reconcile-debt-check, risk-map-check, verified-commits, ledger-guard, member-check), only while the file is the copy this yadflow ships',
1942
+ never: 'secrets, tokens, variables, keys, webhooks, GraphQL, API writes, file writes, $ (variables) outside single quotes, brace lists, globs, ( ), a word starting with ~ or =, $(…), bash -c, env prefixes',
1943
+ });
1944
+ export const PREAPPROVED_GATES = Object.freeze(['spec-link.sh', 'contract-check.sh', 'commit-message.sh', 'lineage-check.sh', 'epic-open.sh',
1945
+ 'reconcile-debt-check.sh', 'risk-map-check.sh', 'verified-commits.sh', 'ledger-guard.sh', 'member-check.mjs']);
1946
+ const SHIPPED_CHECKS = fileURLToPath(new URL('../skills/yad-checks/templates/checks/', import.meta.url));
1947
+
1948
+ // The line with its harmless redirects blanked out (`2>/dev/null`, `>/dev/null`, `&>/dev/null`, `2>&1`, `>&2`),
1949
+ // or null when it has any other: a `>` to a file writes it, a `<` (a file, a heredoc, a here-string) or a
1950
+ // process substitution feeds text from somewhere this does not judge. Quotes are respected, so the `>` in
1951
+ // `jq '.a > 1'` is text. Null too for anything the shell EXPANDS before the program sees it, because the words
1952
+ // judged here would not be the words run: a `$` outside single quotes (`"$GH_TOKEN"`, `${HOME}`, `$((…))`).
1953
+ // Unquoted text is held to an ALLOW list of characters — letters, digits, `_ . / : @ % + , ^ ~ = -`, spaces and
1954
+ // the separators — because bash and zsh each expand more than any list of bad ones names: a brace list
1955
+ // (`{~/.ssh/id_rsa,x}`), a glob (`*`, `?`, `[`, which can reach a link out of the project), zsh's glob
1956
+ // qualifiers (`file(e:cmd:)` runs cmd) and `=(cmd)` / `=ls`. So also: no `=` or `~` starting a word. One form is
1957
+ // let through because neither shell expands it: a brace around one plain word (`{owner}` in a gh path, `@{u}`).
1958
+ // Only a space, a tab and a newline break words: `\r`, `\v`, a no-break space are word characters to the shell,
1959
+ // and a guard that read them as breaks would judge different words than the shell runs. No `#` either: where a
1960
+ // comment starts depends on that same reading (a `\`-newline joins words), so a `#` gets the prompt.
1961
+ // Not `^`: zsh's `extendedglob` (on in setups such as Prezto) makes it a glob.
1962
+ const UNQUOTED_SAFE = /[A-Za-z0-9_./:@%+,~=-]/;
1963
+ function blankHarmlessRedirects(line) {
1964
+ let out = '';
1965
+ let quote = null;
1966
+ for (let i = 0; i < line.length; i++) {
1967
+ const ch = line[i];
1968
+ if (quote) {
1969
+ if (ch === quote) quote = null;
1970
+ else if (quote === '"' && (ch === '$' || ch === '`')) return null;
1971
+ else if (ch === '\\' && quote === '"') { out += ch + (line[i + 1] ?? ''); i++; continue; }
1972
+ out += ch;
1973
+ continue;
1974
+ }
1975
+ // An escaped character is literal, except a CR, which the guard's reader and the shell do not split alike.
1976
+ if (ch === '\\') { if (line[i + 1] === '\r') return null; out += ch + (line[i + 1] ?? ''); i++; continue; }
1977
+ if (ch === '\'' || ch === '"') { quote = ch; out += ch; continue; }
1978
+ const wordStart = i === 0 || /[ \t\n;|&]/.test(line[i - 1]);
1979
+ if ((ch === '~' || ch === '=') && (wordStart || /[=:]/.test(line[i - 1]))) return null;
1980
+ if (ch === '{') {
1981
+ const m = /^\{[A-Za-z0-9_]*\}/.exec(line.slice(i));
1982
+ if (!m) return null;
1983
+ out += m[0]; i += m[0].length - 1; continue;
1984
+ }
1985
+ if (ch === '<') return null;
1986
+ if (ch !== '>' && !UNQUOTED_SAFE.test(ch) && !/[ \t\n;|&]/.test(ch)) return null;
1987
+ if (ch !== '>') { out += ch; continue; }
1988
+ // The fd before it (`2>`) or `&>`: blanked with it.
1989
+ let start = out.length;
1990
+ while (start > 0 && /[0-9&]/.test(out[start - 1])) start--;
1991
+ if (start > 0 && !/[\s;|&]/.test(out[start - 1])) return null;
1992
+ let j = i + 1;
1993
+ if (line[j] === '(') return null;
1994
+ let dup = false;
1995
+ if (line[j] === '>') j++;
1996
+ else if (line[j] === '&') { dup = true; j++; } else if (line[j] === '|') return null;
1997
+ while (line[j] === ' ' || line[j] === '\t') j++;
1998
+ let k = j;
1999
+ while (k < line.length && !/[\s;|&<>()'"`$\\]/.test(line[k])) k++;
2000
+ const target = line.slice(j, k);
2001
+ if (!(dup ? /^[0-9]+$/.test(target) : target === '/dev/null')) return null;
2002
+ // The target ends the word: `2>/dev/null"x"` writes to `/dev/nullx`.
2003
+ if (k < line.length && !/[\s;|&)]/.test(line[k])) return null;
2004
+ out = `${out.slice(0, start)}${' '.repeat(i - start)}${' '.repeat(k - i)}`;
2005
+ i = k - 1;
2006
+ }
2007
+ return quote ? null : out;
2008
+ }
2009
+
2010
+ // A file named on a command line, read inside the project only: no `~`, no `$`, nothing that resolves (through a
2011
+ // link too) outside the project. `at` is `{ cwd, root }`: the word resolves from `cwd` and must land in `root`.
2012
+ // `-` is standard input.
2013
+ function insideProject(word, at) {
2014
+ if (word === '-') return true;
2015
+ if (!word || /^~|\$/.test(word)) return false;
2016
+ let root, cwd;
2017
+ // Both through realpath, so a link in either (macOS's /var is /private/var) does not make a file look outside.
2018
+ try { root = fs.realpathSync(at.root); cwd = fs.realpathSync(at.cwd); } catch { return false; }
2019
+ let full = path.resolve(cwd, word);
2020
+ try { full = fs.realpathSync(full); } catch { /* not there yet (or a glob): judged by its spelling */ }
2021
+ const rel = path.relative(root, full);
2022
+ return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
2023
+ }
2024
+
2025
+ // Read a program's arguments against its options: `bool` takes no value, `value` takes one (`-n 5`, `-n5`,
2026
+ // `--lines=5`, `--lines 5`), `pairs` takes two (`--arg name value`). Short options may be clustered (`-in`) while
2027
+ // they take no value. `numeric` allows `-5` (head, tail). Returns the plain operands, or null for an option it
2028
+ // does not know: an unknown option is never guessed at.
2029
+ function operandsOf(args, { bool = [], value = [], pairs = [], numeric = false } = {}) {
2030
+ const B = new Set(bool), V = new Set(value), P = new Set(pairs);
2031
+ const ops = [];
2032
+ const values = {};
2033
+ for (let i = 0; i < args.length; i++) {
2034
+ const a = args[i];
2035
+ if (a === '--') { ops.push(...args.slice(i + 1)); break; }
2036
+ if (a === '-' || !a.startsWith('-')) { ops.push(a); continue; }
2037
+ if (a.startsWith('--')) {
2038
+ const [name, eq] = [a.split('=')[0], a.includes('=')];
2039
+ if (B.has(name) && !eq) continue;
2040
+ if (V.has(name)) { (values[name] ??= []).push(eq ? a.slice(a.indexOf('=') + 1) : args[++i]); if (!eq && i >= args.length) return null; continue; }
2041
+ if (P.has(name) && !eq) { (values[name] ??= []).push([args[i + 1], args[i + 2]]); i += 2; if (i >= args.length) return null; continue; }
2042
+ return null;
2043
+ }
2044
+ if (numeric && /^-[0-9]+$/.test(a)) continue;
2045
+ // A short option or a cluster of them.
2046
+ for (let c = 1; c < a.length; c++) {
2047
+ const o = `-${a[c]}`;
2048
+ if (B.has(o)) continue;
2049
+ if (V.has(o)) {
2050
+ const rest = a.slice(c + 1);
2051
+ (values[o] ??= []).push(rest || args[++i]);
2052
+ if (!rest && i >= args.length) return null;
2053
+ break;
2054
+ }
2055
+ return null;
2056
+ }
2057
+ }
2058
+ return { ops, values };
2059
+ }
2060
+
2061
+ // The tools a part may run, each judged on its own words (the program name first, bare: `./gh` is a script).
2062
+ const FILTERS = {
2063
+ head: { bool: ['-q', '-v', '--quiet', '--silent', '--verbose'], value: ['-n', '-c', '--lines', '--bytes'], numeric: true },
2064
+ tail: { bool: ['-q', '-v', '-r', '--quiet', '--silent', '--verbose'], value: ['-n', '-c', '--lines', '--bytes'], numeric: true },
2065
+ wc: { bool: ['-l', '-w', '-c', '-m', '-L', '--lines', '--words', '--bytes', '--chars', '--max-line-length'] },
2066
+ cut: { bool: ['-s', '-n', '--only-delimited', '--complement'], value: ['-d', '-f', '-c', '-b', '--delimiter', '--fields', '--characters', '--bytes', '--output-delimiter'] },
2067
+ cat: { bool: ['-n', '-b', '-s', '-v', '-e', '-t', '-A', '-E', '-T', '-u', '--number', '--number-nonblank', '--squeeze-blank', '--show-all'] },
2068
+ grep: { bool: ['-i', '-v', '-c', '-n', '-E', '-F', '-G', '-o', '-q', '-w', '-x', '-l', '-L', '-h', '-H', '-s', '-r', '-z', '-a', '-I',
2069
+ '--ignore-case', '--invert-match', '--count', '--line-number', '--extended-regexp', '--fixed-strings', '--only-matching', '--quiet', '--silent',
2070
+ '--word-regexp', '--line-regexp', '--files-with-matches', '--files-without-match', '--no-filename', '--with-filename', '--recursive', '--color', '--no-messages'],
2071
+ // Not -R / --dereference-recursive: it follows every link under the folder, out of the project too.
2072
+ value: ['-e', '-m', '-A', '-B', '-C', '--regexp', '--max-count', '--after-context', '--before-context', '--context', '--include', '--exclude', '--exclude-dir'] },
2073
+ };
2074
+ function filterPart(prog, args, at) {
2075
+ if (prog === 'uniq') {
2076
+ const r = operandsOf(args, { bool: ['-c', '-d', '-u', '-i', '--count', '--repeated', '--unique', '--ignore-case'] });
2077
+ // A second operand is the file uniq WRITES.
2078
+ return Boolean(r && r.ops.length <= 1 && r.ops.every((f) => insideProject(f, at)));
2079
+ }
2080
+ if (prog === 'tr') {
2081
+ const r = operandsOf(args, { bool: ['-d', '-s', '-c', '-C', '--delete', '--squeeze-repeats', '--complement'] });
2082
+ return Boolean(r && r.ops.length >= 1 && r.ops.length <= 2);
2083
+ }
2084
+ const spec = FILTERS[prog];
2085
+ if (!spec) return false;
2086
+ const r = operandsOf(args, spec);
2087
+ if (!r) return false;
2088
+ // grep's first operand is its pattern, unless one came with -e.
2089
+ const files = prog === 'grep' && !r.values['-e'] && !r.values['--regexp'] ? r.ops.slice(1) : r.ops;
2090
+ if (prog === 'grep' && !r.values['-e'] && !r.values['--regexp'] && !r.ops.length) return false;
2091
+ return files.every((f) => insideProject(f, at));
2092
+ }
2093
+
2094
+ const JQ_SPEC = { bool: ['-r', '-j', '-c', '-n', '-s', '-e', '-a', '-S', '-C', '-M', '--raw-output', '--join-output', '--compact-output', '--null-input',
2095
+ '--slurp', '--exit-status', '--ascii-output', '--sort-keys', '--color-output', '--monochrome-output', '--tab', '--seq', '--stream', '--raw-output0', '--raw-input', '-R'],
2096
+ // Not -f / --from-file: the filter would come from a file this does not read (it could hold `env`); not -L.
2097
+ value: ['--indent'], pairs: ['--arg', '--argjson', '--slurpfile', '--rawfile'] };
2098
+ // `env` and `$ENV` print the environment, where the platform tokens live; `import` and `include` read a file
2099
+ // from any path. A filter that only names a field `.env` is caught too: it gets the prompt, which is safe.
2100
+ const READS_ENV = /\benv\b|\bENV\b|\$__prog_args\b|\bimport\b|\binclude\b/;
2101
+ function jqPart(args, at) {
2102
+ const r = operandsOf(args, JQ_SPEC);
2103
+ if (!r) return false;
2104
+ const filter = r.ops[0];
2105
+ if (filter === undefined || READS_ENV.test(filter)) return false;
2106
+ for (const [, f] of [...(r.values['--slurpfile'] ?? []), ...(r.values['--rawfile'] ?? [])]) if (!insideProject(f, at)) return false;
2107
+ return r.ops.slice(1).every((f) => insideProject(f, at));
2108
+ }
2109
+
2110
+ // `gh api` / `glab api`: a GET of a REST path, with only the options that keep it one.
2111
+ const API_SPEC = { bool: ['--paginate', '--slurp', '-i', '--include', '--silent', '--verbose'], value: ['-X', '--method', '-H', '--header', '-q', '--jq', '-t', '--template', '-p', '--preview'] };
2112
+ // (Not --cache: it writes gh's cache files, outside the project.)
2113
+ // Any path segment that names a secret, token, variable, key or hook (`gpg_keys`, `webhooks`, `access_tokens`),
2114
+ // a person's e-mail addresses, a pipeline trigger (its token), an integration or service (a webhook URL), a
2115
+ // credential, CI logs, traces and artifacts (masking there is best effort, or none), GitLab's secure files,
2116
+ // Terraform state, pipeline schedules (one lists its variables with their values) and admin settings, and
2117
+ // GitLab's `user` (the caller's private e-mail).
2118
+ const NEVER_PATH = /secret|secure|token|variable|key|hook|email|trigger|integration|service|credential|terraform|schedule|artifact|^logs$|^trace$|^application$|^user$/i;
2119
+ function apiPart(prog, args) {
2120
+ const r = operandsOf(args, API_SPEC);
2121
+ if (!r || r.ops.length !== 1) return false;
2122
+ const methods = [...(r.values['-X'] ?? []), ...(r.values['--method'] ?? [])];
2123
+ if (methods.some((m) => String(m).toUpperCase() !== 'GET')) return false;
2124
+ if ([...(r.values['-H'] ?? []), ...(r.values['--header'] ?? [])].some((h) => !/^accept\s*:/i.test(String(h)))) return false;
2125
+ if ([...(r.values['-q'] ?? []), ...(r.values['--jq'] ?? [])].some((q) => READS_ENV.test(String(q)))) return false;
2126
+ const endpoint = r.ops[0];
2127
+ if (/^[a-z][a-z0-9+.-]*:|^\/\//i.test(endpoint) || /\$/.test(endpoint)) return false;
2128
+ // Decoded first, then split, so `user%2F` is two parts; each part is tested as written and without a format
2129
+ // suffix (`user.json`).
2130
+ const bare = decodeURIComponent(endpoint.split(/[?#]/)[0]);
2131
+ if (bare.replace(/^\/+/, '') === 'graphql') return false;
2132
+ if (bare.split('/').some((seg) => NEVER_PATH.test(seg) || NEVER_PATH.test(seg.replace(/\.[A-Za-z0-9]*$/, '')))) return false;
2133
+ return apiMethod([prog, 'api', ...args]) === 'GET';
2134
+ }
2135
+
2136
+ const GIT_READS = new Set(['log', 'status', 'diff', 'show', 'rev-parse', 'ls-files', 'blame']);
2137
+ // The options that write a file, read one from anywhere, or run a program. git accepts any unique shortening of a
2138
+ // long option in some commands (`git blame --conten=/etc/hosts` is `--contents`), so a long option is refused
2139
+ // when it is a prefix of one of these, not only when it equals one. The short ones: blame's `-S <file>`,
2140
+ // ls-files' `-X <file>`, diff's `-O<file>`, in any cluster.
2141
+ const GIT_RISKY = ['--output', '--output-directory', '--ext-diff', '--textconv', '--no-index', '--contents', '--open-files-in-pager', '--ignore-revs-file',
2142
+ '--exclude-from', '--exclude-per-directory', '--pathspec-from-file', '--orderfile', '--show-signature', '--rotate-to', '--skip-to'];
2143
+ // Real options that happen to begin a risky one: allowed as written.
2144
+ const GIT_EXACT_SAFE = new Set(['--text', '--ignore-rev', '--output-indicator-new', '--output-indicator-old', '--output-indicator-context']);
2145
+ // The short options that read a file, by command: blame's `-S <file>`, ls-files' `-X <file>`, `-O<file>` (diff's
2146
+ // order file). `git log -S <text>` is a search, not a file, so it stays.
2147
+ const GIT_RISKY_SHORT = { blame: 'S', 'ls-files': 'X', diff: 'O', log: 'O', show: 'O' };
2148
+ function gitPart(args, at) {
2149
+ if (!GIT_READS.has(args[0])) return false;
2150
+ const shortRisk = GIT_RISKY_SHORT[args[0]] ?? '';
2151
+ let afterDashes = false;
2152
+ for (const a of args.slice(1)) {
2153
+ if (a === '--') { afterDashes = true; continue; }
2154
+ // `%G…` in a format makes git check signatures, which runs gpg.
2155
+ if (/%G/.test(a)) return false;
2156
+ if (!afterDashes && a.startsWith('--')) {
2157
+ const name = a.split('=')[0];
2158
+ if (!GIT_EXACT_SAFE.has(name) && name.length > 2 && GIT_RISKY.some((r) => r.startsWith(name))) return false;
2159
+ } else if (!afterDashes && a.startsWith('-') && shortRisk && new RegExp(`^-[A-Za-z]*[${shortRisk}]`).test(a)) return false;
2160
+ // `git diff` turns to --no-index by itself when a path is outside the repo, and prints both files: every path
2161
+ // it is given must be inside the project. A ref (`main`, `origin/main`, `HEAD~1`) reads as one inside.
2162
+ else if (args[0] === 'diff' && (afterDashes || !a.startsWith('-')) && !insideProject(a, at)) return false;
2163
+ }
2164
+ return true;
2165
+ }
2166
+
2167
+ // A read gate run from checks/, unchanged from the copy this yadflow ships.
2168
+ function gatePart(prog, args, at) {
2169
+ const file = args[0] ?? '';
2170
+ const name = file.replace(/^\.\//, '');
2171
+ const m = /^checks\/([A-Za-z0-9._-]+)$/.exec(name);
2172
+ if (!m || !PREAPPROVED_GATES.includes(m[1])) return false;
2173
+ if (m[1].endsWith('.mjs') ? prog !== 'node' : !(prog === 'bash' || prog === 'sh')) return false;
2174
+ if (!insideProject(name, at)) return false;
2175
+ try {
2176
+ // A plain file only: a named pipe there would block the read, and the hook with it (#498 review).
2177
+ const local = path.resolve(at.cwd, name);
2178
+ if (!fs.statSync(local).isFile()) return false;
2179
+ return fs.readFileSync(local).equals(fs.readFileSync(path.join(SHIPPED_CHECKS, m[1])));
2180
+ } catch { return false; }
2181
+ }
2182
+
2183
+ function yadPart(args) {
2184
+ const { words, flags } = yadWords(args);
2185
+ // yad's own reading of the words and flags must be a read too (`check --fix` is not, whatever the prefix).
2186
+ if (classify(words, flags) !== 'read') return false;
2187
+ const key = words.join(' ');
2188
+ return readAllowList().some((rule) => {
2189
+ const k = rule.slice('Bash(yad '.length, -':*)'.length);
2190
+ return key === k || key.startsWith(`${k} `);
2191
+ });
2192
+ }
2193
+
2194
+ // What one part of the line is, when it is a read this pre-approves; else null.
2195
+ function readKind(words, at) {
2196
+ if (!words.length) return null;
2197
+ const [prog, ...args] = words;
2198
+ // A bare program name: no path (a script that shares a name), no `VAR=value`, no prefix (`env`, `sudo`, …).
2199
+ if (!/^[a-z][a-z0-9_-]*$/.test(prog) || PREFIXES.has(prog)) return null;
2200
+ if ((prog === 'gh' || prog === 'glab') && args[0] === 'api') return apiPart(prog, args.slice(1)) ? `${prog} api GET` : null;
2201
+ if (prog === 'git') return gitPart(args, at) ? `git ${args[0]}` : null;
2202
+ if (prog === 'jq') return jqPart(args, at) ? 'jq' : null;
2203
+ if (prog === 'yad') return yadPart(args) ? 'a read-only yad command' : null;
2204
+ if (prog === 'bash' || prog === 'sh' || prog === 'node') return gatePart(prog, args, at) ? `the ${args[0].replace(/^\.\/|^checks\//g, '')} gate` : null;
2205
+ return filterPart(prog, args, at) ? prog : null;
2206
+ }
2207
+
2208
+ // `{ preapproved: true, reason }` when every part of the line is a read named above, else `{ preapproved: false }`.
2209
+ // It never judges a refusal: the caller asks `agentGuardDecision` first, and a refused line is never pre-approved.
2210
+ // `cwd` is where the line runs (files resolve from it); `root` is the project, and `cwd` must be inside it — an
2211
+ // agent that changed to `/` would otherwise make every file "inside".
2212
+ export function agentGuardPreapproval(line, { cwd = process.cwd(), root = cwd } = {}) {
2213
+ const no = { preapproved: false };
2214
+ try {
2215
+ if (typeof line !== 'string' || !line.trim() || !agentGuardDecision(line).allow) return no;
2216
+ // The reader replaces these (the brace shield), so a file named with one would be judged under another name.
2217
+ if (/[\uE000-\uE002]/.test(line)) return no;
2218
+ const at = { cwd: path.resolve(root, cwd), root };
2219
+ if (!insideProject('.', at)) return no;
2220
+ const clean = blankHarmlessRedirects(line);
2221
+ if (clean === null) return no;
2222
+ if (clean.includes('`') || /\$\(/.test(clean)) return no;
2223
+ const parts = shellParts(clean);
2224
+ if (!parts.length || parts.subs.length) return no;
2225
+ const kinds = [];
2226
+ for (const words of parts) {
2227
+ const kind = readKind(words, at);
2228
+ if (!kind) return no;
2229
+ if (!kinds.includes(kind)) kinds.push(kind);
2230
+ }
2231
+ return { preapproved: true, reason: kinds.join(', ') };
2232
+ } catch {
2233
+ return no;
2234
+ }
2235
+ }