@venizia/vulcan 0.4.8 → 0.4.9-0

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 (126) hide show
  1. package/base/hooks/antigravity-guards.ts +2 -1
  2. package/base/hooks/codex-guards.ts +2 -1
  3. package/base/hooks/guard-manifest.ts +2 -1
  4. package/base/hooks/guard-package.ts +2 -1
  5. package/base/hooks/guard-remote-hosts.ts +9 -3
  6. package/base/hooks/guard-scripting.ts +2 -1
  7. package/base/hooks/guard-writes.ts +14 -4
  8. package/base/hooks/post-tool.ts +2 -1
  9. package/base/hooks/prompt-submit.ts +2 -1
  10. package/base/hooks/session-start.ts +3 -1
  11. package/base/hooks/stop.ts +2 -1
  12. package/base/make/vulcan.mk +1 -4
  13. package/base/skills/build-a-feature/SKILL.md +1 -1
  14. package/base/skills/docs-update/SKILL.md +11 -5
  15. package/base/skills/docs-update/evals/evals.json +1 -1
  16. package/base/skills/docs-writing/SKILL.md +1 -1
  17. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  18. package/base/skills/ship/SKILL.md +1 -1
  19. package/base/skills/visualize-work/SKILL.md +20 -6
  20. package/base/skills/visualize-work/references/spec.md +16 -5
  21. package/package.json +5 -6
  22. package/src/agents/codex-hooks.ts +11 -10
  23. package/src/agents/common/types.ts +1 -1
  24. package/src/agents/exclude.ts +1 -1
  25. package/src/agents/hooks-json.ts +4 -8
  26. package/src/agents/prompt.ts +2 -2
  27. package/src/agents/render.ts +8 -12
  28. package/src/cli.ts +3 -1
  29. package/src/commands/doctor.command.ts +3 -1
  30. package/src/commands/help.command.ts +11 -9
  31. package/src/commands/init.command.ts +3 -1
  32. package/src/commands/profile.command.ts +1 -1
  33. package/src/commands/upgrade.command.ts +5 -3
  34. package/src/commands/visualize.command.ts +23 -2
  35. package/src/common/index.ts +2 -0
  36. package/src/common/layout-folder.ts +2 -20
  37. package/src/common/record.ts +7 -0
  38. package/src/common/text.ts +7 -0
  39. package/src/config/common/constants.ts +13 -1
  40. package/src/config/common/types.ts +8 -1
  41. package/src/config/loader.ts +4 -2
  42. package/src/config/packages.ts +4 -1
  43. package/src/config/schema.ts +51 -4
  44. package/src/create/add-app.ts +170 -69
  45. package/src/create/add-lib.ts +41 -31
  46. package/src/create/common/constants.ts +1 -0
  47. package/src/create/common/failure.ts +10 -0
  48. package/src/create/common/index.ts +2 -0
  49. package/src/create/common/preset-path.ts +11 -0
  50. package/src/create/common/types.ts +7 -2
  51. package/src/create/init-monorepo.ts +5 -2
  52. package/src/create/lib-preset.ts +22 -17
  53. package/src/create/names.ts +1 -1
  54. package/src/create/next.ts +1 -1
  55. package/src/create/preset-diff.ts +232 -55
  56. package/src/create/preset-menu.ts +3 -3
  57. package/src/create/preset.ts +18 -10
  58. package/src/create/process.ts +4 -2
  59. package/src/create/scratch.ts +3 -1
  60. package/src/create/workspace.ts +37 -20
  61. package/src/doctor/checks.ts +74 -16
  62. package/src/doctor/runner.ts +2 -0
  63. package/src/doctor/tags.ts +2 -4
  64. package/src/hooks/codex-patch.ts +2 -2
  65. package/src/hooks/common/constants.ts +0 -3
  66. package/src/hooks/common/types.ts +15 -1
  67. package/src/hooks/decision.ts +1 -5
  68. package/src/hooks/guard-git.ts +1 -1
  69. package/src/hooks/guard-outside.ts +28 -9
  70. package/src/hooks/guard-package.ts +13 -7
  71. package/src/hooks/guard-scripting.ts +1 -1
  72. package/src/hooks/guard-writes.ts +73 -20
  73. package/src/hooks/owner-reply.ts +1 -1
  74. package/src/hooks/project-guards.ts +39 -4
  75. package/src/hooks/remote-hosts.ts +5 -20
  76. package/src/hooks/session-digest.ts +7 -0
  77. package/src/hooks/shell.ts +13 -4
  78. package/src/hooks/trusted-scripts.ts +80 -4
  79. package/src/init/common/types.ts +1 -1
  80. package/src/init/scaffold.ts +2 -2
  81. package/src/local/clean.ts +1 -1
  82. package/src/local/scan.ts +2 -2
  83. package/src/manifest/render.ts +20 -11
  84. package/src/owner/profile.ts +1 -3
  85. package/src/owner/shape.ts +1 -1
  86. package/src/owner/survey.ts +27 -18
  87. package/src/router.ts +4 -1
  88. package/src/rules/common/types.ts +1 -1
  89. package/src/signals/state.ts +1 -4
  90. package/src/sync/agent-removal.ts +7 -10
  91. package/src/sync/claude-launch.ts +36 -1
  92. package/src/sync/common/constants.ts +4 -0
  93. package/src/sync/common/index.ts +1 -0
  94. package/src/sync/common/symlink.ts +9 -0
  95. package/src/sync/common/types.ts +2 -2
  96. package/src/sync/planner.ts +10 -12
  97. package/src/sync/settings.ts +1 -1
  98. package/src/ui/keyboard.ts +3 -1
  99. package/src/ui/prompt.ts +4 -2
  100. package/src/visualize/assets.ts +370 -195
  101. package/src/visualize/charts.ts +11 -2
  102. package/src/visualize/compare-css.ts +30 -0
  103. package/src/visualize/compare-render.ts +194 -0
  104. package/src/visualize/compare-schema.ts +81 -0
  105. package/src/visualize/compare-validate.ts +126 -0
  106. package/src/visualize/constants.ts +29 -3
  107. package/src/visualize/diagrams.ts +1 -1
  108. package/src/visualize/gate.ts +136 -0
  109. package/src/visualize/icons.ts +5 -2
  110. package/src/visualize/index.ts +2 -0
  111. package/src/visualize/kinds-css.ts +54 -0
  112. package/src/visualize/kinds-render.ts +693 -0
  113. package/src/visualize/kinds-schema.ts +148 -0
  114. package/src/visualize/kinds-validate.ts +184 -0
  115. package/src/visualize/labels-vi.ts +109 -0
  116. package/src/visualize/labels.ts +49 -0
  117. package/src/visualize/layout.ts +10 -5
  118. package/src/visualize/page.ts +99 -61
  119. package/src/visualize/render.ts +48 -7
  120. package/src/visualize/schema.ts +21 -1
  121. package/src/visualize/sections.ts +115 -34
  122. package/src/visualize/sources.ts +270 -0
  123. package/src/visualize/theme.ts +472 -0
  124. package/src/visualize/validate.ts +6 -0
  125. package/src/wiki/anchors.ts +1 -1
  126. package/src/wiki/source-links.ts +3 -5
