@venizia/vulcan 0.4.10-2 → 0.4.10-3

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 (50) hide show
  1. package/README.md +19 -14
  2. package/base/hooks/guard-outside.ts +6 -17
  3. package/base/hooks/guard-writes.ts +3 -24
  4. package/base/rules.md +3 -3
  5. package/base/skills/visualize-work/SKILL.md +1 -1
  6. package/base/skills/visualize-work/references/spec.md +1 -1
  7. package/package.json +3 -3
  8. package/src/agents/resolve.ts +1 -0
  9. package/src/board/common/types.ts +2 -2
  10. package/src/board/schema.ts +4 -1
  11. package/src/board/settings.ts +1 -1
  12. package/src/commands/help.command.ts +2 -63
  13. package/src/commands/table.ts +315 -0
  14. package/src/commit/check.ts +1 -0
  15. package/src/commit/common/constants.ts +2 -0
  16. package/src/commit/hook.ts +44 -4
  17. package/src/common/constants.ts +6 -3
  18. package/src/common/env-variables.ts +37 -0
  19. package/src/common/index.ts +1 -0
  20. package/src/config/loader.ts +22 -0
  21. package/src/config/schema.ts +121 -4
  22. package/src/create/add-app.ts +5 -0
  23. package/src/create/common/constants.ts +5 -3
  24. package/src/create/preset.ts +1 -0
  25. package/src/doctor/checks.ts +10 -0
  26. package/src/doctor/common/constants.ts +26 -0
  27. package/src/doctor/runner.ts +1 -0
  28. package/src/doctor/schema.ts +4 -0
  29. package/src/hooks/owner-reply.ts +5 -0
  30. package/src/hooks/project-guards.ts +25 -4
  31. package/src/hooks/session-digest.ts +9 -0
  32. package/src/init/scaffold.ts +1 -0
  33. package/src/local/auto-clean.ts +2 -1
  34. package/src/local/clean.ts +1 -0
  35. package/src/manifest/render.ts +48 -6
  36. package/src/owner/constants.ts +3 -1
  37. package/src/owner/profile.ts +1 -0
  38. package/src/owner/schema.ts +37 -6
  39. package/src/router.ts +4 -130
  40. package/src/rules/base.ts +1 -0
  41. package/src/signals/loop.ts +1 -0
  42. package/src/skills/frontmatter.ts +1 -0
  43. package/src/sync/planner.ts +1 -0
  44. package/src/theme/index.ts +1 -0
  45. package/src/theme/tokens.ts +305 -0
  46. package/src/ui/prompt.ts +1 -0
  47. package/src/visualize/page.ts +4 -4
  48. package/src/visualize/render.ts +2 -1
  49. package/src/visualize/theme.ts +27 -10
  50. package/src/wiki/anchors.ts +1 -0
