@venizia/vulcan 0.4.9-3 → 0.4.9-5

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 (61) hide show
  1. package/base/ci-global.json +13 -0
  2. package/base/claude/commit-attribution.json +7 -0
  3. package/base/claude/events.json +60 -0
  4. package/base/commit-agents.json +41 -0
  5. package/base/hooks/event.ts +37 -0
  6. package/base/rules.md +1 -1
  7. package/base/templates/ci/github-actions.yml +75 -0
  8. package/base/templates/ci/gitlab-ci.yml +52 -0
  9. package/package.json +3 -3
  10. package/src/ci/affected.ts +176 -0
  11. package/src/ci/command.ts +166 -0
  12. package/src/ci/common/constants.ts +76 -0
  13. package/src/ci/common/index.ts +2 -0
  14. package/src/ci/common/types.ts +37 -0
  15. package/src/ci/git.ts +72 -0
  16. package/src/ci/global.ts +48 -0
  17. package/src/ci/graph.ts +43 -0
  18. package/src/ci/index.ts +7 -0
  19. package/src/ci/workspace.ts +119 -0
  20. package/src/commands/ci.command.ts +4 -0
  21. package/src/commands/clean.command.ts +3 -5
  22. package/src/commands/commit-check.command.ts +5 -0
  23. package/src/commands/event.command.ts +5 -0
  24. package/src/commands/help.command.ts +14 -2
  25. package/src/commands/index.ts +28 -27
  26. package/src/commands/sync.command.ts +2 -0
  27. package/src/commit/agents.ts +32 -0
  28. package/src/commit/check.ts +160 -0
  29. package/src/commit/common/constants.ts +28 -0
  30. package/src/commit/common/index.ts +2 -0
  31. package/src/commit/common/types.ts +57 -0
  32. package/src/commit/hook.ts +187 -0
  33. package/src/commit/index.ts +8 -0
  34. package/src/commit/message.ts +74 -0
  35. package/src/commit/policy.ts +110 -0
  36. package/src/commit/signature.ts +94 -0
  37. package/src/commit/subject.ts +40 -0
  38. package/src/common/constants.ts +13 -0
  39. package/src/config/common/constants.ts +1 -0
  40. package/src/config/schema.ts +102 -0
  41. package/src/doctor/checks.ts +129 -7
  42. package/src/doctor/common/constants.ts +2 -0
  43. package/src/doctor/runner.ts +3 -0
  44. package/src/events/actor.ts +116 -0
  45. package/src/events/command.ts +191 -0
  46. package/src/events/common/constants.ts +118 -0
  47. package/src/events/common/index.ts +2 -0
  48. package/src/events/common/types.ts +39 -0
  49. package/src/events/flow.ts +92 -0
  50. package/src/events/hook.ts +163 -0
  51. package/src/events/index.ts +8 -0
  52. package/src/events/log.ts +162 -0
  53. package/src/events/settings.ts +80 -0
  54. package/src/events/text.ts +49 -0
  55. package/src/local/constants.ts +36 -1
  56. package/src/local/scan.ts +256 -27
  57. package/src/manifest/render.ts +42 -0
  58. package/src/router.ts +47 -7
  59. package/src/sync/common/constants.ts +3 -0
  60. package/src/sync/local-choice.ts +3 -3
  61. package/src/sync/planner.ts +20 -1
