@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.
- package/LICENSE.md +1 -1
- package/README.md +13 -0
- package/base/agents.json +22 -1
- package/base/checks/wiki-anchors.ts +8 -0
- package/base/checks/wiki-source-links.ts +8 -0
- package/base/claude/remote-hosts.json +1 -1
- package/base/claude/settings.json +12 -12
- package/base/extensions/vulcan-guards.ts +301 -0
- package/base/hooks/antigravity-guards.ts +68 -0
- package/base/hooks/codex-guards.ts +66 -0
- package/base/hooks/guard-git.ts +38 -9
- package/base/hooks/guard-outside.ts +29 -9
- package/base/hooks/guard-writes.ts +29 -1
- package/base/hooks/session-start.ts +14 -4
- package/base/make/vulcan.mk +12 -1
- package/base/references/delegation-brief.md +5 -4
- package/base/rules.md +2 -2
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/docs-writing/references/agent-documents.md +1 -1
- package/base/skills/knowledge-sync/SKILL.md +1 -1
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/report-back/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +1 -1
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +33 -11
- package/base/skills/visualize-work/references/spec.md +77 -12
- package/package.json +4 -4
- package/src/agents/codex-hooks.ts +133 -0
- package/src/agents/common/constants.ts +54 -0
- package/src/agents/common/schema.ts +10 -1
- package/src/agents/common/types.ts +3 -1
- package/src/agents/exclude.ts +4 -0
- package/src/agents/hooks-json.ts +111 -0
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +5 -4
- package/src/agents/resolve.ts +24 -9
- package/src/config/common/constants.ts +12 -0
- package/src/config/common/types.ts +2 -1
- package/src/config/packages.ts +2 -1
- package/src/config/schema.ts +84 -5
- package/src/create/add-app.ts +2 -2
- package/src/create/add-lib.ts +21 -8
- package/src/create/common/constants.ts +12 -0
- package/src/create/common/types.ts +2 -1
- package/src/create/preset-diff.ts +4 -2
- package/src/create/workspace.ts +13 -9
- package/src/doctor/checks.ts +71 -1
- package/src/doctor/common/constants.ts +2 -0
- package/src/doctor/runner.ts +6 -0
- package/src/hooks/codex-patch.ts +47 -0
- package/src/hooks/command-view.ts +97 -0
- package/src/hooks/common/constants.ts +46 -0
- package/src/hooks/common/types.ts +9 -1
- package/src/hooks/decision.ts +50 -8
- package/src/hooks/guard-git.ts +64 -5
- package/src/hooks/guard-manifest.ts +22 -8
- package/src/hooks/guard-outside.ts +38 -6
- package/src/hooks/guard-package.ts +15 -12
- package/src/hooks/guard-writes.ts +72 -21
- package/src/hooks/index.ts +5 -0
- package/src/hooks/project-guards.ts +123 -0
- package/src/hooks/project-tmp.ts +36 -0
- package/src/hooks/remote-hosts.ts +38 -14
- package/src/hooks/session-digest.ts +5 -0
- package/src/hooks/shell.ts +665 -35
- package/src/hooks/trusted-scripts.ts +134 -0
- package/src/manifest/render.ts +38 -0
- package/src/sync/agent-files.ts +122 -4
- package/src/sync/agent-removal.ts +118 -4
- package/src/sync/claude-launch.ts +48 -0
- package/src/sync/index.ts +1 -0
- package/src/sync/local-choice.ts +2 -0
- package/src/visualize/assets.ts +195 -54
- package/src/visualize/charts.ts +235 -0
- package/src/visualize/constants.ts +122 -1
- package/src/visualize/diagrams.ts +224 -0
- package/src/visualize/icons.ts +28 -0
- package/src/visualize/layout.ts +58 -8
- package/src/visualize/page.ts +151 -145
- package/src/visualize/schema.ts +252 -2
- package/src/visualize/sections.ts +370 -0
- package/src/visualize/validate.ts +100 -7
- package/src/wiki/anchors.ts +118 -0
- package/src/wiki/command.ts +110 -0
- package/src/wiki/constants.ts +30 -0
- package/src/wiki/index.ts +4 -0
- package/src/wiki/source-links.ts +186 -0
package/src/hooks/shell.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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 (
|
|
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
|
|
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
|
|
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
|
|
751
|
+
const heredoc = heredocOf({ line });
|
|
291
752
|
|
|
292
|
-
if (
|
|
293
|
-
stripTabs =
|
|
294
|
-
terminator =
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
307
|
-
|
|
308
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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 (
|
|
408
|
-
const
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
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
|
-
|
|
414
|
-
|
|
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
|
-
|
|
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
|
-
...
|
|
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
|
+
});
|