@@ -1,12 +1,13 @@
1
- import { existsSync, readFileSync } from 'node:fs';
2
- import { isAbsolute, join } from 'node:path';
1
+ import { existsSync, readFileSync, statSync } from 'node:fs';
2
+ import { isAbsolute, resolve } from 'node:path';
3
3
  import { HookConstants } from './common/index.ts';
4
4
  import { TrustStates } from './common/index.ts';
5
- import type { IHookCommand, IWriteCheck, IWriteHit } from './common/index.ts';
5
+ import type { IHookCommand, IReadOnlyScript, IWriteCheck, IWriteHit } from './common/index.ts';
6
6
  import { commandTextsOf } from './command-view.ts';
7
7
  import { forHost } from './decision.ts';
8
8
  import type { IProjectCommandCheck } from './project-guards.ts';
9
- import { listedScriptOf, trustOf } from './trusted-scripts.ts';
9
+ import { basenameOf, parseShell, programOf } from './shell.ts';
10
+ import { listedScriptOf, ReadOnlyScripts, ScriptPaths, trustOf } from './trusted-scripts.ts';
10
11
 
11
12
  const MUTATING_VERB = '(?:POST|PUT|PATCH|DELETE)';
12
13
 
@@ -72,22 +73,32 @@ const SCRIPT_CHECKS: IWriteCheck[] = [
72
73
  const extractScriptTargets = (opts: { command: string }): string[] =>
73
74
  [...opts.command.matchAll(/\bbun\s+(?:run\s+)?(\S+\.ts)\b/g)].map((match) => match[1]);
74
75
 
75
- const readScript = (opts: { target: string; cwd: string }): string | undefined => {
76
- const path = isAbsolute(opts.target) ? opts.target : join(opts.cwd, opts.target);
76
+ /**
77
+ * The files a script word can mean. `bun x.ts` opens the path as the OS does, following a link before a `..`;
78
+ * `bun run x.ts` folds the `..` as text first. Both are read, so neither spelling hides the other.
79
+ */
80
+ const scriptPathsOf = (opts: { target: string; cwd: string }): string[] => [
81
+ ...new Set([ScriptPaths.targetPath(opts), resolve(opts.cwd, opts.target)]),
82
+ ];
77
83
 
78
- return existsSync(path) ? readFileSync(path, 'utf8') : undefined;
79
- };
84
+ /** The text of a regular file; a folder, a pipe and a missing path read as nothing, so nothing is opened that can block. */
85
+ const readScript = (opts: { path: string }): string | undefined =>
86
+ existsSync(opts.path) && statSync(opts.path).isFile()
87
+ ? readFileSync(opts.path, 'utf8')
88
+ : undefined;
80
89
 
81
90
  /**
82
91
  * Every reason `command` looks like a write the base rules reserve for a human (V-W-02, V-W-03).
83
92
  * `trust` lists the scripts the project vouches for (`guard.writes.trustedScripts`, repo-relative, under
84
93
  * `root`): a listed script that is tracked and identical to HEAD skips the script checks only. The checks
85
94
  * on the command line itself always run, and a listed script that git says changed is checked like any other.
95
+ * `trust.readOnlyScripts` (`guard.writes.trustedScripts` objects, from the manifest) skips them for one call: the
96
+ * word right after the script is one of the entry's `readOnly` words and the script is tracked and equals HEAD.
86
97
  */
87
98
  export const inspectCommand = (opts: {
88
99
  command: string;
89
100
  cwd: string;
90
- trust?: { root: string; scripts: string[] };
101
+ trust?: { root: string; scripts: string[]; readOnlyScripts?: IReadOnlyScript[] };
91
102
  /** The project's own commands (`guard.writes.commands`), checked beside the fixed list. */
92
103
  extra?: IProjectCommandCheck[];
93
104
  }): IWriteHit[] => {
@@ -109,22 +120,62 @@ export const inspectCommand = (opts: {
109
120
  message: check.what,
110
121
  }));
111
122
 
112
- for (const target of extractScriptTargets({ command: texts.join('\n') })) {
113
- const source = readScript({ target, cwd: opts.cwd });
123
+ const targets = extractScriptTargets({ command: texts.join('\n') });
124
+ const entries = opts.trust?.readOnlyScripts ?? [];
125
+ // A subcommand counts only when the shell's own words give the same scripts in the same order as the text
126
+ // does; any other line (a script named in an argument, a pipe into a runner) is read as a whole.
127
+ const invocations = ReadOnlyScripts.extractInvocations({ command: opts.command });
128
+ const isPaired =
129
+ invocations.length === targets.length &&
130
+ invocations.every((invocation, index) => invocation.script === targets[index]);
131
+ const hasMoving = texts.some((text) =>
132
+ parseShell({ command: text }).some((command) =>
133
+ ReadOnlyScripts.MOVING_COMMANDS.has(basenameOf({ word: programOf({ command }).name })),
134
+ ),
135
+ );
136
+
137
+ for (const [index, target] of targets.entries()) {
138
+ const sources = scriptPathsOf({ target, cwd: opts.cwd })
139
+ .map((path) => readScript({ path }))
140
+ .filter((text): text is string => text !== undefined);
114
141
 
115
- if (source === undefined) {
142
+ if (sources.length === 0) {
116
143
  continue;
117
144
  }
118
145
 
146
+ const subcommand = isPaired ? invocations[index]?.subcommand : undefined;
147
+ // After a `cd` the hook does not know the folder a relative script word is from, so no entry covers it.
148
+ const isFromUnknownFolder =
149
+ !isAbsolute(target) && (isPaired ? invocations[index]?.moved === true : hasMoving);
150
+ // An entry covers the word only when both spellings of it (see `scriptPathsOf`) name that same entry.
151
+ const covered = (lookup: (spelling: { target: string }) => string | undefined) => {
152
+ const asWritten = lookup({ target });
153
+
154
+ return asWritten === lookup({ target: resolve(opts.cwd, target) }) ? asWritten : undefined;
155
+ };
156
+ const trusted = opts.trust;
119
157
  const listed =
120
- opts.trust === undefined
158
+ trusted === undefined || isFromUnknownFolder
121
159
  ? undefined
122
- : listedScriptOf({
123
- target,
124
- cwd: opts.cwd,
125
- root: opts.trust.root,
126
- scripts: opts.trust.scripts,
127
- });
160
+ : (covered((spelling) =>
161
+ listedScriptOf({
162
+ target: spelling.target,
163
+ cwd: opts.cwd,
164
+ root: trusted.root,
165
+ scripts: trusted.scripts,
166
+ }),
167
+ ) ??
168
+ (subcommand === undefined
169
+ ? undefined
170
+ : covered((spelling) =>
171
+ ReadOnlyScripts.find({
172
+ target: spelling.target,
173
+ subcommand,
174
+ cwd: opts.cwd,
175
+ root: trusted.root,
176
+ entries,
177
+ }),
178
+ )));
128
179
  const trust =
129
180
  listed === undefined || opts.trust === undefined
130
181
  ? undefined
@@ -134,7 +185,9 @@ export const inspectCommand = (opts: {
134
185
  continue;
135
186
  }
136
187
 
137
- for (const check of SCRIPT_CHECKS.filter((scriptCheck) => scriptCheck.pattern.test(source))) {
188
+ for (const check of SCRIPT_CHECKS.filter((scriptCheck) =>
189
+ sources.some((text) => scriptCheck.pattern.test(text)),
190
+ )) {
138
191
  hits.push({
139
192
  rule: check.rule,
140
193
  message: `${target} looks like it is ${check.what}${trust === undefined ? '' : ` (listed in guard.writes.trustedScripts, but not trusted: ${trust.reason})`}`,
@@ -33,7 +33,7 @@ const FIXES: Record<string, string> = {
33
33
  };
34
34
 
35
35
  /** The owner's view of the project in `projectRoot`; a project whose config cannot load gets the defaults. */
36
- export const loadOwnerView = async (opts: { projectRoot: string }): Promise<IOwnerView> => {
36
+ const loadOwnerView = async (opts: { projectRoot: string }): Promise<IOwnerView> => {
37
37
  const loaded = await loadConfig({ root: opts.projectRoot });
38
38
  const profile = readProfile({ root: opts.projectRoot });
39
39
 
@@ -1,5 +1,6 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
+ import type { IReadOnlyScript } from './common/index.ts';
3
4
 
4
5
  /** A command the project says is a database write or a deploy: guard-writes asks on a match. */
5
6
  export interface IProjectCommandCheck {
@@ -9,13 +10,15 @@ export interface IProjectCommandCheck {
9
10
  }
10
11
 
11
12
  /** What the project adds to the guards: the manifest's `guard` block, compiled. */
12
- export interface IGuardPolicy {
13
+ interface IGuardPolicy {
13
14
  commands: IProjectCommandCheck[];
14
15
  askPush: string[];
16
+ /** `guard.writes.readOnlyScripts`; absent when the manifest lists none. */
17
+ readOnlyScripts?: IReadOnlyScript[];
15
18
  }
16
19
 
17
- /** Spelt out: the blocking hooks import nothing that reads the package (a test holds it equal to the manifest's name). */
18
- export const GUARD_MANIFEST_FILE = '.agents/vulcan.manifest.json';
20
+ /** Spelt out: the blocking hooks import nothing that reads the package. */
21
+ const GUARD_MANIFEST_FILE = '.agents/vulcan.manifest.json';
19
22
 
20
23
  const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
21
24
  typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
@@ -61,8 +64,33 @@ const commandOf = (opts: { value: unknown }): IProjectCommandCheck | undefined =
61
64
  }
62
65
  };
63
66
 
67
+ const readOnlyScriptOf = (opts: { value: unknown }): IReadOnlyScript | undefined => {
68
+ const holder = { value: opts.value };
69
+ const script = isRecord(holder) ? holder.value['script'] : undefined;
70
+ const listed = isRecord(holder) ? holder.value['readOnly'] : undefined;
71
+ const words = Array.isArray(listed)
72
+ ? listed.filter((word): word is string => typeof word === 'string' && word !== '')
73
+ : [];
74
+
75
+ if (
76
+ typeof script !== 'string' ||
77
+ script === '' ||
78
+ !Array.isArray(listed) ||
79
+ words.length !== listed.length
80
+ ) {
81
+ note({
82
+ message:
83
+ 'ignoring a guard.writes.readOnlyScripts entry that has no script or no readOnly list of words',
84
+ });
85
+
86
+ return undefined;
87
+ }
88
+
89
+ return { script, readOnly: words };
90
+ };
91
+
64
92
  /**
65
- * The commands and push targets a project lists, from the committed manifest (`vulcan sync` renders
93
+ * The commands, push targets and read-only scripts a project lists, from the committed manifest (`vulcan sync` renders
66
94
  * them from the config), so a hook reads them with no config loader and no zod. A project with no
67
95
  * manifest, or none of the block, has none; an entry that cannot be used is skipped, said once on
68
96
  * stderr, and the others stay.
@@ -97,7 +125,13 @@ export const readGuardPolicy = (opts: { root: string }): IGuardPolicy => {
97
125
  const writes = { value: guard.value['writes'] };
98
126
  const git = { value: guard.value['git'] };
99
127
  const listed = isRecord(writes) ? writes.value['commands'] : undefined;
128
+ const scripts = isRecord(writes) ? writes.value['readOnlyScripts'] : undefined;
100
129
  const targets = isRecord(git) ? git.value['askPush'] : undefined;
130
+ const readOnlyScripts = (Array.isArray(scripts) ? scripts : []).flatMap((entry) => {
131
+ const script = readOnlyScriptOf({ value: entry });
132
+
133
+ return script === undefined ? [] : [script];
134
+ });
101
135
 
102
136
  return {
103
137
  commands: (Array.isArray(listed) ? listed : []).flatMap((entry) => {
@@ -108,6 +142,7 @@ export const readGuardPolicy = (opts: { root: string }): IGuardPolicy => {
108
142
  askPush: (Array.isArray(targets) ? targets : []).filter(
109
143
  (target): target is string => typeof target === 'string' && target !== '',
110
144
  ),
145
+ ...(readOnlyScripts.length === 0 ? {} : { readOnlyScripts }),
111
146
  };
112
147
  };
113
148
 
@@ -2,7 +2,7 @@ import { HookConstants } from './common/index.ts';
2
2
  import type { IWriteHit } from './common/index.ts';
3
3
  import { isDataOnly } from './command-view.ts';
4
4
  import { forHost } from './decision.ts';
5
- import { optionTakesNextWord, programOf, splitHeredocs } from './shell.ts';
5
+ import { optionTakesNextWord, programOf, ShellPrograms, splitHeredocs } 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. */
@@ -241,25 +241,10 @@ const SHELL_KEYWORDS = new Set([
241
241
 
242
242
  const HTTP_CLIENTS = new Set(['curl', 'wget', 'http', 'https', 'httpie', 'xh', 'xhs']);
243
243
 
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
- ]);
244
+ /** 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. */
245
+ const WRAPPERS = new Set(ShellPrograms.WRAPPER_NAMES.filter((name) => name !== 'command'));
261
246
 
262
- const SHELLS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh', 'ash']);
247
+ const SHELLS = new Set([...ShellPrograms.SHELL_NAMES, 'ksh', 'ash']);
263
248
 
264
249
  /** Look a command up or describe it; running none of the words that follow. */
265
250
  const LOOKUPS = new Set(['man', 'which', 'type', 'whereis', 'apropos', 'whatis', 'echo', 'printf']);
@@ -11,6 +11,7 @@ import {
11
11
  resolveOwnerView,
12
12
  } from '../owner/index.ts';
13
13
  import { extractRuleRows, parseRuleIds, readSlots, RuleConstants } from '../rules/index.ts';
14
+ import { ClaudeLaunch } from '../sync/claude-launch.ts';
14
15
  import { projectTmpOf } from './project-tmp.ts';
15
16
 
16
17
  /** A project row whose first cell lists IDs - `| V-W-02, V-W-03 |` - elaborates those base rules. */
@@ -80,9 +81,15 @@ export const buildSessionDigest = async (opts: {
80
81
  return `| ${id} | this project: \`${choice}\` - ${slot.options[choice]?.text ?? `unknown option - run \`${ProjectLayout.VULCAN_COMMAND} doctor\``} |`;
81
82
  });
82
83
 
84
+ const launchWarning = ClaudeLaunch.missWarning({
85
+ root: opts.projectRoot,
86
+ env: opts.env ?? process.env,
87
+ });
88
+
83
89
  const lines = [
84
90
  '# VULCAN rules - read this before acting',
85
91
  '',
92
+ ...(launchWarning === undefined ? [] : ['## Launch warning', '', launchWarning, '']),
86
93
  'Base rules: `node_modules/@venizia/vulcan/base/rules.md`. This project: `.agents/rules.md`.',
87
94
  '',
88
95
  ...buildAtlasBlock({
@@ -146,9 +146,18 @@ export const optionTakesNextWord = (opts: { wrapper: string; word: string }): bo
146
146
  };
147
147
 
148
148
  /** The plain words a wrapper takes before its command (`timeout 5 cmd`). */
149
- export const wrapperPositionals = (opts: { wrapper: string }): number =>
149
+ const wrapperPositionals = (opts: { wrapper: string }): number =>
150
150
  WRAPPER_OPTIONS[opts.wrapper]?.positionals ?? 0;
151
- const SHELLS = new Set(['bash', 'sh', 'zsh', 'dash']);
151
+
152
+ /** The program names `remote-hosts.ts` reads too: one table here, so the two parsers cannot drift apart. */
153
+ export class ShellPrograms {
154
+ /** Every wrapper whose options the parser knows, `command` and `sshpass` included; a reader drops what it handles apart. */
155
+ static readonly WRAPPER_NAMES: readonly string[] = Object.keys(WRAPPER_OPTIONS);
156
+ /** The shells whose heredoc body is read as commands; `remote-hosts.ts` adds the ones it only follows. */
157
+ static readonly SHELL_NAMES: readonly string[] = ['bash', 'sh', 'zsh', 'dash'];
158
+ }
159
+
160
+ const SHELLS = new Set(ShellPrograms.SHELL_NAMES);
152
161
  const MAX_DEPTH = 4;
153
162
 
154
163
  /** What the parser reads of one command line at most: a guard that reads more would be slow, and a slow guard is skipped. */
@@ -706,7 +715,7 @@ const programBefore = (opts: { prefix: string }): string => {
706
715
  });
707
716
  };
708
717
 
709
- export interface IHeredoc {
718
+ interface IHeredoc {
710
719
  body: string;
711
720
  /** The body was left in the text because a shell reads it as commands (`bash <<EOF`). */
712
721
  isInline: boolean;
@@ -1017,7 +1026,7 @@ const parseWithBudget = (opts: {
1017
1026
  ];
1018
1027
  };
1019
1028
 
1020
- export interface IParsedShell {
1029
+ interface IParsedShell {
1021
1030
  commands: ISimpleCommand[];
1022
1031
  /** Part of the line was not read: it is larger, or nests deeper, than the parser's budget. */
1023
1032
  isOverBudget: boolean;
@@ -2,7 +2,8 @@ import { spawnSync } from 'node:child_process';
2
2
  import { existsSync, realpathSync } from 'node:fs';
3
3
  import { isAbsolute, join, relative, resolve, sep } from 'node:path';
4
4
  import { HookConstants, TrustStates } from './common/index.ts';
5
- import type { IScriptTrust } from './common/index.ts';
5
+ import type { IReadOnlyScript, IScriptInvocation, IScriptTrust } from './common/index.ts';
6
+ import { basenameOf, parseShell, programOf } from './shell.ts';
6
7
 
7
8
  /** Variables that point git at another repository or index than the one in `cwd`. */
8
9
  const REDIRECTING_VARIABLES = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE'];
@@ -121,14 +122,89 @@ export const trustOf = (opts: { root: string; script: string }): IScriptTrust =>
121
122
  return { state: TrustStates.TRUSTED, reason: 'tracked, and identical to the last commit' };
122
123
  };
123
124
 
124
- /** The listed script `target` names, if any: both resolved to absolute paths, an exact match. */
125
+ export class ScriptPaths {
126
+ /**
127
+ * The script word as the shell opens it: joined to the working folder without folding `..`, so a link
128
+ * before a `..` is followed the way the shell follows it.
129
+ */
130
+ static targetPath(opts: { target: string; cwd: string }): string {
131
+ return isAbsolute(opts.target) ? opts.target : `${opts.cwd}${sep}${opts.target}`;
132
+ }
133
+
134
+ /** The file `path` is on disk, links followed by the OS; the path folded as written when nothing is there. */
135
+ static physicalOf(opts: { path: string }): string {
136
+ try {
137
+ return realpathSync.native(opts.path);
138
+ } catch {
139
+ return resolve(opts.path);
140
+ }
141
+ }
142
+ }
143
+
144
+ /** The listed script `target` names, if any: both resolved to the file on disk, an exact match. */
125
145
  export const listedScriptOf = (opts: {
126
146
  target: string;
127
147
  cwd: string;
128
148
  root: string;
129
149
  scripts: string[];
130
150
  }): string | undefined => {
131
- const path = isAbsolute(opts.target) ? resolve(opts.target) : resolve(opts.cwd, opts.target);
151
+ const path = ScriptPaths.physicalOf({
152
+ path: ScriptPaths.targetPath({ target: opts.target, cwd: opts.cwd }),
153
+ });
132
154
 
133
- return opts.scripts.find((script) => resolve(opts.root, script) === path);
155
+ return opts.scripts.find(
156
+ (script) => ScriptPaths.physicalOf({ path: resolve(opts.root, script) }) === path,
157
+ );
134
158
  };
159
+
160
+ export class ReadOnlyScripts {
161
+ /**
162
+ * The `bun x.ts` calls of a command line, in order, one per simple command: the script word and the word
163
+ * right after it. The words are the shell's own, so a quoted `"plan x"` stays one word and a `;` or `&&`
164
+ * ends the command and is never part of one.
165
+ */
166
+ static extractInvocations(opts: { command: string }): IScriptInvocation[] {
167
+ let moved = false;
168
+
169
+ return parseShell({ command: opts.command }).flatMap((command) => {
170
+ const { name, args } = programOf({ command });
171
+ const program = basenameOf({ word: name });
172
+
173
+ if (ReadOnlyScripts.MOVING_COMMANDS.has(program)) {
174
+ moved = true;
175
+ }
176
+
177
+ if (program !== 'bun') {
178
+ return [];
179
+ }
180
+
181
+ const [script, subcommand] = args[0] === 'run' ? args.slice(1) : args;
182
+
183
+ return script !== undefined && script.endsWith('.ts') ? [{ script, subcommand, moved }] : [];
184
+ });
185
+ }
186
+
187
+ /** Commands that change the folder the next commands of the line run in, which the hook does not follow. */
188
+ static readonly MOVING_COMMANDS = new Set(['cd', 'pushd', 'popd']);
189
+
190
+ /**
191
+ * The listed script a call to `target` with `subcommand` is read-only for: both resolved to absolute
192
+ * paths, the subcommand matched as one whole word. `undefined` when no entry covers this call.
193
+ */
194
+ static find(opts: {
195
+ target: string;
196
+ subcommand: string;
197
+ cwd: string;
198
+ root: string;
199
+ entries: IReadOnlyScript[];
200
+ }): string | undefined {
201
+ return listedScriptOf({
202
+ target: opts.target,
203
+ cwd: opts.cwd,
204
+ root: opts.root,
205
+ scripts: opts.entries
206
+ .filter((entry) => entry.readOnly.includes(opts.subcommand))
207
+ .map((entry) => entry.script),
208
+ });
209
+ }
210
+ }
@@ -1,7 +1,7 @@
1
1
  import type { TConstValue } from '../../common/index.ts';
2
2
  import type { InitStatuses } from './constants.ts';
3
3
 
4
- export type TInitStatus = TConstValue<typeof InitStatuses>;
4
+ type TInitStatus = TConstValue<typeof InitStatuses>;
5
5
 
6
6
  /** One line of the init report: a file created or kept, or a line the user should add by hand. */
7
7
  export interface IInitEntry {
@@ -26,7 +26,7 @@ const LINT_CONFIG_FILES: IScaffoldFile[] = [
26
26
  { path: '.configs/lints/eslint.config.mjs', template: 'eslint.config.mjs' },
27
27
  ];
28
28
 
29
- export interface IScaffoldResult {
29
+ interface IScaffoldResult {
30
30
  entries: IInitEntry[];
31
31
  /** Packages to `bun add -d`, empty when everything is declared. */
32
32
  install: string[];
@@ -103,7 +103,7 @@ export const coversFolder = (opts: { globs: string[]; folder: string }): boolean
103
103
  });
104
104
 
105
105
  /** The `package.json` name, or the directory name when there is none. */
106
- export const resolveProjectName = (opts: { root: string }): string => {
106
+ const resolveProjectName = (opts: { root: string }): string => {
107
107
  const name = readManifest(opts)?.name;
108
108
 
109
109
  return typeof name === 'string' && name !== '' ? name : basename(opts.root);
@@ -4,7 +4,7 @@ import { LocalConstants } from './constants.ts';
4
4
  import { isInsideLocal, scanLocal } from './scan.ts';
5
5
  import type { ILocalEntry } from './scan.ts';
6
6
 
7
- export interface ICleanPlan {
7
+ interface ICleanPlan {
8
8
  /** What the chosen scopes would remove. */
9
9
  remove: ILocalEntry[];
10
10
  /** In a chosen scope but not removable (an unmerged worktree, a worktree git could not read). */
package/src/local/scan.ts CHANGED
@@ -28,7 +28,7 @@ interface IRegistered {
28
28
  }
29
29
 
30
30
  /** The newest modification time under `path`, itself included: a folder's own time moves only when its direct children do. */
31
- export const newestModifiedAt = (opts: { path: string }): number => {
31
+ const newestModifiedAt = (opts: { path: string }): number => {
32
32
  let stat;
33
33
 
34
34
  try {
@@ -48,7 +48,7 @@ export const newestModifiedAt = (opts: { path: string }): number => {
48
48
  };
49
49
 
50
50
  /** The bytes under `path`, symlinks counted as themselves and never followed. */
51
- export const sizeOf = (opts: { path: string }): number => {
51
+ const sizeOf = (opts: { path: string }): number => {
52
52
  let stat;
53
53
 
54
54
  try {
@@ -46,23 +46,29 @@ export const buildBaseRuleHashes = (): Record<string, string> =>
46
46
  }),
47
47
  );
48
48
 
49
- /** The manifest's `guard` block: what the project adds to guard-writes and guard-git, as data a hook reads without the config. */
49
+ /** The manifest's `guard` block: what the project adds to guard-writes and guard-git, as data a hook reads without the config (the read-only script entries of `trustedScripts` included). */
50
50
  const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<string, unknown> } => {
51
- const { commands } = opts.config.guard.writes;
51
+ const { commands, trustedScripts } = opts.config.guard.writes;
52
52
  const { askPush } = opts.config.guard.git;
53
- const block = {
53
+ // Only the object entries: a path string is read from the config by the hook, as before.
54
+ const readOnlyScripts = trustedScripts.flatMap((entry) =>
55
+ typeof entry === 'string' ? [] : [{ script: entry.script, readOnly: entry.readOnly }],
56
+ );
57
+ const writes = {
54
58
  ...(commands.length === 0
55
59
  ? {}
56
60
  : {
57
- writes: {
58
- commands: commands.map((command) => ({
59
- rule: command.rule,
60
- what: command.what,
61
- pattern: command.pattern,
62
- ...(command.ignoreCase === true ? { ignoreCase: true } : {}),
63
- })),
64
- },
61
+ commands: commands.map((command) => ({
62
+ rule: command.rule,
63
+ what: command.what,
64
+ pattern: command.pattern,
65
+ ...(command.ignoreCase === true ? { ignoreCase: true } : {}),
66
+ })),
65
67
  }),
68
+ ...(readOnlyScripts.length === 0 ? {} : { readOnlyScripts }),
69
+ };
70
+ const block = {
71
+ ...(Object.keys(writes).length === 0 ? {} : { writes }),
66
72
  ...(askPush.length === 0 ? {} : { git: { askPush } }),
67
73
  };
68
74
 
@@ -99,6 +105,7 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
99
105
  aliases: entry.aliases,
100
106
  retired: entry.retired,
101
107
  ...(entry.kind === undefined ? {} : { kind: entry.kind }),
108
+ ...(entry.presetKind === undefined ? {} : { presetKind: entry.presetKind }),
102
109
  })),
103
110
  // Where each kind of app goes and the presets that make one: what an agent asked for a new app needs.
104
111
  ...(config.layout === undefined ? {} : { layout: config.layout }),
@@ -126,6 +133,8 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
126
133
  ...guardBlockOf({ config }),
127
134
  // The remote-host guard reads its policy here; a project without the key has no guard.
128
135
  ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
136
+ // The colour `vulcan visualize` takes for its pages; a project without the key gets the neutral default.
137
+ ...(config.theme === undefined ? {} : { theme: config.theme }),
129
138
  };
130
139
 
131
140
  return formatWithBun({
@@ -5,9 +5,7 @@ import { OwnerConstants } from './constants.ts';
5
5
  import { PROFILE_SCHEMA } from './schema.ts';
6
6
  import type { TProfile } from './schema.ts';
7
7
 
8
- export type TProfileRead =
9
- | { ok: true; profile: TProfile | undefined }
10
- | { ok: false; error: string };
8
+ type TProfileRead = { ok: true; profile: TProfile | undefined } | { ok: false; error: string };
11
9
 
12
10
  /** A symlink at the profile's place, or at `.agents/local`, would read or write a file outside the project. */
13
11
  export const linkedAt = (opts: { root: string }): string | undefined =>
@@ -40,7 +40,7 @@ export class ShapeClasses {
40
40
  }
41
41
  }
42
42
 
43
- export interface IShapeResult {
43
+ interface IShapeResult {
44
44
  /** False for an empty reply or a short one the view exempts. */
45
45
  isChecked: boolean;
46
46
  classes: string[];