@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
@@ -0,0 +1,94 @@
1
+ import type { ICommentStyle, ICommitAgents, ISignatureHit } from './common/index.ts';
2
+ import { CommitMessage } from './message.ts';
3
+
4
+ /** Any `*-by:` trailer: Co-authored-by, Signed-off-by, Co-developed-by, Assisted-by, Reviewed-by. */
5
+ const TRAILER = /^\s*[A-Za-z][A-Za-z-]*-by\s*:\s*(.*)$/i;
6
+ const ADDRESS = /<([^>]+)>/;
7
+ /** `noreply`, `no-reply`, `no_reply`, or GitHub's `<id>+noreply`: the local part of an address no person reads. */
8
+ const NOREPLY_LOCAL = /^(?:\d+\+)?no[-_]?reply$/i;
9
+ const LEADING_PICTOGRAPH = /^\s*(?:\p{Extended_Pictographic}\s*)?/u;
10
+ /** Markup between "Generated with" and the name: `[`, `**`, a backtick, a space. */
11
+ const MARKUP = /^[\s[\]*_`(]+/;
12
+
13
+ export class AgentSignature {
14
+ static find(opts: {
15
+ message: string;
16
+ agents: ICommitAgents;
17
+ comment?: ICommentStyle;
18
+ }): ISignatureHit[] {
19
+ return CommitMessage.linesOf({ message: opts.message, comment: opts.comment }).flatMap(
20
+ (raw, index) => {
21
+ const text = CommitMessage.cleanOf({ text: raw });
22
+
23
+ if (CommitMessage.isComment({ line: text, comment: opts.comment })) {
24
+ return [];
25
+ }
26
+
27
+ const isSigned =
28
+ AgentSignature.isSigningTrailer({ text, agents: opts.agents }) ||
29
+ AgentSignature.isGeneratedLine({ text, agents: opts.agents });
30
+
31
+ return isSigned ? [{ line: index + 1, text: raw.trim() }] : [];
32
+ },
33
+ );
34
+ }
35
+
36
+ /** A name on the allow list clears a trailer only when it is the whole name and the address is not an agent's. */
37
+ private static isSigningTrailer(opts: { text: string; agents: ICommitAgents }): boolean {
38
+ const value = TRAILER.exec(opts.text)?.[1];
39
+
40
+ if (value === undefined) {
41
+ return false;
42
+ }
43
+
44
+ const address = ADDRESS.exec(value)?.[1] ?? '';
45
+ const display = value.replace(ADDRESS, ' ');
46
+ const isAgentAddress = AgentSignature.isAgentAddress({ address, agents: opts.agents });
47
+ const name = CommitMessage.compactOf({ text: display });
48
+ const isAllowed =
49
+ !isAgentAddress &&
50
+ opts.agents.allow.some((allowed) => CommitMessage.compactOf({ text: allowed }) === name);
51
+
52
+ return (
53
+ !isAllowed &&
54
+ (isAgentAddress ||
55
+ CommitMessage.beginsWithForm({ text: display, forms: opts.agents.products }))
56
+ );
57
+ }
58
+
59
+ /** `noreply` at a vendor's domain, or a local part that names an agent at a domain an agent uses. */
60
+ private static isAgentAddress(opts: { address: string; agents: ICommitAgents }): boolean {
61
+ const at = opts.address.lastIndexOf('@');
62
+
63
+ if (at === -1) {
64
+ return false;
65
+ }
66
+
67
+ const local = opts.address.slice(0, at);
68
+ const bare = local.replace(/^\d+\+/, '').toLowerCase();
69
+ const domain = opts.address.slice(at + 1).toLowerCase();
70
+ const isAt = (domains: string[]): boolean =>
71
+ domains.some((listed) => domain === listed || domain.endsWith(`.${listed}`));
72
+
73
+ return (
74
+ (NOREPLY_LOCAL.test(local) && isAt(opts.agents.noreplyDomains)) ||
75
+ (opts.agents.addressNames.some((name) => name.toLowerCase() === bare) &&
76
+ isAt(opts.agents.addressDomains))
77
+ );
78
+ }
79
+
80
+ /** At the start of a line, and only when an agent's name comes right after: "Generated by scripts/gen.ts from CLAUDE.md" is a note about a file. */
81
+ private static isGeneratedLine(opts: { text: string; agents: ICommitAgents }): boolean {
82
+ const body = opts.text.replace(LEADING_PICTOGRAPH, '').replace(MARKUP, '');
83
+ const lower = body.toLowerCase();
84
+ const phrase = opts.agents.generatedPhrases.find((listed) => lower.startsWith(listed));
85
+
86
+ return (
87
+ phrase !== undefined &&
88
+ CommitMessage.beginsWithForm({
89
+ text: body.slice(phrase.length).replace(MARKUP, ''),
90
+ forms: [...opts.agents.products, ...opts.agents.mentions],
91
+ })
92
+ );
93
+ }
94
+ }
@@ -0,0 +1,40 @@
1
+ import type { ICommentStyle, ICommitSubject, ISubjectProblem } from './common/index.ts';
2
+ import { CommitMessage } from './message.ts';
3
+
4
+ const GENERATED_SUBJECT = /^(?:Merge |Revert "|(?:fixup|squash|amend)! )/;
5
+
6
+ export class SubjectShape {
7
+ static problemOf(opts: {
8
+ message: string;
9
+ subject: ICommitSubject;
10
+ comment?: ICommentStyle;
11
+ }): ISubjectProblem | undefined {
12
+ const lines = CommitMessage.linesOf({ message: opts.message, comment: opts.comment });
13
+ const index = lines.findIndex(
14
+ (text) =>
15
+ text.trim() !== '' && !CommitMessage.isComment({ line: text, comment: opts.comment }),
16
+ );
17
+
18
+ if (index === -1) {
19
+ return undefined;
20
+ }
21
+
22
+ const text = lines[index].trim();
23
+
24
+ if (GENERATED_SUBJECT.test(text) || new RegExp(opts.subject.pattern).test(text)) {
25
+ return undefined;
26
+ }
27
+
28
+ return { line: index + 1, text, hint: opts.subject.hint };
29
+ }
30
+
31
+ static patternError(opts: { pattern: string }): string | undefined {
32
+ try {
33
+ new RegExp(opts.pattern);
34
+
35
+ return undefined;
36
+ } catch (error) {
37
+ return `not a regular expression: ${error instanceof Error ? error.message : String(error)}`;
38
+ }
39
+ }
40
+ }
@@ -9,6 +9,9 @@ export class VulcanCommands {
9
9
  static readonly PROFILE = 'profile';
10
10
  static readonly PRESET = 'preset';
11
11
  static readonly VISUALIZE = 'visualize';
12
+ static readonly COMMIT_CHECK = 'commit-check';
13
+ static readonly CI = 'ci';
14
+ static readonly EVENT = 'event';
12
15
  static readonly X = 'x';
13
16
  static readonly HELP = 'help';
14
17
  static readonly VERSION = 'version';
@@ -25,6 +28,8 @@ export class UpgradeFlags {
25
28
  export class ExitCodes {
26
29
  static readonly OK = 0;
27
30
  static readonly FAILURE = 1;
31
+ /** A command that cannot run as asked: the arguments, a file or a range it cannot read. */
32
+ static readonly USAGE = 2;
28
33
  }
29
34
 
30
35
  /** The tools `vulcan x` runs; each is a dependency of @venizia/vulcan at the exact same version. */
@@ -71,6 +76,14 @@ export class ProjectLayout {
71
76
  { name: 'cache', lifetime: 'kept', removedWhen: 'the user asks; it rebuilds' },
72
77
  { name: 'reports', lifetime: 'kept', removedWhen: 'the user deletes it' },
73
78
  { name: 'prototypes', lifetime: 'kept', removedWhen: 'the user deletes it' },
79
+ // On demand: sync does not create these; the folder appears when something writes there.
80
+ { name: 'events', lifetime: 'kept', removedWhen: 'the user deletes it', onDemand: true },
81
+ {
82
+ name: 'release-candidates',
83
+ lifetime: 'release',
84
+ removedWhen: 'the release ships',
85
+ onDemand: true,
86
+ },
74
87
  ] as const;
75
88
  /** What the scaffolded lint configs run; optional peers of dev-configs, so bun never installs them alone. */
76
89
  static readonly LINT_TOOLS = ['oxlint', 'oxlint-tsgolint', 'eslint'];
@@ -73,6 +73,7 @@ export class ConfigConstants {
73
73
  'V-B-04',
74
74
  'V-W-04',
75
75
  'V-C-02',
76
+ 'V-C-09',
76
77
  'V-C-10',
77
78
  'V-P-08',
78
79
  'V-B-07',
@@ -2,6 +2,10 @@ import { isAbsolute } from 'node:path';
2
2
  import { z } from 'zod';
3
3
  import { LayoutFolder } from '../common/layout-folder.ts';
4
4
  import { OWNER_SCHEMA } from '../owner/schema.ts';
5
+ import { AgentSignaturePolicies } from '../commit/common/index.ts';
6
+ import type { TAgentSignaturePolicy } from '../commit/common/index.ts';
7
+ import { SubjectShape } from '../commit/subject.ts';
8
+ import { EventSettings } from '../events/settings.ts';
5
9
  import {
6
10
  CodingAgents,
7
11
  ConfigConstants,
@@ -110,6 +114,11 @@ const NPM_PACKAGE_NAME = z.string().superRefine((value, context) => {
110
114
  }
111
115
  });
112
116
 
117
+ /** A name that holds a letter or a digit: an entry of only punctuation or spaces would match everything. */
118
+ const AGENT_NAME = z
119
+ .string()
120
+ .regex(/[\p{L}\p{N}]/u, { message: 'a name with at least one letter or digit' });
121
+
113
122
  const PROJECT_PACKAGE = z.strictObject({
114
123
  dir: z.string().regex(/^[a-z0-9][a-z0-9.-]*$/),
115
124
  name: NPM_PACKAGE_NAME,
@@ -407,6 +416,99 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
407
416
  writes: { trustedScripts: [], commands: [] },
408
417
  git: { askPush: [] },
409
418
  }),
419
+ /**
420
+ * What `vulcan commit-check` looks for in a commit message, and what `vulcan sync` installs the
421
+ * `commit-msg` hook for, nested by scope. Every check is off until the project turns it on:
422
+ * `message.agent.signature: 'deny'` rejects a trailer or a "generated with" line that names an agent
423
+ * (rule W-00 of a project that has one); `message.agent.names` adds names to the shipped list and
424
+ * `message.agent.allow` lists names never flagged; `message.subject` is the project's own one-line
425
+ * shape. Written to the manifest only when a check is on.
426
+ */
427
+ commit: z
428
+ .strictObject({
429
+ message: z
430
+ .strictObject({
431
+ agent: z
432
+ .strictObject({
433
+ signature: z
434
+ .custom<TAgentSignaturePolicy>(
435
+ (value) => typeof value === 'string' && AgentSignaturePolicies.isValid(value),
436
+ { message: `one of ${[...AgentSignaturePolicies.SCHEME_SET].join(', ')}` },
437
+ )
438
+ .default(AgentSignaturePolicies.ALLOW),
439
+ names: z.array(AGENT_NAME).default([]),
440
+ allow: z.array(AGENT_NAME).default([]),
441
+ })
442
+ .default({ signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] }),
443
+ subject: z
444
+ .strictObject({
445
+ pattern: z
446
+ .string()
447
+ .min(1)
448
+ .superRefine((value, context) => {
449
+ const error = SubjectShape.patternError({ pattern: value });
450
+
451
+ if (error !== undefined) {
452
+ context.addIssue({ code: 'custom', message: error });
453
+ }
454
+ }),
455
+ hint: z.string().min(1).optional(),
456
+ })
457
+ .optional(),
458
+ })
459
+ .default({ agent: { signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] } }),
460
+ })
461
+ .default({
462
+ message: { agent: { signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] } },
463
+ }),
464
+ /**
465
+ * What `vulcan ci affected` treats as touching every package. `affected.global` adds root-relative globs
466
+ * to the shipped list (lockfiles, `bunfig.toml`, root `tsconfig*.json`, `.configs/`, the workflow files);
467
+ * a project cannot remove a shipped one. Written to the manifest only when it is not empty.
468
+ */
469
+ ci: z
470
+ .strictObject({
471
+ affected: z
472
+ .strictObject({
473
+ global: z
474
+ .array(
475
+ z
476
+ .string()
477
+ .min(1)
478
+ .refine((glob) => !glob.startsWith('/') && !glob.split('/').includes('..'), {
479
+ message:
480
+ 'a glob relative to the project root, with no leading / and no .. segment',
481
+ }),
482
+ )
483
+ .default([]),
484
+ })
485
+ .default({ global: [] }),
486
+ })
487
+ .default({ affected: { global: [] } }),
488
+ /**
489
+ * The agent event log: one JSON line per thing an agent did (a session started, a message sent, an
490
+ * owner is needed), summaries only, in `.agents/local/events/<day>.jsonl`. `log: true` makes
491
+ * `vulcan sync` install the Claude Code hooks that write it; `vulcan event add` writes it for any
492
+ * other agent whatever this says. `dir` is an absolute folder that takes the log instead of the
493
+ * project's own, so one coordinator can read the events of sessions in different repositories.
494
+ * Off by default; written to the manifest only when `log` is true or `dir` is set.
495
+ */
496
+ events: z
497
+ .strictObject({
498
+ log: z.boolean().default(false),
499
+ dir: z
500
+ .string()
501
+ .min(1)
502
+ .superRefine((value, context) => {
503
+ const error = EventSettings.dirError({ dir: value });
504
+
505
+ if (error !== undefined) {
506
+ context.addIssue({ code: 'custom', message: `dir must be ${error}` });
507
+ }
508
+ })
509
+ .optional(),
510
+ })
511
+ .default({ log: false }),
410
512
  });
411
513
 
412
514
  export type VulcanConfig = z.input<typeof VULCAN_CONFIG_SCHEMA>;
@@ -1,7 +1,16 @@
1
1
  import { Glob } from 'bun';
2
2
  import { spawnSync } from 'node:child_process';
3
- import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
4
- import { basename, dirname, join, relative, sep } from 'node:path';
3
+ import {
4
+ accessSync,
5
+ constants,
6
+ existsSync,
7
+ lstatSync,
8
+ readdirSync,
9
+ readFileSync,
10
+ realpathSync,
11
+ statSync,
12
+ } from 'node:fs';
13
+ import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
5
14
  import { BASE_DIRECTORY, ProjectLayout, RecordValue } from '../common/index.ts';
6
15
  import { LayoutKeys, LayoutFolder } from '../common/layout-folder.ts';
7
16
  import { MCP_SERVER_HINT, ProjectScaffold } from '../init/index.ts';
@@ -10,6 +19,7 @@ import type { TResolvedConfig } from '../config/index.ts';
10
19
  import { BaseRules, RuleParser, RuleSlots } from '../rules/index.ts';
11
20
  import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
12
21
  import { AgentScopes, AgentSelection, AgentTable, LocalChoice } from '../agents/index.ts';
22
+ import { CommitHook, CommitHookStates } from '../commit/index.ts';
13
23
  import { AgentFiles, AtlasBlockPlan, LocalPlan, SyncPlanner, SyncStatuses } from '../sync/index.ts';
14
24
  import { LocalConstants, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
15
25
  import {
@@ -670,6 +680,100 @@ export class ProjectContract {
670
680
  ];
671
681
  }
672
682
 
683
+ /**
684
+ * The `commit-msg` hook of this clone, when the project turned a commit check on: a missing or out-of-date
685
+ * one is fixed by `vulcan sync`; one that is not ours and does not call the check, or one a project with
686
+ * `core.hooksPath` owns, is told the line to add. Per clone, so a warning and never a violation.
687
+ */
688
+ static checkCommitHook(opts: ICheckContext): IViolation[] {
689
+ const status = CommitHook.stateOf({ root: opts.root, config: opts.config });
690
+ const file = relative(opts.root, status.path);
691
+ const fix = `run '${ProjectLayout.VULCAN_COMMAND} sync' (make vulcan-sync)`;
692
+
693
+ switch (status.state) {
694
+ case CommitHookStates.MISSING: {
695
+ return [
696
+ createViolation({
697
+ check: DoctorChecks.COMMIT_HOOK,
698
+ file,
699
+ message: `the commit-msg hook is not installed, so commit messages are not checked - ${fix}`,
700
+ }),
701
+ ];
702
+ }
703
+
704
+ case CommitHookStates.STALE: {
705
+ return [
706
+ createViolation({
707
+ check: DoctorChecks.COMMIT_HOOK,
708
+ file,
709
+ message: `the commit-msg hook is out of date - ${fix}`,
710
+ }),
711
+ ];
712
+ }
713
+
714
+ case CommitHookStates.UNWIRED: {
715
+ return [
716
+ createViolation({
717
+ check: DoctorChecks.COMMIT_HOOK,
718
+ file,
719
+ message: `the commit-msg hook does not run the commit check - ${status.note ?? fix}`,
720
+ }),
721
+ ];
722
+ }
723
+
724
+ default: {
725
+ return [];
726
+ }
727
+ }
728
+ }
729
+
730
+ /**
731
+ * `events.dir` names a folder outside the project: it must exist and be writable by this user, or the
732
+ * event hooks lose every line without a word (they fail open). A folder inside the project is made
733
+ * on the first write and is not checked. A warning: the folder belongs to the machine, not to the repository.
734
+ */
735
+ static checkEventsDir(opts: ICheckContext): IViolation[] {
736
+ const { dir } = opts.config.events;
737
+
738
+ if (dir === undefined) {
739
+ return [];
740
+ }
741
+
742
+ const away = relative(opts.root, dir);
743
+
744
+ if (away !== '' && !away.startsWith('..') && !isAbsolute(away)) {
745
+ return [];
746
+ }
747
+
748
+ const problem = ((): string | undefined => {
749
+ if (!existsSync(dir)) {
750
+ return `does not exist - create it (mkdir -p ${dir})`;
751
+ }
752
+
753
+ if (!statSync(dir).isDirectory()) {
754
+ return 'is not a folder';
755
+ }
756
+
757
+ try {
758
+ accessSync(dir, constants.W_OK);
759
+
760
+ return undefined;
761
+ } catch {
762
+ return 'is not writable by this user';
763
+ }
764
+ })();
765
+
766
+ return problem === undefined
767
+ ? []
768
+ : [
769
+ createViolation({
770
+ check: DoctorChecks.EVENTS_DIR,
771
+ file: opts.configFile,
772
+ message: `events.dir ${dir} ${problem}, so the event log hooks cannot write there`,
773
+ }),
774
+ ];
775
+ }
776
+
673
777
  /**
674
778
  * The atlas server is registered the one way every project does: the root `.mcp.json` (a per-machine
675
779
  * file `sync` writes for the agents that read it) holds an `atlas` entry that runs the project's own
@@ -1040,19 +1144,37 @@ export class ProjectContract {
1040
1144
  return violations;
1041
1145
  }
1042
1146
 
1147
+ /**
1148
+ * Something directly under `.agents/local/` that is not a folder of the layout, a file VULCAN writes, or a
1149
+ * browser's scratch folder. Nothing removes it; the message says where scratch belongs. A warning.
1150
+ */
1151
+ static checkUnknownLocal(opts: ICheckContext): IViolation[] {
1152
+ return LocalScan.unknown({ root: opts.root }).map((entry) =>
1153
+ createViolation({
1154
+ check: DoctorChecks.LOCAL,
1155
+ file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.name}`,
1156
+ message: `not an entry VULCAN knows (${LocalFormat.formatBytes({ bytes: entry.bytes })}): put scratch in tmp/ and what you want to keep in reports/; nothing removes it`,
1157
+ }),
1158
+ );
1159
+ }
1160
+
1043
1161
  /** What an agent left under `.agents/local/` that has outlived its use, one line each with the command that clears it. */
