@venizia/vulcan 0.4.8 → 0.4.9-1

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 (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -1,21 +1,25 @@
1
1
  import { lstatSync, readlinkSync, realpathSync } from 'node:fs';
2
2
  import { tmpdir } from 'node:os';
3
3
  import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
4
- import { basenameOf, parseShellChecked, programOf } from './shell.ts';
4
+ import { ShellParser } from './shell.ts';
5
5
  import type { ISimpleCommand } from './shell.ts';
6
6
  import { HookConstants } from './common/index.ts';
7
- import { projectTmpOf } from './project-tmp.ts';
7
+ import { ProjectTmp } from './project-tmp.ts';
8
8
  import type { IManifestHookInput, IOutsideHit } from './common/index.ts';
9
9
 
10
10
  const FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
11
11
 
12
12
  type TEnvironment = Record<string, string | undefined>;
13
13
 
14
- /** `~` and `$NAME` / `${NAME}` expanded; `undefined` when a variable is unset or the word is not a plain path. */
14
+ /**
15
+ * `~` and `$NAME` / `${NAME}` expanded; `undefined` when a variable is unset or the word is not a plain path.
16
+ * `$PWD` is the folder the command runs in (`cwd`), not the `PWD` of this hook's own process.
17
+ */
15
18
  const expandPath = (opts: {
16
19
  word: string;
17
20
  home: string;
18
21
  env: TEnvironment;
22
+ cwd?: string;
19
23
  }): string | undefined => {
20
24
  if (opts.word === '' || /[`*?[]/.test(opts.word) || opts.word.includes('$(')) {
21
25
  return undefined;
@@ -25,7 +29,7 @@ const expandPath = (opts: {
25
29
  const home = opts.word === '~' || opts.word.startsWith('~/') ? opts.home : undefined;
26
30
  const withHome = home === undefined ? opts.word : `${home}${opts.word.slice(1)}`;
27
31
  const expanded = withHome.replace(/\$\{?(\w+)\}?/g, (_, name: string) => {
28
- const value = opts.env[name];
32
+ const value = name === 'PWD' && opts.cwd !== undefined ? opts.cwd : opts.env[name];
29
33
 
30
34
  if (value === undefined || value === '') {
31
35
  unresolved = true;
@@ -61,10 +65,15 @@ const realOf = (opts: { path: string; depth?: number }): string => {
61
65
  try {
62
66
  base = realpathSync(existing);
63
67
  } catch {
64
- // A dangling link: its target is where a write through it lands.
65
- const target = depth < 8 ? readlinkSync(existing) : existing;
68
+ // A dangling link: its target is where a write through it lands; a chain this long is a loop.
69
+ if (depth >= 8) {
70
+ return join(existing, ...rest);
71
+ }
66
72
 
67
- base = realOf({ path: resolve(dirname(existing), target), depth: depth + 1 });
73
+ base = realOf({
74
+ path: resolve(dirname(existing), readlinkSync(existing)),
75
+ depth: depth + 1,
76
+ });
68
77
  }
69
78
 
70
79
  return join(base, ...rest);
@@ -111,6 +120,8 @@ interface ITarget {
111
120
  message: string;
112
121
  /** The directory a relative `word` is taken from: the hook's, moved by `cd` and `git -C`. */
113
122
  base: string;
123
+ /** What `$PWD` is in `word`: the shell's folder, moved by `cd` but not by `git -C`; undefined when it is not known. */
124
+ pwd?: string;
114
125
  }
115
126
 
116
127
  const positional = (opts: { args: string[] }): string[] =>
@@ -240,8 +251,8 @@ const gitTargets = (opts: { rest: string[]; base: string; dir: string | undefine
240
251
 
241
252
  /** The words a simple command would create or write, with a name for what writes them. */
242
253
  const targetsOf = (opts: { command: ISimpleCommand; base: string; tmp: string }): ITarget[] => {
243
- const program = programOf({ command: opts.command });
244
- const name = basenameOf({ word: program.name });
254
+ const program = ShellParser.programOf({ command: opts.command });
255
+ const name = ShellParser.basenameOf({ word: program.name });
245
256
  const { args } = program;
246
257
  const { base } = opts;
247
258
  const targets: ITarget[] = opts.command.redirects.map((word) => ({
@@ -340,100 +351,110 @@ const commandTmpdirOf = (opts: { env: TEnvironment; projectRoot: string }): stri
340
351
 
341
352
  return opts.env.CLAUDE_PROJECT_DIR === undefined
342
353
  ? tmpdir()
343
- : projectTmpOf({ root: opts.projectRoot });
354
+ : ProjectTmp.projectOf({ root: opts.projectRoot });
344
355
  };
345
356
 
346
- /**
347
- * Every file, worktree, clone or temp file `input` would create outside the project. Files a package
348
- * manager, a runtime or the agent tool manage themselves are allowed (`toolOwnedPaths`, extending the
349
- * defaults); pointing `TMPDIR` or `mktemp` at the system temp directory is not. It reads common
350
- * forms - redirects, mkdir, cp, mv, tee, curl -o, git clone, git worktree add, mktemp, `cd` - and is a
351
- * guard against drift, not a sandbox: a path it cannot work out (an unset variable, a glob) passes.
352
- */
353
- export const inspectOutside = (opts: {
354
- input: IManifestHookInput;
355
- projectRoot: string;
356
- toolOwnedPaths?: string[];
357
- home?: string;
358
- env?: TEnvironment;
359
- }): IOutsideHit[] => {
360
- const env = opts.env ?? process.env;
361
- const home = opts.home ?? env.HOME ?? '';
362
- const root = realOf({ path: resolve(opts.projectRoot) });
363
- const patterns = allowPatterns({
364
- patterns: [...HookConstants.TOOL_OWNED_PATHS, ...(opts.toolOwnedPaths ?? [])],
365
- home,
366
- env,
367
- });
368
- const start = opts.input.cwd ?? opts.projectRoot;
369
- const tmp = commandTmpdirOf({ env, projectRoot: opts.projectRoot });
370
- const targets: ITarget[] = [];
371
-
372
- if (FILE_TOOLS.has(opts.input.tool) && opts.input.filePath !== undefined) {
373
- targets.push({
374
- word: opts.input.filePath,
375
- base: start,
376
- message: `${opts.input.tool} writes ${opts.input.filePath}`,
357
+ export class OutsideGuard {
358
+ /**
359
+ * Every file, worktree, clone or temp file `input` would create outside the project. Files a package
360
+ * manager, a runtime or the agent tool manage themselves are allowed (`toolOwnedPaths`, extending the
361
+ * defaults); pointing `TMPDIR` or `mktemp` at the system temp directory is not. It reads common
362
+ * forms - redirects, mkdir, cp, mv, tee, curl -o, git clone, git worktree add, mktemp, `cd` - and is a
363
+ * guard against drift, not a sandbox: a path it cannot work out (an unset variable, a glob) passes.
364
+ */
365
+ static inspect(opts: {
366
+ input: IManifestHookInput;
367
+ projectRoot: string;
368
+ toolOwnedPaths?: string[];
369
+ home?: string;
370
+ env?: TEnvironment;
371
+ }): IOutsideHit[] {
372
+ const env = opts.env ?? process.env;
373
+ const home = opts.home ?? env.HOME ?? '';
374
+ const root = realOf({ path: resolve(opts.projectRoot) });
375
+ const patterns = allowPatterns({
376
+ patterns: [...HookConstants.TOOL_OWNED_PATHS, ...(opts.toolOwnedPaths ?? [])],
377
+ home,
378
+ env,
377
379
  });
378
- }
380
+ const start = resolve(opts.input.cwd ?? opts.projectRoot);
381
+ // `$PWD` is the call's folder only when the host said which one it is; otherwise the hook's own `PWD` stays the fallback.
382
+ const startPwd = opts.input.cwd === undefined ? undefined : start;
383
+ const tmp = commandTmpdirOf({ env, projectRoot: opts.projectRoot });
384
+ const targets: ITarget[] = [];
385
+
386
+ if (FILE_TOOLS.has(opts.input.tool) && opts.input.filePath !== undefined) {
387
+ targets.push({
388
+ word: opts.input.filePath,
389
+ base: start,
390
+ pwd: startPwd,
391
+ message: `${opts.input.tool} writes ${opts.input.filePath}`,
392
+ });
393
+ }
379
394
 
380
- let isUnread = false;
395
+ let isUnread = false;
381
396
 
382
- if (opts.input.command !== undefined) {
383
- let base = start;
397
+ if (opts.input.command !== undefined) {
398
+ let base = start;
399
+ let pwd = startPwd;
384
400
 
385
- const parsed = parseShellChecked({ command: opts.input.command });
401
+ const parsed = ShellParser.parseChecked({ command: opts.input.command });
386
402
 
387
- isUnread = parsed.isOverBudget;
403
+ isUnread = parsed.isOverBudget;
388
404
 
389
- for (const command of parsed.commands) {
390
- const program = programOf({ command });
405
+ for (const command of parsed.commands) {
406
+ const program = ShellParser.programOf({ command });
391
407
 
392
- if (basenameOf({ word: program.name }) === 'cd') {
393
- const [destination] = positional({ args: program.args });
394
- const expanded =
395
- destination === undefined ? undefined : expandPath({ word: destination, home, env });
408
+ if (ShellParser.basenameOf({ word: program.name }) === 'cd') {
409
+ const [destination] = positional({ args: program.args });
410
+ const expanded =
411
+ destination === undefined
412
+ ? undefined
413
+ : expandPath({ word: destination, home, env, cwd: pwd });
396
414
 
397
- base = expanded === undefined ? base : resolve(base, expanded);
398
- continue;
399
- }
415
+ base = expanded === undefined ? base : resolve(base, expanded);
416
+ // A `cd` the guard cannot work out leaves the shell's folder unknown.
417
+ pwd = expanded === undefined ? undefined : base;
418
+ continue;
419
+ }
400
420
 
401
- targets.push(...targetsOf({ command, base, tmp }));
421
+ targets.push(...targetsOf({ command, base, tmp }).map((target) => ({ ...target, pwd })));
422
+ }
402
423
  }
403
- }
404
424
 
405
- // Part of the line was not read: never an allow.
406
- const hits: IOutsideHit[] = isUnread
407
- ? [
408
- {
409
- path: '(the command line)',
410
- message:
411
- 'this command line is larger, or nests deeper, than the guard reads, so it could not be checked',
412
- isAgentToolScratchpad: false,
413
- },
414
- ]
415
- : [];
416
-
417
- for (const target of targets) {
418
- const expanded = expandPath({ word: target.word, home, env });
419
-
420
- if (expanded === undefined) {
421
- continue;
422
- }
425
+ // Part of the line was not read: never an allow.
426
+ const hits: IOutsideHit[] = isUnread
427
+ ? [
428
+ {
429
+ path: '(the command line)',
430
+ message:
431
+ 'this command line is larger, or nests deeper, than the guard reads, so it could not be checked',
432
+ isAgentToolScratchpad: false,
433
+ },
434
+ ]
435
+ : [];
436
+
437
+ for (const target of targets) {
438
+ const expanded = expandPath({ word: target.word, home, env, cwd: target.pwd });
423
439
 
424
- const path = realOf({ path: resolve(target.base, expanded) });
440
+ if (expanded === undefined) {
441
+ continue;
442
+ }
425
443
 
426
- if (!isInside({ path, root }) && !matchesAny({ path, patterns })) {
427
- hits.push({
428
- path,
429
- message: target.message,
430
- isAgentToolScratchpad: matchesAny({
444
+ const path = realOf({ path: resolve(target.base, expanded) });
445
+
446
+ if (!isInside({ path, root }) && !matchesAny({ path, patterns })) {
447
+ hits.push({
431
448
  path,
432
- patterns: HookConstants.AGENT_TOOL_SCRATCHPAD_PATTERNS,
433
- }),
434
- });
449
+ message: target.message,
450
+ isAgentToolScratchpad: matchesAny({
451
+ path,
452
+ patterns: HookConstants.AGENT_TOOL_SCRATCHPAD_PATTERNS,
453
+ }),
454
+ });
455
+ }
435
456
  }
436
- }
437
457
 
438
- return hits;
439
- };
458
+ return hits;
459
+ }
460
+ }
@@ -2,8 +2,8 @@ import { existsSync, readFileSync } from 'node:fs';
2
2
  import { basename, dirname, isAbsolute, join, normalize, relative, sep } from 'node:path';
3
3
  import { GuardDecisions, HookConstants, PackageVerdictKinds } from './common/index.ts';
4
4
  import type { IManifestHookInput, TPackageVerdictKind } from './common/index.ts';
5
- import { forHost } from './decision.ts';
6
- import { LayoutKeys, validLayoutFolders } from '../common/layout-folder.ts';
5
+ import { HookDecision } from './decision.ts';
6
+ import { LayoutFolder, LayoutKeys } from '../common/layout-folder.ts';
7
7
 
8
8
  const MANIFEST_FILE = '.agents/vulcan.manifest.json';
9
9
  const PACKAGE_FILE = 'package.json';
@@ -11,7 +11,7 @@ const NODE_MODULES = 'node_modules';
11
11
  const ADD = 'bun x --no-install vulcan add';
12
12
  const NO_HAND_WRITING = 'do not hand-write package.json, tsconfig or scripts';
13
13
 
14
- export interface IPackageVerdict {
14
+ interface IPackageVerdict {
15
15
  /** `deny` only when a real `vulcan add` command exists for the folder; otherwise `warn`. */
16
16
  kind: TPackageVerdictKind;
17
17
  message: string;
@@ -21,6 +21,7 @@ interface IRecordedPreset {
21
21
  spec: string;
22
22
  side: string;
23
23
  lib: boolean;
24
+ shared: boolean;
24
25
  }
25
26
 
26
27
  interface IProjectView {
@@ -84,7 +85,7 @@ const readProject = (opts: { start: string }): IProjectView | undefined => {
84
85
  // The manifest is read through the same validator as the config: a folder that is not one is dropped.
85
86
  if (isRecord(layoutHolder)) {
86
87
  for (const key of LayoutKeys.MANAGED) {
87
- const folders = validLayoutFolders({ value: layoutHolder.value[key] });
88
+ const folders = LayoutFolder.valid({ value: layoutHolder.value[key] });
88
89
 
89
90
  if (folders.length > 0) {
90
91
  layout[key] = folders;
@@ -100,10 +101,10 @@ const readProject = (opts: { start: string }): IProjectView | undefined => {
100
101
  return [];
101
102
  }
102
103
 
103
- const { spec, side, lib } = entry.value;
104
+ const { spec, side, lib, shared } = entry.value;
104
105
 
105
106
  return typeof spec === 'string' && typeof side === 'string'
106
- ? [{ spec, side, lib: typeof lib === 'string' }]
107
+ ? [{ spec, side, lib: typeof lib === 'string', shared: typeof shared === 'string' }]
107
108
  : [];
108
109
  });
109
110
 
@@ -130,88 +131,96 @@ const newPackageOf = (opts: {
130
131
  const appCommand = (opts: { preset: IRecordedPreset; name: string; folderFlag: string }): string =>
131
132
  `${ADD} --preset ${opts.preset.spec} --app ${opts.name}${opts.folderFlag}${opts.preset.side === 'frontend' ? ' --api <backend app> | --no-api' : ''}`;
132
133
 
133
- /**
134
- * Whether this tool call creates the `package.json` of a new app or shared package in one of the
135
- * project's layout folders. A real `vulcan add` command for that folder makes it a `deny`; with no
136
- * preset behind the folder it is only a `warn`: the guard never blocks without a command to offer.
137
- */
138
- export const inspectPackageWrite = (opts: {
139
- input: IManifestHookInput;
140
- }): IPackageVerdict | undefined => {
141
- const { tool, filePath, cwd } = opts.input;
142
-
143
- if (tool !== 'Write' || filePath === undefined || basename(filePath) !== PACKAGE_FILE) {
144
- return undefined;
145
- }
134
+ export class PackageGuard {
135
+ /**
136
+ * Whether this tool call creates the `package.json` of a new app or shared package in one of the
137
+ * project's layout folders. A real `vulcan add` command for that folder makes it a `deny`; with no
138
+ * preset behind the folder it is only a `warn`: the guard never blocks without a command to offer.
139
+ */
140
+ static inspectWrite(opts: { input: IManifestHookInput }): IPackageVerdict | undefined {
141
+ const { tool, filePath, cwd } = opts.input;
146
142
 
147
- const absolute = normalize(
148
- isAbsolute(filePath) ? filePath : join(cwd ?? process.cwd(), filePath),
149
- );
143
+ if (tool !== 'Write' || filePath === undefined || basename(filePath) !== PACKAGE_FILE) {
144
+ return undefined;
145
+ }
150
146
 
151
- if (absolute.split(sep).includes(NODE_MODULES) || existsSync(absolute)) {
152
- return undefined;
153
- }
147
+ const absolute = normalize(
148
+ isAbsolute(filePath) ? filePath : join(cwd ?? process.cwd(), filePath),
149
+ );
154
150
 
155
- const project = readProject({ start: dirname(absolute) });
156
- const created =
157
- project === undefined ? undefined : newPackageOf({ root: project.root, path: absolute });
151
+ if (absolute.split(sep).includes(NODE_MODULES) || existsSync(absolute)) {
152
+ return undefined;
153
+ }
158
154
 
159
- if (project === undefined || created === undefined) {
160
- return undefined;
161
- }
155
+ const project = readProject({ start: dirname(absolute) });
156
+ const created =
157
+ project === undefined ? undefined : newPackageOf({ root: project.root, path: absolute });
162
158
 
163
- const entry = Object.entries(project.layout).find(([, folders]) =>
164
- folders.includes(created.folder),
165
- );
159
+ if (project === undefined || created === undefined) {
160
+ return undefined;
161
+ }
166
162
 
167
- if (entry === undefined) {
168
- return undefined;
169
- }
163
+ const entry = Object.entries(project.layout).find(([, folders]) =>
164
+ folders.includes(created.folder),
165
+ );
166
+
167
+ if (entry === undefined) {
168
+ return undefined;
169
+ }
170
+
171
+ const [key, folders] = entry;
172
+ const isLib = key === 'shared';
173
+ const what = isLib ? 'lib' : `${key} app`;
174
+ // A side with several folders needs the one it is written in named, so the command is exact.
175
+ const folderFlag =
176
+ folders.length > 1 ? ` ${isLib ? '--dir' : `--${key}-dir`} ${created.folder}` : '';
177
+ const commands = isLib
178
+ ? [
179
+ ...project.presets
180
+ .filter((preset) => preset.lib)
181
+ .map((preset) => `${ADD} --preset ${preset.spec} --lib ${created.name}${folderFlag}`),
182
+ ...project.presets
183
+ .filter((preset) => preset.shared)
184
+ .map(
185
+ (preset) => `${ADD} --preset ${preset.spec} --shared ${created.name}${folderFlag}`,
186
+ ),
187
+ ]
188
+ : project.presets
189
+ .filter((preset) => preset.side === key)
190
+ .map((preset) => appCommand({ preset, name: created.name, folderFlag }));
191
+
192
+ if (commands.length > 0) {
193
+ return {
194
+ kind: PackageVerdictKinds.DENY,
195
+ message: `${created.folder}/${created.name} is a new ${what}: create it with a preset, not by hand - run ${commands.join(' or ')} (ask atlas \`presets\` for the choice); ${NO_HAND_WRITING}`,
196
+ };
197
+ }
170
198
 
171
- const [key, folders] = entry;
172
- const isLib = key === 'shared';
173
- const what = isLib ? 'lib' : `${key} app`;
174
- // A side with several folders needs the one it is written in named, so the command is exact.
175
- const folderFlag =
176
- folders.length > 1 ? ` ${isLib ? '--dir' : `--${key}-dir`} ${created.folder}` : '';
177
- const commands = isLib
178
- ? project.presets
179
- .filter((preset) => preset.lib)
180
- .map((preset) => `${ADD} --preset ${preset.spec} --lib ${created.name}${folderFlag}`)
181
- : project.presets
182
- .filter((preset) => preset.side === key)
183
- .map((preset) => appCommand({ preset, name: created.name, folderFlag }));
184
-
185
- if (commands.length > 0) {
186
199
  return {
187
- kind: PackageVerdictKinds.DENY,
188
- message: `${created.folder}/${created.name} is a new ${what}: create it with a preset, not by hand - run ${commands.join(' or ')} (ask atlas \`presets\` for the choice); ${NO_HAND_WRITING}`,
200
+ kind: PackageVerdictKinds.WARN,
201
+ message:
202
+ project.presets.length === 0
203
+ ? `${created.folder}/${created.name} looks like a new ${what} and this project recorded no preset: ask the user which preset to use (\`vulcan add --preset <name|file:path> --app <name>\`, --lib <name> for a library other apps import, --shared <name> for a side-neutral package); ${NO_HAND_WRITING}`
204
+ : `${created.folder}/${created.name} looks like a new ${what} but no recorded preset makes a ${what}: ask the user how it should be made; ${NO_HAND_WRITING}`,
189
205
  };
190
206
  }
191
207
 
192
- return {
193
- kind: PackageVerdictKinds.WARN,
194
- message:
195
- project.presets.length === 0
196
- ? `${created.folder}/${created.name} looks like a new ${what} and this project recorded no preset: ask the user which preset to use (\`vulcan add --preset <name|file:path> --app <name>\`, --lib <name> for a shared package); ${NO_HAND_WRITING}`
197
- : `${created.folder}/${created.name} looks like a new ${what} but no recorded preset makes a ${what}: ask the user how it should be made; ${NO_HAND_WRITING}`,
198
- };
199
- };
200
-
201
- export const buildPackageDecision = (opts: { verdict: IPackageVerdict }) =>
202
- opts.verdict.kind === PackageVerdictKinds.DENY
203
- ? forHost({
204
- output: {
208
+ static buildDecision(opts: { verdict: IPackageVerdict }) {
209
+ return opts.verdict.kind === PackageVerdictKinds.DENY
210
+ ? HookDecision.forHost({
211
+ output: {
212
+ hookSpecificOutput: {
213
+ hookEventName: HookConstants.PRE_TOOL_USE,
214
+ permissionDecision: GuardDecisions.DENY,
215
+ permissionDecisionReason: opts.verdict.message,
216
+ },
217
+ },
218
+ })
219
+ : {
205
220
  hookSpecificOutput: {
206
221
  hookEventName: HookConstants.PRE_TOOL_USE,
207
- permissionDecision: GuardDecisions.DENY,
208
- permissionDecisionReason: opts.verdict.message,
222
+ additionalContext: opts.verdict.message,
209
223
  },
210
- },
211
- })
212
- : {
213
- hookSpecificOutput: {
214
- hookEventName: HookConstants.PRE_TOOL_USE,
215
- additionalContext: opts.verdict.message,
216
- },
217
- };
224
+ };
225
+ }
226
+ }
@@ -1,11 +1,11 @@
1
1
  import { HookConstants } from './common/index.ts';
2
- import { basenameOf, parseShell, programOf } from './shell.ts';
2
+ import { ShellParser } from './shell.ts';
3
3
 
4
4
  /** `python`, `python3`, `python3.12`, `pip`, `pip3`: the program a command runs, not a word it mentions. */
5
5
  const SCRIPTING_PROGRAM = /^(?:python\d*(?:\.\d+)?|pip\d*(?:\.\d+)?)$/;
6
6
 
7
7
  /** One line, worded like the rule: a preference, never a ban. */
8
- export const SCRIPTING_ADVICE =
8
+ const SCRIPTING_ADVICE =
9
9
  'V-B-09: agent scripting uses bun by default (bun -e, bun file.ts, Bun.file()). Python or another language is fine when the task needs it (an existing project script, a tool only that language has); say so in one line when you use it.';
10
10
 
11
11
  /** `command -v python3` asks whether a program exists; it does not run it. */
@@ -15,17 +15,22 @@ const isExistenceProbe = (opts: { words: string[] }): boolean => {
15
15
  return at !== -1 && ['-v', '-V'].includes(opts.words[at + 1] ?? '');
16
16
  };
17
17
 
18
- /** The scripting programs a command runs, in order: a mention in an argument, a message, a heredoc or an existence probe is not one. */
19
- export const inspectScripting = (opts: { command: string }): string[] =>
20
- parseShell({ command: opts.command })
21
- .filter((command) => !isExistenceProbe({ words: command.words }))
22
- .map((command) => basenameOf({ word: programOf({ command }).name }))
23
- .filter((name) => SCRIPTING_PROGRAM.test(name));
18
+ export class ScriptingGuard {
19
+ /** The scripting programs a command runs, in order: a mention in an argument, a message, a heredoc or an existence probe is not one. */
20
+ static inspect(opts: { command: string }): string[] {
21
+ return ShellParser.parse({ command: opts.command })
22
+ .filter((command) => !isExistenceProbe({ words: command.words }))
23
+ .map((command) => ShellParser.basenameOf({ word: ShellParser.programOf({ command }).name }))
24
+ .filter((name) => SCRIPTING_PROGRAM.test(name));
25
+ }
24
26
 
25
- /** The PreToolUse answer that adds the advice to the model's context and lets the call through. */
26
- export const buildScriptingAdvice = () => ({
27
- hookSpecificOutput: {
28
- hookEventName: HookConstants.PRE_TOOL_USE,
29
- additionalContext: SCRIPTING_ADVICE,
30
- },
31
- });
27
+ /** The PreToolUse answer that adds the advice to the model's context and lets the call through. */
28
+ static buildAdvice() {
29
+ return {
30
+ hookSpecificOutput: {
31
+ hookEventName: HookConstants.PRE_TOOL_USE,
32
+ additionalContext: SCRIPTING_ADVICE,
33
+ },
34
+ };
35
+ }
36
+ }