@venizia/vulcan 0.4.9-0 → 0.4.9-2

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 (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -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, ShellPrograms, 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.
@@ -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. */
@@ -259,8 +224,11 @@ const SSH_ARGUMENT_LETTERS: Record<string, string> = {
259
224
  };
260
225
 
261
226
  const NETWORK_CLIENTS = new Set(['nc', 'ncat', 'netcat', 'telnet']);
227
+
262
228
  const NETWORK_ARGUMENT_LETTERS = 'pswiIOTxXPZ';
229
+
263
230
  const KUBERNETES_CLIENTS = new Set(['kubectl', 'helm', 'k9s', 'oc']);
231
+
264
232
  const KUBERNETES_TARGET_OPTIONS = [
265
233
  '--context',
266
234
  '--kube-context',
@@ -276,16 +244,19 @@ const UNPARSED_CLIENTS =
276
244
 
277
245
  const SENSITIVE_ASSIGNMENT =
278
246
  /(?:^|[\s;&|(])(?:export\s+)?(?:git_ssh(?:_command)?|rsync_rsh|docker_host|docker_context|kubeconfig)=|core\.sshcommand/i;
247
+
279
248
  const URL_HOST = /(?:ssh|scp|sftp|rsync):\/\/(?:[^@\s/'"]*@)?(\[[^\]]+\]|[^\s/:'"]+)/gi;
249
+
280
250
  const DEVICE_HOST = /\/dev\/(?:tcp|udp)\/([^/\s'"]+)\//gi;
281
251
 
282
252
  const UNSAFE_OPTION_KEYS = new Set(['proxycommand', 'localcommand', 'knownhostscommand']);
283
253
 
284
- // --- the strict read-only forms ---
285
-
286
254
  const LABEL = '\\w[\\w-]*';
255
+
287
256
  const REMOTE_PATH = '/[\\w./-]*';
257
+
288
258
  const LOCAL_PATH = '(?:\\./)?\\w[\\w-]*(?:[./][\\w-]+)*/?';
259
+
289
260
  const UNIT = '[\\w@][\\w.@-]*';
290
261
 
291
262
  const READ_ONLY_REMOTE = new RegExp(
@@ -304,14 +275,18 @@ const READ_ONLY_REMOTE = new RegExp(
304
275
  `docker logs --tail \\d+ ${UNIT}`,
305
276
  ].join('|')})$`,
306
277
  );
278
+
307
279
  const COPY_SOURCE = new RegExp(`^(?:${LABEL}(?:\\.${LABEL})*@)?[^@\\s/:]+:${REMOTE_PATH}$`);
280
+
308
281
  const COPY_TARGET = new RegExp(`^${LOCAL_PATH}$`);
282
+
309
283
  const SCP_SAFE_FLAGS = /^-[rpqC]+$/;
284
+
310
285
  const RSYNC_SAFE_FLAGS = /^-[avzrhPt]+$/;
286
+
311
287
  const KUBECTL_READ_VERBS = new Set(['get', 'describe', 'logs', 'top']);
312
- const KUBECTL_SAFE_WORD = /^[\w./=:,@-]+$/;
313
288
 
314
- // --- per-client analysis ---
289
+ const KUBECTL_SAFE_WORD = /^[\w./=:,@-]+$/;
315
290
 
316
291
  const unreadable = (opts: { why: string }): IFinding => ({
317
292
  hosts: [],
@@ -320,11 +295,6 @@ const unreadable = (opts: { why: string }): IFinding => ({
320
295
  redirect: false,
321
296
  });
322
297
 
323
- interface IOptionEffect {
324
- hosts: string[];
325
- unreadable?: string;
326
- }
327
-
328
298
  /** What one ssh-family option means for where the connection goes. */
329
299
  const optionEffect = (opts: { letter: string; value: string }): IOptionEffect => {
330
300
  const { letter, value } = opts;
@@ -707,7 +677,7 @@ const unwrap = (opts: { program: string; words: string[] }): string[] => {
707
677
  const word = opts.words[index] ?? '';
708
678
 
709
679
  if (word.startsWith('-') && word.length > 1) {
710
- index += optionTakesNextWord({ wrapper: opts.program, word }) ? 2 : 1;
680
+ index += ShellParser.optionTakesNextWord({ wrapper: opts.program, word }) ? 2 : 1;
711
681
  } else if (
712
682
  ENVIRONMENT_ASSIGNMENT.test(word) ||
713
683
  (/^\d[\w.]*$/.test(word) && opts.program !== 'sshpass')
@@ -740,7 +710,12 @@ const analyzeWords = (opts: {
740
710
  const program = basenameOf({ word: words[0] ?? '' });
741
711
 
742
712
  // `rg -n "ssh|scp" docs/`: the arguments of a search or a print are data.
743
- if (isDataOnly({ command: { words, redirects: [], assignments: [] }, withMessages: false })) {
713
+ if (
714
+ CommandView.isDataOnly({
715
+ command: { words, redirects: [], assignments: [] },
716
+ withMessages: false,
717
+ })
718
+ ) {
744
719
  return [];
745
720
  }
746
721
 
@@ -754,7 +729,7 @@ const analyzeWords = (opts: {
754
729
 
755
730
  if (program === 'env') {
756
731
  // `env -S "ssh host"` carries a whole command line in one word: the command it makes is read as one.
757
- const splits = programOf({
732
+ const splits = ShellParser.programOf({
758
733
  command: { words, redirects: [], assignments: [] },
759
734
  }).splitCommands;
760
735
 
@@ -851,25 +826,25 @@ const analyzeWords = (opts: {
851
826
 
852
827
  const analyzeCommand = (opts: { command: string; depth: number }): IFinding[] =>
853
828
  // A heredoc body that is data (`cat > f <<EOF`) is not a command; one a shell reads stays in the text.
854
- tokenize({ command: splitHeredocs({ command: opts.command }).text }).flatMap((segment) => {
855
- const findings = analyzeWords({
856
- words: segment.words,
857
- depth: opts.depth,
858
- recurse: analyzeCommand,
859
- });
860
-
861
- return findings.map((finding): IFinding =>
862
- segment.substitution && (finding.hosts.length > 0 || finding.unreadable !== undefined)
863
- ? {
864
- ...finding,
865
- unreadable: finding.unreadable ?? 'a substitution runs inside it',
866
- redirect: finding.redirect || segment.redirect,
867
- }
868
- : { ...finding, redirect: finding.redirect || segment.redirect },
869
- );
870
- });
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
+ });
871
836
 
872
- // --- 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
+ );
873
848
 
874
849
  const trustedMessage = (opts: { host: string; policy: IRemoteHostsPolicy }): string =>
875
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`;
@@ -877,82 +852,130 @@ const trustedMessage = (opts: { host: string; policy: IRemoteHostsPolicy }): str
877
852
  const readOnlyMessage = (opts: { host: string }): string =>
878
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`;
879
854
 
880
- /** Why each host this command reaches may not be reached without asking; empty means nothing to ask. */
881
- export const inspectRemoteCommand = (opts: {
882
- command: string;
883
- policy: IRemoteHostsPolicy;
884
- }): IWriteHit[] => {
885
- const { command, policy } = opts;
886
- const findings = analyzeCommand({ command, depth: 0 });
887
- const hits: IWriteHit[] = [];
888
- const asked = new Set<string>();
889
-
890
- const ask = (message: string): void => {
891
- if (!asked.has(message)) {
892
- asked.add(message);
893
- hits.push({ rule: 'remote-hosts', message });
894
- }
895
- };
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() });
896
859
 
897
- for (const finding of findings) {
898
- if (finding.unreadable !== undefined) {
899
- ask(
900
- `the target of this command cannot be read (${finding.unreadable}), so any host could be reached`,
901
- );
902
- continue;
903
- }
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
+ }
890
+
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>();
904
897
 
905
- for (const host of finding.hosts) {
906
- if (matchesHost({ host, entries: policy.trusted })) {
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
+ );
907
910
  continue;
908
911
  }
909
912
 
910
- if (matchesHost({ host, entries: policy.readOnly })) {
911
- if (!finding.strict || finding.redirect) {
912
- ask(readOnlyMessage({ host }));
913
+ for (const host of finding.hosts) {
914
+ if (RemoteHosts.matches({ host, entries: policy.trusted })) {
915
+ continue;
913
916
  }
914
917
 
915
- 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
+ }
916
929
  }
930
+ }
917
931
 
918
- 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 })) {
919
939
  ask(trustedMessage({ host, policy }));
920
940
  }
921
941
  }
922
- }
923
-
924
- const devices = [...command.matchAll(DEVICE_HOST)].map((match) =>
925
- hostOf({ value: match[1] ?? '' }),
926
- );
927
- const urls = [...command.matchAll(URL_HOST)].map((match) => hostOf({ value: match[1] ?? '' }));
928
942
 
929
- for (const host of [...devices, ...urls]) {
930
- if (!matchesHost({ host, entries: policy.trusted })) {
931
- 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
+ );
932
947
  }
933
- }
934
948
 
935
- if (SENSITIVE_ASSIGNMENT.test(command)) {
936
- ask(
937
- 'the target of this command cannot be read (an environment variable or git option redirects ssh, rsync, docker or kubectl)',
938
- );
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
+ });
939
967
  }
968
+ }
940
969
 
941
- return hits;
942
- };
970
+ // --- reading a command ---
943
971
 
944
- export const buildRemoteDecision = (opts: { hits: IWriteHit[] }) =>
945
- forHost({
946
- output: {
947
- hookSpecificOutput: {
948
- hookEventName: HookConstants.PRE_TOOL_USE,
949
- permissionDecision: HookConstants.GUARD_DECISION,
950
- permissionDecisionReason: [
951
- 'This command may reach a remote host the project has not listed:',
952
- ...opts.hits.map((hit) => ` - ${hit.message}`),
953
- '',
954
- 'Read on the host, never edit, restart or copy onto it. Produce the command and hand it over.',
955
- ].join('\n'),
956
- },
957
- },
958
- });
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,18 +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';
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';
14
7
  import { ClaudeLaunch } from '../sync/claude-launch.ts';
15
- import { projectTmpOf } from './project-tmp.ts';
8
+ import { ProjectTmp } from './project-tmp.ts';
16
9
 
17
10
  /** A project row whose first cell lists IDs - `| V-W-02, V-W-03 |` - elaborates those base rules. */
18
11
  const ID_LIST_ROW =
@@ -26,7 +19,7 @@ const TABLE_HEADER = ['| ID | Rule | Enforced by |', '|----|------|-------------
26
19
  /** Each listed ID's row, plain or bold (`| **W-00** |`), quoted from its rule file so it cannot drift. */
27
20
  const selectRows = (opts: { rows: string[]; ids: string[] }): string[] =>
28
21
  opts.ids
29
- .map((id) => opts.rows.find((row) => parseRuleIds({ markdown: row })[0] === id))
22
+ .map((id) => opts.rows.find((row) => RuleParser.parseIds({ markdown: row })[0] === id))
30
23
  .filter((row): row is string => row !== undefined);
31
24
 
32
25
  const readText = (opts: { file: string }): string =>
@@ -51,99 +44,103 @@ const buildAtlasBlock = (opts: {
51
44
  ];
52
45
  };
53
46
 
54
- /** The SessionStart context: base write boundaries, this project's slot choices and own rules, the often-dropped rules. */
55
- export const buildSessionDigest = async (opts: {
56
- projectRoot: string;
57
- /** The environment of the session; `VULCAN_OWNER_REPLY=off` leaves out the owner's shape and profile cards. */
58
- env?: Record<string, string | undefined>;
59
- }): Promise<string> => {
60
- const baseRows = extractRuleRows({
61
- markdown: readText({ file: join(BASE_DIRECTORY, 'rules.md') }),
62
- });
63
- const projectText = readText({ file: join(opts.projectRoot, '.agents', 'rules.md') });
64
- const projectRows = projectText
65
- .split('\n')
66
- .filter((line) => extractRuleRows({ markdown: line }).length > 0 || ID_LIST_ROW.test(line));
67
- const minimap = MINIMAP.exec(projectText)?.[1].trim();
68
- const loaded = await loadConfig({ root: opts.projectRoot });
69
- const choices = loaded.ok ? loaded.config.rules : {};
70
- const oftenDropped = loaded.ok
71
- ? loaded.config.digest.oftenDropped
72
- : ConfigConstants.DEFAULT_OFTEN_DROPPED;
73
-
74
- const slotRows = Object.entries(readSlots()).map(([id, slot]) => {
75
- const choice = choices[id];
76
-
77
- if (choice === undefined) {
78
- 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
+ }
79
126
  }
80
127
 
81
- return `| ${id} | this project: \`${choice}\` - ${slot.options[choice]?.text ?? `unknown option - run \`${ProjectLayout.VULCAN_COMMAND} doctor\``} |`;
82
- });
83
-
84
- const launchWarning = ClaudeLaunch.missWarning({
85
- root: opts.projectRoot,
86
- env: opts.env ?? process.env,
87
- });
88
-
89
- const lines = [
90
- '# VULCAN rules - read this before acting',
91
- '',
92
- ...(launchWarning === undefined ? [] : ['## Launch warning', '', launchWarning, '']),
93
- 'Base rules: `node_modules/@venizia/vulcan/base/rules.md`. This project: `.agents/rules.md`.',
94
- '',
95
- ...buildAtlasBlock({
96
- projectRoot: opts.projectRoot,
97
- project: loaded.ok
98
- ? (loaded.config.name ?? basename(opts.projectRoot))
99
- : basename(opts.projectRoot),
100
- sources: loaded.ok ? loaded.config.atlas.sources.map((source) => source.name) : [],
101
- }),
102
- '## Write boundaries',
103
- '',
104
- ...TABLE_HEADER,
105
- ...baseRows.filter((row) => row.startsWith(`| ${RuleConstants.BASE_NAMESPACE}W-`)),
106
- '',
107
- '## Temporary files',
108
- '',
109
- `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.`,
110
- '',
111
- "## This project's slot choices",
112
- '',
113
- ...slotRows,
114
- ];
115
-
116
- const profile = readProfile({ root: opts.projectRoot });
117
- const view = resolveOwnerView({
118
- owner: loaded.ok ? loaded.config.owner : OWNER_SCHEMA.parse(undefined),
119
- profile: profile.ok ? profile.profile : undefined,
120
- });
121
- const profileCard = renderProfileCard({ view });
122
-
123
- // A session whose reader is an agent: the owner's shape and the person's profile are not its business.
124
- if (!isOwnerReplyOff({ env: opts.env ?? process.env })) {
125
- lines.push('', ...renderOwnerShapeCard({ view }));
128
+ if (projectRows.length > 0) {
129
+ lines.push('', "## This project's own rules", '', ...TABLE_HEADER, ...projectRows);
130
+ }
126
131
 
127
- if (profileCard.length > 0) {
128
- lines.push('', ...profileCard);
132
+ if (minimap !== undefined && minimap.length > 0) {
133
+ lines.push('', "## This project's minimap", '', minimap);
129
134
  }
130
- }
131
135
 
132
- if (projectRows.length > 0) {
133
- lines.push('', "## This project's own rules", '', ...TABLE_HEADER, ...projectRows);
134
- }
136
+ lines.push(
137
+ '',
138
+ '## The rules sessions drop most',
139
+ '',
140
+ ...TABLE_HEADER,
141
+ ...selectRows({ rows: [...baseRows, ...projectRows], ids: oftenDropped }),
142
+ );
135
143
 
136
- if (minimap !== undefined && minimap.length > 0) {
137
- lines.push('', "## This project's minimap", '', minimap);
144
+ return `${lines.join('\n')}\n`;
138
145
  }
139
-
140
- lines.push(
141
- '',
142
- '## The rules sessions drop most',
143
- '',
144
- ...TABLE_HEADER,
145
- ...selectRows({ rows: [...baseRows, ...projectRows], ids: oftenDropped }),
146
- );
147
-
148
- return `${lines.join('\n')}\n`;
149
- };
146
+ }