@venizia/vulcan 0.4.9-4 → 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 (46) hide show
  1. package/base/ci-global.json +13 -0
  2. package/base/claude/events.json +60 -0
  3. package/base/hooks/event.ts +37 -0
  4. package/base/rules.md +1 -1
  5. package/base/templates/ci/github-actions.yml +75 -0
  6. package/base/templates/ci/gitlab-ci.yml +52 -0
  7. package/package.json +3 -3
  8. package/src/ci/affected.ts +176 -0
  9. package/src/ci/command.ts +166 -0
  10. package/src/ci/common/constants.ts +76 -0
  11. package/src/ci/common/index.ts +2 -0
  12. package/src/ci/common/types.ts +37 -0
  13. package/src/ci/git.ts +72 -0
  14. package/src/ci/global.ts +48 -0
  15. package/src/ci/graph.ts +43 -0
  16. package/src/ci/index.ts +7 -0
  17. package/src/ci/workspace.ts +119 -0
  18. package/src/commands/ci.command.ts +4 -0
  19. package/src/commands/clean.command.ts +3 -5
  20. package/src/commands/event.command.ts +5 -0
  21. package/src/commands/help.command.ts +10 -2
  22. package/src/commands/index.ts +3 -0
  23. package/src/common/constants.ts +10 -0
  24. package/src/config/common/constants.ts +1 -0
  25. package/src/config/schema.ts +49 -0
  26. package/src/doctor/checks.ts +81 -7
  27. package/src/doctor/common/constants.ts +1 -0
  28. package/src/doctor/runner.ts +2 -0
  29. package/src/events/actor.ts +116 -0
  30. package/src/events/command.ts +191 -0
  31. package/src/events/common/constants.ts +118 -0
  32. package/src/events/common/index.ts +2 -0
  33. package/src/events/common/types.ts +39 -0
  34. package/src/events/flow.ts +92 -0
  35. package/src/events/hook.ts +163 -0
  36. package/src/events/index.ts +8 -0
  37. package/src/events/log.ts +162 -0
  38. package/src/events/settings.ts +80 -0
  39. package/src/events/text.ts +49 -0
  40. package/src/local/constants.ts +36 -1
  41. package/src/local/scan.ts +256 -27
  42. package/src/manifest/render.ts +18 -0
  43. package/src/router.ts +24 -0
  44. package/src/sync/common/constants.ts +2 -0
  45. package/src/sync/local-choice.ts +3 -3
  46. package/src/sync/planner.ts +10 -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
  /**
@@ -70,6 +70,20 @@ const commitBlockOf = (opts: { config: TResolvedConfig }): { commit?: Record<str
70
70
  };
71
71
  };
72
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
+
73
87
  /** The manifest's `atlas` block: only what the config sets (keys listed, the download turned off). */
74
88
  const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<string, unknown> } => {
75
89
  const keys = opts.config.atlas.index?.keys ?? [];
@@ -164,6 +178,10 @@ export class ProjectManifest {
164
178
  // The colour `vulcan visualize` takes for its pages; a project without the key gets the neutral default.
165
179
  ...(config.theme === undefined ? {} : { theme: config.theme }),
166
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 }),
167
185
  };
168
186
 
169
187
  return BunFormatter.format({
package/src/router.ts CHANGED
@@ -1,8 +1,10 @@
1
1
  import { AgentConstants } from './agents/index.ts';
2
2
  import { COMMAND_LOADERS } from './commands/index.ts';
3
+ import { CiFlags } from './ci/common/index.ts';
3
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']);
@@ -68,6 +70,8 @@ const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
68
70
  '--reports',
69
71
  '--prototypes',
70
72
  '--profile',
73
+ '--events',
74
+ '--release-candidates',
71
75
  '--all',
72
76
  '--yes',
73
77
  ],
@@ -80,6 +84,26 @@ const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
80
84
  values: [CommitCheckFlags.RANGE, CommitCheckFlags.TEXT],
81
85
  positionals: 2,
82
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
+ },
83
107
  [VulcanCommands.DOCTOR]: { flags: [], values: [], positionals: 0 },
84
108
  [VulcanCommands.PROFILE]: { flags: ['--yes'], values: [], positionals: 1 },
85
109
  [VulcanCommands.VISUALIZE]: { flags: ['--schema'], values: ['--out'], positionals: 1 },
@@ -17,6 +17,8 @@ export class SyncConstants {
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
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';
20
22
  /** What sync applied last time, so a later sync can take back what the project no longer asks for. */
21
23
  static readonly MANAGED_FILE = 'vulcan-managed.json';
22
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}/` }),
@@ -64,7 +64,7 @@ const readSettingsFile = (opts: { path: string }): TSettings | undefined => {
64
64
  }
65
65
  };
66
66
 
67
- /** Shipped settings, the chosen slot options, the empty attribution of a project that denies agent signatures, 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. */
68
68
  const buildManagedOverlay = (opts: { config: TResolvedConfig }): TSettings => {
69
69
  let overlay: TSettings = JSON.parse(
70
70
  readFileSync(join(BASE_DIRECTORY, 'claude', SyncConstants.SETTINGS_FILE), 'utf8'),
@@ -97,6 +97,15 @@ const buildManagedOverlay = (opts: { config: TResolvedConfig }): TSettings => {
97
97
  });
98
98
  }
99
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
+
100
109
  overlay = ProjectSettings.merge({
101
110
  base: overlay,
102
111
  overlay: ProjectSettings.buildHook({ hooks: opts.config.hooks }),