@@ -0,0 +1,315 @@
1
+ import { AgentConstants } from '../agents/index.ts';
2
+ import { BoardFlags } from '../board/common/index.ts';
3
+ import { CiFlags } from '../ci/common/index.ts';
4
+ import { CommitCheckFlags } from '../commit/common/index.ts';
5
+ import { ExitCodes, UpgradeFlags, VULCAN_VERSION, VulcanCommands } from '../common/index.ts';
6
+ import { CreateFlags } from '../create/common/index.ts';
7
+ import { EventFlags } from '../events/common/index.ts';
8
+
9
+ /** What the router lets through for a command: the flags that stand alone, the flags that take the next argument, and how many plain arguments. */
10
+ export interface IAcceptedArgs {
11
+ flags: string[];
12
+ /** The exit code for an argument the command does not take; `1` when absent. */
13
+ unknownExit?: number;
14
+ values: string[];
15
+ positionals: number;
16
+ }
17
+
18
+ /** One command: what `vulcan help` prints for it, what its flags do, and what its exit codes mean. */
19
+ export interface ICommandSpec {
20
+ /** The block `vulcan help` prints for the command: its usage lines, then what it does. */
21
+ help: string;
22
+ /** Flags that stand alone, each with what it does. */
23
+ flags?: Record<string, string>;
24
+ /** Flags that take the next argument, each with what it does. */
25
+ values?: Record<string, string>;
26
+ /** Flags the router lets through and the command does not read. */
27
+ ignored?: { flags: string[]; values: string[] };
28
+ /** How many arguments without a flag the command takes. */
29
+ positionals?: number;
30
+ /** The exit code for an argument the command does not take; `1` when absent. */
31
+ unknownExit?: number;
32
+ /** What the exit codes mean. */
33
+ exits: string;
34
+ /** The arguments are not checked by the router: `x` hands them to its tool, `help` and `version` take none. */
35
+ passthrough?: true;
36
+ }
37
+
38
+ /** Every command in one table: `vulcan help` prints its blocks and the router takes its accepted arguments from it; the generated command reference is to read the flag descriptions and exit codes. */
39
+ export class CommandTable {
40
+ static readonly COMMANDS: Record<string, ICommandSpec> = {
41
+ [VulcanCommands.INIT]: {
42
+ help: ` init [--key <KEY>] Scaffold the project layer (never overwrites); --key is the project's flow key
43
+ (2 to 8 uppercase letters or digits; a terminal asks, else it is made from the name)
44
+ init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <path>]
45
+ [--shared-dir <path>] [--scope <@scope>] [--key <KEY>]
46
+ Create a monorepo with its first app, from a framework preset
47
+ (a name missing from the flags is asked in a terminal)`,
48
+ values: {
49
+ [CreateFlags.PRESET]: 'The preset package; its presence selects the monorepo mode',
50
+ [CreateFlags.PROJECT]: 'The project name and the folder to create',
51
+ [CreateFlags.BACKEND_DIR]: 'The folder that holds backend apps, 1 to 4 segments',
52
+ [CreateFlags.FRONTEND_DIR]: 'The folder that holds frontend apps, 1 to 4 segments',
53
+ [CreateFlags.SHARED_DIR]: 'A folder for code shared between apps; optional',
54
+ [CreateFlags.APP]: 'The name of the first app',
55
+ [CreateFlags.SCOPE]: "The npm scope of the first app's package, such as @acme",
56
+ [CreateFlags.KEY]: "The project's flow key, 2 to 8 uppercase letters or digits",
57
+ },
58
+ ignored: { flags: [CreateFlags.NO_API], values: [CreateFlags.API] },
59
+ exits:
60
+ '0 on success; 1 when it refuses before writing (not a project, bad or missing name, folder not empty) or bun add fails.',
61
+ },
62
+ [VulcanCommands.ADD]: {
63
+ help: ` add --preset <name|file:path> (--app <name> | --lib <name> | --shared <name>) [--dir <folder>]
64
+ [--scope <@scope>] [--backend-dir|--frontend-dir <path>] [--api <app> | --no-api]
65
+ Add an app, a library other apps import (--lib) or a side-neutral package
66
+ other apps import (--shared) to the monorepo (a frontend says which
67
+ backend to proxy to; --dir is for a library or a shared package;
68
+ --scope names the package @scope/<name>; a terminal asks for the kind
69
+ and every name the flags leave out)`,
70
+ flags: {
71
+ [CreateFlags.NO_API]: 'A frontend only: proxy to nothing',
72
+ },
73
+ values: {
74
+ [CreateFlags.PRESET]: 'The preset package; a bare name means @venizia/<name>',
75
+ [CreateFlags.BACKEND_DIR]: 'The folder for backend apps, used when the preset is a backend',
76
+ [CreateFlags.FRONTEND_DIR]:
77
+ 'The folder for frontend apps, used when the preset is a frontend',
78
+ [CreateFlags.APP]: 'The name of the new app',
79
+ [CreateFlags.API]: 'A frontend only: the backend app to proxy /api to',
80
+ [CreateFlags.LIB]: 'Create a library other apps import, instead of an app',
81
+ [CreateFlags.SHARED]: 'Create a side-neutral package that apps of either side import',
82
+ [CreateFlags.DIR]: 'A library or shared package only: the folder it goes in',
83
+ [CreateFlags.SCOPE]: 'The npm scope of the package name, such as @acme',
84
+ },
85
+ exits: '0 on success; 1 on any refusal, which happens before the first write.',
86
+ },
87
+ [VulcanCommands.PRESET]: {
88
+ help: ` preset diff <package> [--preset <name|file:path>] [--api <app> | --no-api] [--full] [--check]
89
+ Read-only: set each file the preset makes now (for an app, a library or
90
+ a shared package) against the file the package has (same, differs,
91
+ missing); --full prints the unified diffs, --check exits 1 when
92
+ anything differs or is missing`,
93
+ flags: {
94
+ [CreateFlags.NO_API]: 'A frontend app only: proxy to nothing',
95
+ [CreateFlags.FULL]: 'Print the unified diff under each file that differs',
96
+ [CreateFlags.CHECK]: 'Exit 1 when a file differs or is missing, for CI',
97
+ },
98
+ values: {
99
+ [CreateFlags.PRESET]: 'The preset to render, when it cannot be found from the package',
100
+ [CreateFlags.API]: 'A frontend app only: the backend app to proxy /api to',
101
+ },
102
+ positionals: 2,
103
+ exits:
104
+ '0 when a report is printed (with --check, and nothing differs); 1 on --check with a difference or missing file, or any refusal.',
105
+ },
106
+ [VulcanCommands.SYNC]: {
107
+ help: ` sync [--agents <list>|list] [--dry-run]
108
+ Write the adapters of the agents you chose (--agents claude,omp or none,
109
+ stored in .agents/vulcan.local.json; --agents list shows the table)`,
110
+ flags: {
111
+ '--dry-run': 'Print planned changes without writing to disk',
112
+ },
113
+ values: {
114
+ [AgentConstants.FLAG]: 'The agents to write adapters for, comma-separated, none, or list',
115
+ },
116
+ exits:
117
+ '0 on success; 1 when .claude/settings.json cannot be written, or the configuration fails to load.',
118
+ },
119
+ [VulcanCommands.AGENTS]: {
120
+ help: ` agents [list|add <ids>|remove <ids>|setup] [--dry-run]
121
+ See, add, remove or re-choose the coding agents you use on this machine`,
122
+ flags: {
123
+ '--dry-run': 'Print what would change and write nothing',
124
+ },
125
+ positionals: 2,
126
+ exits:
127
+ '0 on success, including an agent already chosen or not chosen; 1 on an unknown id, a bad argument or a failed write.',
128
+ },
129
+ [VulcanCommands.DOCTOR]: {
130
+ help: ` doctor Check the project follows VULCAN; exit 1 on any violation`,
131
+ exits: '0 for a conformant project; 1 on one or more contract violations.',
132
+ },
133
+ [VulcanCommands.COMMIT_CHECK]: {
134
+ help: ` commit-check <message-file> | --range <revs> | --text <message>
135
+ Check a commit message against the commit.message checks of the config (an
136
+ agent in a trailer or a "generated with" line, the project's subject shape);
137
+ sync installs it as the commit-msg hook; exit 1 on a problem, 2 on bad input`,
138
+ values: {
139
+ [CommitCheckFlags.RANGE]: 'Check every commit of a git range, such as origin/develop..HEAD',
140
+ [CommitCheckFlags.TEXT]: 'Check the message text you give',
141
+ },
142
+ positionals: 2,
143
+ unknownExit: ExitCodes.USAGE,
144
+ exits:
145
+ '0 when nothing is wrong or no check is configured; 1 when a message has a problem; 2 on bad input.',
146
+ },
147
+ [VulcanCommands.BOARD]: {
148
+ help: ` board [--out <file>] [--open] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]
149
+ Fold the event log (and GitHub pull requests, checks and reviews when gh
150
+ can read them) into flows and write one HTML file, by default
151
+ .agents/local/reports/board.html; read-only; exit 2 on bad input
152
+ board serve [--port <n>] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]
153
+ Serve the same page on 127.0.0.1 (default port 4317) and push the new events to the open page, with no reload`,
154
+ flags: {
155
+ [BoardFlags.OPEN]: 'Open the file in your browser when it is written',
156
+ [BoardFlags.NO_GITHUB]: 'Do not read GitHub',
157
+ },
158
+ values: {
159
+ [BoardFlags.OUT]: 'The file to write; default .agents/local/reports/board.html',
160
+ [BoardFlags.PORT]: 'serve only: the port to listen on; default 4317',
161
+ [BoardFlags.SINCE]: 'Read events and pull requests changed at or after this date',
162
+ [BoardFlags.DIR]: 'The events folder; default events.dir, else .agents/local/events',
163
+ [BoardFlags.REPO]: 'A GitHub repository, owner/name; repeat it to read several',
164
+ },
165
+ positionals: 1,
166
+ unknownExit: ExitCodes.USAGE,
167
+ exits:
168
+ '0 on written or serve stopped; 1 when the file cannot be written or serve cannot start; 2 on bad input.',
169
+ },
170
+ [VulcanCommands.CI]: {
171
+ help: ` ci affected --base <ref> [--head <ref>] [--check <check>] [--json | --names] | template <github|gitlab>
172
+ List the workspace packages a change touches (changed ones and what
173
+ depends on them) with the checks each has; template prints a CI file that
174
+ runs exactly those; exit 2 on bad input`,
175
+ flags: {
176
+ [CiFlags.JSON]: 'Print the result as JSON',
177
+ [CiFlags.NAMES]: 'Print only the package names, one per line',
178
+ },
179
+ values: {
180
+ [CiFlags.BASE]: 'The commit to compare with; required',
181
+ [CiFlags.HEAD]: 'The commit that holds the change; default HEAD',
182
+ [CiFlags.CHECK]: 'Keep only packages with this check: typecheck, lint, test or compile',
183
+ },
184
+ positionals: 2,
185
+ unknownExit: ExitCodes.USAGE,
186
+ exits: '0 with a list, an empty one included; 2 on bad input or a run that cannot finish.',
187
+ },
188
+ [VulcanCommands.EVENT]: {
189
+ help: ` event add --kind <k> --summary <text> [--flow <flow id>] [--ref <r>] [--status approve|park|reject] [--actor <name>] | add --kind flow [--flow <flow id>] --title <text> [--why <text>] [--context <text>] [--next <text>] [--step|--step-done <text>]... [--check|--check-done <text>]... [--app <name>]... [--due YYYY-MM-DD] | tail [--since <time>] [--json] [--dir <folder>]
190
+ Write a line to the agent event log (.agents/local/events/<day>.jsonl) or
191
+ read it; with events.log on, sync installs the Claude Code hooks that
192
+ write it; exit 2 on bad input`,
193
+ flags: {
194
+ [EventFlags.JSON]: 'Print each line as written (tail)',
195
+ },
196
+ values: {
197
+ [EventFlags.KIND]: 'One of the twelve event kinds',
198
+ [EventFlags.SUMMARY]: 'A short label, cut to one line of 200 characters',
199
+ [EventFlags.FLOW]: 'The id of a flow the log already has',
200
+ [EventFlags.STEP]: 'Flow only, repeatable: a step still to do',
201
+ [EventFlags.STEP_DONE]: 'Flow only, repeatable: a step done',
202
+ [EventFlags.CHECK]: 'Flow only, repeatable: an acceptance check still open',
203
+ [EventFlags.CHECK_DONE]: 'Flow only, repeatable: an acceptance check done',
204
+ [EventFlags.APP]: 'Flow only, repeatable: an app or module the flow touches',
205
+ [EventFlags.DUE]: 'Flow only: the day it is due, YYYY-MM-DD',
206
+ [EventFlags.REF]: 'A commit, a PR number, a recipient, or a tracker id',
207
+ [EventFlags.STATUS]: 'approve, park or reject; required on a decision',
208
+ [EventFlags.TITLE]: 'Flow only, required: the title of the flow',
209
+ [EventFlags.WHY]: 'Flow only: one line on why the flow exists',
210
+ [EventFlags.CONTEXT]: 'Flow only: two to four sentences on what the flow is',
211
+ [EventFlags.NEXT]: 'Flow only: the next step and who does it',
212
+ [EventFlags.ACTOR]: 'Who wrote the event; else VULCAN_ACTOR or the session name',
213
+ [EventFlags.DIR]: 'The events folder for this call, over events.dir',
214
+ [EventFlags.SINCE]: 'tail only: print events at or after this time; default 24 hours',
215
+ },
216
+ positionals: 1,
217
+ unknownExit: ExitCodes.USAGE,
218
+ exits: '0 written; 1 when the folder cannot be written; 2 on bad input.',
219
+ },
220
+ [VulcanCommands.VISUALIZE]: {
221
+ help: ` visualize <spec.json> [--out <name>] | --schema
222
+ Make one small static HTML page (a flow, a status, a before and after) from
223
+ a JSON spec, in .agents/local/prototypes/; --schema prints the spec's schema`,
224
+ flags: {
225
+ '--schema': 'Print the schema of the spec',
226
+ },
227
+ values: {
228
+ [BoardFlags.OUT]: 'The name of the page written in .agents/local/prototypes/',
229
+ },
230
+ positionals: 1,
231
+ exits:
232
+ '0 on success; 1 when the spec is missing or not renderable, or .agents/local/ is missing or outside the project.',
233
+ },
234
+ [VulcanCommands.PROFILE]: {
235
+ help: ` profile [show|edit|reset [--yes]]
236
+ Tell VULCAN how you like to work (reply language, how to address you,
237
+ tone, habits) in .agents/local/profile.json; no argument runs the form,
238
+ show prints it, reset deletes it`,
239
+ flags: {
240
+ '--yes': 'With reset: delete .agents/local/profile.json',
241
+ },
242
+ positionals: 1,
243
+ exits:
244
+ '0 on saved, shown, reset or nothing to reset; 1 on cancelled, unreadable profile, .agents/local/ not gitignored, or unknown argument.',
245
+ },
246
+ [VulcanCommands.CLEAN]: {
247
+ help: ` clean [--tmp|--worktrees|--clones|--cache|--all] [--reports|--prototypes|--events|--release-candidates|--profile] [--yes]
248
+ List what an agent left under .agents/local/ (a dry run) and, with
249
+ --yes, remove it; --tmp is the default, --worktrees takes merged or
250
+ gone branches only, --all never touches reports, prototypes, events, release candidates or the profile`,
251
+ flags: {
252
+ '--tmp': 'Remove every item in tmp/, whatever its age; the default',
253
+ '--worktrees': 'Remove worktrees whose branch is merged or gone and that are clean',
254
+ '--clones': 'Remove clones of other repositories',
255
+ '--cache': 'Remove what atlas fetched; it rebuilds',
256
+ '--reports': 'Remove reports/; kept unless named',
257
+ '--prototypes': 'Remove prototypes/; kept unless named',
258
+ '--profile': 'Remove profile.json; kept unless named',
259
+ '--events': 'Remove event day files past the events limits; only when named',
260
+ '--release-candidates':
261
+ 'Remove release-candidate folders whose version tag exists; only when named',
262
+ '--all':
263
+ 'Select tmp, worktrees, clones and cache; never reports, prototypes, events, candidates or profile',
264
+ '--yes': 'Remove what the dry run listed',
265
+ },
266
+ exits:
267
+ '0 on a dry run, a removal or nothing to remove; 1 when an item cannot be removed, or on an unknown flag.',
268
+ },
269
+ [VulcanCommands.UPGRADE]: {
270
+ help: ` upgrade [--stable | --nightly] [<version|tag>]
271
+ Bump the pinned @venizia/vulcan, then sync; --stable (default)
272
+ takes the latest tag, --nightly the newest of latest and next`,
273
+ flags: {
274
+ [UpgradeFlags.STABLE]: 'Install the latest stable release; the default',
275
+ [UpgradeFlags.NIGHTLY]: 'Install the higher of latest and next',
276
+ },
277
+ positionals: 1,
278
+ exits:
279
+ '0 on success; 1 when --stable and --nightly are both given, the dist-tags cannot be read, or the install or sync fails.',
280
+ },
281
+ [VulcanCommands.X]: {
282
+ help: ` x <tool> [args...] Run a shipped tool at the pinned version: okf, atlas`,
283
+ passthrough: true,
284
+ exits:
285
+ 'the exit code of the tool; 1 on a missing or unknown tool, an unresolvable package or an invalid configuration',
286
+ },
287
+ [VulcanCommands.HELP]: { help: '', passthrough: true, exits: '0' },
288
+ [VulcanCommands.VERSION]: { help: '', passthrough: true, exits: '0' },
289
+ };
290
+
291
+ /** The arguments the router lets `name` take; undefined when it checks none. */
292
+ static accepted(opts: { name: string }): IAcceptedArgs | undefined {
293
+ const spec = CommandTable.COMMANDS[opts.name];
294
+
295
+ if (spec === undefined || spec.passthrough === true) {
296
+ return undefined;
297
+ }
298
+
299
+ return {
300
+ flags: [...Object.keys(spec.flags ?? {}), ...(spec.ignored?.flags ?? [])],
301
+ values: [...Object.keys(spec.values ?? {}), ...(spec.ignored?.values ?? [])],
302
+ positionals: spec.positionals ?? 0,
303
+ ...(spec.unknownExit === undefined ? {} : { unknownExit: spec.unknownExit }),
304
+ };
305
+ }
306
+
307
+ /** What `vulcan help` prints. */
308
+ static helpText(): string {
309
+ const blocks = Object.values(CommandTable.COMMANDS).flatMap((spec) =>
310
+ spec.help === '' ? [] : [spec.help],
311
+ );
312
+
313
+ return `vulcan ${VULCAN_VERSION} - one setup, one workflow for every project\n\nUsage: bun x vulcan <command>\n\n${blocks.join('\n')}\n help · version\n`;
314
+ }
315
+ }
@@ -23,6 +23,7 @@ type TSource =
23
23
 
