@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
@@ -1,6 +1,6 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
- import type { IReadOnlyScript } from './common/index.ts';
3
+ import { GuardDecisions, HookConstants } from './common/index.ts';
4
4
 
5
5
  /** A command the project says is a database write or a deploy: guard-writes asks on a match. */
6
6
  export interface IProjectCommandCheck {
@@ -13,8 +13,19 @@ export interface IProjectCommandCheck {
13
13
  interface IGuardPolicy {
14
14
  commands: IProjectCommandCheck[];
15
15
  askPush: string[];
16
- /** `guard.writes.readOnlyScripts`; absent when the manifest lists none. */
17
- readOnlyScripts?: IReadOnlyScript[];
16
+ /** `guard.outside`: what guard-outside does with a write outside the project; the strictest of `VULCAN_GUARD_OUTSIDE` and the manifest, `ask` when neither says `deny`. */
17
+ outside: string;
18
+ /**
19
+ * `guard.asks`: `deny` makes every answer that would ask a human a refusal. The strictest of the launch environment
20
+ * (`VULCAN_GUARD_ASKS`), the manifest, and a manifest that exists but cannot be read; `ask` when none says otherwise.
21
+ */
22
+ asks: string;
23
+ /** What the answer adds when an ask is held: which of the three held it; `undefined` when asks stay asks. */
24
+ asksNote?: string;
25
+ /** `guard.toolOwnedPaths`: stores a tool manages itself, which guard-outside lets through. */
26
+ toolOwnedPaths: string[];
27
+ /** `guard.runners.allow`: the package names bunx, `bun x`, npx and `pnpm dlx` may run beyond `@venizia/*`. */
28
+ runnersAllow: string[];
18
29
  }
19
30
 
20
31
  /** Spelt out: the blocking hooks import nothing that reads the package. */
@@ -64,41 +75,57 @@ const commandOf = (opts: { value: unknown }): IProjectCommandCheck | undefined =
64
75
  }
65
76
  };
66
77
 
