@venizia/vulcan 0.4.10-2 → 0.4.10-21
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/README.md +30 -23
- package/base/checks/wiki-source-links.ts +17 -1
- package/base/claude/events.json +1 -11
- package/base/claude/settings.json +5 -76
- package/base/extensions/vulcan-guards.ts +81 -18
- package/base/hooks/guard-git.ts +95 -19
- package/base/hooks/guard-outside.ts +163 -43
- package/base/hooks/guard-writes.ts +15 -36
- package/base/hooks/session-start.ts +1 -1
- package/base/make/vulcan.mk +8 -5
- package/base/packs/venizia.md +16 -0
- package/base/references/delegation-brief.md +3 -5
- package/base/references/testing.md +1 -9
- package/base/rules.md +33 -38
- package/base/skills/build-a-feature/SKILL.md +4 -4
- package/base/skills/docs-update/SKILL.md +19 -8
- package/base/skills/fix-a-bug/SKILL.md +4 -2
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/research/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +2 -2
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +3 -3
- package/base/skills/visualize-work/references/spec.md +6 -3
- package/base/templates/AGENTS.md +9 -7
- package/base/templates/board.html +10 -110
- package/package.json +3 -3
- package/src/agents/atlas-block.ts +8 -31
- package/src/agents/codex-hooks.ts +1 -1
- package/src/agents/generated-block.ts +52 -0
- package/src/agents/hooks-json.ts +22 -3
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +15 -2
- package/src/agents/resolve.ts +1 -0
- package/src/agents/rules-block.ts +92 -0
- package/src/board/command.ts +92 -30
- package/src/board/common/constants.ts +26 -0
- package/src/board/common/types.ts +10 -3
- package/src/board/fold.ts +1 -1
- package/src/board/github.ts +1 -2
- package/src/board/gitlab.ts +436 -0
- package/src/board/index.ts +1 -0
- package/src/board/logo.ts +49 -0
- package/src/board/open-file.ts +110 -0
- package/src/board/page.ts +57 -5
- package/src/board/schema.ts +4 -1
- package/src/board/server.ts +87 -3
- package/src/board/settings.ts +21 -24
- package/src/commands/changelog.command.ts +40 -0
- package/src/commands/clean.command.ts +6 -1
- package/src/commands/help.command.ts +2 -63
- package/src/commands/index.ts +6 -1
- package/src/commands/migrate.command.ts +71 -0
- package/src/commands/profile.command.ts +1 -1
- package/src/commands/runners.command.ts +43 -0
- package/src/commands/sync.command.ts +8 -4
- package/src/commands/table.ts +362 -0
- package/src/commit/check.ts +1 -0
- package/src/commit/common/constants.ts +4 -0
- package/src/commit/hook.ts +112 -8
- package/src/common/constants.ts +11 -9
- package/src/common/env-variables.ts +41 -0
- package/src/common/index.ts +1 -0
- package/src/common/layout-folder.ts +3 -4
- package/src/common/record.ts +5 -0
- package/src/config/common/constants.ts +28 -22
- package/src/config/loader.ts +22 -0
- package/src/config/schema.ts +330 -146
- package/src/create/add-app.ts +7 -2
- package/src/create/add-lib.ts +2 -4
- package/src/create/common/constants.ts +5 -3
- package/src/create/preset.ts +1 -0
- package/src/create/scratch.ts +2 -1
- package/src/doctor/checks.ts +277 -448
- package/src/doctor/common/constants.ts +27 -19
- package/src/doctor/private-values.ts +4 -1
- package/src/doctor/runner.ts +5 -12
- package/src/doctor/schema.ts +4 -0
- package/src/events/common/actor-names.ts +12 -0
- package/src/events/common/constants.ts +65 -38
- package/src/events/common/index.ts +1 -0
- package/src/events/hook.ts +5 -56
- package/src/events/text.ts +41 -6
- package/src/hooks/command-view.ts +80 -19
- package/src/hooks/common/constants.ts +26 -17
- package/src/hooks/common/types.ts +13 -24
- package/src/hooks/decision.ts +30 -12
- package/src/hooks/git-queries.ts +113 -0
- package/src/hooks/guard-git.ts +76 -24
- package/src/hooks/guard-outside.ts +334 -311
- package/src/hooks/guard-runner.ts +206 -0
- package/src/hooks/guard-writes.ts +87 -184
- package/src/hooks/hook-input.ts +57 -0
- package/src/hooks/index.ts +3 -6
- package/src/hooks/link-makers.ts +315 -0
- package/src/hooks/package-runners.ts +268 -0
- package/src/hooks/project-guards.ts +81 -44
- package/src/hooks/project-tmp.ts +39 -4
- package/src/hooks/runner-scan.ts +257 -0
- package/src/hooks/script-runners.ts +400 -0
- package/src/hooks/session-digest.ts +27 -117
- package/src/hooks/shell-folders.ts +760 -0
- package/src/hooks/shell-writes.ts +646 -0
- package/src/hooks/shell.ts +1421 -194
- package/src/hooks/subagent-card.ts +2 -2
- package/src/hooks/write-commands.ts +898 -0
- package/src/init/scaffold.ts +2 -3
- package/src/local/auto-clean.ts +2 -1
- package/src/local/browser-socket.ts +33 -0
- package/src/local/clean.ts +37 -6
- package/src/local/constants.ts +15 -1
- package/src/local/index.ts +1 -0
- package/src/local/scan.ts +41 -10
- package/src/manifest/render.ts +84 -30
- package/src/owner/constants.ts +4 -5
- package/src/owner/index.ts +0 -2
- package/src/owner/profile.ts +1 -0
- package/src/owner/schema.ts +51 -27
- package/src/owner/survey.ts +0 -3
- package/src/owner/view.ts +0 -9
- package/src/router.ts +8 -132
- package/src/rules/base.ts +12 -7
- package/src/rules/index.ts +1 -0
- package/src/rules/packs.ts +44 -0
- package/src/runners/check.ts +130 -0
- package/src/skills/frontmatter.ts +1 -0
- package/src/sync/agents-block.ts +104 -0
- package/src/sync/base-rules.ts +3 -3
- package/src/sync/claude-launch.ts +12 -12
- package/src/sync/common/constants.ts +0 -2
- package/src/sync/index.ts +1 -1
- package/src/sync/local-choice.ts +32 -3
- package/src/sync/planner.ts +2 -15
- package/src/sync/settings.ts +0 -17
- package/src/theme/index.ts +1 -0
- package/src/theme/tokens.ts +410 -0
- package/src/ui/prompt.ts +1 -0
- package/src/visualize/architecture.ts +504 -0
- package/src/visualize/assets.ts +41 -30
- package/src/visualize/compare-render.ts +22 -24
- package/src/visualize/constants.ts +27 -0
- package/src/visualize/diagrams.ts +13 -121
- package/src/visualize/kinds-render.ts +2 -2
- package/src/visualize/kinds-schema.ts +49 -0
- package/src/visualize/labels-vi.ts +25 -0
- package/src/visualize/labels.ts +2 -0
- package/src/visualize/layout.ts +415 -66
- package/src/visualize/page.ts +82 -15
- package/src/visualize/render.ts +2 -1
- package/src/visualize/schema.ts +29 -1
- package/src/visualize/sections.ts +78 -9
- package/src/visualize/theme.ts +49 -18
- package/src/wiki/anchors.ts +1 -0
- package/src/wiki/command.ts +10 -3
- package/src/wiki/source-links.ts +57 -18
- package/base/ci-global.json +0 -13
- package/base/claude/remote-hosts.json +0 -15
- package/base/hooks/guard-manifest.ts +0 -27
- package/base/hooks/guard-package.ts +0 -30
- package/base/hooks/guard-remote-hosts.ts +0 -70
- package/base/hooks/guard-scripting.ts +0 -32
- package/base/hooks/post-tool.ts +0 -37
- package/base/hooks/prompt-submit.ts +0 -54
- package/base/hooks/stop.ts +0 -40
- package/base/skills/build-a-feature/evals/evals.json +0 -29
- package/base/skills/docs-update/evals/evals.json +0 -23
- package/base/skills/docs-writing/evals/evals.json +0 -17
- package/base/skills/fix-a-bug/evals/evals.json +0 -17
- package/base/skills/knowledge-sync/SKILL.md +0 -81
- package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
- package/base/skills/knowledge-sync/references/workflow.md +0 -44
- package/base/skills/plan-a-change/evals/evals.json +0 -47
- package/base/skills/report-back/evals/evals.json +0 -23
- package/base/skills/research/evals/evals.json +0 -17
- package/base/skills/retro/evals/evals.json +0 -17
- package/base/skills/review-a-change/evals/evals.json +0 -17
- package/base/skills/ship/evals/evals.json +0 -23
- package/base/skills/visualize-work/evals/evals.json +0 -17
- package/base/templates/ci/github-actions.yml +0 -75
- package/base/templates/ci/gitlab-ci.yml +0 -52
- package/base/templates/trusted-hosts.local.example +0 -11
- package/src/ci/affected.ts +0 -176
- package/src/ci/command.ts +0 -166
- package/src/ci/common/constants.ts +0 -76
- package/src/ci/common/index.ts +0 -2
- package/src/ci/common/types.ts +0 -37
- package/src/ci/git.ts +0 -72
- package/src/ci/global.ts +0 -48
- package/src/ci/graph.ts +0 -43
- package/src/ci/index.ts +0 -7
- package/src/ci/workspace.ts +0 -119
- package/src/commands/ci.command.ts +0 -4
- package/src/hooks/guard-manifest.ts +0 -109
- package/src/hooks/guard-package.ts +0 -226
- package/src/hooks/guard-scripting.ts +0 -36
- package/src/hooks/host-pattern.ts +0 -17
- package/src/hooks/owner-reply.ts +0 -162
- package/src/hooks/post-tool.ts +0 -138
- package/src/hooks/remote-hosts.ts +0 -1013
- package/src/hooks/trusted-scripts.ts +0 -212
- package/src/owner/shape.ts +0 -496
- package/src/owner/violations.ts +0 -332
- package/src/signals/claims.ts +0 -73
- package/src/signals/classify.ts +0 -137
- package/src/signals/constants.ts +0 -88
- package/src/signals/index.ts +0 -5
- package/src/signals/loop.ts +0 -48
- package/src/signals/state.ts +0 -271
- package/src/sync/atlas-block.ts +0 -56
|
@@ -0,0 +1,646 @@
|
|
|
1
|
+
import { resolve } from 'node:path';
|
|
2
|
+
import { LinkMakers } from './link-makers.ts';
|
|
3
|
+
import { ShellParser } from './shell.ts';
|
|
4
|
+
import type { ISimpleCommand } from './shell.ts';
|
|
5
|
+
|
|
6
|
+
/** A path a command writes, and the folder it is taken from. */
|
|
7
|
+
export interface IWriteTarget {
|
|
8
|
+
word: string;
|
|
9
|
+
message: string;
|
|
10
|
+
/** The directory a relative `word` is taken from: the hook's, moved by `cd` and `git -C`. */
|
|
11
|
+
base: string;
|
|
12
|
+
/** What `$PWD` is in `word`: the shell's folder, moved by `cd` but not by `git -C`; undefined when it is not known. */
|
|
13
|
+
pwd?: string;
|
|
14
|
+
/** The plain variables the same shell set earlier on the line. */
|
|
15
|
+
vars?: Record<string, string>;
|
|
16
|
+
/** False after a `cd` the guard could not work out: `base` is then only the last folder it knew. */
|
|
17
|
+
isKnown?: boolean;
|
|
18
|
+
/** `>&word` with an expansion in it: a file, or a descriptor held in a variable. */
|
|
19
|
+
isAmbiguous?: boolean;
|
|
20
|
+
/** The target of a shell redirect. */
|
|
21
|
+
isRedirect?: boolean;
|
|
22
|
+
/** The word has a brace the guard cannot expand into its branches, so where it writes is not known. */
|
|
23
|
+
hasUnreadBrace?: boolean;
|
|
24
|
+
/** What a hard link of the line (`ln`, `cp -l`) links to, not a file it writes: the same file, so outside the project is outside. */
|
|
25
|
+
isLinkSource?: boolean;
|
|
26
|
+
/** What `cp`, `mv`, `rsync`, `install` or `ln` reads: not a write, but a link made on the line would be copied or moved by it. */
|
|
27
|
+
isLinkRead?: boolean;
|
|
28
|
+
/** The name a link is made at (or the folder it is made in): it is the command's own, so it is not a path through an earlier link. */
|
|
29
|
+
isLinkName?: boolean;
|
|
30
|
+
/** The absolute names of the symbolic links the line made before this command. */
|
|
31
|
+
links?: string[];
|
|
32
|
+
/** The line made a symbolic link this check could not name, so any path after it may go through one. */
|
|
33
|
+
hasUnknownLink?: boolean;
|
|
34
|
+
/** A `$` of the word was quoted or escaped: it is a character, and the word's text reads it as a variable. */
|
|
35
|
+
hasLiteralDollar?: boolean;
|
|
36
|
+
/**
|
|
37
|
+
* A removal or an in-place edit (`rm`, `sed -i`, `mv` of a source...): it creates nothing, so only a file the guards read
|
|
38
|
+
* their policy from counts. Every other path of such a word is left to the owner.
|
|
39
|
+
*/
|
|
40
|
+
isProtectedOnly?: boolean;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** The most words one word may make of its brace lists before the guard stops expanding it. */
|
|
44
|
+
const MAX_BRACE_WORDS = 64;
|
|
45
|
+
|
|
46
|
+
/** The `}` that closes the `{` at `open`, and the top-level commas between them; -1 when it never closes. */
|
|
47
|
+
const braceGroupAt = (opts: {
|
|
48
|
+
word: string;
|
|
49
|
+
open: number;
|
|
50
|
+
}): { close: number; commas: number[] } => {
|
|
51
|
+
const commas: number[] = [];
|
|
52
|
+
let depth = 0;
|
|
53
|
+
|
|
54
|
+
for (let index = opts.open; index < opts.word.length; index += 1) {
|
|
55
|
+
const char = opts.word[index];
|
|
56
|
+
|
|
57
|
+
depth += Number(char === '{') - Number(char === '}');
|
|
58
|
+
|
|
59
|
+
if (depth === 0) {
|
|
60
|
+
// Like bash: a `}` closes a list only after a comma or a `..`; before that it is text (`{a},/etc}`).
|
|
61
|
+
if (commas.length > 0 || opts.word.slice(opts.open, index).includes('..')) {
|
|
62
|
+
return { close: index, commas };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
depth = 1;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
if (char === ',' && depth === 1) {
|
|
69
|
+
commas.push(index);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
return { close: -1, commas };
|
|
74
|
+
};
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* The words a shell makes of a word with brace lists (`{out,/etc}/x` is `out/x` and `/etc/x`), each branch alone, so a
|
|
78
|
+
* branch outside the project is a target of its own. `{a}` and `{}` stay as written, and a
|
|
79
|
+
* sequence of digits or letters (`{1..3}`) is its first value: it can change no folder. What the guard cannot expand -
|
|
80
|
+
* another sequence of single characters (zsh makes `/` and `0` of `{/..0}`), a word that makes more than
|
|
81
|
+
* `MAX_BRACE_WORDS` words - is kept as written and marked unread.
|
|
82
|
+
*/
|
|
83
|
+
const bracedWordsOf = (opts: { word: string }): { words: string[]; isUnread: boolean } => {
|
|
84
|
+
const words: string[] = [];
|
|
85
|
+
let isUnread = false;
|
|
86
|
+
const expand = (word: string, from: number): void => {
|
|
87
|
+
// Stops the expansion itself: thirty lists of two make a billion words.
|
|
88
|
+
if (words.length > MAX_BRACE_WORDS) {
|
|
89
|
+
return;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const open = word.indexOf('{', from);
|
|
93
|
+
const { close, commas } =
|
|
94
|
+
open === -1 ? { close: -1, commas: [] } : braceGroupAt({ word, open });
|
|
95
|
+
|
|
96
|
+
if (close === -1) {
|
|
97
|
+
// An unmatched `{` is text, and a list after it is still expanded.
|
|
98
|
+
if (open === -1) {
|
|
99
|
+
words.push(word);
|
|
100
|
+
} else {
|
|
101
|
+
expand(word, open + 1);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
return;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
const [head, tail, inner] = [
|
|
108
|
+
word.slice(0, open),
|
|
109
|
+
word.slice(close + 1),
|
|
110
|
+
word.slice(open + 1, close),
|
|
111
|
+
];
|
|
112
|
+
const sequence = /^(?:(-?\d+)\.\.-?\d+|([A-Za-z])\.\.[A-Za-z])(?:\.\.-?\d+)?$/.exec(inner);
|
|
113
|
+
|
|
114
|
+
if (commas.length > 0) {
|
|
115
|
+
const bounds = [open, ...commas, close];
|
|
116
|
+
|
|
117
|
+
for (const [index, start] of bounds.slice(0, -1).entries()) {
|
|
118
|
+
expand(`${head}${word.slice(start + 1, bounds[index + 1])}${tail}`, open);
|
|
119
|
+
}
|
|
120
|
+
} else if (sequence !== null) {
|
|
121
|
+
expand(`${head}${sequence[1] ?? sequence[2]}${tail}`, open);
|
|
122
|
+
} else {
|
|
123
|
+
isUnread ||= /^.\.\..(?:\.\.-?\d+)?$/s.test(inner);
|
|
124
|
+
expand(word, open + 1);
|
|
125
|
+
}
|
|
126
|
+
};
|
|
127
|
+
|
|
128
|
+
expand(opts.word, 0);
|
|
129
|
+
|
|
130
|
+
return words.length > MAX_BRACE_WORDS
|
|
131
|
+
? { words: [opts.word], isUnread: true }
|
|
132
|
+
: { words, isUnread };
|
|
133
|
+
};
|
|
134
|
+
|
|
135
|
+
/** The options of a program that take a value, so the word after one is its value and no file of its own. */
|
|
136
|
+
interface IOptionValues {
|
|
137
|
+
/** Short options that take a value: `-t DIR`, `-tDIR`, `-vtDIR`. */
|
|
138
|
+
shorts: string;
|
|
139
|
+
/** Long options that take the next word as their value (`--suffix .bak`). */
|
|
140
|
+
longs: readonly string[];
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** Whether a short-option cluster ends in an option whose value is the next word (`-t`, `-vt`, not `-tDIR`). */
|
|
144
|
+
const takesNext = (opts: { word: string; shorts: string }): boolean => {
|
|
145
|
+
if (!/^-[A-Za-z0-9]/.test(opts.word)) {
|
|
146
|
+
return false;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
const letters = [...opts.word.slice(1)];
|
|
150
|
+
const at = letters.findIndex((letter) => opts.shorts.includes(letter));
|
|
151
|
+
|
|
152
|
+
return at === letters.length - 1;
|
|
153
|
+
};
|
|
154
|
+
|
|
155
|
+
/** The words that are not options, and not the values of the options `values` lists; after `--` every word. */
|
|
156
|
+
const positional = (opts: { args: string[]; values?: IOptionValues }): string[] => {
|
|
157
|
+
const words: string[] = [];
|
|
158
|
+
let isEnd = false;
|
|
159
|
+
|
|
160
|
+
for (let index = 0; index < opts.args.length; index += 1) {
|
|
161
|
+
const word = opts.args[index] ?? '';
|
|
162
|
+
|
|
163
|
+
if (!isEnd && word === '--') {
|
|
164
|
+
isEnd = true;
|
|
165
|
+
} else if (isEnd || !word.startsWith('-')) {
|
|
166
|
+
words.push(word);
|
|
167
|
+
} else if (opts.values !== undefined) {
|
|
168
|
+
const isLong = word.startsWith('--');
|
|
169
|
+
|
|
170
|
+
if (
|
|
171
|
+
isLong ? opts.values.longs.includes(word) : takesNext({ word, shorts: opts.values.shorts })
|
|
172
|
+
) {
|
|
173
|
+
index += 1;
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
return words;
|
|
179
|
+
};
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* The value of an option, long (`--output X`, `--output=X`) or short, next word or attached (`-o X`, `-oX`,
|
|
183
|
+
* `-sLo X`). `valued` lists every short letter of the program that takes a value, so a cluster is cut where
|
|
184
|
+
* its first value starts (`-dofile` is `-d` with the value `ofile`); without it only the letters asked for count.
|
|
185
|
+
*/
|
|
186
|
+
/** Whether `name` is a long option written short: `--output-doc` for `--output-document`. */
|
|
187
|
+
const isPrefixOf = (opts: { name: string; flag: string }): boolean =>
|
|
188
|
+
opts.name.length >= 3 && opts.name.startsWith('--') && opts.flag.startsWith(opts.name);
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* The word before each long option of the program that is not in its table of valued options and has no `=`:
|
|
192
|
+
* what it takes next may be the destination, so the word before it may be too (`cp a dest --sparse never`).
|
|
193
|
+
*/
|
|
194
|
+
const wordsBeforeUnknownOptions = (opts: { args: string[]; values: IOptionValues }): string[] => {
|
|
195
|
+
const found: string[] = [];
|
|
196
|
+
let last: string | undefined;
|
|
197
|
+
let isEnd = false;
|
|
198
|
+
|
|
199
|
+
for (let index = 0; index < opts.args.length; index += 1) {
|
|
200
|
+
const word = opts.args[index] ?? '';
|
|
201
|
+
|
|
202
|
+
if (!isEnd && word === '--') {
|
|
203
|
+
isEnd = true;
|
|
204
|
+
} else if (isEnd || !word.startsWith('-')) {
|
|
205
|
+
last = word;
|
|
206
|
+
} else if (word.startsWith('--')) {
|
|
207
|
+
if (opts.values.longs.includes(word)) {
|
|
208
|
+
index += 1;
|
|
209
|
+
} else if (!word.includes('=') && last !== undefined) {
|
|
210
|
+
found.push(last);
|
|
211
|
+
}
|
|
212
|
+
} else if (takesNext({ word, shorts: opts.values.shorts })) {
|
|
213
|
+
index += 1;
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
return found;
|
|
218
|
+
};
|
|
219
|
+
|
|
220
|
+
const valueOf = (opts: {
|
|
221
|
+
args: string[];
|
|
222
|
+
long?: string[];
|
|
223
|
+
short?: string[];
|
|
224
|
+
valued?: string;
|
|
225
|
+
}): string | undefined => {
|
|
226
|
+
const valued = opts.valued ?? (opts.short ?? []).join('');
|
|
227
|
+
|
|
228
|
+
for (const [index, word] of opts.args.entries()) {
|
|
229
|
+
for (const flag of opts.long ?? []) {
|
|
230
|
+
const name = word.split('=')[0] ?? word;
|
|
231
|
+
|
|
232
|
+
// getopt takes a unique prefix of a long option for it (`--output-doc`).
|
|
233
|
+
if (name === flag || isPrefixOf({ name, flag })) {
|
|
234
|
+
return word.includes('=') ? word.slice(name.length + 1) : opts.args[index + 1];
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
if (/^-[A-Za-z0-9]/.test(word)) {
|
|
239
|
+
const letters = [...word.slice(1)];
|
|
240
|
+
const at = letters.findIndex((letter) => valued.includes(letter));
|
|
241
|
+
const letter = letters[at];
|
|
242
|
+
|
|
243
|
+
if (at !== -1 && letter !== undefined && (opts.short ?? []).includes(letter)) {
|
|
244
|
+
const attached = letters.slice(at + 1).join('');
|
|
245
|
+
|
|
246
|
+
return attached === '' ? opts.args[index + 1] : attached;
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
return undefined;
|
|
252
|
+
};
|
|
253
|
+
/** Options of `git clone` that take the next word, so it is not the URL or the directory. */
|
|
254
|
+
const CLONE_VALUE_FLAGS = new Set([
|
|
255
|
+
'-b',
|
|
256
|
+
'--branch',
|
|
257
|
+
'--depth',
|
|
258
|
+
'-c',
|
|
259
|
+
'--config',
|
|
260
|
+
'-o',
|
|
261
|
+
'--origin',
|
|
262
|
+
'--reference',
|
|
263
|
+
'--separate-git-dir',
|
|
264
|
+
'--template',
|
|
265
|
+
'-j',
|
|
266
|
+
'--jobs',
|
|
267
|
+
'-u',
|
|
268
|
+
'--upload-pack',
|
|
269
|
+
'--filter',
|
|
270
|
+
'--shallow-since',
|
|
271
|
+
'--shallow-exclude',
|
|
272
|
+
]);
|
|
273
|
+
|
|
274
|
+
/** Words after `git`'s global options (`-C dir`, `-c k=v`, `--no-pager`) and the directory `-C` names. */
|
|
275
|
+
const gitArguments = (opts: { args: string[] }): { rest: string[]; dir: string | undefined } => {
|
|
276
|
+
let dir: string | undefined;
|
|
277
|
+
let index = 0;
|
|
278
|
+
|
|
279
|
+
while (index < opts.args.length && opts.args[index].startsWith('-')) {
|
|
280
|
+
const word = opts.args[index];
|
|
281
|
+
|
|
282
|
+
if (word === '-C') {
|
|
283
|
+
dir = opts.args[index + 1];
|
|
284
|
+
index += 2;
|
|
285
|
+
} else if (['-c', '--git-dir', '--work-tree', '--namespace'].includes(word)) {
|
|
286
|
+
index += 2;
|
|
287
|
+
} else {
|
|
288
|
+
index += 1;
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
return { rest: opts.args.slice(index), dir };
|
|
293
|
+
};
|
|
294
|
+
|
|
295
|
+
const gitTargets = (opts: {
|
|
296
|
+
rest: string[];
|
|
297
|
+
base: string;
|
|
298
|
+
dir: string | undefined;
|
|
299
|
+
}): IWriteTarget[] => {
|
|
300
|
+
const base = opts.dir === undefined ? opts.base : resolve(opts.base, opts.dir);
|
|
301
|
+
const [sub, second] = positional({ args: opts.rest });
|
|
302
|
+
|
|
303
|
+
if (sub === 'worktree' && second === 'add') {
|
|
304
|
+
const afterAdd = opts.rest.slice(opts.rest.indexOf('add') + 1);
|
|
305
|
+
const skipped = new Set<number>();
|
|
306
|
+
|
|
307
|
+
for (const [index, word] of afterAdd.entries()) {
|
|
308
|
+
if (word === '-b' || word === '-B') {
|
|
309
|
+
skipped.add(index);
|
|
310
|
+
skipped.add(index + 1);
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
const path = afterAdd.find((word, index) => !word.startsWith('-') && !skipped.has(index));
|
|
315
|
+
|
|
316
|
+
return path === undefined
|
|
317
|
+
? []
|
|
318
|
+
: [{ word: path, base, message: `git worktree add creates ${path}` }];
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
if (sub === 'clone') {
|
|
322
|
+
const afterClone = opts.rest.slice(opts.rest.indexOf('clone') + 1);
|
|
323
|
+
const words: string[] = [];
|
|
324
|
+
|
|
325
|
+
for (let index = 0; index < afterClone.length; index += 1) {
|
|
326
|
+
if (CLONE_VALUE_FLAGS.has(afterClone[index])) {
|
|
327
|
+
index += 1;
|
|
328
|
+
} else if (!afterClone[index].startsWith('-')) {
|
|
329
|
+
words.push(afterClone[index]);
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
const [, destination] = words;
|
|
334
|
+
|
|
335
|
+
return words.length === 0
|
|
336
|
+
? []
|
|
337
|
+
: [
|
|
338
|
+
{
|
|
339
|
+
word: destination ?? '.',
|
|
340
|
+
base,
|
|
341
|
+
message:
|
|
342
|
+
destination === undefined
|
|
343
|
+
? 'git clone writes into the current directory'
|
|
344
|
+
: `git clone writes ${destination}`,
|
|
345
|
+
},
|
|
346
|
+
];
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
return [];
|
|
350
|
+
};
|
|
351
|
+
|
|
352
|
+
export class ShellWrites {
|
|
353
|
+
/** curl's short options that take a value; every other letter is a switch (`-sL`). */
|
|
354
|
+
private static readonly CURL_VALUED_SHORT = 'AbcCdDeEFHKmoPQrtTuUwxXyYz';
|
|
355
|
+
|
|
356
|
+
/** What the options of the programs that name a destination take as values, so a value is not read as the destination. */
|
|
357
|
+
private static readonly VALUES: Readonly<Record<string, IOptionValues>> = {
|
|
358
|
+
cp: { shorts: 'St', longs: ['--suffix', '--target-directory'] },
|
|
359
|
+
mv: { shorts: 'St', longs: ['--suffix', '--target-directory'] },
|
|
360
|
+
ln: { shorts: 'St', longs: ['--suffix', '--target-directory'] },
|
|
361
|
+
install: {
|
|
362
|
+
shorts: 'gmoSt',
|
|
363
|
+
longs: ['--group', '--mode', '--owner', '--suffix', '--target-directory', '--strip-program'],
|
|
364
|
+
},
|
|
365
|
+
rsync: {
|
|
366
|
+
shorts: 'efBMT@',
|
|
367
|
+
longs: [
|
|
368
|
+
'--rsh',
|
|
369
|
+
'--rsync-path',
|
|
370
|
+
'--exclude',
|
|
371
|
+
'--exclude-from',
|
|
372
|
+
'--include',
|
|
373
|
+
'--include-from',
|
|
374
|
+
'--filter',
|
|
375
|
+
'--files-from',
|
|
376
|
+
'--backup-dir',
|
|
377
|
+
'--suffix',
|
|
378
|
+
'--log-file',
|
|
379
|
+
'--log-file-format',
|
|
380
|
+
'--out-format',
|
|
381
|
+
'--port',
|
|
382
|
+
'--bwlimit',
|
|
383
|
+
'--partial-dir',
|
|
384
|
+
'--temp-dir',
|
|
385
|
+
'--compare-dest',
|
|
386
|
+
'--copy-dest',
|
|
387
|
+
'--link-dest',
|
|
388
|
+
'--chmod',
|
|
389
|
+
'--chown',
|
|
390
|
+
'--usermap',
|
|
391
|
+
'--groupmap',
|
|
392
|
+
'--timeout',
|
|
393
|
+
'--contimeout',
|
|
394
|
+
'--max-size',
|
|
395
|
+
'--min-size',
|
|
396
|
+
'--max-delete',
|
|
397
|
+
'--modify-window',
|
|
398
|
+
'--block-size',
|
|
399
|
+
'--compress-level',
|
|
400
|
+
'--skip-compress',
|
|
401
|
+
'--compress-choice',
|
|
402
|
+
'--checksum-choice',
|
|
403
|
+
'--iconv',
|
|
404
|
+
'--password-file',
|
|
405
|
+
'--read-batch',
|
|
406
|
+
'--write-batch',
|
|
407
|
+
'--only-write-batch',
|
|
408
|
+
'--address',
|
|
409
|
+
'--sockopts',
|
|
410
|
+
'--info',
|
|
411
|
+
'--debug',
|
|
412
|
+
'--stop-after',
|
|
413
|
+
'--stop-at',
|
|
414
|
+
'--protocol',
|
|
415
|
+
'--copy-as',
|
|
416
|
+
'--early-input',
|
|
417
|
+
'--outbuf',
|
|
418
|
+
'--remote-option',
|
|
419
|
+
],
|
|
420
|
+
},
|
|
421
|
+
};
|
|
422
|
+
/** The programs that remove or empty the files they are given. */
|
|
423
|
+
private static readonly REMOVERS = new Set(['rm', 'unlink', 'rmdir', 'shred', 'truncate']);
|
|
424
|
+
/** The `git` subcommands that remove, move or restore the files they are given. */
|
|
425
|
+
private static readonly GIT_FILE_COMMANDS = new Set(['rm', 'mv', 'restore', 'checkout']);
|
|
426
|
+
|
|
427
|
+
/**
|
|
428
|
+
* The words of a command that removes, moves away or edits in place the files it names: `rm`, `unlink`, `rmdir`, `shred`,
|
|
429
|
+
* `truncate`, `sed -i`, `perl -i`, the sources of `mv`, and `git rm`, `git mv`, `git restore` and `git checkout`. Each non-option
|
|
430
|
+
* word is a candidate; the guard keeps only those that are a file it protects.
|
|
431
|
+
*/
|
|
432
|
+
private static protectedWordsOf(opts: {
|
|
433
|
+
name: string;
|
|
434
|
+
args: string[];
|
|
435
|
+
values?: IOptionValues;
|
|
436
|
+
}): { word: string; message: string }[] {
|
|
437
|
+
const { name, args } = opts;
|
|
438
|
+
const words = (list: string[]): string[] => list.filter((word) => !word.startsWith('-'));
|
|
439
|
+
const named = (list: string[], what: string): { word: string; message: string }[] =>
|
|
440
|
+
words(list).map((word) => ({ word, message: `${what} ${word}` }));
|
|
441
|
+
|
|
442
|
+
if (ShellWrites.REMOVERS.has(name)) {
|
|
443
|
+
return named(args, `${name} removes or empties`);
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
if (
|
|
447
|
+
name === 'sed' &&
|
|
448
|
+
args.some(
|
|
449
|
+
(word) =>
|
|
450
|
+
word === '--in-place' || word.startsWith('--in-place=') || /^-[a-zA-Z]*i/.test(word),
|
|
451
|
+
)
|
|
452
|
+
) {
|
|
453
|
+
return named(args, 'sed edits in place');
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
if (name === 'perl' && args.some((word) => /^-[a-zA-Z]*i/.test(word))) {
|
|
457
|
+
return named(args, 'perl edits in place');
|
|
458
|
+
}
|
|
459
|
+
|
|
460
|
+
if (name === 'mv') {
|
|
461
|
+
const directory = valueOf({
|
|
462
|
+
args,
|
|
463
|
+
long: ['--target-directory'],
|
|
464
|
+
short: ['t'],
|
|
465
|
+
valued: opts.values?.shorts,
|
|
466
|
+
});
|
|
467
|
+
const sources = positional({ args, values: opts.values });
|
|
468
|
+
|
|
469
|
+
return named(directory === undefined ? sources.slice(0, -1) : sources, 'mv moves away');
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
if (name === 'git') {
|
|
473
|
+
const { rest } = gitArguments({ args });
|
|
474
|
+
const [sub, ...after] = rest;
|
|
475
|
+
|
|
476
|
+
return sub !== undefined && ShellWrites.GIT_FILE_COMMANDS.has(sub)
|
|
477
|
+
? named(after, `git ${sub} changes`)
|
|
478
|
+
: [];
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
return [];
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
/** The words a simple command would create or write, with a name for what writes them. */
|
|
485
|
+
static targetsOf(opts: { command: ISimpleCommand; base: string; tmp: string }): IWriteTarget[] {
|
|
486
|
+
const program = ShellParser.programOf({ command: opts.command });
|
|
487
|
+
const name = ShellParser.basenameOf({ word: program.name });
|
|
488
|
+
const { base } = opts;
|
|
489
|
+
// The shell expands braces before the program sees its words: `{-t,/etc}` is `-t /etc`, so the options are read after.
|
|
490
|
+
const redirected = opts.command.redirects.map((word) => ({ word, ...bracedWordsOf({ word }) }));
|
|
491
|
+
const braced = program.args.map((word) => bracedWordsOf({ word }));
|
|
492
|
+
// Bash drops an empty branch (`{,/etc}` is the one word `/etc`).
|
|
493
|
+
const args = braced.flatMap((entry) =>
|
|
494
|
+
entry.words.length > 1 ? entry.words.filter((word) => word !== '') : entry.words,
|
|
495
|
+
);
|
|
496
|
+
const isUnread = [...redirected, ...braced].some((entry) => entry.isUnread);
|
|
497
|
+
const targets: IWriteTarget[] = redirected.flatMap(({ word, words }) =>
|
|
498
|
+
words.map((expanded) => ({
|
|
499
|
+
word: expanded,
|
|
500
|
+
base,
|
|
501
|
+
message: `a shell redirect writes ${expanded}`,
|
|
502
|
+
isAmbiguous: opts.command.copies?.includes(word) === true,
|
|
503
|
+
isRedirect: true,
|
|
504
|
+
})),
|
|
505
|
+
);
|
|
506
|
+
const assignments = [
|
|
507
|
+
...opts.command.assignments,
|
|
508
|
+
...(['export', 'declare', 'typeset', 'local', 'readonly'].includes(name) ? args : []),
|
|
509
|
+
];
|
|
510
|
+
|
|
511
|
+
// A prefix assignment (`TMPDIR={a,b} cmd`) is not expanded for braces; the arguments of `export` and the like are.
|
|
512
|
+
const assigned: IWriteTarget[] = [];
|
|
513
|
+
|
|
514
|
+
for (const assignment of assignments.filter((word) => word.startsWith('TMPDIR='))) {
|
|
515
|
+
assigned.push({
|
|
516
|
+
word: assignment.slice('TMPDIR='.length),
|
|
517
|
+
base,
|
|
518
|
+
message: 'TMPDIR points outside the project',
|
|
519
|
+
});
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
const values = ShellWrites.VALUES[name];
|
|
523
|
+
const maker = LinkMakers.of({ name, args });
|
|
524
|
+
const last = positional({ args, values }).at(-1);
|
|
525
|
+
const add = (word: string, message: string): number => targets.push({ word, base, message });
|
|
526
|
+
|
|
527
|
+
if (['mkdir', 'touch'].includes(name)) {
|
|
528
|
+
for (const word of positional({ args })) {
|
|
529
|
+
add(word, `${name} creates ${word}`);
|
|
530
|
+
}
|
|
531
|
+
} else if (['cp', 'mv', 'install', 'ln', 'rsync', 'link'].includes(name)) {
|
|
532
|
+
// `-t` names the destination of `cp`, `mv`, `install` and `ln`; in `rsync` it is `--times`.
|
|
533
|
+
const directory =
|
|
534
|
+
name === 'rsync'
|
|
535
|
+
? undefined
|
|
536
|
+
: valueOf({ args, long: ['--target-directory'], short: ['t'], valued: values?.shorts });
|
|
537
|
+
|
|
538
|
+
if (directory !== undefined) {
|
|
539
|
+
add(directory, `${name} writes into ${directory}`);
|
|
540
|
+
} else if (last !== undefined) {
|
|
541
|
+
add(last, `${name} writes ${last}`);
|
|
542
|
+
}
|
|
543
|
+
|
|
544
|
+
for (const word of values === undefined ? [] : wordsBeforeUnknownOptions({ args, values })) {
|
|
545
|
+
if (word !== last) {
|
|
546
|
+
add(
|
|
547
|
+
word,
|
|
548
|
+
`${name} may write ${word}: an option it does not know could take what follows`,
|
|
549
|
+
);
|
|
550
|
+
}
|
|
551
|
+
}
|
|
552
|
+
for (const word of maker?.hardSources ?? []) {
|
|
553
|
+
targets.push({
|
|
554
|
+
word,
|
|
555
|
+
base,
|
|
556
|
+
message: `${name} links to ${word}`,
|
|
557
|
+
isLinkSource: true,
|
|
558
|
+
isAmbiguous: true,
|
|
559
|
+
});
|
|
560
|
+
}
|
|
561
|
+
|
|
562
|
+
// What the command reads may be a link the line made: a copy or a move carries a relative link somewhere else.
|
|
563
|
+
const words = positional({ args, values });
|
|
564
|
+
const readFrom = directory !== undefined || words.length < 2 ? words : words.slice(0, -1);
|
|
565
|
+
|
|
566
|
+
for (const word of readFrom) {
|
|
567
|
+
targets.push({ word, base, message: `${name} reads ${word}`, isLinkRead: true });
|
|
568
|
+
}
|
|
569
|
+
} else if (name === 'tee') {
|
|
570
|
+
for (const word of positional({ args })) {
|
|
571
|
+
add(word, `tee writes ${word}`);
|
|
572
|
+
}
|
|
573
|
+
} else if (name === 'dd') {
|
|
574
|
+
const output = args.find((word) => word.startsWith('of='));
|
|
575
|
+
|
|
576
|
+
if (output !== undefined) {
|
|
577
|
+
add(output.slice(3), `dd writes ${output.slice(3)}`);
|
|
578
|
+
}
|
|
579
|
+
} else if (name === 'curl') {
|
|
580
|
+
const output = valueOf({
|
|
581
|
+
args,
|
|
582
|
+
long: ['--output'],
|
|
583
|
+
short: ['o'],
|
|
584
|
+
valued: ShellWrites.CURL_VALUED_SHORT,
|
|
585
|
+
});
|
|
586
|
+
const directory = valueOf({ args, long: ['--output-dir'] });
|
|
587
|
+
|
|
588
|
+
if (output !== undefined) {
|
|
589
|
+
add(output, `curl saves to ${output}`);
|
|
590
|
+
}
|
|
591
|
+
|
|
592
|
+
if (directory !== undefined) {
|
|
593
|
+
add(directory, `curl saves into ${directory}`);
|
|
594
|
+
}
|
|
595
|
+
} else if (name === 'wget') {
|
|
596
|
+
const valued = 'aoeTtwQiBIXARDlUPO';
|
|
597
|
+
const output = valueOf({ args, long: ['--output-document'], short: ['O'], valued });
|
|
598
|
+
const directory = valueOf({ args, long: ['--directory-prefix'], short: ['P'], valued });
|
|
599
|
+
|
|
600
|
+
for (const word of [output, directory]) {
|
|
601
|
+
if (word !== undefined) {
|
|
602
|
+
add(word, `wget saves to ${word}`);
|
|
603
|
+
}
|
|
604
|
+
}
|
|
605
|
+
} else if (name === 'mktemp') {
|
|
606
|
+
const directory = valueOf({ args, long: ['--tmpdir'], short: ['p'], valued: 'p' });
|
|
607
|
+
const inTmpdir = args.some((word) => /^-[a-zA-Z]*t[a-zA-Z]*$/.test(word));
|
|
608
|
+
const [template] = positional({ args }).filter((word) => word !== directory);
|
|
609
|
+
|
|
610
|
+
if (directory !== undefined) {
|
|
611
|
+
add(directory, 'mktemp creates a temporary file');
|
|
612
|
+
} else if (inTmpdir || template === undefined) {
|
|
613
|
+
add(opts.tmp, 'mktemp creates a file in the system temp directory');
|
|
614
|
+
} else {
|
|
615
|
+
add(template, 'mktemp creates a temporary file');
|
|
616
|
+
}
|
|
617
|
+
} else if (name === 'git') {
|
|
618
|
+
const { rest, dir } = gitArguments({ args });
|
|
619
|
+
|
|
620
|
+
targets.push(...gitTargets({ rest, base, dir }));
|
|
621
|
+
|
|
622
|
+
// `git -C <dir>` runs in that folder, which may be reached through a link the line made.
|
|
623
|
+
if (dir !== undefined) {
|
|
624
|
+
targets.push({ word: dir, base, message: `git runs in ${dir}`, isLinkRead: true });
|
|
625
|
+
}
|
|
626
|
+
}
|
|
627
|
+
|
|
628
|
+
// A removal or an in-place edit makes nothing outside the project, but it is how an agent loosens a guard.
|
|
629
|
+
for (const { word, message } of ShellWrites.protectedWordsOf({ name, args, values })) {
|
|
630
|
+
targets.push({ word, base, message, isProtectedOnly: true });
|
|
631
|
+
}
|
|
632
|
+
|
|
633
|
+
const own = maker !== undefined && maker.names.length > 0 ? maker.destination : undefined;
|
|
634
|
+
|
|
635
|
+
return [...assigned, ...targets]
|
|
636
|
+
.map((target) =>
|
|
637
|
+
own !== undefined &&
|
|
638
|
+
target.word === own &&
|
|
639
|
+
target.isLinkSource !== true &&
|
|
640
|
+
target.isLinkRead !== true
|
|
641
|
+
? { ...target, isLinkName: true }
|
|
642
|
+
: target,
|
|
643
|
+
)
|
|
644
|
+
.map((target) => (isUnread ? { ...target, hasUnreadBrace: true } : target));
|
|
645
|
+
}
|
|
646
|
+
}
|