@venizia/vulcan 0.4.4 → 0.4.6

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 (88) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/agents.json +22 -1
  4. package/base/checks/wiki-anchors.ts +8 -0
  5. package/base/checks/wiki-source-links.ts +8 -0
  6. package/base/claude/remote-hosts.json +1 -1
  7. package/base/claude/settings.json +12 -12
  8. package/base/extensions/vulcan-guards.ts +301 -0
  9. package/base/hooks/antigravity-guards.ts +68 -0
  10. package/base/hooks/codex-guards.ts +66 -0
  11. package/base/hooks/guard-git.ts +38 -9
  12. package/base/hooks/guard-outside.ts +29 -9
  13. package/base/hooks/guard-writes.ts +29 -1
  14. package/base/hooks/session-start.ts +14 -4
  15. package/base/make/vulcan.mk +12 -1
  16. package/base/references/delegation-brief.md +5 -4
  17. package/base/rules.md +2 -2
  18. package/base/skills/docs-writing/SKILL.md +1 -1
  19. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  20. package/base/skills/knowledge-sync/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/SKILL.md +1 -1
  22. package/base/skills/report-back/SKILL.md +1 -1
  23. package/base/skills/retro/SKILL.md +1 -1
  24. package/base/skills/review-a-change/SKILL.md +1 -1
  25. package/base/skills/ship/SKILL.md +1 -1
  26. package/base/skills/visualize-work/SKILL.md +33 -11
  27. package/base/skills/visualize-work/references/spec.md +77 -12
  28. package/package.json +4 -4
  29. package/src/agents/codex-hooks.ts +133 -0
  30. package/src/agents/common/constants.ts +54 -0
  31. package/src/agents/common/schema.ts +10 -1
  32. package/src/agents/common/types.ts +3 -1
  33. package/src/agents/exclude.ts +4 -0
  34. package/src/agents/hooks-json.ts +111 -0
  35. package/src/agents/index.ts +2 -0
  36. package/src/agents/render.ts +5 -4
  37. package/src/agents/resolve.ts +24 -9
  38. package/src/config/common/constants.ts +12 -0
  39. package/src/config/common/types.ts +2 -1
  40. package/src/config/packages.ts +2 -1
  41. package/src/config/schema.ts +84 -5
  42. package/src/create/add-app.ts +2 -2
  43. package/src/create/add-lib.ts +21 -8
  44. package/src/create/common/constants.ts +12 -0
  45. package/src/create/common/types.ts +2 -1
  46. package/src/create/preset-diff.ts +4 -2
  47. package/src/create/workspace.ts +13 -9
  48. package/src/doctor/checks.ts +71 -1
  49. package/src/doctor/common/constants.ts +2 -0
  50. package/src/doctor/runner.ts +6 -0
  51. package/src/hooks/codex-patch.ts +47 -0
  52. package/src/hooks/command-view.ts +97 -0
  53. package/src/hooks/common/constants.ts +46 -0
  54. package/src/hooks/common/types.ts +9 -1
  55. package/src/hooks/decision.ts +50 -8
  56. package/src/hooks/guard-git.ts +64 -5
  57. package/src/hooks/guard-manifest.ts +22 -8
  58. package/src/hooks/guard-outside.ts +38 -6
  59. package/src/hooks/guard-package.ts +15 -12
  60. package/src/hooks/guard-writes.ts +72 -21
  61. package/src/hooks/index.ts +5 -0
  62. package/src/hooks/project-guards.ts +123 -0
  63. package/src/hooks/project-tmp.ts +36 -0
  64. package/src/hooks/remote-hosts.ts +38 -14
  65. package/src/hooks/session-digest.ts +5 -0
  66. package/src/hooks/shell.ts +665 -35
  67. package/src/hooks/trusted-scripts.ts +134 -0
  68. package/src/manifest/render.ts +38 -0
  69. package/src/sync/agent-files.ts +122 -4
  70. package/src/sync/agent-removal.ts +118 -4
  71. package/src/sync/claude-launch.ts +48 -0
  72. package/src/sync/index.ts +1 -0
  73. package/src/sync/local-choice.ts +2 -0
  74. package/src/visualize/assets.ts +195 -54
  75. package/src/visualize/charts.ts +235 -0
  76. package/src/visualize/constants.ts +122 -1
  77. package/src/visualize/diagrams.ts +224 -0
  78. package/src/visualize/icons.ts +28 -0
  79. package/src/visualize/layout.ts +58 -8
  80. package/src/visualize/page.ts +151 -145
  81. package/src/visualize/schema.ts +252 -2
  82. package/src/visualize/sections.ts +370 -0
  83. package/src/visualize/validate.ts +100 -7
  84. package/src/wiki/anchors.ts +118 -0
  85. package/src/wiki/command.ts +110 -0
  86. package/src/wiki/constants.ts +30 -0
  87. package/src/wiki/index.ts +4 -0
  88. package/src/wiki/source-links.ts +186 -0