67
- const readOnlyScriptOf = (opts: { value: unknown }): IReadOnlyScript | undefined => {
68
- const holder = { value: opts.value };
69
- const script = isRecord(holder) ? holder.value['script'] : undefined;
70
- const listed = isRecord(holder) ? holder.value['readOnly'] : undefined;
71
- const words = Array.isArray(listed)
72
- ? listed.filter((word): word is string => typeof word === 'string' && word !== '')
73
- : [];
74
-
75
- if (
76
- typeof script !== 'string' ||
77
- script === '' ||
78
- !Array.isArray(listed) ||
79
- words.length !== listed.length
80
- ) {
81
- note({
82
- message:
83
- 'ignoring a guard.writes.readOnlyScripts entry that has no script or no readOnly list of words',
84
- });
85
-
86
- return undefined;
87
- }
88
-
89
- return { script, readOnly: words };
90
- };
91
-
92
78
  export class ProjectGuards {
79
+ /** The committed manifest, which a hook reads instead of the config. */
80
+ static readonly MANIFEST_FILE = GUARD_MANIFEST_FILE;
81
+
93
82
  /**
94
- * The commands, push targets and read-only scripts a project lists, from the committed manifest (`vulcan sync` renders
83
+ * The commands and push targets a project lists, from the committed manifest (`vulcan sync` renders
95
84
  * them from the config), so a hook reads them with no config loader and no zod. A project with no
96
85
  * manifest, or none of the block, has none; an entry that cannot be used is skipped, said once on
97
86
  * stderr, and the others stay.
98
87
  */
99
- static readPolicy(opts: { root: string }): IGuardPolicy {
88
+ static readPolicy(opts: {
89
+ root: string;
90
+ env?: Record<string, string | undefined>;
91
+ }): IGuardPolicy {
92
+ const policy = ProjectGuards.readManifest({ root: opts.root });
93
+ const env = opts.env ?? process.env;
94
+ const isEnvAsks = env[HookConstants.ENV_ASKS] === GuardDecisions.DENY;
95
+ const isEnvOutside = env[HookConstants.ENV_OUTSIDE] === GuardDecisions.DENY;
96
+ const isAsksDenied = isEnvAsks || policy.asks === GuardDecisions.DENY;
97
+ // Where the environment holds deny, the manifest is not trusted to loosen anything: the stores it would allow and the runners it would add are ignored.
98
+ const isEnvHeld = isEnvAsks || isEnvOutside;
99
+
100
+ return {
101
+ ...policy,
102
+ toolOwnedPaths: isEnvHeld ? [] : policy.toolOwnedPaths,
103
+ runnersAllow: isEnvHeld ? [] : policy.runnersAllow,
104
+ asks: isAsksDenied ? GuardDecisions.DENY : GuardDecisions.ASK,
105
+ asksNote: isEnvAsks ? HookConstants.HELD_ASK_ENV : policy.asksNote,
106
+ outside:
107
+ isEnvOutside || policy.outside === GuardDecisions.DENY
108
+ ? GuardDecisions.DENY
109
+ : GuardDecisions.ASK,
110
+ };
111
+ }
112
+
113
+ /** What the manifest sets, before the launch environment tightens it. A manifest that exists and cannot be read holds every ask. */
114
+ private static readManifest(opts: { root: string }): IGuardPolicy {
100
115
  const path = join(opts.root, GUARD_MANIFEST_FILE);
101
- const empty: IGuardPolicy = { commands: [], askPush: [] };
116
+ const empty: IGuardPolicy = {
117
+ commands: [],
118
+ askPush: [],
119
+ outside: GuardDecisions.ASK,
120
+ asks: GuardDecisions.ASK,
121
+ toolOwnedPaths: [],
122
+ runnersAllow: [],
123
+ };
124
+ const unreadable: IGuardPolicy = {
125
+ ...empty,
126
+ asks: GuardDecisions.DENY,
127
+ asksNote: HookConstants.MANIFEST_UNREADABLE,
128
+ };
102
129
 
103
130
  if (!existsSync(path)) {
104
131
  return empty;
@@ -110,14 +137,21 @@ export class ProjectGuards {
110
137
  manifest = JSON.parse(readFileSync(path, 'utf8'));
111
138
  } catch (error) {
112
139
  note({
113
- message: `the manifest could not be read, so the project's own patterns are off (${error instanceof Error ? error.message : String(error)})`,
140
+ message: `the manifest could not be read, so the project's own patterns are off and every ask is a deny (${error instanceof Error ? error.message : String(error)})`,
114
141
  });
115
142
 
116
- return empty;
143
+ return unreadable;
117
144
  }
118
145
 
119
146
  const top = { value: manifest };
120
- const guard = isRecord(top) ? { value: top.value['guard'] } : { value: undefined };
147
+
148
+ if (!isRecord(top)) {
149
+ note({ message: 'the manifest is not an object, so every ask is a deny' });
150
+
151
+ return unreadable;
152
+ }
153
+
154
+ const guard = { value: top.value['guard'] };
121
155
 
122
156
  if (!isRecord(guard)) {
123
157
  return empty;
@@ -126,13 +160,13 @@ export class ProjectGuards {
126
160
  const writes = { value: guard.value['writes'] };
127
161
  const git = { value: guard.value['git'] };
128
162
  const listed = isRecord(writes) ? writes.value['commands'] : undefined;
129
- const scripts = isRecord(writes) ? writes.value['readOnlyScripts'] : undefined;
130
163
  const targets = isRecord(git) ? git.value['askPush'] : undefined;
131
- const readOnlyScripts = (Array.isArray(scripts) ? scripts : []).flatMap((entry) => {
132
- const script = readOnlyScriptOf({ value: entry });
133
-
134
- return script === undefined ? [] : [script];
135
- });
164
+ const owned = guard.value['toolOwnedPaths'];
165
+ const runners = { value: guard.value['runners'] };
166
+ const words = (value: unknown): string[] =>
167
+ (Array.isArray(value) ? value : []).filter(
168
+ (item): item is string => typeof item === 'string' && item !== '',
169
+ );
136
170
 
137
171
  return {
138
172
  commands: (Array.isArray(listed) ? listed : []).flatMap((entry) => {
@@ -140,10 +174,13 @@ export class ProjectGuards {
140
174
 
141
175
  return check === undefined ? [] : [check];
142
176
  }),
143
- askPush: (Array.isArray(targets) ? targets : []).filter(
144
- (target): target is string => typeof target === 'string' && target !== '',
145
- ),
146
- ...(readOnlyScripts.length === 0 ? {} : { readOnlyScripts }),
177
+ askPush: words(targets),
178
+ outside:
179
+ guard.value['outside'] === GuardDecisions.DENY ? GuardDecisions.DENY : GuardDecisions.ASK,
180
+ asks: guard.value['asks'] === GuardDecisions.DENY ? GuardDecisions.DENY : GuardDecisions.ASK,
181
+ asksNote: guard.value['asks'] === GuardDecisions.DENY ? HookConstants.HELD_ASK : undefined,
182
+ toolOwnedPaths: words(owned),
183
+ runnersAllow: isRecord(runners) ? words(runners.value['allow']) : [],
147
184
  };
148
185
  }
149
186
 
@@ -1,14 +1,49 @@
1
- import { appendFileSync, mkdirSync } from 'node:fs';
1
+ import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
+ import { LayoutFolder } from '../common/layout-folder.ts';
4
+ import { RecordValue } from '../common/record.ts';
3
5
  import { HookConstants } from './common/index.ts';
6
+ import { ProjectGuards } from './project-guards.ts';
4
7
 
5
8
  /** A word for `sh`, whatever it holds: in single quotes, a quote itself closed, escaped and opened again. */
6
9
  const shellQuote = (opts: { text: string }): string => `'${opts.text.replaceAll("'", "'\\''")}'`;
7
10
 
8
11
  export class ProjectTmp {
9
- /** `<root>/.agents/local/tmp`: where a session's temporary files go, absolute. `vulcan clean` reads its age. */
10
- static projectOf(opts: { root: string }): string {
11
- return join(opts.root, HookConstants.PROJECT_TMP);
12
+ /**
13
+ * The folder the project names for its temporary files, relative to its root: `local.tmp` of the committed manifest
14
+ * (which `vulcan sync` renders from the config), read here so a hook needs no config loader. A missing manifest, a
15
+ * missing key or a value that is not a layout folder gives the default, `.agents/local/tmp`.
16
+ */
17
+ static relativeOf(opts: { root: string }): string {
18
+ try {
19
+ const manifest: unknown = JSON.parse(
20
+ readFileSync(join(opts.root, ProjectGuards.MANIFEST_FILE), 'utf8'),
21
+ );
22
+ const local = RecordValue.isRecord(manifest) ? manifest['local'] : undefined;
23
+ const tmp = RecordValue.isRecord(local) ? local['tmp'] : undefined;
24
+
25
+ return typeof tmp === 'string' &&
26
+ LayoutFolder.layoutFolderProblem({ folder: tmp }) === undefined
27
+ ? tmp
28
+ : HookConstants.PROJECT_TMP;
29
+ } catch {
30
+ return HookConstants.PROJECT_TMP;
31
+ }
32
+ }
33
+
34
+ /** What a caller that holds the config passes as `tmp`: the key, or the default when the project does not set it (never the manifest, which `sync` has not rewritten yet). */
35
+ static configuredOf(opts: { tmp: string | undefined }): string {
36
+ return opts.tmp ?? HookConstants.PROJECT_TMP;
37
+ }
38
+
39
+ /**
40
+ * Where a session's temporary files go, absolute: the guard, the session digest, the session-start export, the launch
41
+ * file, `vulcan clean` and the scratch of `add` all call this. `tmp` is the config's `local.tmp` for a caller that
42
+ * has just read the config (`sync`, which writes the manifest after it plans the launch file); the others leave it
43
+ * out and get the manifest's.
44
+ */
45
+ static projectOf(opts: { root: string; tmp?: string }): string {
46
+ return join(opts.root, opts.tmp ?? ProjectTmp.relativeOf({ root: opts.root }));
12
47
  }
13
48
 
14
49
  /**
@@ -0,0 +1,257 @@
1
+ import { PackageRunners } from './package-runners.ts';
2
+ import type { IRunnerCall } from './package-runners.ts';
3
+
4
+ /** One command that fetches a package and runs it: `bunx`, `bun x`, `npx`, `npm exec`, `pnpm dlx`, `yarn dlx`, `pnpx`. */
5
+ export interface IRunnerUse {
6
+ /** The runner as written (`bunx`, `bun x`, `npx`, ...). */
7
+ runner: string;
8
+ /** The first word after the flags: the package or bin the command runs, as written (a version included); empty when none is given (`xargs bunx`). */
9
+ name: string;
10
+ /** The package a `-p` or `--package` flag names, as written; the command runs a bin of that package. */
11
+ packageName?: string;
12
+ /** The exact flag `--no-install` stands before the name. */
13
+ hasNoInstall: boolean;
14
+ /** Every flag on the way to the name, and the flags before the runner's subcommand (`bun --cwd other x`). */
15
+ flags: string[];
16
+ /** The line the command starts on, from 1 (a continuation joins the lines that follow it). */
17
+ line: number;
18
+ /** The command runs a command string in a shell (`npx -c`), and no package is named: nothing is fetched by name. */
19
+ runsCommand: boolean;
20
+ /** The line is marked as an example (`<!-- runners: example -->`) in a Markdown file. */
21
+ isExample: boolean;
22
+ }
23
+
24
+ /** What may stand before a runner for the text to be a command and not a sentence about one. */
25
+ const COMMAND_START = /(?:^|[\s&|;(`"':>$=])$|(?:^|\s)[@+-]+$/;
26
+ const COMMAND_WORDS =
27
+ /(?:^|\s)(?:sudo|time|exec|env|command|nohup|then|do|else|RUN|CMD|ENTRYPOINT)$/;
28
+ const ENVIRONMENT = /(?:^|\s)[A-Za-z_][A-Za-z0-9_]*=\S*\s+$/;
29
+ /** Every program that may start a runner command; `PackageRunners.find` decides whether the words after it make one. */
30
+ const PROGRAM = /(?<![\w./-])(bunx|pnpx|npx|bun|npm|pnpm|yarn|corepack)(?![\w.-])/g;
31
+ /** An array of quoted words, the form a script or a test spells a command in. */
32
+ const ARRAY_FORM = /\[\s*(['"][^'"]*['"](?:\s*,\s*['"][^'"]*['"])*)/g;
33
+ const QUOTED = /['"]([^'"]*)['"]/g;
34
+ /** A comment that marks the line or the fenced block after it as an example of a command that is refused (Markdown only). */
35
+ const EXAMPLE_MARKER = /^\s*<!--\s*runners:\s*example\s*-->\s*$/;
36
+ const FENCE = /^\s*(`{3,}|~{3,})/;
37
+
38
+ /** A version, a tag or a range: no `:` (so no `npm:` or `github:` alias), no `/`. */
39
+ const VERSION = '[\\w.^~*<>=+-]+';
40
+ /** `@scope/name`, any scope, with a version, or a shell placeholder for one (the pinned form of a workflow). */
41
+ const SCOPED = new RegExp(`^@[a-z0-9][\\w.-]*/[\\w.-]+(?:@${VERSION})?$`, 'i');
42
+ /** The same, with the pinned form of a workflow: `$(...)` or `${...}` after the `@`. A file may carry it, a typed command may not (a variable could print `npm:<name>`). */
43
+ const SCOPED_PINNED = new RegExp(
44
+ `^@[a-z0-9][\\w.-]*/[\\w.-]+(?:@(?:${VERSION}|\\$\\(.*|\\$\\{.*))?$`,
45
+ 'i',
46
+ );
47
+ const SPEC_VERSION = new RegExp(`^${VERSION}$`);
48
+
49
+ /**
50
+ * Finds the commands of a text that run a package fetched by name. One scan serves the tracked-file check and the
51
+ * guard on an agent's command, so the cases of what counts as one are decided, and tested, once.
52
+ */
53
+ export class RunnerScan {
54
+ /** `text` with each `\` continuation joined to its line, and the line number each logical line starts on. */
55
+ private static logicalLines(opts: {
56
+ text: string;
57
+ }): { text: string; line: number; end: number }[] {
58
+ const lines = opts.text.split('\n');
59
+ const joined: { text: string; line: number; end: number }[] = [];
60
+
61
+ for (let index = 0; index < lines.length; index += 1) {
62
+ let text = lines[index];
63
+ const line = index + 1;
64
+
65
+ while (/\\\s*$/.test(text) && index + 1 < lines.length) {
66
+ index += 1;
67
+ text = `${text.replace(/\\\s*$/, ' ')}${lines[index]}`;
68
+ }
69
+
70
+ joined.push({ text, line, end: index + 1 });
71
+ }
72
+
73
+ return joined;
74
+ }
75
+
76
+ /** The lines, from 1, that a marker comment sets apart: the line after it, or the whole fenced block that opens there. */
77
+ private static exampleLines(opts: { text: string }): Set<number> {
78
+ const lines = opts.text.split('\n');
79
+ const marked = new Set<number>();
80
+
81
+ for (let index = 0; index < lines.length; index += 1) {
82
+ if (!EXAMPLE_MARKER.test(lines[index] ?? '')) {
83
+ continue;
84
+ }
85
+
86
+ const next = index + 1;
87
+ const fence = FENCE.exec(lines[next] ?? '')?.[1];
88
+
89
+ if (fence === undefined) {
90
+ marked.add(next + 1);
91
+ continue;
92
+ }
93
+
94
+ let end = next + 1;
95
+
96
+ while (end < lines.length) {
97
+ const closing = FENCE.exec(lines[end] ?? '')?.[1];
98
+
99
+ if (closing !== undefined && closing[0] === fence[0] && closing.length >= fence.length) {
100
+ break;
101
+ }
102
+
103
+ end += 1;
104
+ }
105
+
106
+ // a fence that never closes would cover the rest of the file: it counts as no marker
107
+ if (end >= lines.length) {
108
+ continue;
109
+ }
110
+
111
+ for (let at = next; at <= end; at += 1) {
112
+ marked.add(at + 1);
113
+ }
114
+ }
115
+
116
+ return marked;
117
+ }
118
+
119
+ /** Whether `before` ends where a command may begin: a line start, a separator, a prompt, a quote, a keyword. */
120
+ private static isCommandPosition(opts: { before: string }): boolean {
121
+ let before = opts.before;
122
+
123
+ while (ENVIRONMENT.test(before)) {
124
+ before = before.replace(ENVIRONMENT, ' ');
125
+ }
126
+
127
+ const trimmed = before.trimEnd();
128
+
129
+ // a comma right against the program is an argument separator of a make `$(foreach ...)`; a comma and a space is prose
130
+ return (
131
+ trimmed === '' ||
132
+ before.endsWith(',') ||
133
+ COMMAND_START.test(trimmed) ||
134
+ COMMAND_WORDS.test(trimmed)
135
+ );
136
+ }
137
+
138
+ /** The command a runner call makes: the package it runs and the flags on the way to it. */
139
+ static useOf(opts: { call: IRunnerCall; line: number; isExample: boolean }): IRunnerUse {
140
+ const target = PackageRunners.targetOf({ words: opts.call.words, runner: opts.call.runner });
141
+
142
+ return {
143
+ runner: opts.call.runner,
144
+ name: target.name,
145
+ ...(target.packageName === undefined ? {} : { packageName: target.packageName }),
146
+ hasNoInstall: target.hasNoInstall,
147
+ flags: [...opts.call.leading, ...target.flags],
148
+ runsCommand: target.isCommandString && PackageRunners.COMMAND_RUNNERS.has(opts.call.runner),
149
+ line: opts.line,
150
+ isExample: opts.isExample,
151
+ };
152
+ }
153
+
154
+ /** Every command of `text` that runs a package by name, in order. `isMarkdown` lets a marker comment set a line apart as an example. */
155
+ static find(opts: { text: string; isMarkdown?: boolean }): IRunnerUse[] {
156
+ const uses: IRunnerUse[] = [];
157
+ const examples =
158
+ opts.isMarkdown === true ? RunnerScan.exampleLines({ text: opts.text }) : undefined;
159
+ const lines = RunnerScan.logicalLines({ text: opts.text });
160
+
161
+ for (const [at, { text, line }] of lines.entries()) {
162
+ const isExample = examples?.has(line) ?? false;
163
+
164
+ for (const match of text.matchAll(PROGRAM)) {
165
+ const index = match.index ?? 0;
166
+
167
+ if (!RunnerScan.isCommandPosition({ before: text.slice(0, index) })) {
168
+ continue;
169
+ }
170
+
171
+ const rest = text.slice(index + match[0].length);
172
+
173
+ // `bunx` straight into a quote or a backtick is a word in a sentence, not the start of a command
174
+ if (!/^\s+\S/.test(rest)) {
175
+ continue;
176
+ }
177
+
178
+ const words = rest.trim().split(/\s+/);
179
+ let call = PackageRunners.find({ program: match[1], args: words });
180
+
181
+ if (call === undefined) {
182
+ continue;
183
+ }
184
+
185
+ let use = RunnerScan.useOf({ call, line, isExample });
186
+
187
+ // a Markdown wrap can leave the name on the next line, after the flags
188
+ if (use.name === '' && use.packageName === undefined && use.flags.length > 0) {
189
+ const following = lines[at + 1]?.text.trim().split(/\s+/) ?? [];
190
+
191
+ call = PackageRunners.find({ program: match[1], args: [...words, ...following] });
192
+ use = call === undefined ? use : RunnerScan.useOf({ call, line, isExample });
193
+ }
194
+
195
+ if (
196
+ (use.name !== '' || use.packageName !== undefined) &&
197
+ !RunnerScan.isCommandString({ use })
198
+ ) {
199
+ uses.push(use);
200
+ }
201
+ }
202
+
203
+ for (const array of text.matchAll(ARRAY_FORM)) {
204
+ const [program, ...args] = [...(array[1] ?? '').matchAll(QUOTED)].map(
205
+ (word) => word[1] ?? '',
206
+ );
207
+ const call = PackageRunners.find({ program: program ?? '', args });
208
+ const use = call === undefined ? undefined : RunnerScan.useOf({ call, line, isExample });
209
+
210
+ if (
211
+ use !== undefined &&
212
+ (use.name !== '' || use.packageName !== undefined) &&
213
+ !RunnerScan.isCommandString({ use })
214
+ ) {
215
+ uses.push(use);
216
+ }
217
+ }
218
+ }
219
+
220
+ return uses;
221
+ }
222
+
223
+ /** Whether the command runs a command string and names no package: `-c` takes that string, so the word after it is no name. */
224
+ static isCommandString(opts: { use: IRunnerUse }): boolean {
225
+ return opts.use.runsCommand && opts.use.packageName === undefined;
226
+ }
227
+
228
+ /** `shadcn@latest` is `shadcn`; a scoped name keeps its scope. */
229
+ static bareName(opts: { name: string }): string {
230
+ return opts.name.replace(/(?<=.)@[^@]*$/, '');
231
+ }
232
+
233
+ /**
234
+ * The name a command runs that a project may not accept, or `undefined`. A scoped package (`@scope/name`, any scope: an
235
+ * owner holds it and nobody can register it) passes, and so does a name on the allow-list, with a version or a tag after
236
+ * it and nothing else: `shadcn@npm:tool` and `shadcn@github:owner/repo` are other packages. A `-p` package decides when
237
+ * there is one: the command runs a bin of that package. A command with no name at all is refused (the empty name).
238
+ */
239
+ static refusedName(opts: {
240
+ use: IRunnerUse;
241
+ allow: string[];
242
+ /** True for a tracked file: it may pin a scoped package with `$(...)` or `${...}`. */
243
+ isFile?: boolean;
244
+ }): string | undefined {
245
+ const name = opts.use.packageName ?? opts.use.name;
246
+
247
+ if ((opts.isFile === true ? SCOPED_PINNED : SCOPED).test(name)) {
248
+ return undefined;
249
+ }
250
+
251
+ const bareName = RunnerScan.bareName({ name });
252
+ const spec = name.slice(bareName.length);
253
+ const isSpecKnown = spec === '' || SPEC_VERSION.test(spec.slice(1));
254
+
255
+ return opts.allow.includes(bareName) && isSpecKnown ? undefined : name;
256
+ }
257
+ }