@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.
Files changed (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -0,0 +1,315 @@
1
+ import { basename } from 'node:path';
2
+
3
+ /** How one program that can make a link reads its options. */
4
+ interface IMakerTable {
5
+ /** The short options that take a value (the rest of the cluster, or the next word). */
6
+ valued: string;
7
+ /** Every long option: whether it takes its value as the next word. A unique prefix names one, as getopt reads it. */
8
+ longs: Readonly<Record<string, boolean>>;
9
+ /** The short options that matter here, by the key the long option of the same meaning has. */
10
+ shorts: Readonly<Record<string, string>>;
11
+ /** The key of the option that makes symbolic links. */
12
+ symbolic: string;
13
+ /** The key of the option that makes hard links; `ln` makes them unless told otherwise. */
14
+ hard?: string;
15
+ }
16
+
17
+ /** What a program that makes links does with its words: where they point and the names they are made at. */
18
+ export interface ILinkMaker {
19
+ /** What a hard link points at, as written: from the folder the command runs in. Empty for a symbolic link. */
20
+ hardSources: string[];
21
+ /** Every source word, hard or symbolic. */
22
+ sources: string[];
23
+ /** The names a symbolic link is made at, as candidates (the name may be a folder that exists); empty for a hard link. */
24
+ names: string[];
25
+ /** The name the links are made at, or the folder they are made in, as written. */
26
+ destination: string | undefined;
27
+ }
28
+
29
+ const LN: IMakerTable = {
30
+ valued: 'St',
31
+ longs: {
32
+ symbolic: false,
33
+ relative: false,
34
+ force: false,
35
+ interactive: false,
36
+ verbose: false,
37
+ logical: false,
38
+ physical: false,
39
+ 'no-dereference': false,
40
+ 'no-target-directory': false,
41
+ 'target-directory': true,
42
+ suffix: true,
43
+ backup: false,
44
+ directory: false,
45
+ help: false,
46
+ version: false,
47
+ },
48
+ shorts: { s: 'symbolic' },
49
+ symbolic: 'symbolic',
50
+ };
51
+
52
+ const CP: IMakerTable = {
53
+ valued: 'St',
54
+ longs: {
55
+ 'symbolic-link': false,
56
+ link: false,
57
+ archive: false,
58
+ 'attributes-only': false,
59
+ backup: false,
60
+ 'copy-contents': false,
61
+ 'no-dereference': false,
62
+ force: false,
63
+ interactive: false,
64
+ dereference: false,
65
+ 'no-clobber': false,
66
+ 'no-preserve': true,
67
+ parents: false,
68
+ preserve: false,
69
+ recursive: false,
70
+ reflink: false,
71
+ 'remove-destination': false,
72
+ sparse: true,
73
+ 'strip-trailing-slashes': false,
74
+ suffix: true,
75
+ 'target-directory': true,
76
+ 'no-target-directory': false,
77
+ update: false,
78
+ verbose: false,
79
+ 'one-file-system': false,
80
+ context: false,
81
+ debug: false,
82
+ 'keep-directory-symlink': false,
83
+ help: false,
84
+ version: false,
85
+ },
86
+ shorts: {
87
+ s: 'symbolic-link',
88
+ l: 'link',
89
+ a: 'archive',
90
+ P: 'no-dereference',
91
+ d: 'no-dereference',
92
+ r: 'recursive',
93
+ R: 'recursive',
94
+ },
95
+ symbolic: 'symbolic-link',
96
+ hard: 'link',
97
+ };
98
+
99
+ /** `mv` carries any link it moves; its options are only read to find the destination. */
100
+ const MV: IMakerTable = {
101
+ valued: 'St',
102
+ longs: {
103
+ 'target-directory': true,
104
+ suffix: true,
105
+ backup: false,
106
+ force: false,
107
+ interactive: false,
108
+ 'no-clobber': false,
109
+ 'no-target-directory': false,
110
+ update: false,
111
+ verbose: false,
112
+ 'strip-trailing-slashes': false,
113
+ context: false,
114
+ debug: false,
115
+ help: false,
116
+ version: false,
117
+ },
118
+ shorts: {},
119
+ symbolic: '',
120
+ };
121
+
122
+ /** `rsync` copies a link as a link with `-l`, `-a` and `--links`; the options it takes a value for are read to find the destination. */
123
+ const RSYNC: IMakerTable = {
124
+ valued: 'efBMT@',
125
+ longs: { links: false, archive: false },
126
+ shorts: { l: 'links', a: 'archive' },
127
+ symbolic: '',
128
+ };
129
+
130
+ /** Coreutils `link FILE1 FILE2`: one hard link, with no options. */
131
+ const LINK: IMakerTable = { valued: '', longs: {}, shorts: {}, symbolic: 'symbolic' };
132
+
133
+ const CARRIERS: Readonly<Record<string, IMakerTable>> = { mv: MV, cp: CP, rsync: RSYNC };
134
+
135
+ const TABLES: Readonly<Record<string, IMakerTable>> = { ln: LN, cp: CP, link: LINK };
136
+
137
+ /** The options set, the other words and the target folder (`-t`, `--target-directory`) of a command line, read left to right. */
138
+ const read = (opts: {
139
+ args: string[];
140
+ table: IMakerTable;
141
+ }): { flags: Set<string>; words: string[]; directory: string | undefined } => {
142
+ const { args, table } = opts;
143
+ const flags = new Set<string>();
144
+ const words: string[] = [];
145
+ let directory: string | undefined;
146
+ let isEnd = false;
147
+
148
+ for (let index = 0; index < args.length; index += 1) {
149
+ const word = args[index] ?? '';
150
+
151
+ if (isEnd || !word.startsWith('-') || word === '-') {
152
+ words.push(word);
153
+ continue;
154
+ }
155
+
156
+ if (word === '--') {
157
+ isEnd = true;
158
+ continue;
159
+ }
160
+
161
+ if (word.startsWith('--')) {
162
+ const equals = word.indexOf('=');
163
+ const name = word.slice(2, equals === -1 ? undefined : equals);
164
+ const inline = equals === -1 ? undefined : word.slice(equals + 1);
165
+ const keys = Object.hasOwn(table.longs, name)
166
+ ? [name]
167
+ : Object.keys(table.longs).filter((key) => key.startsWith(name));
168
+
169
+ for (const key of keys) {
170
+ flags.add(key);
171
+ }
172
+
173
+ const takesValue = keys.length > 0 && keys.every((key) => table.longs[key] === true);
174
+
175
+ if (keys.length === 1 && keys[0] === 'target-directory') {
176
+ directory = inline ?? args[index + 1];
177
+ }
178
+
179
+ if (takesValue && inline === undefined) {
180
+ index += 1;
181
+ }
182
+
183
+ continue;
184
+ }
185
+
186
+ const letters = [...word.slice(1)];
187
+
188
+ for (const [at, letter] of letters.entries()) {
189
+ if (table.valued.includes(letter)) {
190
+ const rest = letters.slice(at + 1).join('');
191
+
192
+ if (letter === 't') {
193
+ directory = rest === '' ? args[index + 1] : rest;
194
+ }
195
+
196
+ if (rest === '') {
197
+ index += 1;
198
+ }
199
+
200
+ break;
201
+ }
202
+
203
+ const key = table.shorts[letter];
204
+
205
+ if (key !== undefined) {
206
+ flags.add(key);
207
+ }
208
+ }
209
+ }
210
+
211
+ return { flags, words, directory };
212
+ };
213
+
214
+ /** The folder `tar` extracts into, when it extracts (`tar xf a.tar -C dir`), as written. */
215
+ const tarDestination = (opts: { args: string[] }): string | undefined => {
216
+ const first = opts.args[0] ?? '';
217
+ const isExtract =
218
+ (/^-?[a-zA-Z]+$/.test(first) && !first.startsWith('--') && first.includes('x')) ||
219
+ opts.args.some((word) => word === '--extract' || word === '--get');
220
+
221
+ if (!isExtract) {
222
+ return undefined;
223
+ }
224
+
225
+ for (const [index, word] of opts.args.entries()) {
226
+ if (word === '-C' || word === '--directory') {
227
+ return opts.args[index + 1];
228
+ }
229
+
230
+ if (word.startsWith('--directory=')) {
231
+ return word.slice('--directory='.length);
232
+ }
233
+
234
+ if (/^-[a-zA-Z]*C.+/.test(word)) {
235
+ return word.slice(word.indexOf('C') + 1);
236
+ }
237
+ }
238
+
239
+ return undefined;
240
+ };
241
+
242
+ export class LinkMakers {
243
+ /**
244
+ * The destination of a command that may carry a link the line made to a new name: `mv`, a `cp` that copies links (`-a`, `-P`,
245
+ * `-d`, `-r`, `-R`), an `rsync` that does (`-l`, `-a`), a `tar` that extracts into a folder. The new name is one a later path
246
+ * may go through, and the guard does not know whether the thing moved was a link, so the name counts as a link of the line.
247
+ */
248
+ static carriedTo(opts: { name: string; args: string[] }): string[] {
249
+ if (opts.name === 'tar') {
250
+ const destination = tarDestination({ args: opts.args });
251
+
252
+ return destination === undefined ? [] : [destination];
253
+ }
254
+
255
+ const table = CARRIERS[opts.name];
256
+
257
+ if (table === undefined) {
258
+ return [];
259
+ }
260
+
261
+ const { flags, words, directory } = read({ args: opts.args, table });
262
+ const isCarrying =
263
+ opts.name === 'mv' ||
264
+ (opts.name === 'cp' &&
265
+ ['archive', 'no-dereference', 'recursive'].some((key) => flags.has(key))) ||
266
+ (opts.name === 'rsync' && ['links', 'archive'].some((key) => flags.has(key)));
267
+ const destination = directory ?? (words.length > 1 ? words.at(-1) : undefined);
268
+
269
+ return isCarrying && destination !== undefined ? [destination] : [];
270
+ }
271
+
272
+ /**
273
+ * What `ln` (and `cp -s`, `cp -l`) links, or `undefined` for a command that makes no link. A hard link keeps nothing of the
274
+ * name it was given: the file is the same one, so what it points at is judged. A symbolic link keeps its text, which the
275
+ * system reads from the link's own folder later, so what matters on the line is the names it is made at.
276
+ */
277
+ static of(opts: { name: string; args: string[] }): ILinkMaker | undefined {
278
+ const table = TABLES[opts.name];
279
+
280
+ if (table === undefined) {
281
+ return undefined;
282
+ }
283
+
284
+ const { flags, words, directory } = read({ args: opts.args, table });
285
+ const isSymbolic = flags.has(table.symbolic);
286
+ const isHard = !isSymbolic && (table.hard === undefined || flags.has(table.hard));
287
+
288
+ if (!isSymbolic && !isHard) {
289
+ return undefined;
290
+ }
291
+
292
+ const link = directory === undefined && words.length > 1 ? words.at(-1) : undefined;
293
+ const sources = directory !== undefined || link === undefined ? words : words.slice(0, -1);
294
+ const named = (folder: string): string[] =>
295
+ sources.map((source) => `${folder}${basename(source)}`);
296
+ let names: string[] = [];
297
+
298
+ if (isSymbolic) {
299
+ if (directory !== undefined) {
300
+ names = named(`${directory}/`);
301
+ } else if (link === undefined) {
302
+ names = named('');
303
+ } else {
304
+ names = link.endsWith('/') ? named(link) : [link, ...named(`${link}/`)];
305
+ }
306
+ }
307
+
308
+ return {
309
+ hardSources: isHard ? sources : [],
310
+ sources,
311
+ names: names.filter((name) => !/(?:^|\/)\.{1,2}$/.test(name)),
312
+ destination: directory ?? link,
313
+ };
314
+ }
315
+ }
@@ -0,0 +1,268 @@
1
+ /** What a runner command is once its program and subcommand are found: the runner as written, and the words after it. */
2
+ export interface IRunnerCall {
3
+ /** `bunx`, `bun x`, `npm exec`, ... */
4
+ runner: string;
5
+ /** The words after the runner: its flags, then the package it runs. */
6
+ words: string[];
7
+ /** The flags that stood between the program and its subcommand (`bun --cwd other x`), with the value a flag took. */
8
+ leading: string[];
9
+ }
10
+
11
+ /** The package a runner's words run, and the flags on the way to it. */
12
+ export interface IRunnerTarget {
13
+ /** The first word after the flags: the package or bin, as written (a version included); empty when there is none. */
14
+ name: string;
15
+ /** The package a `-p` or `--package` flag names, as written. */
16
+ packageName?: string;
17
+ /** The exact flag `--no-install` stands before the name. */
18
+ hasNoInstall: boolean;
19
+ /** Every flag before the name, as written, and the value a flag that takes one was given. */
20
+ flags: string[];
21
+ /** The words after the name: the arguments of the program the package runs. */
22
+ rest: string[];
23
+ /** A `-c` or `--call` flag stood before the name: the program runs a command string, not a package. */
24
+ isCommandString: boolean;
25
+ }
26
+
27
+ const bare = (opts: { word: string }): string => opts.word.replace(/^["'`]+|["'`,;:.)\]}]+$/g, '');
28
+ /** A word without its quotes only: a subcommand is the whole word, so `x`.` or `x,` in a sentence is not one. */
29
+ const unquoted = (opts: { word: string }): string => opts.word.replace(/^["']+|["']+$/g, '');
30
+
31
+ /**
32
+ * The one table of the programs that fetch a package by name and run it, read by the runner guard, by `vulcan runners
33
+ * check` and by the script guard that follows the program `npx` runs. A flag is read the way that fails closed: the switches
34
+ * below take no value, and any other flag without `=` takes the next word, so a flag this table does not know can hide
35
+ * neither the package (the last word it took is read as the name) nor a second runner.
36
+ */
37
+ export class PackageRunners {
38
+ /** The program, and the words after it that make it run a package: none when the program itself does. */
39
+ static readonly PROGRAMS: Readonly<Record<string, readonly string[]>> = {
40
+ bunx: [],
41
+ pnpx: [],
42
+ npx: [],
43
+ bun: ['x'],
44
+ npm: ['exec', 'x'],
45
+ pnpm: ['dlx'],
46
+ yarn: ['dlx'],
47
+ };
48
+
49
+ /** Whether `name` is one of the programs of the table: an own key, so `constructor` in a sentence is not one. */
50
+ static isProgram(opts: { name: string }): boolean {
51
+ return Object.hasOwn(PackageRunners.PROGRAMS, opts.name);
52
+ }
53
+
54
+ /** Programs that run the program named after their own flags (`corepack` then `pnpm`). */
55
+ static readonly WRAPPERS: ReadonlySet<string> = new Set(['corepack']);
56
+
57
+ /** Flags that take no value, in any of the programs: every other flag without `=` takes the next word. */
58
+ static readonly SWITCHES: ReadonlySet<string> = new Set([
59
+ '--bun',
60
+ '--silent',
61
+ '-s',
62
+ '--quiet',
63
+ '-q',
64
+ '--verbose',
65
+ '--yes',
66
+ '-y',
67
+ '--no',
68
+ '--no-install',
69
+ '--ignore-existing',
70
+ '--offline',
71
+ '--prefer-offline',
72
+ '--prefer-online',
73
+ '--no-update-notifier',
74
+ '--no-color',
75
+ '--no-progress',
76
+ '--no-cache',
77
+ '--no-fund',
78
+ '--no-audit',
79
+ '--json',
80
+ '--global',
81
+ '-g',
82
+ '--force',
83
+ '-f',
84
+ '--latest',
85
+ '--hot',
86
+ '--watch',
87
+ '--smol',
88
+ ]);
89
+
90
+ /** The flags whose value is a package to run, and the bin is then one of its own. */
91
+ static readonly PACKAGE_FLAGS: ReadonlySet<string> = new Set(['-p', '--package']);
92
+
93
+ /** The flags that make `npx` and `npm exec` run a command string in a shell instead of a package. */
94
+ static readonly COMMAND_FLAGS: ReadonlySet<string> = new Set(['-c', '--call']);
95
+
96
+ /**
97
+ * The runners whose `COMMAND_FLAGS` run a string, which the guard then reads as a command line of its own. For `bunx` and
98
+ * `bun x`, `-c` is a config file; for pnpm, `-c` and `--shell-mode` are switches and the first word is still fetched.
99
+ */
100
+ static readonly COMMAND_RUNNERS: ReadonlySet<string> = new Set('npx,npm exec,npm x'.split(','));
101
+
102
+ /** Switches that only one runner has: they take no value there, and are unknown flags (which take one) elsewhere. */
103
+ static readonly RUNNER_SWITCHES: ReadonlyMap<string, ReadonlySet<string>> = new Map([
104
+ ['pnpm dlx', new Set(['-c', '--shell-mode'])],
105
+ ]);
106
+
107
+ /** The string a `-c` or `--call` flag among `words` gives, or `undefined` when there is none. */
108
+ static commandStringOf(opts: { words: string[] }): string | undefined {
109
+ for (const [index, word] of opts.words.entries()) {
110
+ if (word === '-c' || word === '--call') {
111
+ return opts.words[index + 1];
112
+ }
113
+
114
+ if (word.startsWith('--call=')) {
115
+ return word.slice('--call='.length);
116
+ }
117
+ }
118
+
119
+ return undefined;
120
+ }
121
+
122
+ /** The flags the `--no-install` form may carry: none of them moves the folder, the registry or the cache. */
123
+ static readonly HARMLESS: ReadonlySet<string> = new Set(['--bun', '--silent', '--no-install']);
124
+
125
+ /**
126
+ * The runner a command is and the words after it, or `undefined` when it runs no package by name. A flag of the program before
127
+ * its subcommand (`bun` with `--cwd`, `npm` with `--yes`) and a `corepack` in front are found: the flags before the subcommand are
128
+ * skipped, and a word after a flag may be that flag's value or the subcommand, so it is read as either.
129
+ */
130
+ static find(opts: { program: string; args: string[] }): IRunnerCall | undefined {
131
+ const name = opts.program.split('/').pop() ?? opts.program;
132
+
133
+ if (PackageRunners.WRAPPERS.has(name)) {
134
+ const at = opts.args.findIndex((word) => PackageRunners.isProgram({ name: word }));
135
+
136
+ return at === -1
137
+ ? undefined
138
+ : PackageRunners.find({ program: opts.args[at] ?? '', args: opts.args.slice(at + 1) });
139
+ }
140
+
141
+ const subcommands = PackageRunners.isProgram({ name })
142
+ ? PackageRunners.PROGRAMS[name]
143
+ : undefined;
144
+
145
+ if (subcommands === undefined) {
146
+ return undefined;
147
+ }
148
+
149
+ if (subcommands.length === 0) {
150
+ return { runner: name, words: opts.args, leading: [] };
151
+ }
152
+
153
+ const leading: string[] = [];
154
+
155
+ for (let index = 0; index < opts.args.length; index += 1) {
156
+ const word = unquoted({ word: opts.args[index] ?? '' });
157
+
158
+ if (word.startsWith('-')) {
159
+ leading.push(word);
160
+
161
+ const next = unquoted({ word: opts.args[index + 1] ?? '' });
162
+ const takes =
163
+ !word.includes('=') &&
164
+ !PackageRunners.SWITCHES.has(word) &&
165
+ next !== '' &&
166
+ !next.startsWith('-') &&
167
+ !subcommands.includes(next);
168
+
169
+ if (takes) {
170
+ leading.push(next);
171
+ index += 1;
172
+ }
173
+
174
+ continue;
175
+ }
176
+
177
+ return subcommands.includes(word)
178
+ ? { runner: `${name} ${word}`, words: opts.args.slice(index + 1), leading }
179
+ : undefined;
180
+ }
181
+
182
+ return undefined;
183
+ }
184
+
185
+ /**
186
+ * The package a runner's words run. The last word a flag this table does not know took is read as the name when no
187
+ * word follows it, so a switch the table lacks does not turn the package into a value.
188
+ */
189
+ static targetOf(opts: { words: string[]; runner?: string }): IRunnerTarget {
190
+ const own = PackageRunners.RUNNER_SWITCHES.get(opts.runner ?? '');
191
+ const flags: string[] = [];
192
+ let hasNoInstall = false;
193
+ let packageName: string | undefined;
194
+ let taken: string | undefined;
195
+
196
+ for (let index = 0; index < opts.words.length; index += 1) {
197
+ const word = bare({ word: opts.words[index] ?? '' });
198
+
199
+ if (word === '') {
200
+ continue;
201
+ }
202
+
203
+ if (word === '--') {
204
+ flags.push(word);
205
+ continue;
206
+ }
207
+
208
+ if (!word.startsWith('-')) {
209
+ return {
210
+ name: word,
211
+ ...(packageName === undefined ? {} : { packageName }),
212
+ hasNoInstall,
213
+ flags,
214
+ rest: opts.words.slice(index + 1),
215
+ isCommandString: flags.some((flag) =>
216
+ PackageRunners.COMMAND_FLAGS.has(flag.split('=')[0] ?? flag),
217
+ ),
218
+ };
219
+ }
220
+
221
+ flags.push(word);
222
+
223
+ const [flag, value] = word.split(/=(.*)/s);
224
+
225
+ if (value !== undefined) {
226
+ if (PackageRunners.PACKAGE_FLAGS.has(flag)) {
227
+ packageName = bare({ word: value });
228
+ }
229
+
230
+ continue;
231
+ }
232
+
233
+ if (flag === '--no-install') {
234
+ hasNoInstall = true;
235
+ continue;
236
+ }
237
+
238
+ if (PackageRunners.SWITCHES.has(flag) || own?.has(flag) === true) {
239
+ continue;
240
+ }
241
+
242
+ index += 1;
243
+
244
+ const given = bare({ word: opts.words[index] ?? '' });
245
+
246
+ if (given !== '') {
247
+ flags.push(given);
248
+ }
249
+
250
+ if (PackageRunners.PACKAGE_FLAGS.has(flag)) {
251
+ packageName = given;
252
+ } else {
253
+ taken = given === '' ? taken : given;
254
+ }
255
+ }
256
+
257
+ return {
258
+ name: packageName === undefined ? (taken ?? '') : '',
259
+ ...(packageName === undefined ? {} : { packageName }),
260
+ hasNoInstall,
261
+ flags,
262
+ rest: [],
263
+ isCommandString: flags.some((flag) =>
264
+ PackageRunners.COMMAND_FLAGS.has(flag.split('=')[0] ?? flag),
265
+ ),
266
+ };
267
+ }
268
+ }