@venizia/vulcan 0.4.10-2 → 0.4.10-21

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 (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -1,29 +1,50 @@
1
1
  export class DoctorChecks {
2
+ /** The config file: missing, unloadable or without a default export is an error, and the only check run then. */
2
3
  static readonly CONFIG = 'config';
4
+ /** The required files (AGENTS.md, .agents/rules.md, knowledge bundle root); a missing one is an error. */
3
5
  static readonly LAYOUT = 'layout';
6
+ /** Rule references in .agents/rules.md; one to a base rule the base does not carry is an error. */
4
7
  static readonly RULE_IDS = 'rule-ids';
8
+ /** The rule slot choices in the config; an unknown option or a key that is not a slot is an error. */
5
9
  static readonly RULE_SLOTS = 'rule-slots';
10
+ /** Skill names and lint: an error; a skill description with no "Use when" part is a warning. */
6
11
  static readonly SKILLS = 'skills';
12
+ /** The Makefile include of vulcan.mk and clashes with shipped target names; a violation is an error. */
7
13
  static readonly MAKE = 'make';
8
- static readonly HOOKS = 'hooks';
14
+ /** Project hooks in the config; one that registers a shipped hook path is an error. */
15
+ /** Generated tool files, settings and links against the config; a missing or stale one is an error. */
9
16
  static readonly ADAPTERS = 'adapters';
17
+ /** Packages declare @venizia/dev-configs and lint configs import the shared style; a miss is an error. */
10
18
  static readonly STYLE = 'style';
19
+ /** The committed .agents/vulcan.manifest.json against the config; a missing or outdated one is an error. */
11
20
  static readonly MANIFEST = 'manifest';
21
+ /** Version folders under the changelog directory while the installed vulcan predates the atlas that reads them; an error. */
22
+ static readonly CHANGELOG_FOLDERS = 'changelog-folders';
23
+ /** Git tags matching atlas.tagPattern that name no declared package, alias or ignored tag; an error. */
12
24
  static readonly TAGS = 'tags';
25
+ /** Workspaces declare packages and the knowledge index no longer holds scaffold text; a miss is an error. */
13
26
  static readonly SCAFFOLD = 'scaffold';
27
+ /** Layout folders are workspaces and every package lives in a listed folder; a miss is an error. */
14
28
  static readonly APPS = 'apps';
15
- static readonly SCRIPTS = 'scripts';
29
+ /** The stored agents file must parse and name known agents (an error); a stale Atlas block in AGENTS.md is a note. */
16
30
  static readonly AGENTS = 'agents';
17
- static readonly DOCKERIGNORE = 'dockerignore';
31
+ /** The .mcp.json atlas entry, its git visibility and the Claude settings that enable atlas; a warning. */
18
32
  static readonly MCP = 'mcp';
33
+ /** The bunfig.toml [fmt] oxfmt setup, no fmt script and no leftover oxfmt config; a warning. */
19
34
  static readonly FORMAT = 'format';
35
+ /** The .agents/local workspace, leftovers, reply switch and the tmp folder: mostly warnings, some notes. */
20
36
  static readonly LOCAL = 'local';
37
+ /** The personal profile file: unreadable, not gitignored or tracked by git; a warning. */
21
38
  static readonly PROFILE = 'profile';
22
- static readonly GUARDS = 'guards';
39
+ /** The clone commit-msg hook when a commit check is on: missing, stale or not calling commit-check; a warning. */
23
40
  static readonly COMMIT_HOOK = 'commit-hook';
41
+ /** The events.dir folder when outside the project: missing, not a folder or not writable; a warning. */
24
42
  static readonly EVENTS_DIR = 'events-dir';
43
+ /** Today's event file when it alone is over events.maxSize; a warning. */
25
44
  static readonly EVENTS_SIZE = 'events-size';
45
+ /** The event log is on but project.key is unset, so no flow can be created; a warning. */
26
46
  static readonly PROJECT_KEY = 'project-key';
47
+ /** Tracked files holding keys, tokens, URL credentials, IPv4 or machine paths: a warning; the count of acknowledged files: a note. */
27
48
  static readonly PRIVATE_VALUES = 'private-values';
28
49
  }
29
50
 
@@ -73,24 +94,11 @@ export class PrivateValueScan {
73
94
  static readonly MAX_BYTES = 1_000_000;
74
95
  }
75
96
 
76
- /** The `package.json` scripts every app carries, and the names the standard retired. */
77
- export class AppScripts {
78
- static readonly STANDARD = [
79
- 'server:dev',
80
- 'compile',
81
- 'typecheck',
82
- 'lint',
83
- 'lint:fix',
84
- 'test',
85
- 'clean',
86
- ];
87
- static readonly LEGACY = ['dev', 'start', 'build', 'rebuild', 'preview', 'server:prod'];
88
- }
89
-
90
97
  export class DoctorConstants {
98
+ /** The first VULCAN version whose atlas reads version folders (the first prerelease of the line to carry the reader); an older installed vulcan ignores them. */
99
+ static readonly CHANGELOG_FOLDERS_FROM = '0.4.10-16';
91
100
  static readonly MAKE_INCLUDE_PATTERN =
92
101
  /^-?include\s+\S*@venizia\/vulcan\/base\/make\/vulcan\.mk\s*$/m;
93
- static readonly SHIPPED_HOOKS_PATH = '@venizia/vulcan/base/hooks/';
94
102
  /** The `[fmt]` table header of a `bunfig.toml`, on a line of its own, a trailing comment allowed. */
95
103
  static readonly BUNFIG_FMT_SECTION = /^\s*\[fmt\]\s*(#.*)?$/m;
96
104
  static readonly BUNFIG_FMT_FLAVOR = /^\s*flavor\s*=\s*["']oxfmt["']/m;
@@ -94,7 +94,10 @@ export class PrivateValues {
94
94
  (sum, pattern) => sum + countOf({ text, pattern }),
95
95
  0,
96
96
  ),
97
- [PrivateValueKinds.URL_CREDENTIALS]: countOf({ text, pattern: EventSecrets.URL_USERINFO }),
97
+ [PrivateValueKinds.URL_CREDENTIALS]: EventSecrets.URL_CREDENTIALS.reduce(
98
+ (sum, pattern) => sum + countOf({ text, pattern }),
99
+ 0,
100
+ ),
98
101
  [PrivateValueKinds.IPV4]: countOf({
99
102
  text,
100
103
  pattern: PrivateValueScan.IPV4,
@@ -1,11 +1,12 @@
1
1
  import { relative } from 'node:path';
2
2
  import { ConfigLoader } from '../config/index.ts';
3
- import { ProjectContract, ReadOnlySubcommandChecks } from './checks.ts';
3
+ import { ProjectContract } from './checks.ts';
4
4
  import { SkillLint } from './skills.ts';
5
5
  import { TagCheck } from './tags.ts';
6
6
  import { DoctorChecks } from './common/index.ts';
7
7
  import type { IViolation } from './common/index.ts';
8
8
 
9
+ /** Runs the doctor checks and sorts their findings into violations, notes and warnings; used by `vulcan doctor`. */
9
10
  export class DoctorRunner {
10
11
  /** Every violation of the VULCAN contract in the project at `root`; empty means conformant. */
11
12
  static async runChecks(opts: { root: string }): Promise<IViolation[]> {
@@ -33,15 +34,16 @@ export class DoctorRunner {
33
34
  ...ProjectContract.checkRuleSlots(context),
34
35
  ...ProjectContract.checkSkills(context),
35
36
  ...ProjectContract.checkMake(context),
36
- ...ProjectContract.checkHooks(context),
37
37
  ...ProjectContract.checkAdapters(context),
38
38
  ...ProjectContract.checkAgents(context),
39
39
  ...ProjectContract.checkManifest(context),
40
+ ...ProjectContract.checkChangelogFolders(context),
40
41
  ...TagCheck.check(context),
41
42
  ...SkillLint.check(context),
42
43
  ...ProjectContract.checkStyle(context),
43
44
  ...ProjectContract.checkScaffold(context),
44
45
  ...ProjectContract.checkApps(context),
46
+ ...ProjectContract.checkTmpFolder(context),
45
47
  ];
46
48
  }
47
49
 
@@ -64,16 +66,9 @@ export class DoctorRunner {
64
66
  };
65
67
 
66
68
  return [
67
- ...ProjectContract.checkAppScripts(context),
68
69
  ...ProjectContract.checkAtlasBlock(context),
69
- ...ProjectContract.checkLocalSize(context),
70
- ...ProjectContract.checkGuardPatterns(context),
71
70
  ...ProjectContract.checkAcknowledgedValues(context),
72
- ...ProjectContract.checkReplyShape(context),
73
71
  ...ProjectContract.checkOwnerReplySwitch({ env: opts.env ?? process.env }),
74
- ...ProjectContract.checkLaunchSettings({ root: opts.root, env: opts.env ?? process.env }),
75
- ...ProjectContract.checkTrustedScripts(context),
76
- ...ReadOnlySubcommandChecks.check(context),
77
72
  ];
78
73
  }
79
74
 
@@ -97,16 +92,14 @@ export class DoctorRunner {
97
92
  ...ProjectContract.checkEventsDir(context),
98
93
  ...ProjectContract.checkEventsSize(context),
99
94
  ...ProjectContract.checkProjectKey(context),
100
- ...ProjectContract.checkDockerignore(context),
95
+ ...ProjectContract.checkBrowserSocket({ root: opts.root, tmp: context.config.local.tmp }),
101
96
  ...ProjectContract.checkSkillTriggers(context),
102
97
  ...ProjectContract.checkFormat(context),
103
98
  ...ProjectContract.checkLocalWorkspace(context),
104
- ...ProjectContract.checkOutsideWorktrees(context),
105
99
  ...ProjectContract.checkProfile(context),
106
100
  ...ProjectContract.checkOwnerReplySettings(context),
107
101
  ...ProjectContract.checkStaleLocal(context),
108
102
  ...ProjectContract.checkUnknownLocal(context),
109
- ...ProjectContract.checkStaleTrustedScripts(context),
110
103
  ...ProjectContract.checkPrivateValues(context),
111
104
  ];
112
105
  }
@@ -10,17 +10,21 @@ const KIND = z.custom<TPrivateValueKind>(
10
10
 
11
11
  /** A decision to keep private values in files: where, which kinds (all when absent), and why. */
12
12
  const ACKNOWLEDGEMENT = z.strictObject({
13
+ /** Glob relative to the repo root, with no `..`, of the files that may keep private values. */
13
14
  path: z
14
15
  .string()
15
16
  .min(1)
16
17
  .refine((value) => !isAbsolute(value) && !value.split(/[\\/]/).includes('..'), {
17
18
  message: 'a glob relative to the repo root, without ..',
18
19
  }),
20
+ /** Kinds of private value the decision covers: `private-key`, `token`, `url-credentials`, `ipv4` or `machine-path`; at least one, all kinds when absent. */
19
21
  kinds: z.array(KIND).min(1).optional(),
22
+ /** Why the private values may stay in these files; trimmed, at least one character. */
20
23
  reason: z.string().trim().min(1),
21
24
  });
22
25
 
23
26
  export const DOCTOR_SCHEMA = z.strictObject({
27
+ /** Private values doctor tolerates: `acknowledged` lists files that may keep them, each with a reason; default none. */
24
28
  privateValues: z
25
29
  .strictObject({ acknowledged: z.array(ACKNOWLEDGEMENT).default([]) })
26
30
  .default({ acknowledged: [] }),
@@ -0,0 +1,12 @@
1
+ /** What the name of an actor says about its session. It imports nothing: the board page is built from it. */
2
+ export class EventActorNames {
3
+ /** Where the log goes for a hook that has no better answer: the name of an actor with no session name. */
4
+ static readonly UNKNOWN = 'unknown';
5
+ /** What the actor of a session with no name starts with; a name that starts with it is read as no name. */
6
+ static readonly UNNAMED_PREFIX = 'claude:';
7
+
8
+ /** Whether the actor is a name somebody gave, and not the fallback of a session with none (`claude:<id>`, `unknown`). */
9
+ static isNamed(opts: { actor: string }): boolean {
10
+ return opts.actor !== this.UNKNOWN && !opts.actor.startsWith(this.UNNAMED_PREFIX);
11
+ }
12
+ }
@@ -1,6 +1,9 @@
1
+ import { EventActorNames } from './actor-names.ts';
2
+
1
3
  /** What happened. A board reads these; add one only when a reader needs to tell it apart. */
2
4
  export class EventKinds {
3
5
  static readonly SESSION_START = 'session-start';
6
+ /** No longer written (a turn that ends is not an event); read so a log written before still folds until its retention removes it. */
4
7
  static readonly SESSION_STOP = 'session-stop';
5
8
  static readonly MSG_SENT = 'msg-sent';
6
9
  static readonly MSG_RECEIVED = 'msg-received';
@@ -14,7 +17,7 @@ export class EventKinds {
14
17
  static readonly FLOW = 'flow';
15
18
  /** Something was put live; a milestone of its flow, like a merge. Its summary says what. */
16
19
  static readonly DEPLOY = 'deploy';
17
- /** An agent used a tool, at most once in `EventConstants.TICK_SECONDS` per session: the board reads it as working. */
20
+ /** No longer written (a tool that is used is not an event); read so a log written before still folds until its retention removes it. */
18
21
  static readonly TOOL_TICK = 'tool-tick';
19
22
 
20
23
  static readonly SCHEME_SET = new Set<string>([
@@ -110,7 +113,6 @@ export class EventFlags {
110
113
  /** The names a Claude Code hook payload carries, as Claude Code 2.1.317 sends them. */
111
114
  export class ClaudeHookEvents {
112
115
  static readonly SESSION_START = 'SessionStart';
113
- static readonly STOP = 'Stop';
114
116
  static readonly SUBAGENT_STOP = 'SubagentStop';
115
117
  static readonly NOTIFICATION = 'Notification';
116
118
  static readonly POST_TOOL_USE = 'PostToolUse';
@@ -150,16 +152,6 @@ export class EventConstants {
150
152
  static readonly CONTEXT_MAX = 600;
151
153
  /** What a sent message is called when its sender gave no label: the text of a message is never used. */
152
154
  static readonly MESSAGE_SENT_LABEL = 'message sent';
153
- /** The summary of a tool tick: it says that a tool was used, and nothing of which. */
154
- static readonly TOOL_TICK_LABEL = 'using a tool';
155
- /** A session writes at most one tool tick in each window of this many seconds. */
156
- static readonly TICK_SECONDS = 30;
157
- /**
158
- * The folder, from the project root, that holds one empty stamp per session and window, `<session>.<window>`; a tick
159
- * removes the stamps of earlier windows. Spelt out because the hook imports no other module of the package (a test holds it
160
- * inside `ProjectLayout.LOCAL_DIRECTORY/tmp`).
161
- */
162
- static readonly TICK_FOLDER = '.agents/local/tmp/event-ticks';
163
155
  static readonly REF_MAX = 120;
164
156
  /** A flow line's lists: how many items, and how long one is. */
165
157
  static readonly ITEM_COUNT_MAX = 30;
@@ -171,6 +163,8 @@ export class EventConstants {
171
163
  static readonly MODEL_MAX = 80;
172
164
  static readonly ACTOR_MAX = 80;
173
165
  static readonly REDACTED = '[redacted]';
166
+ /** How much of a long text the redaction reads for a result of `max` characters: `max * factor`, at least `min`. */
167
+ static readonly REDACT_SCAN = { factor: 4, min: 1024 };
174
168
  /** A flow is named `VULZ-<key>-<number>`; the older `F-<number>` is still read and shows as the new form. */
175
169
  static readonly FLOW_PREFIX = 'VULZ';
176
170
  static readonly FLOW_ID = 'VULZ-[A-Z0-9]{2,8}-\\d+|F-\\d+';
@@ -184,10 +178,8 @@ export class EventConstants {
184
178
  static readonly FLOW_CLAIM_DIR = '.flow-ids';
185
179
  /** How many recent flows a refusal lists. */
186
180
  static readonly FLOW_RECENT_COUNT = 5;
187
- /** Where the log goes for a hook that has no better answer: the name of an actor with no session name. */
188
- static readonly UNKNOWN_ACTOR = 'unknown';
189
- /** What the actor of a session with no name starts with; a name that starts with it is read as no name. */
190
- static readonly UNNAMED_PREFIX = 'claude:';
181
+ static readonly UNKNOWN_ACTOR = EventActorNames.UNKNOWN;
182
+ static readonly UNNAMED_PREFIX = EventActorNames.UNNAMED_PREFIX;
191
183
  /** The `nameSource` values of a name Claude Code made up (from the folder, a counter or a clash), not a person's. */
192
184
  static readonly MADE_UP_NAME_SOURCES = new Set(['derived', 'auto', 'collision']);
193
185
  static readonly ACTOR_ENV = 'VULCAN_ACTOR';
@@ -196,21 +188,15 @@ export class EventConstants {
196
188
  static readonly DAY_MS = 24 * 60 * 60 * 1000;
197
189
  }
198
190
 
199
- /** What the name of an actor says about its session. Light on purpose: the board page is built from it. */
200
- export class EventActorNames {
201
- /** Whether the actor is a name somebody gave, and not the fallback of a session with none (`claude:<id>`, `unknown`). */
202
- static isNamed(opts: { actor: string }): boolean {
203
- return (
204
- opts.actor !== EventConstants.UNKNOWN_ACTOR &&
205
- !opts.actor.startsWith(EventConstants.UNNAMED_PREFIX)
206
- );
207
- }
208
- }
209
-
210
- /** Shapes of a secret that must never reach a log line. Best effort: a summary is a label, not a document. */
191
+ /**
192
+ * Shapes of a secret that must never reach a log line. Best effort: a summary is a label, not a document. Each pattern
193
+ * reads a long line in time in proportion to its length (doctor runs them over whole files); a test times each one.
194
+ * Group 1, in a pattern that has one, is the name, flag or command before the secret: it is kept and the rest replaced.
195
+ * A value that starts with `$`, `<`, `%` or `{`, quoted or not, is a variable or a placeholder, not a secret.
196
+ */
211
197
  export class EventSecrets {
212
- static readonly PRIVATE_KEY = /-----BEGIN [A-Z ]*PRIVATE KEY-----.*/g;
213
- /** The known token prefixes and shapes. */
198
+ static readonly PRIVATE_KEY = /-----BEGIN [A-Z ]{0,64}PRIVATE KEY-----.*/g;
199
+ /** The known token prefixes and shapes, and the credentials a command line, a header or a query carries. */
214
200
  static readonly TOKENS: RegExp[] = [
215
201
  /\b(?:ghp|gho|ghs|ghu|ghr)_[A-Za-z0-9]{16,}/g,
216
202
  /\bgithub_pat_[A-Za-z0-9_]{16,}/g,
@@ -220,29 +206,70 @@ export class EventSecrets {
220
206
  /\bAIza[0-9A-Za-z_-]{35}/g,
221
207
  /\bglpat-[A-Za-z0-9_-]{16,}/g,
222
208
  /\b[sr]k_(?:live|test)_[A-Za-z0-9]{8,}/g,
223
- /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]*/g,
209
+ /\bhf_[A-Za-z0-9]{30,}/g,
210
+ /\bdop_v1_[0-9a-f]{64}\b/g,
211
+ /\bshpat_[0-9a-fA-F]{32}\b/g,
212
+ /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/g,
213
+ /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]*/g,
224
214
  // A Basic credential is base64 of user:password: it has a digit, a + or a /, a capital inside it, or ends in =; a plain word after "Basic" has none of these.
225
215
  /\bBasic\s+(?:(?=[A-Za-z0-9+/]*(?:[0-9+/]|[a-z][A-Z]))[A-Za-z0-9+/]{8,}={0,2}|[A-Za-z0-9+/]{8,}={1,2})/g,
226
216
  /\bxox[abprs]-[A-Za-z0-9-]{10,}/g,
227
- /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi,
217
+ // A Bearer credential has a digit, a + / or =, a dot between two characters, or a capital inside it; a plain word of letters ("Bearer authentication", "Bearer authentication.") has none of these. No `i` flag: it would make every pair of letters an inner capital.
218
+ /\b(?:Bearer|bearer|BEARER)\s+(?=[A-Za-z0-9._~+/=-]*(?:[0-9+/=]|[a-z][A-Z]|[A-Za-z0-9]\.[A-Za-z0-9]))[A-Za-z0-9._~+/=-]{8,}/g,
219
+ // Any other scheme of an Authorization header, with its value: the value has a digit, a + / or =, or a capital inside it, so a placeholder or a word does not count. Bearer and Basic are the two patterns above.
220
+ /(\b(?:[Aa]uthorization|AUTHORIZATION)["']?\s{0,8}:\s{0,8})(?![Bb]earer\s|BEARER\s|[Bb]asic\s|BASIC\s)(?:[A-Za-z][A-Za-z0-9_-]{0,31}\s{1,8})?(?!["']?[$<%{])(?=[^\s]{0,511}(?:[0-9+/=]|[a-z][A-Z]))[^\s]{8,512}/g,
221
+ // The cookies of a Cookie or Set-Cookie header, each `name=value` and the attributes after them.
222
+ /(\b(?:[Ss]et-)?(?:[Cc]ookie|COOKIE):\s{0,8})(?!["']?[$<%{])[^\s;=]{1,64}=[^\s;]{1,512}(?:;\s{0,8}[^\s;=]{1,64}(?:=[^\s;]{0,512})?){0,16}/g,
223
+ // The password in the user and password pair given to curl's user flag, in the same command.
224
+ /(\bcurl\s(?:[^|;&]{0,256}?\s)?(?:-u|--user)(?:\s{1,8}|=)?(?!-)["']?[^\s:]{1,128}:)(?![\s-])(?!["']?[$<%{])[^\s]{1,256}/g,
225
+ // The value of `-p` joined to it (`-p` with a space asks for the password) for the MySQL and MariaDB clients.
226
+ /(\b(?:mysql|mysqldump|mysqladmin|mariadb|mariadb-dump)\s(?:[^|;&]{0,256}?\s)?-p)(?![\s-])(?!["']?[$<%{])[^\s]{1,256}/g,
227
+ // The value of `-p`, joined or after a space, for sshpass before the command it wraps, and for a docker, podman or az login.
228
+ /(\bsshpass\s{1,8}(?:-[A-Za-z]\S{0,64}\s{1,8}){0,4}-p(?:\s{1,8})?)(?![\s-])(?!["']?[$<%{])[^\s]{1,256}/g,
229
+ /(\b(?:docker|podman|az)\s{1,8}login\s(?:[^|;&]{0,256}?\s)?-p(?:\s{1,8}|=)?)(?![\s-])(?!["']?[$<%{])[^\s]{1,256}/g,
230
+ // The password flag of redis-cli (`-a`) and sqlcmd (`-P`), after a space.
231
+ /(\bredis-cli\s(?:[^|;&]{0,256}?\s)?-a\s{1,8})(?!-)(?!["']?[$<%{])[^\s]{1,256}/g,
232
+ /(\bsqlcmd\s(?:[^|;&]{0,256}?\s)?-P\s{1,8})(?!-)(?!["']?[$<%{])[^\s]{1,256}/g,
233
+ // The secret key or session token that `aws configure set` writes.
234
+ /(\baws\s{1,8}configure\s{1,8}set\s{1,8}(?:[A-Za-z0-9_-]{1,64}\.)?(?:aws_secret_access_key|aws_session_token)\s{1,8})(?!-)(?!["']?[$<%{])[^\s]{1,256}/g,
235
+ // The value after a flag that names a secret, given with a space; `--name=value` is the assignment.
236
+ /((?:^|\s)--(?:password|passwd|http-password|ftp-password|proxy-password|token|secret|api-key|apikey|auth-token|access-token)\s{1,8})(?!-)(?!["']?[$<%{])[^\s]{1,256}/g,
237
+ // `--key` names many things that are not secret: its value counts when it has a digit, a + or =, or a capital inside it, and is not a path or a file name.
238
+ /((?:^|\s)--key\s{1,8})(?!["']?[$<%{]|[~./-])(?![^\s]{0,251}\.[A-Za-z]{1,4}(?:\s|$))(?=[^\s]{0,255}(?:[0-9+=]|[a-z][A-Z]))[^\s]{8,256}/g,
239
+ // The path of a Slack incoming webhook: the workspace, the channel and the secret.
240
+ /(\bhooks\.slack\.com\/services\/)T[A-Z0-9]{6,32}\/B[A-Z0-9]{6,32}\/[A-Za-z0-9]{16,64}/g,
241
+ // A 40-character AWS secret access key assigned to a name that holds `aws` or `secret`.
242
+ /((?<![A-Za-z0-9_.-])[A-Za-z0-9_.-]{0,64}(?:aws|secret)[A-Za-z0-9_.-]{0,64}["']?\s{0,8}[:=]\s{0,8}["']?)[A-Za-z0-9/+]{40}(?![A-Za-z0-9/+=])/gi,
243
+ // The signature of a shared access URL, `sig=` in its query.
244
+ /([?&]sig=)[A-Za-z0-9%+/=_-]{16,256}/g,
228
245
  ];
229
246
  /** Long runs that are secrets in a log line but hashes in a lockfile. */
230
247
  static readonly HIGH_ENTROPY: RegExp[] = [
231
248
  /\b[0-9a-fA-F]{64,}\b/g,
232
- /\b(?=[A-Za-z0-9+]*\d)(?=[A-Za-z0-9+]*[a-z])(?=[A-Za-z0-9+]*[A-Z])[A-Za-z0-9+]{40,}={0,2}/g,
249
+ /(?<![A-Za-z0-9+_])(?=[A-Za-z0-9+]*\d)(?=[A-Za-z0-9+]*[a-z])(?=[A-Za-z0-9+]*[A-Z])[A-Za-z0-9+]{40,}={0,2}/g,
250
+ ];
251
+ /**
252
+ * Credentials inside a URL, up to the `@` before the host: `user:password` (the user may be empty, the password runs to
253
+ * the last `@` before the host; a port and a path are not a password), and a DSN key `<32 hex>`.
254
+ */
255
+ static readonly URL_CREDENTIALS: RegExp[] = [
256
+ /(\/\/)[^\s/@:]{0,128}:(?!\d{1,5}(?:[/?#\s]|$))[^\s]{1,256}?(?=@[^\s/@?#]{1,253}(?:[/:?#\s]|$))/g,
257
+ /(\/\/)[0-9a-fA-F]{32}(?::[0-9a-fA-F]{32})?(?=@)/g,
233
258
  ];
234
259
  /** Everything `EventText.redact` replaces, in the order it replaces it. */
235
260
  static readonly PATTERNS: RegExp[] = [
236
261
  EventSecrets.PRIVATE_KEY,
237
262
  ...EventSecrets.TOKENS,
238
263
  ...EventSecrets.HIGH_ENTROPY,
264
+ ...EventSecrets.URL_CREDENTIALS,
239
265
  ];
240
- /** `user:password@host` inside a URL. */
241
- static readonly URL_USERINFO = /(\/\/)[^\s/@:]+:[^\s/@]+@/g;
242
- /** `name=value`, `name: value` and `"name": "value"` where the name says it is a secret. */
266
+ /**
267
+ * `name=value`, `name: value` and `"name": "value"` where the name says it is a secret, or has `pw`, `pass` or
268
+ * `passphrase` as a whole part (`DB_PASS`, `pw_x`). A switch value (`true`, `off`, `1`) is not a secret.
269
+ */
243
270
  static readonly ASSIGNMENT =
244
- /["']?\b([A-Za-z0-9_.-]*(?:key|token|secret|password|passwd|pwd|credential)[A-Za-z0-9_.-]*)["']?\s*[:=]\s*("[^"]*"|'[^']*'|\S+)/gi;
271
+ /["']?(?<![A-Za-z0-9_.-])([A-Za-z0-9_.-]{0,64}(?:key|token|secret|password|passwd|pwd|credential)[A-Za-z0-9_.-]{0,64}|(?:[A-Za-z0-9_.-]{0,64}[_.-])?(?:pw|pass|passphrase)(?:[_.-][A-Za-z0-9_.-]{0,64})?)["']?\s{0,8}[:=]\s{0,8}(?!["']?(?:0|1|true|false|yes|no|on|off)(?![A-Za-z0-9_]))("[^"]{0,256}"|'[^']{0,256}'|\S{1,256})/gi;
245
272
  /** "the password is hunter2". */
246
273
  static readonly SPOKEN =
247
- /\b((?:password|passwd|passphrase|secret|token|api[ _-]?key)s?)\s+(?:is|are|was|were)\s+("[^"]*"|'[^']*'|\S+)/gi;
274
+ /\b((?:password|passwd|passphrase|secret|token|api[ _-]?key)s?)\s{1,8}(?:is|are|was|were)\s{1,8}("[^"]{0,256}"|'[^']{0,256}'|\S{1,256})/gi;
248
275
  }
@@ -1,2 +1,3 @@
1
+ export * from './actor-names.ts';
1
2
  export * from './constants.ts';
2
3
  export * from './types.ts';
@@ -1,5 +1,3 @@
1
- import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
2
- import { join } from 'node:path';
3
1
  import { RecordValue } from '../common/record.ts';
4
2
  import { ClaudeHookEvents, EventConstants, EventKinds, EventSources } from './common/index.ts';
5
3
  import type { IEvent, IHookEvent } from './common/index.ts';
@@ -16,10 +14,10 @@ const text = (opts: { value: unknown }): string =>
16
14
  export class EventHook {
17
15
  /**
18
16
  * The event a payload stands for, or `undefined` when the payload is not one to log. Only these fields are
19
- * read: `source` and `model` of a session start, `stop_hook_active` of a stop, `agent_type` and `agent_id` of a
20
- * subagent stop, `notification_type` and `title` of a notification, and `to` and `summary` of a SendMessage
21
- * call (its first line, only when the sender gave no summary). A tool tick reads nothing but the event's name.
22
- * `last_assistant_message`, `message`, `tool_response`, `tool_input` and every command stay unread.
17
+ * read: `source` and `model` of a session start, `agent_type` and `agent_id` of a subagent stop,
18
+ * `notification_type` and `title` of a notification, and `to` and `summary` of a SendMessage call (the label the
19
+ * sender gave it, or a fixed one). A turn that ends and a tool that is used are not events.
20
+ * `last_assistant_message`, the text of a message, `tool_response`, `tool_input` and every command stay unread.
23
21
  */
24
22
  static map(opts: { input: unknown }): IHookEvent | undefined {
25
23
  const { input } = opts;
@@ -39,12 +37,6 @@ export class EventHook {
39
37
  };
40
38
  }
41
39
 
42
- case ClaudeHookEvents.STOP: {
43
- return input.stop_hook_active === true
44
- ? undefined
45
- : { kind: EventKinds.SESSION_STOP, summary: 'turn ended' };
46
- }
47
-
48
40
  case ClaudeHookEvents.SUBAGENT_STOP: {
49
41
  return {
50
42
  kind: EventKinds.SUBAGENT_STOP,
@@ -67,9 +59,7 @@ export class EventHook {
67
59
  }
68
60
 
69
61
  case ClaudeHookEvents.POST_TOOL_USE: {
70
- return input.tool_name === ClaudeHookEvents.SEND_MESSAGE_TOOL
71
- ? EventHook.mapSend({ input })
72
- : { kind: EventKinds.TOOL_TICK, summary: EventConstants.TOOL_TICK_LABEL };
62
+ return EventHook.mapSend({ input });
73
63
  }
74
64
 
75
65
  default: {
@@ -125,36 +115,6 @@ export class EventHook {
125
115
  };
126
116
  }
127
117
 
128
- /**
129
- * Whether this session may write a tick now: the first call of each window creates the window's stamp and wins; a
130
- * call that finds the stamp already there loses. `wx` makes that one step, so calls at the same instant cannot both win.
131
- */
132
- private static takeTick(opts: { root: string; session: string; now: number }): boolean {
133
- const folder = join(opts.root, EventConstants.TICK_FOLDER);
134
- const window = Math.floor(opts.now / (EventConstants.TICK_SECONDS * 1000));
135
- const stamp = join(folder, `${opts.session.replace(/[^\w-]/g, '_') || 'session'}.${window}`);
136
-
137
- mkdirSync(folder, { recursive: true });
138
-
139
- try {
140
- writeFileSync(stamp, '', { flag: 'wx' });
141
- } catch (error) {
142
- if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
143
- return false;
144
- }
145
-
146
- throw error;
147
- }
148
-
149
- for (const name of readdirSync(folder)) {
150
- if (Number(name.slice(name.lastIndexOf('.') + 1)) < window) {
151
- rmSync(join(folder, name), { force: true });
152
- }
153
- }
154
-
155
- return true;
156
- }
157
-
158
118
  /**
159
119
  * Logs what a payload stands for, when the manifest says the log is on. Returns the line it wrote.
160
120
  * `root` is the project, where the manifest is; the flow comes from the message, else the branch at the
@@ -178,17 +138,6 @@ export class EventHook {
178
138
  return undefined;
179
139
  }
180
140
 
181
- if (
182
- mapped.kind === EventKinds.TOOL_TICK &&
183
- !EventHook.takeTick({
184
- root: opts.root,
185
- session: text({ value: opts.input.session_id }),
186
- now: opts.now ?? Date.now(),
187
- })
188
- ) {
189
- return undefined;
190
- }
191
-
192
141
  const cwd = text({ value: opts.input.cwd }) || opts.root;
193
142
  const flowId =
194
143
  (mapped.flowText === undefined ? undefined : EventFlow.fromText({ text: mapped.flowText })) ??
@@ -8,15 +8,53 @@ export class EventText {
8
8
  let text = opts.text;
9
9
 
10
10
  for (const pattern of EventSecrets.PATTERNS) {
11
- text = text.replace(pattern, EventConstants.REDACTED);
11
+ // Group 1, when the pattern has one, is kept; without it the second argument is the offset, a number.
12
+ text = text.replace(pattern, (_match: string, kept: unknown) =>
13
+ typeof kept === 'string' ? `${kept}${EventConstants.REDACTED}` : EventConstants.REDACTED,
14
+ );
12
15
  }
13
16
 
14
17
  return text
15
- .replace(EventSecrets.URL_USERINFO, `$1${EventConstants.REDACTED}@`)
16
18
  .replace(EventSecrets.ASSIGNMENT, `$1=${EventConstants.REDACTED}`)
17
19
  .replace(EventSecrets.SPOKEN, `$1 is ${EventConstants.REDACTED}`);
18
20
  }
19
21
 
22
+ /**
23
+ * The first `max` characters of `text`, redacted. Only the start of a long text is read, enough of it that a secret
24
+ * across the cut at `max` is whole when it is redacted; the word the read cuts through is dropped, not read in half.
25
+ * When the read holds no space and the redaction shrank it into view, the result ends at its last redaction instead.
26
+ */
27
+ static redactHead(opts: { text: string; max: number }): string {
28
+ const length = Math.max(
29
+ opts.max * EventConstants.REDACT_SCAN.factor,
30
+ EventConstants.REDACT_SCAN.min,
31
+ );
32
+ let head = opts.text;
33
+ let isEdgeCut = false;
34
+
35
+ if (head.length > length) {
36
+ head = head.slice(0, length).replace(/[\uD800-\uDBFF]$/, '');
37
+
38
+ const lastSpace = head.lastIndexOf(' ');
39
+
40
+ if (lastSpace > 0) {
41
+ head = head.slice(0, lastSpace);
42
+ } else {
43
+ isEdgeCut = true;
44
+ }
45
+ }
46
+
47
+ const redacted = EventText.redact({ text: head });
48
+ const characters = Array.from(redacted);
49
+ const lastRedaction = redacted.lastIndexOf(EventConstants.REDACTED);
50
+
51
+ if (isEdgeCut && characters.length <= opts.max && lastRedaction >= 0) {
52
+ return redacted.slice(0, lastRedaction + EventConstants.REDACTED.length);
53
+ }
54
+
55
+ return characters.slice(0, opts.max).join('');
56
+ }
57
+
20
58
  /** `text` with each run of control characters (C0, DEL and C1) replaced by one space: what a reader prints is never an escape sequence. */
21
59
  static stripControl(opts: { text: string }): string {
22
60
  let stripped = '';
@@ -64,9 +102,6 @@ export class EventText {
64
102
  static oneLine(opts: { text: string; max: number }): string {
65
103
  const flat = EventText.stripControl({ text: opts.text }).replace(/\s+/g, ' ').trim();
66
104
 
67
- return Array.from(EventText.redact({ text: flat }))
68
- .slice(0, opts.max)
69
- .join('')
70
- .trim();
105
+ return EventText.redactHead({ text: flat, max: opts.max }).trim();
71
106
  }
72
107
  }