package/src/local/scan.ts CHANGED
@@ -8,6 +8,8 @@ import { CleanScopes, LocalConstants, LocalStates } from './constants.ts';
8
8
  export interface ILocalEntry {
9
9
  scope: string;
10
10
  name: string;
11
+ /** Where it is, relative to `.agents/local/`: `tmp/job-1`, or a bare name for a stray folder. */
12
+ where: string;
11
13
  path: string;
12
14
  bytes: number;
13
15
  ageMs: number;
@@ -77,6 +79,140 @@ const git = (opts: { cwd: string; args: string[] }): string | undefined => {
77
79
  return result.status === 0 ? result.stdout : undefined;
78
80
  };
79
81
 
82
+ /** Whether a release version has a tag in the repository: `v<version>` or `<version>`. */
83
+ class ReleaseTags {
84
+ /** Whether `name` is a version (`LocalConstants.RELEASE_VERSION`); any other name is no candidate and never matched against a tag. */
85
+ static isVersion(opts: { name: string }): boolean {
86
+ return LocalConstants.RELEASE_VERSION.test(opts.name);
87
+ }
88
+
89
+ static isTagged(opts: { root: string; version: string }): boolean {
90
+ const bare = opts.version.replace(/^v/, '');
91
+
92
+ return [`v${bare}`, bare].some(
93
+ (tag) =>
94
+ git({ cwd: opts.root, args: ['show-ref', '--verify', '--quiet', `refs/tags/${tag}`] }) !==
95
+ undefined,
96
+ );
97
+ }
98
+ }
99
+
100
+ /** What the history of a branch says about its own work. */
101
+ class BranchHistory {
102
+ /**
103
+ * Whether anything was ever committed on the branch: `false` when its reflog holds only its creation (a new
104
+ * branch has the commit of the branch it came from, which is why `--merged` calls it merged), `undefined`
105
+ * when there is no reflog to read (the branch is then judged by `--merged` alone).
106
+ */
107
+ static hasOwnCommits(opts: { root: string; branch: string }): boolean | undefined {
108
+ const log = git({
109
+ cwd: opts.root,
110
+ args: ['reflog', 'show', '--format=%gs', `refs/heads/${opts.branch}`, '--'],
111
+ });
112
+ const entries = (log ?? '').split('\n').filter((line) => line.trim() !== '');
113
+
114
+ return entries.length === 0
115
+ ? undefined
116
+ : entries.some((line) => !line.startsWith('branch: Created from'));
117
+ }
118
+ }
119
+
120
+ /** A directory that is really one: not a link, not a file. */
121
+ const isRealDirectory = (opts: { path: string }): boolean => {
122
+ try {
123
+ const stat = lstatSync(opts.path);
124
+
125
+ return stat.isDirectory() && !stat.isSymbolicLink();
126
+ } catch {
127
+ return false;
128
+ }
129
+ };
130
+
131
+ /** Whether a path is something a build or an install makes again, judged by the names in it. */
132
+ const isRebuildable = (opts: { path: string }): boolean => {
133
+ const parts = opts.path.replace(/\/$/, '').split('/');
134
+
135
+ return (
136
+ parts.some((part) => LocalConstants.REBUILDABLE_DIRECTORIES.includes(part)) ||
137
+ LocalConstants.REBUILDABLE_SUFFIXES.some((suffix) => (parts.at(-1) ?? '').endsWith(suffix))
138
+ );
139
+ };
140
+
141
+ /**
142
+ * The files under an ignored directory that are not rebuildable. git lists a directory whose every file is ignored
143
+ * as one entry (`packages/`), so it is walked here, and a rebuildable folder (`node_modules`) is not entered. A
144
+ * link is a file and is not followed. A directory too large to walk is reported whole.
145
+ */
146
+ const walkIgnored = (opts: {
147
+ real: string;
148
+ directory: string;
149
+ budget: { left: number };
150
+ }): string[] => {
151
+ const found: string[] = [];
152
+ let names: string[];
153
+
154
+ try {
155
+ names = readdirSync(join(opts.real, opts.directory));
156
+ } catch {
157
+ return [opts.directory];
158
+ }
159
+
160
+ for (const name of names) {
161
+ const path = `${opts.directory}${name}`;
162
+
163
+ opts.budget.left -= 1;
164
+
165
+ if (opts.budget.left < 0) {
166
+ return [opts.directory];
167
+ }
168
+
169
+ if (isRebuildable({ path })) {
170
+ continue;
171
+ }
172
+
173
+ if (isRealDirectory({ path: join(opts.real, path) })) {
174
+ found.push(...walkIgnored({ ...opts, directory: `${path}/` }));
175
+ } else {
176
+ found.push(path);
177
+ }
178
+ }
179
+
180
+ return found;
181
+ };
182
+
183
+ /** Ignored files a worktree holds that no build or install makes again: `.env`, a local database, a key. */
184
+ const unrebuildableIgnored = (opts: { real: string }): string[] | undefined => {
185
+ const listed = git({
186
+ cwd: opts.real,
187
+ args: ['ls-files', '--others', '--ignored', '--exclude-standard', '--directory'],
188
+ });
189
+
190
+ if (listed === undefined) {
191
+ return undefined;
192
+ }
193
+
194
+ const budget = { left: LocalConstants.IGNORED_WALK_LIMIT };
195
+
196
+ // git can list a file and the directory that holds it both: each path is named once.
197
+ return [
198
+ ...new Set(
199
+ listed
200
+ .split('\n')
201
+ .filter((line) => line.trim() !== '' && !isRebuildable({ path: line }))
202
+ .flatMap((line) =>
203
+ line.endsWith('/') ? walkIgnored({ real: opts.real, directory: line, budget }) : [line],
204
+ ),
205
+ ),
206
+ ];
207
+ };
208
+
209
+ /** Where a merged branch may have gone: the checked-out branch of the root, then develop, then the default branch of origin. */
210
+ const MERGE_TARGETS = [
211
+ { label: 'the branch checked out at the project root', args: [] as string[] },
212
+ { label: 'origin/develop', args: ['origin/develop'] },
213
+ { label: 'the default branch of origin', args: ['origin/HEAD'] },
214
+ ];
215
+
80
216
  const classifyBranch = (opts: {
81
217
  root: string;
82
218
  real: string;
@@ -125,22 +261,32 @@ const classifyBranch = (opts: {
125
261
  };
126
262
  }
127
263
 
128
- const merged = git({
129
- cwd: opts.root,
130
- args: ['branch', '--format=%(refname:short)', '--merged'],
131
- });
132
-
133
- if (
134
- merged
264
+ // Merged into the branch checked out at the root, or into develop or the default branch of origin.
265
+ const target = MERGE_TARGETS.find((candidate) =>
266
+ git({
267
+ cwd: opts.root,
268
+ args: ['branch', '--format=%(refname:short)', '--merged', ...candidate.args],
269
+ })
135
270
  ?.split('\n')
136
271
  .map((line) => line.trim())
137
- .includes(branch)
138
- ) {
272
+ .includes(branch),
273
+ );
274
+
275
+ if (target !== undefined && BranchHistory.hasOwnCommits({ root: opts.root, branch }) === false) {
276
+ return {
277
+ state: LocalStates.UNMERGED,
278
+ removable: false,
279
+ registered: true,
280
+ note: `branch ${branch} has no commits of its own yet`,
281
+ };
282
+ }
283
+
284
+ if (target !== undefined) {
139
285
  return {
140
286
  state: LocalStates.MERGED,
141
287
  removable: true,
142
288
  registered: true,
143
- note: `branch ${branch} is merged into the branch checked out at the project root`,
289
+ note: `branch ${branch} is merged into ${target.label}`,
144
290
  };
145
291
  }
146
292
 
@@ -181,25 +327,34 @@ const classifyWorktree = (opts: {
181
327
  const untracked = git({ cwd: opts.real, args: ['ls-files', '--others', '--exclude-standard'] });
182
328
  const clean = tracked === 0 && untracked !== undefined && untracked.trim() === '';
183
329
 
184
- return clean
185
- ? verdict
186
- : {
187
- state: LocalStates.DIRTY,
188
- removable: false,
189
- registered: true,
190
- note: `${verdict.note}, but it has uncommitted or untracked files`,
191
- };
192
- };
330
+ if (!clean) {
331
+ return {
332
+ state: LocalStates.DIRTY,
333
+ removable: false,
334
+ registered: true,
335
+ note: `${verdict.note}, but it has uncommitted or untracked files`,
336
+ };
337
+ }
193
338
 
194
- /** A directory that is really one: not a link, not a file. */
195
- const isRealDirectory = (opts: { path: string }): boolean => {
196
- try {
197
- const stat = lstatSync(opts.path);
339
+ // `git worktree remove --force` deletes ignored files too: a `.env` or a local database would go with it.
340
+ const ignored = unrebuildableIgnored({ real: opts.real });
198
341
 
199
- return stat.isDirectory() && !stat.isSymbolicLink();
200
- } catch {
201
- return false;
342
+ if (ignored === undefined || ignored.length > 0) {
343
+ const shown = (ignored ?? []).slice(0, LocalConstants.NOTE_FILES).join(', ');
344
+ const more = Math.max(0, (ignored ?? []).length - LocalConstants.NOTE_FILES);
345
+
346
+ return {
347
+ state: LocalStates.DIRTY,
348
+ removable: false,
349
+ registered: true,
350
+ note:
351
+ ignored === undefined
352
+ ? `${verdict.note}, but git could not list its ignored files`
353
+ : `${verdict.note}, but it holds ignored files that are not rebuildable: ${shown}${more > 0 ? ` and ${more} more` : ''}`,
354
+ };
202
355
  }
356
+
357
+ return verdict;
203
358
  };
204
359
 
205
360
  export class LocalScan {
@@ -302,6 +457,25 @@ export class LocalScan {
302
457
  });
303
458
 
304
459
  ({ state, removable, registered: isRegistered, note } = verdict);
460
+ } else if (layout.name === CleanScopes.RELEASE_CANDIDATES) {
461
+ // A candidate is named by its version: once that version is tagged the release has shipped.
462
+ const isShipped =
463
+ ReleaseTags.isVersion({ name }) &&
464
+ ReleaseTags.isTagged({ root: opts.root, version: name });
465
+
466
+ ({ state, removable, note } = isShipped
467
+ ? {
468
+ state: LocalStates.SHIPPED,
469
+ removable: true,
470
+ note: `version ${name} is tagged: the release shipped`,
471
+ }
472
+ : {
473
+ state: LocalStates.OK,
474
+ removable: false,
475
+ note: ReleaseTags.isVersion({ name })
476
+ ? `version ${name} is not tagged yet`
477
+ : `${name} is not a version (1.2.3, v1.2.3 or 1.2.3-rc.1): kept`,
478
+ });
305
479
  } else if (staleAfter !== undefined && ageMs > staleAfter) {
306
480
  state = LocalStates.STALE;
307
481
  }
@@ -309,6 +483,7 @@ export class LocalScan {
309
483
  entries.push({
310
484
  scope: layout.name,
311
485
  name,
486
+ where: `${layout.name}/${name}`,
312
487
  path,
313
488
  bytes: sizeOf({ path }),
314
489
  ageMs,
@@ -329,6 +504,7 @@ export class LocalScan {
329
504
  entries.push({
330
505
  scope: CleanScopes.PROFILE,
331
506
  name: 'profile.json',
507
+ where: 'profile.json',
332
508
  path: profile,
333
509
  bytes: stat.size,
334
510
  ageMs: now - stat.mtimeMs,
@@ -340,7 +516,60 @@ export class LocalScan {
340
516
  });
341
517
  }
342
518
 
343
- return entries;
519
+ return [...entries, ...LocalScan.strays({ local, now })];
520
+ }
521
+
522
+ /**
523
+ * Scratch folders a browser left directly under `.agents/local/` (its temp folder, when that was the short
524
+ * one): scope `tmp`, removable once they are old enough not to belong to a browser that is running.
525
+ */
526
+ private static strays(opts: { local: string; now: number }): ILocalEntry[] {
527
+ return readdirSync(opts.local)
528
+ .filter((name) => LocalConstants.STRAY_TEMP.some((pattern) => pattern.test(name)))
529
+ .map((name) => {
530
+ const path = join(opts.local, name);
531
+ const stat = lstatSync(path);
532
+ const ageMs = opts.now - newestModifiedAt({ path });
533
+ const isOld = ageMs > LocalConstants.STRAY_MIN_AGE_MS;
534
+
535
+ return {
536
+ scope: CleanScopes.TMP,
537
+ name,
538
+ where: name,
539
+ path,
540
+ bytes: sizeOf({ path }),
541
+ ageMs,
542
+ state: isOld ? LocalStates.STALE : LocalStates.OK,
543
+ removable: isOld,
544
+ isSymlink: stat.isSymbolicLink(),
545
+ registered: false,
546
+ note: isOld ? 'a browser left it' : 'younger than an hour: a browser may be using it',
547
+ };
548
+ });
549
+ }
550
+
551
+ /**
552
+ * What sits directly under `.agents/local/` and is neither a folder of the layout, a file VULCAN writes, nor
553
+ * a browser's scratch folder: nobody removes it, `doctor` names it.
554
+ */
555
+ static unknown(opts: { root: string }): { name: string; bytes: number }[] {
556
+ const local = LocalScan.localRootOf({ root: opts.root });
557
+
558
+ if (local === undefined) {
559
+ return [];
560
+ }
561
+
562
+ const known = new Set<string>(ProjectLayout.LOCAL_LAYOUT.map((entry) => entry.name));
563
+
564
+ return readdirSync(local)
565
+ .filter(
566
+ (name) =>
567
+ !known.has(name) &&
568
+ !LocalConstants.KNOWN_FILES.has(name) &&
569
+ !LocalConstants.STRAY_TEMP.some((pattern) => pattern.test(name)),
570
+ )
571
+ .sort()
572
+ .map((name) => ({ name, bytes: sizeOf({ path: join(local, name) }) }));
344
573
  }
345
574
 
346
575
  /**
@@ -1,6 +1,7 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { basename, join } from 'node:path';
3
3
  import { BunFormatter } from '../common/index.ts';
4
+ import { AgentSignaturePolicies } from '../commit/common/index.ts';
4
5
  import { ProjectPackages } from '../config/index.ts';
5
6
  import type { TResolvedConfig } from '../config/index.ts';
6
7
  import { BaseRules } from '../rules/index.ts';
@@ -47,6 +48,42 @@ const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<strin
47
48
  return Object.keys(block).length === 0 ? {} : { guard: block };
48
49
  };
49
50
 
51
+ const commitBlockOf = (opts: { config: TResolvedConfig }): { commit?: Record<string, unknown> } => {
52
+ const { agent, subject } = opts.config.commit.message;
53
+ const isDenied = agent.signature === AgentSignaturePolicies.DENY;
54
+
55
+ if (!isDenied && subject === undefined) {
56
+ return {};
57
+ }
58
+
59
+ return {
60
+ commit: {
61
+ message: {
62
+ agent: {
63
+ signature: agent.signature,
64
+ ...(isDenied && agent.names.length > 0 ? { names: agent.names } : {}),
65
+ ...(isDenied && agent.allow.length > 0 ? { allow: agent.allow } : {}),
66
+ },
67
+ ...(subject === undefined ? {} : { subject }),
68
+ },
69
+ },
70
+ };
71
+ };
72
+
73
+ /** The manifest's `ci` block, which `vulcan ci affected` reads: only the globs the project adds. */
74
+ const ciBlockOf = (opts: { config: TResolvedConfig }): { ci?: Record<string, unknown> } => {
75
+ const { global } = opts.config.ci.affected;
76
+
77
+ return global.length === 0 ? {} : { ci: { affected: { global } } };
78
+ };
79
+
80
+ /** The manifest's `events` block, which the hooks and `vulcan event` read: only when the log is on or has a folder. */
81
+ const eventsBlockOf = (opts: { config: TResolvedConfig }): { events?: Record<string, unknown> } => {
82
+ const { log, dir } = opts.config.events;
83
+
84
+ return log || dir !== undefined ? { events: { log, ...(dir === undefined ? {} : { dir }) } } : {};
85
+ };
86
+
50
87
  /** The manifest's `atlas` block: only what the config sets (keys listed, the download turned off). */
51
88
  const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<string, unknown> } => {
52
89
  const keys = opts.config.atlas.index?.keys ?? [];
@@ -140,6 +177,11 @@ export class ProjectManifest {
140
177
  ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
141
178
  // The colour `vulcan visualize` takes for its pages; a project without the key gets the neutral default.
142
179
  ...(config.theme === undefined ? {} : { theme: config.theme }),
180
+ ...commitBlockOf({ config }),
181
+ // The files the project adds to the ones that make every package affected; none added, nothing is written.
182
+ ...ciBlockOf({ config }),
183
+ // Whether the Claude Code hooks write the agent event log, and the folder it goes to.
184
+ ...eventsBlockOf({ config }),
143
185
  };
144
186
 
145
187
  return BunFormatter.format({
package/src/router.ts CHANGED
@@ -1,8 +1,10 @@
1
1
  import { AgentConstants } from './agents/index.ts';
2
- import { COMMAND_HANDLERS } from './commands/index.ts';
3
- import { runHelpCommand } from './commands/help.command.ts';
2
+ import { COMMAND_LOADERS } from './commands/index.ts';
3
+ import { CiFlags } from './ci/common/index.ts';
4
+ import { CommitCheckFlags } from './commit/common/index.ts';
4
5
  import { ExitCodes, UpgradeFlags, VulcanCommands } from './common/index.ts';
5
6
  import { CreateFlags } from './create/common/index.ts';
7
+ import { EventFlags } from './events/common/index.ts';
6
8
  import { PipedInputRefusal } from './ui/keyboard.ts';
7
9
 
8
10
  const HELP_ALIASES = new Set(['--help', '-h']);
@@ -10,6 +12,8 @@ const VERSION_ALIASES = new Set(['--version', '-v']);
10
12
 
11
13
  interface IAcceptedArgs {
12
14
  flags: string[];
15
+ /** The exit code for an argument the command does not take; `1` when absent. */
16
+ unknownExit?: number;
13
17
  /** Flags that take the next argument as their value. */
14
18
  values: string[];
15
19
  positionals: number;
@@ -66,12 +70,40 @@ const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
66
70
  '--reports',
67
71
  '--prototypes',
68
72
  '--profile',
73
+ '--events',
74
+ '--release-candidates',
69
75
  '--all',
70
76
  '--yes',
71
77
  ],
72
78
  values: [],
73
79
  positionals: 0,
74
80
  },
81
+ [VulcanCommands.COMMIT_CHECK]: {
82
+ flags: [],
83
+ unknownExit: ExitCodes.USAGE,
84
+ values: [CommitCheckFlags.RANGE, CommitCheckFlags.TEXT],
85
+ positionals: 2,
86
+ },
87
+ [VulcanCommands.CI]: {
88
+ flags: [CiFlags.JSON, CiFlags.NAMES],
89
+ unknownExit: ExitCodes.USAGE,
90
+ values: [CiFlags.BASE, CiFlags.HEAD, CiFlags.CHECK],
91
+ positionals: 2,
92
+ },
93
+ [VulcanCommands.EVENT]: {
94
+ flags: [EventFlags.JSON],
95
+ unknownExit: ExitCodes.USAGE,
96
+ values: [
97
+ EventFlags.KIND,
98
+ EventFlags.SUMMARY,
99
+ EventFlags.FLOW,
100
+ EventFlags.REF,
101
+ EventFlags.ACTOR,
102
+ EventFlags.DIR,
103
+ EventFlags.SINCE,
104
+ ],
105
+ positionals: 1,
106
+ },
75
107
  [VulcanCommands.DOCTOR]: { flags: [], values: [], positionals: 0 },
76
108
  [VulcanCommands.PROFILE]: { flags: ['--yes'], values: [], positionals: 1 },
77
109
  [VulcanCommands.VISUALIZE]: { flags: ['--schema'], values: ['--out'], positionals: 1 },
@@ -117,12 +149,18 @@ const findUnknownArg = (opts: { args: string[]; accepted: IAcceptedArgs }): stri
117
149
  return undefined;
118
150
  };
119
151
 
152
+ const runHelp = async (opts: { cwd: string }): Promise<number> => {
153
+ const help = await COMMAND_LOADERS[VulcanCommands.HELP]();
154
+
155
+ return help({ args: [], cwd: opts.cwd });
156
+ };
157
+
120
158
  export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<number> => {
121
159
  const [first, ...args] = opts.argv;
122
160
  const name = resolveCommandName({ first });
123
- const handler = COMMAND_HANDLERS[name];
161
+ const load = COMMAND_LOADERS[name];
124
162
 
125
- if (handler === undefined) {
163
+ if (load === undefined) {
126
164
  process.stderr.write(`vulcan: unknown command '${name}' - run 'bun x vulcan help'\n`);
127
165
 
128
166
  return ExitCodes.FAILURE;
@@ -130,14 +168,14 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
130
168
 
131
169
  // `x` hands its arguments to the tool, so only a help flag in the tool's place is vulcan's.
132
170
  if (name === VulcanCommands.X && HELP_ALIASES.has(args[0] ?? '')) {
133
- return runHelpCommand();
171
+ return runHelp({ cwd: opts.cwd });
134
172
  }
135
173
 
136
174
  const accepted = ACCEPTED_ARGS[name];
137
175
 
138
176
  if (accepted !== undefined) {
139
177
  if (args.some((arg) => HELP_ALIASES.has(arg))) {
140
- return runHelpCommand();
178
+ return runHelp({ cwd: opts.cwd });
141
179
  }
142
180
 
143
181
  const unknown = findUnknownArg({ args, accepted });
@@ -147,10 +185,12 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
147
185
  `vulcan ${name}: unknown argument '${unknown}' - run 'bun x vulcan help'\n`,
148
186
  );
149
187
 
150
- return ExitCodes.FAILURE;
188
+ return accepted.unknownExit ?? ExitCodes.FAILURE;
151
189
  }
152
190
  }
153
191
 
192
+ const handler = await load();
193
+
154
194
  try {
155
195
  const exitCode = await handler({ args, cwd: opts.cwd });
156
196
 
@@ -16,6 +16,9 @@ export class SyncConstants {
16
16
  static readonly SETTINGS_FILE = 'settings.json';
17
17
  /** The hook sync adds when the config sets `remoteHosts`; lives next to the shipped settings. */
18
18
  static readonly REMOTE_HOSTS_FILE = 'remote-hosts.json';
19
+ static readonly COMMIT_ATTRIBUTION_FILE = 'commit-attribution.json';
20
+ /** The hooks sync adds when the config sets `events.log`. */
21
+ static readonly EVENTS_FILE = 'events.json';
19
22
  /** What sync applied last time, so a later sync can take back what the project no longer asks for. */
20
23
  static readonly MANAGED_FILE = 'vulcan-managed.json';
21
24
  static readonly SKILLS_DIRECTORY = 'skills';
@@ -68,9 +68,9 @@ export class LocalPlan {
68
68
  */
69
69
  static planWorkspace(opts: { root: string }): ISyncAction[] {
70
70
  const directory = join(opts.root, ProjectLayout.LOCAL_DIRECTORY);
71
- const missing = ProjectLayout.LOCAL_LAYOUT.map((entry) => entry.name).filter(
72
- (name) => !existsSync(join(directory, name)),
73
- );
71
+ const missing = ProjectLayout.LOCAL_LAYOUT.filter((entry) => !('onDemand' in entry))
72
+ .map((entry) => entry.name)
73
+ .filter((name) => !existsSync(join(directory, name)));
74
74
 
75
75
  return [
76
76
  ...planIgnoreLine({ root: opts.root, line: `${ProjectLayout.LOCAL_DIRECTORY}/` }),
@@ -11,6 +11,7 @@ import {
11
11
  import { basename, dirname, join, resolve } from 'node:path';
12
12
  import { AgentTable } from '../agents/index.ts';
13
13
  import { BASE_DIRECTORY, BaseDirectory } from '../common/index.ts';
14
+ import { AgentSignaturePolicies } from '../commit/common/index.ts';
14
15
  import { CodingAgents } from '../config/index.ts';
15
16
  import type { TResolvedConfig } from '../config/index.ts';
16
17
  import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
@@ -63,7 +64,7 @@ const readSettingsFile = (opts: { path: string }): TSettings | undefined => {
63
64
  }
64
65
  };
65
66
 
66
- /** Shipped settings, the chosen slot options, the project's hooks and `claude.settings` - what sync owns. */
67
+ /** Shipped settings, the chosen slot options, the empty attribution of a project that denies agent signatures, the event log hooks, the project's hooks and `claude.settings` - what sync owns. */
67
68
  const buildManagedOverlay = (opts: { config: TResolvedConfig }): TSettings => {
68
69
  let overlay: TSettings = JSON.parse(
69
70
  readFileSync(join(BASE_DIRECTORY, 'claude', SyncConstants.SETTINGS_FILE), 'utf8'),
@@ -87,6 +88,24 @@ const buildManagedOverlay = (opts: { config: TResolvedConfig }): TSettings => {
87
88
  });
88
89
  }
89
90
 
91
+ if (opts.config.commit.message.agent.signature === AgentSignaturePolicies.DENY) {
92
+ overlay = ProjectSettings.merge({
93
+ base: overlay,
94
+ overlay: JSON.parse(
95
+ readFileSync(join(BASE_DIRECTORY, 'claude', SyncConstants.COMMIT_ATTRIBUTION_FILE), 'utf8'),
96
+ ),
97
+ });
98
+ }
99
+
100
+ if (opts.config.events.log) {
101
+ overlay = ProjectSettings.merge({
102
+ base: overlay,
103
+ overlay: JSON.parse(
104
+ readFileSync(join(BASE_DIRECTORY, 'claude', SyncConstants.EVENTS_FILE), 'utf8'),
105
+ ),
106
+ });
107
+ }
108
+
90
109
  overlay = ProjectSettings.merge({
91
110
  base: overlay,
92
111
  overlay: ProjectSettings.buildHook({ hooks: opts.config.hooks }),