@@ -3,6 +3,8 @@ export interface ISimpleCommand {
3
3
  words: string[];
4
4
  redirects: string[];
5
5
  assignments: string[];
6
+ /** The body of the heredoc this command reads, when it is not read as commands itself (data, or a query or script for another program). */
7
+ heredoc?: string;
6
8
  }
7
9
 
8
10
  interface IWordRead {
@@ -12,6 +14,9 @@ interface IWordRead {
12
14
  nested: string[];
13
15
  }
14
16
 
17
+ /** What a backslash inside double quotes escapes, as the shell reads it. */
18
+ const DOUBLE_QUOTE_ESCAPES = new Set(['$', '`', '"', '\\', '\n']);
19
+
15
20
  /** What stops an unquoted word. */
16
21
  const WORD_END = new Set([' ', '\t', '\n', ';', '|', '&', '<', '>', '(', ')']);
17
22
  /** Shell keywords and braces that open a command: the program is the word after them. */
@@ -92,13 +97,12 @@ const WRAPPER_OPTIONS: Record<string, IWrapperOptions> = {
92
97
  }),
93
98
  setsid: wrapperOptions({}),
94
99
  watch: wrapperOptions({ shortValues: 'nq', longValues: ['--interval', '--equexit'] }),
100
+ // `--eof`, `--max-lines` and `--replace` take an optional value attached with `=`, never the next word.
95
101
  xargs: wrapperOptions({
96
102
  shortValues: 'IanPdELs',
97
103
  longValues: [
98
104
  '--arg-file',
99
105
  '--delimiter',
100
- '--eof',
101
- '--max-lines',
102
106
  '--max-args',
103
107
  '--max-procs',
104
108
  '--max-chars',
@@ -119,8 +123,15 @@ export const optionTakesNextWord = (opts: { wrapper: string; word: string }): bo
119
123
  return false;
120
124
  }
121
125
 
126
+ // A long option may be shortened to any prefix (`--adj 5` is `--adjustment 5`), as getopt_long reads it.
122
127
  if (opts.word.startsWith('--')) {
123
- return options.longValues.includes(opts.word);
128
+ const name = opts.word.slice(2);
129
+
130
+ return (
131
+ name !== '' &&
132
+ !name.includes('=') &&
133
+ options.longValues.some((long) => long.slice(2).startsWith(name))
134
+ );
124
135
  }
125
136
 
126
137
  // A cluster such as `-nu`: the first letter that takes a value ends it; with letters left after it the
@@ -140,12 +151,51 @@ export const wrapperPositionals = (opts: { wrapper: string }): number =>
140
151
  const SHELLS = new Set(['bash', 'sh', 'zsh', 'dash']);
141
152
  const MAX_DEPTH = 4;
142
153
 
154
+ /** What the parser reads of one command line at most: a guard that reads more would be slow, and a slow guard is skipped. */
155
+ export class ShellBudget {
156
+ static readonly MAX_COMMANDS = 2000;
157
+ static readonly MAX_WORDS = 20_000;
158
+ /** The characters of a line and of every text nested in it, together: a line over it is not read at all. */
159
+ static readonly MAX_CHARS = 100_000;
160
+ }
161
+
162
+ interface IBudget {
163
+ commands: number;
164
+ words: number;
165
+ chars: number;
166
+ /** Something was not read: the budget ran out, or a command nests deeper than the depth limit. */
167
+ isOver: boolean;
168
+ }
169
+
170
+ /**
171
+ * The index of the character that closes what was opened just before `from` (`$(` or a backtick), or the end
172
+ * of the text when it never closes. Quotes and backslashes are read: a `)` inside quotes does not close.
173
+ */
143
174
  const closingOf = (opts: { text: string; from: number; open: string; close: string }): number => {
144
175
  let depth = 1;
176
+ let quote: string | undefined;
145
177
 
146
178
  for (let index = opts.from; index < opts.text.length; index += 1) {
147
179
  const char = opts.text[index];
148
180
 
181
+ if (char === '\\' && quote !== "'") {
182
+ index += 1;
183
+ continue;
184
+ }
185
+
186
+ if (quote !== undefined) {
187
+ if (char === quote) {
188
+ quote = undefined;
189
+ }
190
+
191
+ continue;
192
+ }
193
+
194
+ if (char === "'" || char === '"') {
195
+ quote = char;
196
+ continue;
197
+ }
198
+
149
199
  if (char === opts.open && opts.open !== opts.close) {
150
200
  depth += 1;
151
201
  } else if (char === opts.close) {
@@ -160,6 +210,93 @@ const closingOf = (opts: { text: string; from: number; open: string; close: stri
160
210
  return opts.text.length;
161
211
  };
162
212
 
213
+ const ANSI_C_ESCAPES: Record<string, string> = {
214
+ a: '\x07',
215
+ b: '\b',
216
+ e: '\x1b',
217
+ E: '\x1b',
218
+ f: '\f',
219
+ n: '\n',
220
+ r: '\r',
221
+ t: '\t',
222
+ v: '\v',
223
+ '\\': '\\',
224
+ "'": "'",
225
+ '"': '"',
226
+ '?': '?',
227
+ };
228
+
229
+ /** The character of a code point, or nothing for one that is not a character. */
230
+ const fromCodePoint = (opts: { code: number }): string =>
231
+ Number.isInteger(opts.code) && opts.code >= 0 && opts.code <= 0x10ffff
232
+ ? String.fromCodePoint(opts.code)
233
+ : '';
234
+
235
+ /**
236
+ * The text of an ANSI-C quoted string `$'...'`, from the character after the opening quote. The shell finds
237
+ * the closing quote first, a backslash skipping the character after it (so `\'` does not close, and neither
238
+ * does the `c` of `\c`), and decodes what is between: \n, \t, \\, \', octal \nnn, \xHH, \uHHHH, \UHHHHHHHH,
239
+ * \cX. An unknown escape keeps its backslash. A NUL ends the string, as in bash. An unclosed string runs to
240
+ * the end of the text.
241
+ */
242
+ const readAnsiC = (opts: { text: string; from: number }): { value: string; next: number } => {
243
+ const { text } = opts;
244
+ let end = opts.from;
245
+
246
+ while (end < text.length && text[end] !== "'") {
247
+ end += text[end] === '\\' ? 2 : 1;
248
+ }
249
+
250
+ const content = text.slice(opts.from, Math.min(end, text.length));
251
+ let value = '';
252
+ let index = 0;
253
+ let isEnded = false;
254
+
255
+ while (index < content.length) {
256
+ const char = content[index] ?? '';
257
+
258
+ if (char !== '\\') {
259
+ value += isEnded ? '' : char;
260
+ index += 1;
261
+ continue;
262
+ }
263
+
264
+ const next = content[index + 1] ?? '';
265
+ const octal = /^[0-7]{1,3}/.exec(content.slice(index + 1, index + 4))?.[0];
266
+ const hex = /^[xuU][0-9a-fA-F]+/.exec(content.slice(index + 1, index + 10))?.[0];
267
+ let decoded: string;
268
+ let length = 2;
269
+
270
+ if (octal !== undefined) {
271
+ decoded = fromCodePoint({ code: Number.parseInt(octal, 8) });
272
+ length = 1 + octal.length;
273
+ } else if (hex !== undefined) {
274
+ const digits = hex.slice(1, 1 + { x: 2, u: 4, U: 8 }[hex[0] ?? 'x']!);
275
+
276
+ decoded = fromCodePoint({ code: Number.parseInt(digits, 16) });
277
+ length = 2 + digits.length;
278
+ } else if (next === 'c' && content[index + 2] !== undefined) {
279
+ const control = content[index + 2] ?? '';
280
+
281
+ decoded = control === '?' ? '\x7f' : String.fromCharCode(control.charCodeAt(0) & 0x1f);
282
+ // `\c\\` takes both backslashes.
283
+ length = control === '\\' && content[index + 3] === '\\' ? 4 : 3;
284
+ } else {
285
+ decoded = ANSI_C_ESCAPES[next] ?? `\\${next}`;
286
+ }
287
+
288
+ if (decoded === '\0') {
289
+ isEnded = true;
290
+ } else if (!isEnded) {
291
+ value += decoded;
292
+ }
293
+
294
+ index += length;
295
+ }
296
+
297
+ return { value, next: Math.min(end + 1, text.length) };
298
+ };
299
+
163
300
  /** One word from `from`: quotes and escapes resolved, substitutions set aside in `nested`. */
164
301
  const readWord = (opts: { text: string; from: number }): IWordRead => {
165
302
  const { text } = opts;
@@ -175,8 +312,38 @@ const readWord = (opts: { text: string; from: number }): IWordRead => {
175
312
  break;
176
313
  }
177
314
 
315
+ // Inside double quotes a backslash escapes only a few characters; before any other it is itself.
178
316
  if (char === '\\' && quote !== "'") {
179
- value += text[index + 1] ?? '';
317
+ const next = text[index + 1] ?? '';
318
+
319
+ // A backslash before a newline joins the lines: both vanish.
320
+ if (next === '\n') {
321
+ index += 2;
322
+ continue;
323
+ }
324
+
325
+ if (quote === '"' && !DOUBLE_QUOTE_ESCAPES.has(next)) {
326
+ value += char;
327
+ index += 1;
328
+ continue;
329
+ }
330
+
331
+ value += next;
332
+ index += 2;
333
+ continue;
334
+ }
335
+
336
+ // `$'...'` is ANSI-C quoting and `$"..."` is double quotes with a locale mark; both read as the shell reads them.
337
+ if (quote === undefined && char === '$' && text[index + 1] === "'") {
338
+ const decoded = readAnsiC({ text, from: index + 2 });
339
+
340
+ value += decoded.value;
341
+ index = decoded.next;
342
+ continue;
343
+ }
344
+
345
+ if (quote === undefined && char === '$' && text[index + 1] === '"') {
346
+ quote = '"';
180
347
  index += 2;
181
348
  continue;
182
349
  }
@@ -224,13 +391,173 @@ const isAssignment = (opts: { word: string }): boolean => /^[A-Za-z_]\w*=/.test(
224
391
  export const basenameOf = (opts: { word: string }): string =>
225
392
  opts.word.split('/').pop() ?? opts.word;
226
393
 
227
- /** The program a command runs, past wrappers such as `sudo`, `env` and `time`. */
394
+ /**
395
+ * The command line `env -S` (`--split-string`) holds in one word, from its value on: `-S 'a b'`, `-S'a b'`,
396
+ * `-iS 'a b'`, `--split-string='a b'`, `--split-string 'a b'`. `takesNext` says the value is the next word.
397
+ * A cluster ends at its first option that takes a value, so `-uS` holds a name, not a command line.
398
+ */
399
+ const splitStringOf = (opts: {
400
+ word: string;
401
+ next: string | undefined;
402
+ }): { value: string; takesNext: boolean } | undefined => {
403
+ const { word, next } = opts;
404
+
405
+ if (word.startsWith('--')) {
406
+ const equals = word.indexOf('=');
407
+ const name = word.slice(2, equals === -1 ? undefined : equals);
408
+
409
+ // `--split-string` by any prefix: no other option of env starts with an s.
410
+ if (name === '' || !'split-string'.startsWith(name)) {
411
+ return undefined;
412
+ }
413
+
414
+ return equals === -1
415
+ ? { value: next ?? '', takesNext: true }
416
+ : { value: word.slice(equals + 1), takesNext: false };
417
+ }
418
+
419
+ const letters = WRAPPER_OPTIONS['env']?.shortValues ?? '';
420
+
421
+ for (let at = 1; at < word.length; at += 1) {
422
+ if (letters.includes(word[at] ?? '')) {
423
+ if (word[at] !== 'S') {
424
+ return undefined;
425
+ }
426
+
427
+ const rest = word.slice(at + 1);
428
+
429
+ return rest === ''
430
+ ? { value: next ?? '', takesNext: true }
431
+ : { value: rest, takesNext: false };
432
+ }
433
+ }
434
+
435
+ return undefined;
436
+ };
437
+
438
+ const ENV_ESCAPES: Record<string, string> = {
439
+ t: '\t',
440
+ n: '\n',
441
+ r: '\r',
442
+ v: '\v',
443
+ f: '\f',
444
+ '\\': '\\',
445
+ '#': '#',
446
+ $: '$',
447
+ '"': '"',
448
+ "'": "'",
449
+ };
450
+
451
+ /**
452
+ * The words `env -S` makes of its value, by `env`'s own rules and not the shell's: blanks separate, quotes
453
+ * group (in single quotes only `\\\\` and `\\'` are escapes), `\\_` separates outside double quotes and is a
454
+ * space inside them, `\\c` ends the string, a `#` at the start of a word starts a comment, and `;`, `|`
455
+ * and `$(...)` mean nothing. An empty quoted string is a word.
456
+ */
457
+ export const splitEnvString = (opts: { value: string }): string[] => {
458
+ const { value } = opts;
459
+ const words: string[] = [];
460
+ let current = '';
461
+ let hasWord = false;
462
+ let quote: string | undefined;
463
+
464
+ const flush = (): void => {
465
+ if (hasWord) {
466
+ words.push(current);
467
+ }
468
+
469
+ current = '';
470
+ hasWord = false;
471
+ };
472
+
473
+ for (let index = 0; index < value.length; index += 1) {
474
+ const char = value[index] ?? '';
475
+
476
+ if (char === '\\') {
477
+ const next = value[index + 1];
478
+
479
+ index += 1;
480
+
481
+ if (next === undefined) {
482
+ break;
483
+ }
484
+
485
+ // In single quotes only `\\` and `\'` are escapes: every other backslash stays, `\c` and `\_` included.
486
+ if (quote === "'") {
487
+ current += next === '\\' || next === "'" ? next : `\\${next}`;
488
+ hasWord = true;
489
+ continue;
490
+ }
491
+
492
+ if (next === 'c') {
493
+ break;
494
+ }
495
+
496
+ if (next === '_') {
497
+ if (quote === '"') {
498
+ current += ' ';
499
+ hasWord = true;
500
+ } else {
501
+ flush();
502
+ }
503
+
504
+ continue;
505
+ }
506
+
507
+ current += ENV_ESCAPES[next] ?? next;
508
+ hasWord = true;
509
+ continue;
510
+ }
511
+
512
+ if (quote !== undefined) {
513
+ if (char === quote) {
514
+ quote = undefined;
515
+ } else {
516
+ current += char;
517
+ hasWord = true;
518
+ }
519
+
520
+ continue;
521
+ }
522
+
523
+ if (char === "'" || char === '"') {
524
+ quote = char;
525
+ hasWord = true;
526
+ continue;
527
+ }
528
+
529
+ if (char === '#' && !hasWord) {
530
+ break;
531
+ }
532
+
533
+ if (/\s/.test(char)) {
534
+ flush();
535
+ continue;
536
+ }
537
+
538
+ current += char;
539
+ hasWord = true;
540
+ }
541
+
542
+ flush();
543
+
544
+ return words;
545
+ };
546
+
547
+ /**
548
+ * The program a command runs, past wrappers such as `sudo`, `env` and `time`, and the command `env -S`
549
+ * carries: the words `env` makes of the value, then the words after it, behind an `env` word, so its own
550
+ * options inside the value apply. Only the first `-S` of a command counts: it holds the rest of the line.
551
+ * `--` ends the options, so a word after it is the program even when it starts with a dash.
552
+ */
228
553
  export const programOf = (opts: {
229
554
  command: ISimpleCommand;
230
- }): { name: string; index: number; args: string[] } => {
555
+ }): { name: string; index: number; args: string[]; splitCommands: string[][] } => {
231
556
  let index = 0;
232
557
  let wrapper = '';
233
558
  let positionals = 0;
559
+ let optionsEnded = false;
560
+ const splitCommands: string[][] = [];
234
561
 
235
562
  while (index < opts.command.words.length) {
236
563
  const word = opts.command.words[index];
@@ -238,6 +565,7 @@ export const programOf = (opts: {
238
565
  if (WRAPPERS.has(basenameOf({ word }))) {
239
566
  wrapper = basenameOf({ word });
240
567
  positionals = wrapperPositionals({ wrapper });
568
+ optionsEnded = false;
241
569
  index += 1;
242
570
  continue;
243
571
  }
@@ -247,7 +575,26 @@ export const programOf = (opts: {
247
575
  continue;
248
576
  }
249
577
 
250
- if (/^-/.test(word)) {
578
+ if (word === '--') {
579
+ optionsEnded = true;
580
+ index += 1;
581
+ continue;
582
+ }
583
+
584
+ if (!optionsEnded && /^-/.test(word)) {
585
+ const split =
586
+ wrapper === 'env' && splitCommands.length === 0
587
+ ? splitStringOf({ word, next: opts.command.words[index + 1] })
588
+ : undefined;
589
+
590
+ if (split !== undefined && split.value !== '') {
591
+ splitCommands.push([
592
+ 'env',
593
+ ...splitEnvString({ value: split.value }),
594
+ ...opts.command.words.slice(index + (split.takesNext ? 2 : 1)),
595
+ ]);
596
+ }
597
+
251
598
  // An option of the wrapper; `-u X` and `nice -n 5` take a value that is not the program.
252
599
  index += optionTakesNextWord({ wrapper, word }) ? 2 : 1;
253
600
  continue;
@@ -260,26 +607,140 @@ export const programOf = (opts: {
260
607
  continue;
261
608
  }
262
609
 
263
- return { name: word, index, args: opts.command.words.slice(index + 1) };
610
+ return { name: word, index, args: opts.command.words.slice(index + 1), splitCommands };
264
611
  }
265
612
 
266
- return { name: '', index: -1, args: [] };
613
+ return { name: '', index: -1, args: [], splitCommands };
267
614
  };
268
615
 
616
+ /**
617
+ * The delimiter of a heredoc started on `line`: a `<<WORD` outside quotes. `<<<` is a here-string, and a `<<`
618
+ * inside quotes is text.
619
+ */
620
+ const heredocOf = (opts: {
621
+ line: string;
622
+ }): { delimiter: string; stripTabs: boolean; at: number } | undefined => {
623
+ const { line } = opts;
624
+ let quote: string | undefined;
625
+
626
+ for (let index = 0; index < line.length; index += 1) {
627
+ const char = line[index];
628
+
629
+ if (char === '\\' && quote !== "'") {
630
+ index += 1;
631
+ continue;
632
+ }
633
+
634
+ if (quote !== undefined) {
635
+ if (char === quote) {
636
+ quote = undefined;
637
+ }
638
+
639
+ continue;
640
+ }
641
+
642
+ if (char === "'" || char === '"') {
643
+ quote = char;
644
+ continue;
645
+ }
646
+
647
+ if (char === '<' && line[index + 1] === '<') {
648
+ if (line[index + 2] === '<') {
649
+ index += 2;
650
+ continue;
651
+ }
652
+
653
+ const match = /^<<(-?)\s*(["']?)([A-Za-z_]\w*)\2/.exec(line.slice(index));
654
+
655
+ if (match !== null) {
656
+ return { delimiter: match[3] ?? '', stripTabs: match[1] === '-', at: index };
657
+ }
658
+
659
+ index += 1;
660
+ }
661
+ }
662
+
663
+ return undefined;
664
+ };
665
+
666
+ /** The program of the last simple command of `prefix`: what a heredoc that starts after it is fed to. */
667
+ const programBefore = (opts: { prefix: string }): string => {
668
+ const { prefix } = opts;
669
+ let words: string[] = [];
670
+ let index = 0;
671
+
672
+ while (index < prefix.length) {
673
+ const char = prefix[index] ?? '';
674
+
675
+ if (char === ' ' || char === '\t') {
676
+ index += 1;
677
+ continue;
678
+ }
679
+
680
+ if (';|&()\n'.includes(char)) {
681
+ words = [];
682
+ index += 1;
683
+ continue;
684
+ }
685
+
686
+ if (char === '>' || char === '<') {
687
+ // A redirect and its target are not words of the command.
688
+ let cursor = index + 1;
689
+
690
+ while (prefix[cursor] === '>' || prefix[cursor] === '&' || prefix[cursor] === ' ') {
691
+ cursor += 1;
692
+ }
693
+
694
+ index = Math.max(readWord({ text: prefix, from: cursor }).next, index + 1);
695
+ continue;
696
+ }
697
+
698
+ const word = readWord({ text: prefix, from: index });
699
+
700
+ words.push(word.value);
701
+ index = Math.max(word.next, index + 1);
702
+ }
703
+
704
+ return basenameOf({
705
+ word: programOf({ command: { words, redirects: [], assignments: [] } }).name,
706
+ });
707
+ };
708
+
709
+ export interface IHeredoc {
710
+ body: string;
711
+ /** The body was left in the text because a shell reads it as commands (`bash <<EOF`). */
712
+ isInline: boolean;
713
+ }
714
+
269
715
  /**
270
716
  * A heredoc's body is data for the command that reads it (a commit message, a file), not commands: the
271
- * lines between `<<WORD` and the line `WORD` are dropped. A body fed to a shell (`bash <<EOF`) is not read.
717
+ * lines between `<<WORD` and the line `WORD` are taken out of the text and kept in `heredocs`, in order, for
718
+ * the command to carry. A body fed to a shell (`bash <<EOF`) is a script: it stays in the text and is read
719
+ * as commands.
272
720
  */
273
- const stripHeredocs = (opts: { command: string }): string => {
721
+ export const splitHeredocs = (opts: {
722
+ command: string;
723
+ }): { text: string; heredocs: IHeredoc[] } => {
274
724
  const lines = opts.command.split('\n');
275
725
  const kept: string[] = [];
726
+ const heredocs: IHeredoc[] = [];
276
727
  let terminator: string | undefined;
277
728
  let stripTabs = false;
729
+ let body: string[] = [];
730
+ let isInline = false;
278
731
 
279
732
  for (const line of lines) {
280
733
  if (terminator !== undefined) {
281
734
  if ((stripTabs ? line.replace(/^\t+/, '') : line).trim() === terminator) {
282
735
  terminator = undefined;
736
+ heredocs.push({ body: body.join('\n'), isInline });
737
+ continue;
738
+ }
739
+
740
+ body.push(line);
741
+
742
+ if (isInline) {
743
+ kept.push(line);
283
744
  }
284
745
 
285
746
  continue;
@@ -287,25 +748,105 @@ const stripHeredocs = (opts: { command: string }): string => {
287
748
 
288
749
  kept.push(line);
289
750
 
290
- const match = /<<(-?)\s*(["']?)([A-Za-z_]\w*)\2/.exec(line);
751
+ const heredoc = heredocOf({ line });
291
752
 
292
- if (match !== null) {
293
- stripTabs = match[1] === '-';
294
- terminator = match[3];
753
+ if (heredoc !== undefined) {
754
+ stripTabs = heredoc.stripTabs;
755
+ terminator = heredoc.delimiter;
756
+ body = [];
757
+ isInline = SHELLS.has(programBefore({ prefix: line.slice(0, heredoc.at) }));
295
758
  }
296
759
  }
297
760
 
298
- return kept.join('\n');
761
+ if (terminator !== undefined) {
762
+ heredocs.push({ body: body.join('\n'), isInline });
763
+ }
764
+
765
+ return { text: kept.join('\n'), heredocs };
766
+ };
767
+
768
+ /** Appends every item; a spread into `push` overflows the stack at a few hundred thousand items. */
769
+ const pushAll = (opts: { target: string[]; items: string[] }): void => {
770
+ for (const item of opts.items) {
771
+ opts.target.push(item);
772
+ }
773
+ };
774
+
775
+ /**
776
+ * The command lines a command carries as text: the script of `sh -c`, the words of `eval`, and the string
777
+ * `watch` joins its words into and hands to a shell (`watch 'git push'`).
778
+ */
779
+ const nestedScripts = (opts: {
780
+ command: ISimpleCommand;
781
+ program: ReturnType<typeof programOf>;
782
+ }): string[] => {
783
+ const { command, program } = opts;
784
+
785
+ if (program.index === -1) {
786
+ return [];
787
+ }
788
+
789
+ const name = basenameOf({ word: program.name });
790
+ const scripts: string[] = [];
791
+
792
+ if (SHELLS.has(name)) {
793
+ const flag = command.words.findIndex(
794
+ (word, position) => position > program.index && /^-[a-zA-Z]*c$/.test(word),
795
+ );
796
+ const script = flag === -1 ? undefined : command.words[flag + 1];
797
+
798
+ if (script !== undefined) {
799
+ scripts.push(script);
800
+ }
801
+ }
802
+
803
+ if (name === 'eval') {
804
+ scripts.push(program.args.join(' '));
805
+ }
806
+
807
+ if (
808
+ /\s/.test(program.name) &&
809
+ command.words.slice(0, program.index).some((word) => basenameOf({ word }) === 'watch')
810
+ ) {
811
+ scripts.push([program.name, ...program.args].join(' '));
812
+ }
813
+
814
+ return scripts;
815
+ };
816
+
817
+ /** Whether the command carries another command line to read: a script, an eval, a `watch` string, or an `env -S`. */
818
+ const nests = (opts: { command: ISimpleCommand }): boolean => {
819
+ const program = programOf({ command: opts.command });
820
+
821
+ return (
822
+ program.splitCommands.length > 0 || nestedScripts({ command: opts.command, program }).length > 0
823
+ );
299
824
  };
300
825
 
301
826
  /**
302
827
  * The simple commands of a shell line, in order: `;`, `&&`, `||`, `|`, `&` and newlines split them;
303
- * `$(...)`, backticks and `sh -c '...'` arguments are parsed as commands too. It reads quoting, not
304
- * every corner of the shell: a line it cannot follow yields fewer commands, never an error.
828
+ * `$(...)`, backticks, `sh -c '...'` arguments and the command line of `env -S` are parsed as commands too. It
829
+ * reads quoting, not every corner of the shell: a line it cannot follow yields fewer commands, never an error.
305
830
  */
306
- export const parseShell = (opts: { command: string; depth?: number }): ISimpleCommand[] => {
307
- const depth = opts.depth ?? 0;
308
- const text = stripHeredocs({ command: opts.command });
831
+ const parseWithBudget = (opts: {
832
+ command: string;
833
+ depth: number;
834
+ budget: IBudget;
835
+ }): ISimpleCommand[] => {
836
+ const { depth, budget } = opts;
837
+
838
+ // The characters of every text read count together, nested texts too: a line over the cap is not read.
839
+ budget.chars += opts.command.length;
840
+
841
+ if (budget.chars > ShellBudget.MAX_CHARS) {
842
+ budget.isOver = true;
843
+
844
+ return [];
845
+ }
846
+
847
+ const heredocSplit = splitHeredocs({ command: opts.command });
848
+ const { text } = heredocSplit;
849
+ let heredocIndex = 0;
309
850
  const commands: ISimpleCommand[] = [];
310
851
  const nestedTexts: string[] = [];
311
852
  let current: ISimpleCommand = { words: [], redirects: [], assignments: [] };
@@ -331,6 +872,12 @@ export const parseShell = (opts: { command: string; depth?: number }): ISimpleCo
331
872
  continue;
332
873
  }
333
874
 
875
+ // A backslash before a newline joins the lines: both vanish.
876
+ if (char === '\\' && text[index + 1] === '\n') {
877
+ index += 2;
878
+ continue;
879
+ }
880
+
334
881
  if (char === ';' || char === '\n' || char === '|' || char === '(' || char === ')') {
335
882
  finish();
336
883
  index += 1;
@@ -366,12 +913,29 @@ export const parseShell = (opts: { command: string; depth?: number }): ISimpleCo
366
913
  current.redirects.push(target.value);
367
914
  }
368
915
 
369
- nestedTexts.push(...target.nested);
916
+ pushAll({ target: nestedTexts, items: target.nested });
370
917
  index = Math.max(target.next, cursor + 1);
371
918
  continue;
372
919
  }
373
920
 
374
921
  if (char === '<') {
922
+ const operator =
923
+ text[index + 2] === '<' ? null : /^<<-?\s*["']?[A-Za-z_]\w*["']?/.exec(text.slice(index));
924
+
925
+ if (operator !== null) {
926
+ // The delimiter is part of the operator, not a word; the body goes to the command that reads it.
927
+ const heredoc = heredocSplit.heredocs[heredocIndex];
928
+
929
+ heredocIndex += 1;
930
+
931
+ if (heredoc !== undefined && !heredoc.isInline) {
932
+ current.heredoc = heredoc.body;
933
+ }
934
+
935
+ index += operator[0].length;
936
+ continue;
937
+ }
938
+
375
939
  index += 1;
376
940
  continue;
377
941
  }
@@ -384,7 +948,7 @@ export const parseShell = (opts: { command: string; depth?: number }): ISimpleCo
384
948
  continue;
385
949
  }
386
950
 
387
- nestedTexts.push(...word.nested);
951
+ pushAll({ target: nestedTexts, items: word.nested });
388
952
 
389
953
  if (current.words.length === 0 && isAssignment({ word: word.value })) {
390
954
  current.assignments.push(word.value);
@@ -397,31 +961,97 @@ export const parseShell = (opts: { command: string; depth?: number }): ISimpleCo
397
961
 
398
962
  finish();
399
963
 
964
+ budget.commands += commands.length;
965
+ budget.words += commands.reduce((sum, command) => sum + command.words.length, 0);
966
+
967
+ if (budget.commands > ShellBudget.MAX_COMMANDS || budget.words > ShellBudget.MAX_WORDS) {
968
+ budget.isOver = true;
969
+
970
+ return commands;
971
+ }
972
+
973
+ // At the depth limit nothing nests further; a command that would is a part of the line left unread.
400
974
  if (depth >= MAX_DEPTH) {
975
+ budget.isOver ||= nestedTexts.length > 0 || commands.some((command) => nests({ command }));
976
+
401
977
  return commands;
402
978
  }
403
979
 
404
- for (const command of commands) {
980
+ // `env -S "git push -f origin main"` is a command line in one word: the command it makes joins the queue,
981
+ // one nesting level deeper, and is read like any other.
982
+ const synthesized: ISimpleCommand[] = [];
983
+ const queue = commands.map((command) => ({ command, level: 0 }));
984
+
985
+ for (const { command, level } of queue) {
405
986
  const program = programOf({ command });
406
987
 
407
- if (program.index !== -1 && SHELLS.has(basenameOf({ word: program.name }))) {
408
- const flag = command.words.findIndex(
409
- (word, position) => position > program.index && /^-[a-zA-Z]*c$/.test(word),
410
- );
411
- const script = flag === -1 ? undefined : command.words[flag + 1];
988
+ if (depth + level < MAX_DEPTH) {
989
+ for (const words of program.splitCommands) {
990
+ const split: ISimpleCommand = { words, redirects: [], assignments: [] };
991
+
992
+ budget.commands += 1;
993
+ budget.words += words.length;
994
+
995
+ if (budget.commands > ShellBudget.MAX_COMMANDS || budget.words > ShellBudget.MAX_WORDS) {
996
+ budget.isOver = true;
997
+
998
+ return [...commands, ...synthesized];
999
+ }
412
1000
 
413
- if (script !== undefined) {
414
- nestedTexts.push(script);
1001
+ synthesized.push(split);
1002
+ queue.push({ command: split, level: level + 1 });
415
1003
  }
1004
+ } else if (program.splitCommands.length > 0) {
1005
+ budget.isOver = true;
416
1006
  }
417
1007
 
418
- if (program.index !== -1 && basenameOf({ word: program.name }) === 'eval') {
419
- nestedTexts.push(program.args.join(' '));
420
- }
1008
+ pushAll({ target: nestedTexts, items: nestedScripts({ command, program }) });
421
1009
  }
422
1010
 
423
1011
  return [
424
1012
  ...commands,
425
- ...nestedTexts.flatMap((nested) => parseShell({ command: nested, depth: depth + 1 })),
1013
+ ...synthesized,
1014
+ ...nestedTexts.flatMap((nested) =>
1015
+ parseWithBudget({ command: nested, depth: depth + 1, budget }),
1016
+ ),
426
1017
  ];
427
1018
  };
1019
+
1020
+ export interface IParsedShell {
1021
+ commands: ISimpleCommand[];
1022
+ /** Part of the line was not read: it is larger, or nests deeper, than the parser's budget. */
1023
+ isOverBudget: boolean;
1024
+ }
1025
+
1026
+ /**
1027
+ * The commands of a line and whether all of it was read. A guard that can refuse must treat
1028
+ * `isOverBudget` as "ask": an unread part is never an "allow".
1029
+ */
1030
+ /** A parse that throws (a stack or memory limit) reads nothing and says so: the line is not allowed by silence. */
1031
+ const parseGuarded = (opts: {
1032
+ command: string;
1033
+ depth: number;
1034
+ budget: IBudget;
1035
+ }): ISimpleCommand[] => {
1036
+ try {
1037
+ return parseWithBudget(opts);
1038
+ } catch {
1039
+ opts.budget.isOver = true;
1040
+
1041
+ return [];
1042
+ }
1043
+ };
1044
+
1045
+ export const parseShellChecked = (opts: { command: string }): IParsedShell => {
1046
+ const budget: IBudget = { commands: 0, words: 0, chars: 0, isOver: false };
1047
+ const commands = parseGuarded({ command: opts.command, depth: 0, budget });
1048
+
1049
+ return { commands, isOverBudget: budget.isOver };
1050
+ };
1051
+
1052
+ export const parseShell = (opts: { command: string; depth?: number }): ISimpleCommand[] =>
1053
+ parseGuarded({
1054
+ command: opts.command,
1055
+ depth: opts.depth ?? 0,
1056
+ budget: { commands: 0, words: 0, chars: 0, isOver: false },
1057
+ });