24
24
  type TMessages = { ok: true; messages: ICheckedMessage[] } | { ok: false; error: string };
25
25
 
26
+ /** Checks commit messages against the project commit-message rules and returns an exit code; used by `vulcan commit-check`, which the commit-msg hook calls. */
26
27
  export class CommitCheck {
27
28
  static async run(opts: ICommandContext): Promise<number> {
28
29
  const source = CommitCheck.sourceOf({ args: opts.args });
@@ -23,6 +23,8 @@ export class CommitHookStates {
23
23
  static readonly STALE = 'stale';
24
24
  /** A hook that is not ours and does not call the check: the developer adds the line. */
25
25
  static readonly UNWIRED = 'unwired';
26
+ /** A hook that another project of the repository wrote: this project's check is not installed, and the hook is not touched. */
27
+ static readonly OTHER_PROJECT = 'other-project';
26
28
  /** Our hook, and the project turned every check off: sync takes it back. */
27
29
  static readonly LEFTOVER = 'leftover';
28
30
  }
@@ -8,6 +8,8 @@ import type { ICommitHookStatus } from './common/index.ts';
8
8
 
9
9
  const HOOK_NAME = 'commit-msg';
10
10
  const MARKER = '# vulcan:commit-msg';
11
+ /** The marker line, then the folder of the project that wrote it in brackets; a hook of an earlier release has no brackets. */
12
+ const OWNER = new RegExp(`^${MARKER}(?: \\[([^\\]]*)\\])?`);
11
13
  const CALL = /vulcan\s+commit-check/;
12
14
  const COMMAND = 'bun x --no-install vulcan commit-check "$1"';
13
15
 
@@ -39,11 +41,11 @@ export class CommitHook {
39
41
  * no `commit-check` command (an older branch).
40
42
  */
41
43
  static template(opts: { prefix: string }): string {
42
- const folder = opts.prefix.replace(/\/$/, '');
44
+ const folder = CommitHook.folderOf({ prefix: opts.prefix });
43
45
  const enter = folder === '' ? '' : `cd ${CommitHook.quote({ text: folder })} || exit 0\n`;
44
46
 
45
47
  return `#!/bin/sh
46
- ${MARKER} - written by vulcan sync from commit.message in .configs/vulcan.config.mts; do not edit
48
+ ${MARKER} [${CommitHook.encode({ folder })}] - written by vulcan sync from commit.message in .configs/vulcan.config.mts; do not edit
47
49
  message="$1"
48
50
  case "$message" in /*) ;; *) message="$PWD/$message" ;; esac
49
51
  top="$(git rev-parse --show-toplevel)"
@@ -71,6 +73,31 @@ exit "$status"
71
73
  `;
72
74
  }
73
75
 
76
+ /** A folder as the marker line spells it: `%` and `]` are escaped, so a name that holds a bracket cannot end the field. */
77
+ private static encode(opts: { folder: string }): string {
78
+ return opts.folder.replaceAll('%', '%25').replaceAll(']', '%5D');
79
+ }
80
+
81
+ private static decode(opts: { field: string }): string {
82
+ return opts.field.replaceAll('%5D', ']').replaceAll('%25', '%');
83
+ }
84
+
85
+ /** The project folder inside the repository, without the trailing slash; empty for the top level. */
86
+ private static folderOf(opts: { prefix: string }): string {
87
+ return opts.prefix.replace(/\/$/, '');
88
+ }
89
+
90
+ /**
91
+ * The project folder a hook of ours was written for (empty: the repository's top level), or `undefined` when
92
+ * the file is not ours. A hook of an earlier release carries no folder and is the top level's: it is the only
93
+ * kind there was, and a project below the top level that wrote one is not told apart from it.
94
+ */
95
+ static ownerOf(opts: { text: string }): string | undefined {
96
+ const matched = OWNER.exec(opts.text.split('\n')[1] ?? '');
97
+
98
+ return matched === null ? undefined : CommitHook.decode({ field: matched[1] ?? '' });
99
+ }
100
+
74
101
  private static quote(opts: { text: string }): string {
75
102
  return `'${opts.text.replaceAll("'", "'\\''")}'`;
76
103
  }
@@ -92,7 +119,11 @@ exit "$status"
92
119
  const hooksPath = git({ root: opts.root, args: ['config', '--get', 'core.hooksPath'] });
93
120
  const entry = lstatSync(path, { throwIfNoEntry: false });
94
121
  const text = entry?.isFile() === true ? readFileSync(path, 'utf8') : undefined;
95
- const isOurs = hooksPath === undefined && text?.split('\n')[1]?.startsWith(MARKER) === true;
122
+ const folder = CommitHook.folderOf({ prefix });
123
+ const owner = text === undefined ? undefined : CommitHook.ownerOf({ text });
124
+ // Ours is a hook this project wrote. One another project of the repository wrote is neither removed nor replaced.
125
+ const isOurs = hooksPath === undefined && owner === folder;
126
+ const isOtherProjects = hooksPath === undefined && owner !== undefined && owner !== folder;
96
127
 
97
128
  if (!isWanted) {
98
129
  return { state: isOurs ? CommitHookStates.LEFTOVER : CommitHookStates.OFF, path };
@@ -122,6 +153,14 @@ exit "$status"
122
153
  };
123
154
  }
124
155
 
156
+ if (isOtherProjects) {
157
+ return {
158
+ state: CommitHookStates.OTHER_PROJECT,
159
+ path,
160
+ note: `the hook belongs to ${owner === '' ? 'the project at the top of the repository' : `the project in ${owner}`}, not touched: a repository has one ${HOOK_NAME} hook`,
161
+ };
162
+ }
163
+
125
164
  if (isOurs) {
126
165
  const isCurrent = text === CommitHook.template({ prefix }) && (entry.mode & 0o111) !== 0;
127
166
 
@@ -164,7 +203,8 @@ export class CommitHookPlan {
164
203
  return [{ path, status: SyncStatuses.UNCHANGED, apply: () => {} }];
165
204
  }
166
205
 
167
- case CommitHookStates.UNWIRED: {
206
+ case CommitHookStates.UNWIRED:
207
+ case CommitHookStates.OTHER_PROJECT: {
168
208
  return [{ path, status: SyncStatuses.SKIPPED, note: status.note, apply: () => {} }];
169
209
  }
170
210
 
@@ -1,3 +1,6 @@
1
+ import { EnvVariables } from './env-variables.ts';
2
+
3
+ /** The names of the `vulcan` subcommands, shared by the router, the command registry and the help output. */
1
4
  export class VulcanCommands {
2
5
  static readonly INIT = 'init';
3
6
  static readonly ADD = 'add';
@@ -23,7 +26,7 @@ export class UpgradeFlags {
23
26
  static readonly STABLE = '--stable';
24
27
  static readonly NIGHTLY = '--nightly';
25
28
  /** Tests only: a JSON object of dist-tags that stands in for the registry read. */
26
- static readonly DIST_TAGS_ENV = 'VULCAN_DIST_TAGS';
29
+ static readonly DIST_TAGS_ENV = EnvVariables.VULCAN_DIST_TAGS;
27
30
  }
28
31
 
29
32
  export class ExitCodes {
@@ -49,8 +52,8 @@ export class ProjectLayout {
49
52
  static readonly VULCAN_COMMAND = 'bun x --no-install vulcan';
50
53
 
51
54
  /** `vulcan x` hands the resolved project config to the tool in these variables; the tools read nothing else. */
52
- static readonly CONFIG_ENV = 'VULCAN_CONFIG';
53
- static readonly ROOT_ENV = 'VULCAN_PROJECT_ROOT';
55
+ static readonly CONFIG_ENV = EnvVariables.VULCAN_CONFIG;
56
+ static readonly ROOT_ENV = EnvVariables.VULCAN_PROJECT_ROOT;
54
57
  /** `-include`: a fresh clone runs `make install` before node_modules exists. */
55
58
  static readonly MAKE_INCLUDE_LINE = '-include node_modules/@venizia/vulcan/base/make/vulcan.mk';
56
59
  static readonly STYLE_PACKAGE = '@venizia/dev-configs';
@@ -0,0 +1,37 @@
1
+ /** The `VULCAN_` and `CLAUDE_` environment variables (and `CLAUDECODE`) the cli reads; it reads others, such as `HOME` and `TMPDIR`, that are not its own. The test of this class keeps the list complete, and the generated reference is to read the comment above each name. */
2
+ export class EnvVariables {
3
+ /** The name of the writer of an event line; it wins over the name Claude Code gave the session. */
4
+ static readonly VULCAN_ACTOR = 'VULCAN_ACTOR';
5
+ /** `off` turns the daily automatic clean of `.agents/local/` off for the shell. */
6
+ static readonly VULCAN_AUTO_CLEAN = 'VULCAN_AUTO_CLEAN';
7
+ /** `off` takes the session out of the owner reply shape; `vulcan doctor` notes it when the shell has it. */
8
+ static readonly VULCAN_OWNER_REPLY = 'VULCAN_OWNER_REPLY';
9
+ /** `off` switches the guard hooks off for one session. */
10
+ static readonly VULCAN_GUARDS = 'VULCAN_GUARDS';
11
+ /** `1` makes `init`, `add` and `upgrade` print the install, `git init`, `sync` and the checks as skipped; for tests. */
12
+ static readonly VULCAN_NO_INSTALL = 'VULCAN_NO_INSTALL';
13
+ /** Set by `vulcan x` for okf and atlas: the resolved project config as JSON. */
14
+ static readonly VULCAN_CONFIG = 'VULCAN_CONFIG';
15
+ /** Set by `vulcan x` for atlas: the manifest, rendered fresh from the config on each run. */
16
+ static readonly VULCAN_MANIFEST = 'VULCAN_MANIFEST';
17
+ /** Set by `vulcan x` for okf and atlas: the project root. */
18
+ static readonly VULCAN_PROJECT_ROOT = 'VULCAN_PROJECT_ROOT';
19
+ /** Replaces the `bun` that `init` and `add` run; for tests. */
20
+ static readonly VULCAN_BUN = 'VULCAN_BUN';
21
+ /** Replaces the `git` that `init` and `add` run; for tests. */
22
+ static readonly VULCAN_GIT = 'VULCAN_GIT';
23
+ /** The dist-tags of `@venizia/vulcan` as JSON, in place of the registry read of `upgrade --nightly`; for tests. */
24
+ static readonly VULCAN_DIST_TAGS = 'VULCAN_DIST_TAGS';
25
+ /** The project root, set by Claude Code for its hooks and by the guard extension for the hooks it runs; without it the hooks use the working directory. */
26
+ static readonly CLAUDE_PROJECT_DIR = 'CLAUDE_PROJECT_DIR';
27
+ /** Where Claude Code puts its task output; the launch file points it at `.agents/local/tmp`, and `vulcan doctor` warns when it points elsewhere. */
28
+ static readonly CLAUDE_CODE_TMPDIR = 'CLAUDE_CODE_TMPDIR';
29
+ /** The file Claude Code hands a start hook to export variables from; the session-start hook appends `export TMPDIR=...` to it. */
30
+ static readonly CLAUDE_ENV_FILE = 'CLAUDE_ENV_FILE';
31
+ /** The id of the running Claude Code session, used to find the session's name for the event actor. */
32
+ static readonly CLAUDE_CODE_SESSION_ID = 'CLAUDE_CODE_SESSION_ID';
33
+ /** The folder whose `sessions/*.json` names the sessions (default `~/.claude`), read to find the session's name. */
34
+ static readonly CLAUDE_CONFIG_DIR = 'CLAUDE_CONFIG_DIR';
35
+ /** Set by Claude Code in the shell of a session it starts; `vulcan doctor` uses it to know it runs inside one. */
36
+ static readonly CLAUDECODE = 'CLAUDECODE';
37
+ }
@@ -1,4 +1,5 @@
1
1
  export * from './constants.ts';
2
+ export * from './env-variables.ts';
2
3
  export * from './paths.ts';
3
4
  export * from './types.ts';
4
5
  export * from './json.ts';
@@ -12,7 +12,29 @@ type TLoadResult =
12
12
  const describeError = (opts: { error: unknown }): string =>
13
13
  opts.error instanceof Error ? opts.error.message : String(opts.error);
14
14
 
15
+ /** Finds and loads the project `vulcan.config.*` file and reports an unreadable one; used by `vulcan sync`, `vulcan doctor` and the session hooks. */
15
16
  export class ConfigLoader {
17
+ /**
18
+ * What a hook says when the project has a config this VULCAN could not read (a key from a newer release, a
19
+ * failed import) and it falls back to defaults: the first problem and the way out. `undefined` when the config
20
+ * was read, or when the project has none (nothing was ignored).
21
+ */
22
+ static unreadableNote(opts: { loaded: TLoadResult }): string | undefined {
23
+ const { loaded } = opts;
24
+
25
+ if (loaded.ok || loaded.file === undefined) {
26
+ return undefined;
27
+ }
28
+
29
+ // A schema error is "<file>: invalid config" and then one line per issue: the first issue says more than the
30
+ // head. Any other failure (an import that threw, no default export) is told by its head line, whatever follows.
31
+ const [head = '', first = ''] = loaded.error.split('\n');
32
+ const problem =
33
+ head.endsWith('invalid config') && first.trim() !== '' ? first.trim() : head.trim();
34
+
35
+ return `the project config could not be read by this VULCAN, so its defaults apply (${problem}). Run \`vulcan doctor\`; a config newer than this VULCAN needs \`vulcan upgrade\``;
36
+ }
37
+
16
38
  /** `.configs/vulcan.config.mts` when the project has one. */
17
39
  static findFile(opts: { root: string }): string | undefined {
18
40
  const file = join(opts.root, ConfigConstants.DIRECTORY, ConfigConstants.FILE);