1044
1162
  static checkStaleLocal(opts: ICheckContext): IViolation[] {
1045
1163
  return LocalScan.scan({ root: opts.root })
1046
1164
  .filter((entry) =>
1047
- [LocalStates.STALE, LocalStates.MERGED, LocalStates.GONE, LocalStates.ORPHAN].includes(
1048
- entry.state,
1049
- ),
1165
+ [
1166
+ LocalStates.STALE,
1167
+ LocalStates.MERGED,
1168
+ LocalStates.GONE,
1169
+ LocalStates.ORPHAN,
1170
+ LocalStates.SHIPPED,
1171
+ ].includes(entry.state),
1050
1172
  )
1051
1173
  .map((entry) =>
1052
1174
  createViolation({
1053
1175
  check: DoctorChecks.LOCAL,
1054
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.scope}/${entry.name}`,
1055
- message: `${entry.state === LocalStates.STALE ? `left ${LocalFormat.formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${LocalFormat.formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
1176
+ file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.where}`,
1177
+ message: `${entry.state === LocalStates.STALE && entry.note === '' ? `left ${LocalFormat.formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${LocalFormat.formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
1056
1178
  }),
1057
1179
  );
1058
1180
  }
@@ -20,6 +20,8 @@ export class DoctorChecks {
20
20
  static readonly LOCAL = 'local';
21
21
  static readonly PROFILE = 'profile';
22
22
  static readonly GUARDS = 'guards';
23
+ static readonly COMMIT_HOOK = 'commit-hook';
24
+ static readonly EVENTS_DIR = 'events-dir';
23
25
  }
24
26
 
25
27
  /** The `package.json` scripts every app carries, and the names the standard retired. */
@@ -91,6 +91,8 @@ export class DoctorRunner {
91
91
 
92
92
  return [
93
93
  ...ProjectContract.checkMcpAtlas(context),
94
+ ...ProjectContract.checkCommitHook(context),
95
+ ...ProjectContract.checkEventsDir(context),
94
96
  ...ProjectContract.checkDockerignore(context),
95
97
  ...ProjectContract.checkSkillTriggers(context),
96
98
  ...ProjectContract.checkFormat(context),
@@ -99,6 +101,7 @@ export class DoctorRunner {
99
101
  ...ProjectContract.checkProfile(context),
100
102
  ...ProjectContract.checkOwnerReplySettings(context),
101
103
  ...ProjectContract.checkStaleLocal(context),
104
+ ...ProjectContract.checkUnknownLocal(context),
102
105
  ...ProjectContract.checkStaleTrustedScripts(context),
103
106
  ];
104
107
  }
@@ -0,0 +1,116 @@
1
+ import { readdirSync, readFileSync, statSync } from 'node:fs';
2
+ import { homedir } from 'node:os';
3
+ import { join } from 'node:path';
4
+ import { RecordValue } from '../common/record.ts';
5
+ import { EventConstants } from './common/index.ts';
6
+ import { EventText } from './text.ts';
7
+
8
+ const SESSION_FILE = /^[\w.-]+\.json$/;
9
+ const SESSION_ID_SHORT = 8;
10
+ /** A person has a handful of sessions; a folder with more is not the registry this expects. */
11
+ const MAX_SESSION_FILES = 500;
12
+
13
+ /** Who is writing: the session's name, the way other sessions address it. */
14
+ export class EventActor {
15
+ /**
16
+ * In order: `VULCAN_ACTOR` from the environment; the name Claude Code gave the session in its own
17
+ * session registry (`<config dir>/sessions/<pid>.json`, matched by session id); `claude:` and the
18
+ * start of the session id; `unknown`. The registry is not a documented interface, so a read that fails
19
+ * or finds no match falls through to the next answer.
20
+ */
21
+ static resolve(opts: { sessionId?: string; env: Record<string, string | undefined> }): string {
22
+ const fromEnv = EventActor.clean({ text: opts.env[EventConstants.ACTOR_ENV] ?? '' });
23
+
24
+ if (fromEnv !== '') {
25
+ return fromEnv;
26
+ }
27
+
28
+ const { sessionId } = opts;
29
+
30
+ if (sessionId === undefined || sessionId === '') {
31
+ return EventConstants.UNKNOWN_ACTOR;
32
+ }
33
+
34
+ const named = EventActor.registryName({ sessionId, env: opts.env });
35
+
36
+ return named ?? `claude:${sessionId.slice(0, SESSION_ID_SHORT)}`;
37
+ }
38
+
39
+ static clean(opts: { text: string }): string {
40
+ return EventText.oneLine({ text: opts.text, max: EventConstants.ACTOR_MAX });
41
+ }
42
+
43
+ private static registryName(opts: {
44
+ sessionId: string;
45
+ env: Record<string, string | undefined>;
46
+ }): string | undefined {
47
+ const config = opts.env[EventConstants.CONFIG_DIR_ENV] ?? join(homedir(), '.claude');
48
+ const directory = join(config, 'sessions');
49
+
50
+ let files: string[];
51
+
52
+ try {
53
+ files = readdirSync(directory)
54
+ .filter((name) => SESSION_FILE.test(name))
55
+ .slice(0, MAX_SESSION_FILES);
56
+ } catch {
57
+ return undefined;
58
+ }
59
+
60
+ const matches = files.flatMap(
61
+ (file) =>
62
+ EventActor.candidateIn({ file: join(directory, file), sessionId: opts.sessionId }) ?? [],
63
+ );
64
+ // Several files can hold one session id (a resumed session leaves its old file): a live process wins, then the newest.
65
+ const live = matches.filter((match) => match.alive);
66
+ const best = [...(live.length > 0 ? live : matches)].sort(
67
+ (left, right) => right.updatedAt - left.updatedAt,
68
+ )[0];
69
+
70
+ return best?.name;
71
+ }
72
+
73
+ /** The name, the process and the time of one registry file when it is the session's; a file that cannot be read is no match. */
74
+ private static candidateIn(opts: {
75
+ file: string;
76
+ sessionId: string;
77
+ }): { name: string; alive: boolean; updatedAt: number }[] | undefined {
78
+ try {
79
+ const entry: unknown = JSON.parse(readFileSync(opts.file, 'utf8'));
80
+
81
+ if (!RecordValue.isRecord(entry) || entry.sessionId !== opts.sessionId) {
82
+ return undefined;
83
+ }
84
+
85
+ const name = typeof entry.name === 'string' ? EventActor.clean({ text: entry.name }) : '';
86
+
87
+ if (name === '') {
88
+ return undefined;
89
+ }
90
+
91
+ return [
92
+ {
93
+ name,
94
+ alive: typeof entry.pid === 'number' && EventActor.isAlive({ pid: entry.pid }),
95
+ updatedAt:
96
+ typeof entry.updatedAt === 'number'
97
+ ? entry.updatedAt
98
+ : Number(statSync(opts.file).mtimeMs),
99
+ },
100
+ ];
101
+ } catch {
102
+ return undefined;
103
+ }
104
+ }
105
+
106
+ /** Whether a process with this id exists (signal 0 sends nothing); a process of another user exists too. */
107
+ private static isAlive(opts: { pid: number }): boolean {
108
+ try {
109
+ process.kill(opts.pid, 0);
110
+
111
+ return true;
112
+ } catch (error) {
113
+ return error instanceof Error && 'code' in error && error.code === 'EPERM';
114
+ }
115
+ }
116
+ }