@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,8 +1,8 @@
1
1
  import { HookConstants } from './common/index.ts';
2
2
  import type { IWriteHit } from './common/index.ts';
3
- import { isDataOnly } from './command-view.ts';
4
- import { forHost } from './decision.ts';
5
- import { optionTakesNextWord, programOf, splitHeredocs } from './shell.ts';
3
+ import { CommandView } from './command-view.ts';
4
+ import { HookDecision } from './decision.ts';
5
+ import { ShellParser, ShellPrograms } from './shell.ts';
6
6
 
7
7
  // -----------------------------------------------------------------------------
8
8
  // The remote-host guard: a Bash command that reaches a host the project has not listed asks first.
@@ -13,7 +13,7 @@ import { optionTakesNextWord, programOf, splitHeredocs } from './shell.ts';
13
13
  // cannot read (a substitution, a jump through a command, an unknown client) asks.
14
14
  // -----------------------------------------------------------------------------
15
15
 
16
- export interface IRemoteHostsPolicy {
16
+ interface IRemoteHostsPolicy {
17
17
  /** Hosts any command may reach. */
18
18
  trusted: string[];
19
19
  /** Hosts that only the strict read-only forms may reach. */
@@ -54,43 +54,8 @@ const PATTERN_CHARACTERS = /^[a-z0-9._*-]+$/;
54
54
  const normalizeVariable = (opts: { host: string }): string =>
55
55
  opts.host.replace(/^\$\{(\w+)\}$/, '$$$1');
56
56
 
57
- /** Whether `host` is one of `entries`: whole-name equal, or a `*` pattern. Case-insensitive. */
58
- export const matchesHost = (opts: { host: string; entries: string[] }): boolean => {
59
- const host = normalizeVariable({ host: opts.host.toLowerCase() });
60
-
61
- return opts.entries.some((entry) => {
62
- const wanted = normalizeVariable({ host: entry.toLowerCase() });
63
-
64
- if (!wanted.includes(WILDCARD)) {
65
- return host === wanted;
66
- }
67
-
68
- if (
69
- !PATTERN_CHARACTERS.test(wanted) ||
70
- wanted.replaceAll(WILDCARD, '').replaceAll('.', '') === ''
71
- ) {
72
- return false;
73
- }
74
-
75
- const pattern = wanted
76
- .split(WILDCARD)
77
- .map((part) => part.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&'))
78
- .join('[a-z0-9._-]*');
79
-
80
- return new RegExp(`^${pattern}$`).test(host);
81
- });
82
- };
83
-
84
- /** The personal trusted list: one host per line, `#` starts a comment. */
85
- export const parseTrustedList = (opts: { text: string }): string[] =>
86
- opts.text
87
- .split('\n')
88
- .map((line) => line.replace(/#.*$/, '').trim())
89
- .filter((line) => line !== '');
90
-
91
- // --- reading a command ---
92
-
93
57
  const SEPARATORS = new Set([';', '&', '|', '\n', '(', ')']);
58
+
94
59
  const REDIRECTS = new Set(['<', '>']);
95
60
 
96
61
  /** Shell words, split into the commands they form. Quotes are removed; a `#` word starts a comment. */
@@ -241,25 +206,10 @@ const SHELL_KEYWORDS = new Set([
241
206
 
242
207
  const HTTP_CLIENTS = new Set(['curl', 'wget', 'http', 'https', 'httpie', 'xh', 'xhs']);
243
208
 
244
- /** Programs that run the rest of their line; the options each takes a value for are in `hooks/shell.ts`. */
245
- const WRAPPERS = new Set([
246
- 'sudo',
247
- 'doas',
248
- 'env',
249
- 'time',
250
- 'nohup',
251
- 'nice',
252
- 'ionice',
253
- 'exec',
254
- 'stdbuf',
255
- 'timeout',
256
- 'setsid',
257
- 'xargs',
258
- 'watch',
259
- 'sshpass',
260
- ]);
209
+ /** Programs that run the rest of their line: the names and the options each takes a value for are in `hooks/shell.ts`; `command` is handled apart below. */
210
+ const WRAPPERS = new Set(ShellPrograms.WRAPPER_NAMES.filter((name) => name !== 'command'));
261
211
 
262
- const SHELLS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh', 'ash']);
212
+ const SHELLS = new Set([...ShellPrograms.SHELL_NAMES, 'ksh', 'ash']);
263
213
 
264
214
  /** Look a command up or describe it; running none of the words that follow. */
265
215
  const LOOKUPS = new Set(['man', 'which', 'type', 'whereis', 'apropos', 'whatis', 'echo', 'printf']);
@@ -274,8 +224,11 @@ const SSH_ARGUMENT_LETTERS: Record<string, string> = {
274
224
  };
275
225
 
276
226
  const NETWORK_CLIENTS = new Set(['nc', 'ncat', 'netcat', 'telnet']);
227
+
277
228
  const NETWORK_ARGUMENT_LETTERS = 'pswiIOTxXPZ';
229
+
278
230
  const KUBERNETES_CLIENTS = new Set(['kubectl', 'helm', 'k9s', 'oc']);
231
+
279
232
  const KUBERNETES_TARGET_OPTIONS = [
280
233
  '--context',
281
234
  '--kube-context',
@@ -291,16 +244,19 @@ const UNPARSED_CLIENTS =
291
244
 
292
245
  const SENSITIVE_ASSIGNMENT =
293
246
  /(?:^|[\s;&|(])(?:export\s+)?(?:git_ssh(?:_command)?|rsync_rsh|docker_host|docker_context|kubeconfig)=|core\.sshcommand/i;
247
+
294
248
  const URL_HOST = /(?:ssh|scp|sftp|rsync):\/\/(?:[^@\s/'"]*@)?(\[[^\]]+\]|[^\s/:'"]+)/gi;
249
+
295
250
  const DEVICE_HOST = /\/dev\/(?:tcp|udp)\/([^/\s'"]+)\//gi;
296
251
 
297
252
  const UNSAFE_OPTION_KEYS = new Set(['proxycommand', 'localcommand', 'knownhostscommand']);
298
253
 
299
- // --- the strict read-only forms ---
300
-
301
254
  const LABEL = '\\w[\\w-]*';
255
+
302
256
  const REMOTE_PATH = '/[\\w./-]*';
257
+
303
258
  const LOCAL_PATH = '(?:\\./)?\\w[\\w-]*(?:[./][\\w-]+)*/?';
259
+
304
260
  const UNIT = '[\\w@][\\w.@-]*';
305
261
 
306
262
  const READ_ONLY_REMOTE = new RegExp(
@@ -319,14 +275,18 @@ const READ_ONLY_REMOTE = new RegExp(
319
275
  `docker logs --tail \\d+ ${UNIT}`,
320
276
  ].join('|')})$`,
321
277
  );
278
+
322
279
  const COPY_SOURCE = new RegExp(`^(?:${LABEL}(?:\\.${LABEL})*@)?[^@\\s/:]+:${REMOTE_PATH}$`);
280
+
323
281
  const COPY_TARGET = new RegExp(`^${LOCAL_PATH}$`);
282
+
324
283
  const SCP_SAFE_FLAGS = /^-[rpqC]+$/;
284
+
325
285
  const RSYNC_SAFE_FLAGS = /^-[avzrhPt]+$/;
286
+
326
287
  const KUBECTL_READ_VERBS = new Set(['get', 'describe', 'logs', 'top']);
327
- const KUBECTL_SAFE_WORD = /^[\w./=:,@-]+$/;
328
288
 
329
- // --- per-client analysis ---
289
+ const KUBECTL_SAFE_WORD = /^[\w./=:,@-]+$/;
330
290
 
331
291
  const unreadable = (opts: { why: string }): IFinding => ({
332
292
  hosts: [],
@@ -335,11 +295,6 @@ const unreadable = (opts: { why: string }): IFinding => ({
335
295
  redirect: false,
336
296
  });
337
297
 
338
- interface IOptionEffect {
339
- hosts: string[];
340
- unreadable?: string;
341
- }
342
-
343
298
  /** What one ssh-family option means for where the connection goes. */
344
299
  const optionEffect = (opts: { letter: string; value: string }): IOptionEffect => {
345
300
  const { letter, value } = opts;
@@ -722,7 +677,7 @@ const unwrap = (opts: { program: string; words: string[] }): string[] => {
722
677
  const word = opts.words[index] ?? '';
723
678
 
724
679
  if (word.startsWith('-') && word.length > 1) {
725
- index += optionTakesNextWord({ wrapper: opts.program, word }) ? 2 : 1;
680
+ index += ShellParser.optionTakesNextWord({ wrapper: opts.program, word }) ? 2 : 1;
726
681
  } else if (
727
682
  ENVIRONMENT_ASSIGNMENT.test(word) ||
728
683
  (/^\d[\w.]*$/.test(word) && opts.program !== 'sshpass')
@@ -755,7 +710,12 @@ const analyzeWords = (opts: {
755
710
  const program = basenameOf({ word: words[0] ?? '' });
756
711
 
757
712
  // `rg -n "ssh|scp" docs/`: the arguments of a search or a print are data.
758
- if (isDataOnly({ command: { words, redirects: [], assignments: [] }, withMessages: false })) {
713
+ if (
714
+ CommandView.isDataOnly({
715
+ command: { words, redirects: [], assignments: [] },
716
+ withMessages: false,
717
+ })
718
+ ) {
759
719
  return [];
760
720
  }
761
721
 
@@ -769,7 +729,7 @@ const analyzeWords = (opts: {
769
729
 
770
730
  if (program === 'env') {
771
731
  // `env -S "ssh host"` carries a whole command line in one word: the command it makes is read as one.
772
- const splits = programOf({
732
+ const splits = ShellParser.programOf({
773
733
  command: { words, redirects: [], assignments: [] },
774
734
  }).splitCommands;
775
735
 
@@ -866,25 +826,25 @@ const analyzeWords = (opts: {
866
826
 
867
827
  const analyzeCommand = (opts: { command: string; depth: number }): IFinding[] =>
868
828
  // A heredoc body that is data (`cat > f <<EOF`) is not a command; one a shell reads stays in the text.
869
- tokenize({ command: splitHeredocs({ command: opts.command }).text }).flatMap((segment) => {
870
- const findings = analyzeWords({
871
- words: segment.words,
872
- depth: opts.depth,
873
- recurse: analyzeCommand,
874
- });
875
-
876
- return findings.map((finding): IFinding =>
877
- segment.substitution && (finding.hosts.length > 0 || finding.unreadable !== undefined)
878
- ? {
879
- ...finding,
880
- unreadable: finding.unreadable ?? 'a substitution runs inside it',
881
- redirect: finding.redirect || segment.redirect,
882
- }
883
- : { ...finding, redirect: finding.redirect || segment.redirect },
884
- );
885
- });
829
+ tokenize({ command: ShellParser.splitHeredocs({ command: opts.command }).text }).flatMap(
830
+ (segment) => {
831
+ const findings = analyzeWords({
832
+ words: segment.words,
833
+ depth: opts.depth,
834
+ recurse: analyzeCommand,
835
+ });
886
836
 
887
- // --- the decision ---
837
+ return findings.map((finding): IFinding =>
838
+ segment.substitution && (finding.hosts.length > 0 || finding.unreadable !== undefined)
839
+ ? {
840
+ ...finding,
841
+ unreadable: finding.unreadable ?? 'a substitution runs inside it',
842
+ redirect: finding.redirect || segment.redirect,
843
+ }
844
+ : { ...finding, redirect: finding.redirect || segment.redirect },
845
+ );
846
+ },
847
+ );
888
848
 
889
849
  const trustedMessage = (opts: { host: string; policy: IRemoteHostsPolicy }): string =>
890
850
  `reaching '${opts.host}', which is not in remoteHosts.trusted (list it there${opts.policy.localFile === undefined ? '' : `, or in ${opts.policy.localFile} for yourself`}); a remoteHosts.readOnly host passes only the strict read-only forms`;
@@ -892,82 +852,130 @@ const trustedMessage = (opts: { host: string; policy: IRemoteHostsPolicy }): str
892
852
  const readOnlyMessage = (opts: { host: string }): string =>
893
853
  `'${opts.host}' is a remoteHosts.readOnly host: only a strict read-only form passes (uptime, df -h, cat <path>, scp/rsync from it, kubectl get|describe|logs|top), and this command is not one`;
894
854
 
895
- /** Why each host this command reaches may not be reached without asking; empty means nothing to ask. */
896
- export const inspectRemoteCommand = (opts: {
897
- command: string;
898
- policy: IRemoteHostsPolicy;
899
- }): IWriteHit[] => {
900
- const { command, policy } = opts;
901
- const findings = analyzeCommand({ command, depth: 0 });
902
- const hits: IWriteHit[] = [];
903
- const asked = new Set<string>();
904
-
905
- const ask = (message: string): void => {
906
- if (!asked.has(message)) {
907
- asked.add(message);
908
- hits.push({ rule: 'remote-hosts', message });
909
- }
910
- };
855
+ export class RemoteHosts {
856
+ /** Whether `host` is one of `entries`: whole-name equal, or a `*` pattern. Case-insensitive. */
857
+ static matches(opts: { host: string; entries: string[] }): boolean {
858
+ const host = normalizeVariable({ host: opts.host.toLowerCase() });
911
859
 
912
- for (const finding of findings) {
913
- if (finding.unreadable !== undefined) {
914
- ask(
915
- `the target of this command cannot be read (${finding.unreadable}), so any host could be reached`,
916
- );
917
- continue;
918
- }
860
+ return opts.entries.some((entry) => {
861
+ const wanted = normalizeVariable({ host: entry.toLowerCase() });
862
+
863
+ if (!wanted.includes(WILDCARD)) {
864
+ return host === wanted;
865
+ }
866
+
867
+ if (
868
+ !PATTERN_CHARACTERS.test(wanted) ||
869
+ wanted.replaceAll(WILDCARD, '').replaceAll('.', '') === ''
870
+ ) {
871
+ return false;
872
+ }
873
+
874
+ const pattern = wanted
875
+ .split(WILDCARD)
876
+ .map((part) => part.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&'))
877
+ .join('[a-z0-9._-]*');
878
+
879
+ return new RegExp(`^${pattern}$`).test(host);
880
+ });
881
+ }
882
+
883
+ /** The personal trusted list: one host per line, `#` starts a comment. */
884
+ static parseTrustedList(opts: { text: string }): string[] {
885
+ return opts.text
886
+ .split('\n')
887
+ .map((line) => line.replace(/#.*$/, '').trim())
888
+ .filter((line) => line !== '');
889
+ }
919
890
 
920
- for (const host of finding.hosts) {
921
- if (matchesHost({ host, entries: policy.trusted })) {
891
+ /** Why each host this command reaches may not be reached without asking; empty means nothing to ask. */
892
+ static inspectCommand(opts: { command: string; policy: IRemoteHostsPolicy }): IWriteHit[] {
893
+ const { command, policy } = opts;
894
+ const findings = analyzeCommand({ command, depth: 0 });
895
+ const hits: IWriteHit[] = [];
896
+ const asked = new Set<string>();
897
+
898
+ const ask = (message: string): void => {
899
+ if (!asked.has(message)) {
900
+ asked.add(message);
901
+ hits.push({ rule: 'remote-hosts', message });
902
+ }
903
+ };
904
+
905
+ for (const finding of findings) {
906
+ if (finding.unreadable !== undefined) {
907
+ ask(
908
+ `the target of this command cannot be read (${finding.unreadable}), so any host could be reached`,
909
+ );
922
910
  continue;
923
911
  }
924
912
 
925
- if (matchesHost({ host, entries: policy.readOnly })) {
926
- if (!finding.strict || finding.redirect) {
927
- ask(readOnlyMessage({ host }));
913
+ for (const host of finding.hosts) {
914
+ if (RemoteHosts.matches({ host, entries: policy.trusted })) {
915
+ continue;
928
916
  }
929
917
 
930
- continue;
918
+ if (RemoteHosts.matches({ host, entries: policy.readOnly })) {
919
+ if (!finding.strict || finding.redirect) {
920
+ ask(readOnlyMessage({ host }));
921
+ }
922
+
923
+ continue;
924
+ }
925
+
926
+ if (finding.listedOnly !== true) {
927
+ ask(trustedMessage({ host, policy }));
928
+ }
931
929
  }
930
+ }
932
931
 
933
- if (finding.listedOnly !== true) {
932
+ const devices = [...command.matchAll(DEVICE_HOST)].map((match) =>
933
+ hostOf({ value: match[1] ?? '' }),
934
+ );
935
+ const urls = [...command.matchAll(URL_HOST)].map((match) => hostOf({ value: match[1] ?? '' }));
936
+
937
+ for (const host of [...devices, ...urls]) {
938
+ if (!RemoteHosts.matches({ host, entries: policy.trusted })) {
934
939
  ask(trustedMessage({ host, policy }));
935
940
  }
936
941
  }
937
- }
938
942
 
939
- const devices = [...command.matchAll(DEVICE_HOST)].map((match) =>
940
- hostOf({ value: match[1] ?? '' }),
941
- );
942
- const urls = [...command.matchAll(URL_HOST)].map((match) => hostOf({ value: match[1] ?? '' }));
943
-
944
- for (const host of [...devices, ...urls]) {
945
- if (!matchesHost({ host, entries: policy.trusted })) {
946
- ask(trustedMessage({ host, policy }));
943
+ if (SENSITIVE_ASSIGNMENT.test(command)) {
944
+ ask(
945
+ 'the target of this command cannot be read (an environment variable or git option redirects ssh, rsync, docker or kubectl)',
946
+ );
947
947
  }
948
- }
949
948
 
950
- if (SENSITIVE_ASSIGNMENT.test(command)) {
951
- ask(
952
- 'the target of this command cannot be read (an environment variable or git option redirects ssh, rsync, docker or kubectl)',
953
- );
949
+ return hits;
950
+ }
951
+
952
+ static buildDecision(opts: { hits: IWriteHit[] }) {
953
+ return HookDecision.forHost({
954
+ output: {
955
+ hookSpecificOutput: {
956
+ hookEventName: HookConstants.PRE_TOOL_USE,
957
+ permissionDecision: HookConstants.GUARD_DECISION,
958
+ permissionDecisionReason: [
959
+ 'This command may reach a remote host the project has not listed:',
960
+ ...opts.hits.map((hit) => ` - ${hit.message}`),
961
+ '',
962
+ 'Read on the host, never edit, restart or copy onto it. Produce the command and hand it over.',
963
+ ].join('\n'),
964
+ },
965
+ },
966
+ });
954
967
  }
968
+ }
955
969
 
956
- return hits;
957
- };
970
+ // --- reading a command ---
958
971
 
959
- export const buildRemoteDecision = (opts: { hits: IWriteHit[] }) =>
960
- forHost({
961
- output: {
962
- hookSpecificOutput: {
963
- hookEventName: HookConstants.PRE_TOOL_USE,
964
- permissionDecision: HookConstants.GUARD_DECISION,
965
- permissionDecisionReason: [
966
- 'This command may reach a remote host the project has not listed:',
967
- ...opts.hits.map((hit) => ` - ${hit.message}`),
968
- '',
969
- 'Read on the host, never edit, restart or copy onto it. Produce the command and hand it over.',
970
- ].join('\n'),
971
- },
972
- },
973
- });
972
+ // --- the strict read-only forms ---
973
+
974
+ // --- per-client analysis ---
975
+
976
+ interface IOptionEffect {
977
+ hosts: string[];
978
+ unreadable?: string;
979
+ }
980
+
981
+ // --- the decision ---
@@ -1,17 +1,11 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { basename, join } from 'node:path';
3
3
  import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
4
- import { ConfigConstants, loadConfig } from '../config/index.ts';
5
- import {
6
- isOwnerReplyOff,
7
- OWNER_SCHEMA,
8
- readProfile,
9
- renderOwnerShapeCard,
10
- renderProfileCard,
11
- resolveOwnerView,
12
- } from '../owner/index.ts';
13
- import { extractRuleRows, parseRuleIds, readSlots, RuleConstants } from '../rules/index.ts';
14
- import { projectTmpOf } from './project-tmp.ts';
4
+ import { ConfigConstants, ConfigLoader } from '../config/index.ts';
5
+ import { OWNER_SCHEMA, OwnerCard, OwnerProfile, OwnerView, ReplySwitch } from '../owner/index.ts';
6
+ import { RuleConstants, RuleParser, RuleSlots } from '../rules/index.ts';
7
+ import { ClaudeLaunch } from '../sync/claude-launch.ts';
8
+ import { ProjectTmp } from './project-tmp.ts';
15
9
 
16
10
  /** A project row whose first cell lists IDs - `| V-W-02, V-W-03 |` - elaborates those base rules. */
17
11
  const ID_LIST_ROW =
@@ -25,7 +19,7 @@ const TABLE_HEADER = ['| ID | Rule | Enforced by |', '|----|------|-------------
25
19
  /** Each listed ID's row, plain or bold (`| **W-00** |`), quoted from its rule file so it cannot drift. */
26
20
  const selectRows = (opts: { rows: string[]; ids: string[] }): string[] =>
27
21
  opts.ids
28
- .map((id) => opts.rows.find((row) => parseRuleIds({ markdown: row })[0] === id))
22
+ .map((id) => opts.rows.find((row) => RuleParser.parseIds({ markdown: row })[0] === id))
29
23
  .filter((row): row is string => row !== undefined);
30
24
 
31
25
  const readText = (opts: { file: string }): string =>
@@ -50,93 +44,103 @@ const buildAtlasBlock = (opts: {
50
44
  ];
51
45
  };
52
46
 
53
- /** The SessionStart context: base write boundaries, this project's slot choices and own rules, the often-dropped rules. */
54
- export const buildSessionDigest = async (opts: {
55
- projectRoot: string;
56
- /** The environment of the session; `VULCAN_OWNER_REPLY=off` leaves out the owner's shape and profile cards. */
57
- env?: Record<string, string | undefined>;
58
- }): Promise<string> => {
59
- const baseRows = extractRuleRows({
60
- markdown: readText({ file: join(BASE_DIRECTORY, 'rules.md') }),
61
- });
62
- const projectText = readText({ file: join(opts.projectRoot, '.agents', 'rules.md') });
63
- const projectRows = projectText
64
- .split('\n')
65
- .filter((line) => extractRuleRows({ markdown: line }).length > 0 || ID_LIST_ROW.test(line));
66
- const minimap = MINIMAP.exec(projectText)?.[1].trim();
67
- const loaded = await loadConfig({ root: opts.projectRoot });
68
- const choices = loaded.ok ? loaded.config.rules : {};
69
- const oftenDropped = loaded.ok
70
- ? loaded.config.digest.oftenDropped
71
- : ConfigConstants.DEFAULT_OFTEN_DROPPED;
72
-
73
- const slotRows = Object.entries(readSlots()).map(([id, slot]) => {
74
- const choice = choices[id];
75
-
76
- if (choice === undefined) {
77
- return `| ${id} | this project: **not chosen** - run \`${ProjectLayout.VULCAN_COMMAND} doctor\` |`;
47
+ export class SessionDigest {
48
+ /** The SessionStart context: base write boundaries, this project's slot choices and own rules, the often-dropped rules. */
49
+ static async build(opts: {
50
+ projectRoot: string;
51
+ /** The environment of the session; `VULCAN_OWNER_REPLY=off` leaves out the owner's shape and profile cards. */
52
+ env?: Record<string, string | undefined>;
53
+ }): Promise<string> {
54
+ const baseRows = RuleParser.extractRows({
55
+ markdown: readText({ file: join(BASE_DIRECTORY, 'rules.md') }),
56
+ });
57
+ const projectText = readText({ file: join(opts.projectRoot, '.agents', 'rules.md') });
58
+ const projectRows = projectText
59
+ .split('\n')
60
+ .filter(
61
+ (line) => RuleParser.extractRows({ markdown: line }).length > 0 || ID_LIST_ROW.test(line),
62
+ );
63
+ const minimap = MINIMAP.exec(projectText)?.[1].trim();
64
+ const loaded = await ConfigLoader.load({ root: opts.projectRoot });
65
+ const choices = loaded.ok ? loaded.config.rules : {};
66
+ const oftenDropped = loaded.ok
67
+ ? loaded.config.digest.oftenDropped
68
+ : ConfigConstants.DEFAULT_OFTEN_DROPPED;
69
+
70
+ const slotRows = Object.entries(RuleSlots.read()).map(([id, slot]) => {
71
+ const choice = choices[id];
72
+
73
+ if (choice === undefined) {
74
+ return `| ${id} | this project: **not chosen** - run \`${ProjectLayout.VULCAN_COMMAND} doctor\` |`;
75
+ }
76
+
77
+ return `| ${id} | this project: \`${choice}\` - ${slot.options[choice]?.text ?? `unknown option - run \`${ProjectLayout.VULCAN_COMMAND} doctor\``} |`;
78
+ });
79
+
80
+ const launchWarning = ClaudeLaunch.missWarning({
81
+ root: opts.projectRoot,
82
+ env: opts.env ?? process.env,
83
+ });
84
+
85
+ const lines = [
86
+ '# VULCAN rules - read this before acting',
87
+ '',
88
+ ...(launchWarning === undefined ? [] : ['## Launch warning', '', launchWarning, '']),
89
+ 'Base rules: `node_modules/@venizia/vulcan/base/rules.md`. This project: `.agents/rules.md`.',
90
+ '',
91
+ ...buildAtlasBlock({
92
+ projectRoot: opts.projectRoot,
93
+ project: loaded.ok
94
+ ? (loaded.config.name ?? basename(opts.projectRoot))
95
+ : basename(opts.projectRoot),
96
+ sources: loaded.ok ? loaded.config.atlas.sources.map((source) => source.name) : [],
97
+ }),
98
+ '## Write boundaries',
99
+ '',
100
+ ...TABLE_HEADER,
101
+ ...baseRows.filter((row) => row.startsWith(`| ${RuleConstants.BASE_NAMESPACE}W-`)),
102
+ '',
103
+ '## Temporary files',
104
+ '',
105
+ `Scratch and temporary files go in \`${ProjectTmp.projectOf({ root: opts.projectRoot })}\`, never /tmp (V-B-08). The scratchpad folder your tool offers is under /tmp too: do not use it, this rule wins over the tool's line. In Claude Code every Bash command already runs with \`TMPDIR\` set to it; in any other agent run \`export TMPDIR=${ProjectTmp.projectOf({ root: opts.projectRoot })}\` first. Remove what you made when the task ends.`,
106
+ '',
107
+ "## This project's slot choices",
108
+ '',
109
+ ...slotRows,
110
+ ];
111
+
112
+ const profile = OwnerProfile.read({ root: opts.projectRoot });
113
+ const view = OwnerView.resolve({
114
+ owner: loaded.ok ? loaded.config.owner : OWNER_SCHEMA.parse(undefined),
115
+ profile: profile.ok ? profile.profile : undefined,
116
+ });
117
+ const profileCard = OwnerCard.renderProfile({ view });
118
+
119
+ // A session whose reader is an agent: the owner's shape and the person's profile are not its business.
120
+ if (!ReplySwitch.isOwnerOff({ env: opts.env ?? process.env })) {
121
+ lines.push('', ...OwnerCard.renderShape({ view }));
122
+
123
+ if (profileCard.length > 0) {
124
+ lines.push('', ...profileCard);
125
+ }
78
126
  }
79
127
 
80
- return `| ${id} | this project: \`${choice}\` - ${slot.options[choice]?.text ?? `unknown option - run \`${ProjectLayout.VULCAN_COMMAND} doctor\``} |`;
81
- });
82
-
83
- const lines = [
84
- '# VULCAN rules - read this before acting',
85
- '',
86
- 'Base rules: `node_modules/@venizia/vulcan/base/rules.md`. This project: `.agents/rules.md`.',
87
- '',
88
- ...buildAtlasBlock({
89
- projectRoot: opts.projectRoot,
90
- project: loaded.ok
91
- ? (loaded.config.name ?? basename(opts.projectRoot))
92
- : basename(opts.projectRoot),
93
- sources: loaded.ok ? loaded.config.atlas.sources.map((source) => source.name) : [],
94
- }),
95
- '## Write boundaries',
96
- '',
97
- ...TABLE_HEADER,
98
- ...baseRows.filter((row) => row.startsWith(`| ${RuleConstants.BASE_NAMESPACE}W-`)),
99
- '',
100
- '## Temporary files',
101
- '',
102
- `Scratch and temporary files go in \`${projectTmpOf({ root: opts.projectRoot })}\`, never /tmp (V-B-08). The scratchpad folder your tool offers is under /tmp too: do not use it, this rule wins over the tool's line. In Claude Code every Bash command already runs with \`TMPDIR\` set to it; in any other agent run \`export TMPDIR=${projectTmpOf({ root: opts.projectRoot })}\` first. Remove what you made when the task ends.`,
103
- '',
104
- "## This project's slot choices",
105
- '',
106
- ...slotRows,
107
- ];
108
-
109
- const profile = readProfile({ root: opts.projectRoot });
110
- const view = resolveOwnerView({
111
- owner: loaded.ok ? loaded.config.owner : OWNER_SCHEMA.parse(undefined),
112
- profile: profile.ok ? profile.profile : undefined,
113
- });
114
- const profileCard = renderProfileCard({ view });
115
-
116
- // A session whose reader is an agent: the owner's shape and the person's profile are not its business.
117
- if (!isOwnerReplyOff({ env: opts.env ?? process.env })) {
118
- lines.push('', ...renderOwnerShapeCard({ view }));
128
+ if (projectRows.length > 0) {
129
+ lines.push('', "## This project's own rules", '', ...TABLE_HEADER, ...projectRows);
130
+ }
119
131
 
120
- if (profileCard.length > 0) {
121
- lines.push('', ...profileCard);
132
+ if (minimap !== undefined && minimap.length > 0) {
133
+ lines.push('', "## This project's minimap", '', minimap);
122
134
  }
123
- }
124
135
 
125
- if (projectRows.length > 0) {
126
- lines.push('', "## This project's own rules", '', ...TABLE_HEADER, ...projectRows);
127
- }
136
+ lines.push(
137
+ '',
138
+ '## The rules sessions drop most',
139
+ '',
140
+ ...TABLE_HEADER,
141
+ ...selectRows({ rows: [...baseRows, ...projectRows], ids: oftenDropped }),
142
+ );
128
143
 
129
- if (minimap !== undefined && minimap.length > 0) {
130
- lines.push('', "## This project's minimap", '', minimap);
144
+ return `${lines.join('\n')}\n`;
131
145
  }
132
-
133
- lines.push(
134
- '',
135
- '## The rules sessions drop most',
136
- '',
137
- ...TABLE_HEADER,
138
- ...selectRows({ rows: [...baseRows, ...projectRows], ids: oftenDropped }),
139
- );
140
-
141
- return `${lines.join('\n')}\n`;
142
- };
146
+ }