@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
@@ -0,0 +1,41 @@
1
+ /** The `VULCAN_` and `CLAUDE_` environment variables (and `CLAUDECODE`) the cli reads; it reads others, such as `HOME` and `TMPDIR`, that are not its own. The test of this class keeps the list complete, and the generated reference is to read the comment above each name. */
2
+ export class EnvVariables {
3
+ /** The name of the writer of an event line; it wins over the name Claude Code gave the session. */
4
+ static readonly VULCAN_ACTOR = 'VULCAN_ACTOR';
5
+ /** `off` turns the daily automatic clean of `.agents/local/` off for the shell. */
6
+ static readonly VULCAN_AUTO_CLEAN = 'VULCAN_AUTO_CLEAN';
7
+ /** `off` takes the session out of the owner reply shape; `vulcan doctor` notes it when the shell has it. */
8
+ static readonly VULCAN_OWNER_REPLY = 'VULCAN_OWNER_REPLY';
9
+ /** `off` switches the guard hooks off for one session. */
10
+ static readonly VULCAN_GUARDS = 'VULCAN_GUARDS';
11
+ /** `deny` makes every guard refuse what it would ask a person about; the strictest of this and `guard.asks` holds, so the project cannot loosen it. Set it where the agent is launched. */
12
+ static readonly VULCAN_GUARD_ASKS = 'VULCAN_GUARD_ASKS';
13
+ /** `deny` makes `guard-outside` refuse a write outside the project; the strictest of this and `guard.outside` holds. Set it where the agent is launched. */
14
+ static readonly VULCAN_GUARD_OUTSIDE = 'VULCAN_GUARD_OUTSIDE';
15
+ /** `1` makes `init`, `add` and `upgrade` print the install, `git init`, `sync` and the checks as skipped; for tests. */
16
+ static readonly VULCAN_NO_INSTALL = 'VULCAN_NO_INSTALL';
17
+ /** Set by `vulcan x` for okf and atlas: the resolved project config as JSON. */
18
+ static readonly VULCAN_CONFIG = 'VULCAN_CONFIG';
19
+ /** Set by `vulcan x` for atlas: the manifest, rendered fresh from the config on each run. */
20
+ static readonly VULCAN_MANIFEST = 'VULCAN_MANIFEST';
21
+ /** Set by `vulcan x` for okf and atlas: the project root. */
22
+ static readonly VULCAN_PROJECT_ROOT = 'VULCAN_PROJECT_ROOT';
23
+ /** Replaces the `bun` that `init` and `add` run; for tests. */
24
+ static readonly VULCAN_BUN = 'VULCAN_BUN';
25
+ /** Replaces the `git` that `init` and `add` run; for tests. */
26
+ static readonly VULCAN_GIT = 'VULCAN_GIT';
27
+ /** The dist-tags of `@venizia/vulcan` as JSON, in place of the registry read of `upgrade --nightly`; for tests. */
28
+ static readonly VULCAN_DIST_TAGS = 'VULCAN_DIST_TAGS';
29
+ /** The project root, set by Claude Code for its hooks and by the guard extension for the hooks it runs; without it the hooks use the working directory. */
30
+ static readonly CLAUDE_PROJECT_DIR = 'CLAUDE_PROJECT_DIR';
31
+ /** Where Claude Code puts its task output; the launch file points it at `.agents/local/tmp`, and `vulcan doctor` warns when it points elsewhere. */
32
+ static readonly CLAUDE_CODE_TMPDIR = 'CLAUDE_CODE_TMPDIR';
33
+ /** The file Claude Code hands a start hook to export variables from; the session-start hook appends `export TMPDIR=...` to it. */
34
+ static readonly CLAUDE_ENV_FILE = 'CLAUDE_ENV_FILE';
35
+ /** The id of the running Claude Code session, used to find the session's name for the event actor. */
36
+ static readonly CLAUDE_CODE_SESSION_ID = 'CLAUDE_CODE_SESSION_ID';
37
+ /** The folder whose `sessions/*.json` names the sessions (default `~/.claude`), read to find the session's name. */
38
+ static readonly CLAUDE_CONFIG_DIR = 'CLAUDE_CONFIG_DIR';
39
+ /** Set by Claude Code in the shell of a session it starts; `vulcan doctor` uses it to know it runs inside one. */
40
+ static readonly CLAUDECODE = 'CLAUDECODE';
41
+ }
@@ -1,4 +1,5 @@
1
1
  export * from './constants.ts';
2
+ export * from './env-variables.ts';
2
3
  export * from './paths.ts';
3
4
  export * from './types.ts';
4
5
  export * from './json.ts';
@@ -1,7 +1,6 @@
1
1
  /**
2
2
  * The folders a project keeps its apps and shared packages in: the `layout` of the config and of the
3
- * manifest. One validator for the schema, `add`, `doctor` and `guard-package`, so none of them trusts
4
- * another. It imports nothing: `guard-package` is a hook that must run when everything else is broken.
3
+ * manifest. One validator for the schema, `add` and `doctor`, so none of them trusts another.
5
4
  */
6
5
 
7
6
  /** A folder, or a list of folders, as the layout holds it; a string stays valid. */
@@ -11,7 +10,7 @@ export interface ILayout {
11
10
  backend?: TLayoutValue;
12
11
  frontend?: TLayoutValue;
13
12
  shared?: TLayoutValue;
14
- /** Folders the layout deliberately does not manage: packages there are not app targets and are not guarded. */
13
+ /** Folders the layout deliberately does not manage: packages there are not app targets. */
15
14
  other?: TLayoutValue;
16
15
  }
17
16
 
@@ -29,7 +28,7 @@ export class LayoutKeys {
29
28
  static readonly FRONTEND = 'frontend';
30
29
  static readonly SHARED = 'shared';
31
30
  static readonly OTHER = 'other';
32
- /** The keys `add` can target and `guard-package` guards. */
31
+ /** The keys `add` can target. */
33
32
  static readonly MANAGED = [this.BACKEND, this.FRONTEND, this.SHARED] as const;
34
33
  static readonly ALL = [...this.MANAGED, this.OTHER] as const;
35
34
  }
@@ -4,4 +4,9 @@ export class RecordValue {
4
4
  static isRecord(value: unknown): value is Record<string, unknown> {
5
5
  return typeof value === 'object' && value !== null && !Array.isArray(value);
6
6
  }
7
+
8
+ /** The value when it is a string, else the empty string. */
9
+ static textOf(opts: { value: unknown }): string {
10
+ return typeof opts.value === 'string' ? opts.value : '';
11
+ }
7
12
  }
@@ -37,27 +37,6 @@ export class CodingAgents {
37
37
  }
38
38
  }
39
39
 
40
- /** Claude Code hook events a project may add a hook to. */
41
- export class HookEvents {
42
- static readonly PRE_TOOL_USE = 'PreToolUse';
43
- static readonly POST_TOOL_USE = 'PostToolUse';
44
- static readonly USER_PROMPT_SUBMIT = 'UserPromptSubmit';
45
- static readonly SESSION_START = 'SessionStart';
46
- static readonly STOP = 'Stop';
47
-
48
- static readonly SCHEME_SET = new Set<string>([
49
- this.PRE_TOOL_USE,
50
- this.POST_TOOL_USE,
51
- this.USER_PROMPT_SUBMIT,
52
- this.SESSION_START,
53
- this.STOP,
54
- ]);
55
-
56
- static isValid(value: string): boolean {
57
- return this.SCHEME_SET.has(value);
58
- }
59
- }
60
-
61
40
  export class ConfigConstants {
62
41
  static readonly DIRECTORY = '.configs';
63
42
  /** The one config file name, under `.configs/`. */
@@ -71,7 +50,6 @@ export class ConfigConstants {
71
50
  'V-P-05',
72
51
  'V-P-06',
73
52
  'V-B-04',
74
- 'V-W-04',
75
53
  'V-C-02',
76
54
  'V-C-09',
77
55
  'V-C-10',
@@ -80,3 +58,31 @@ export class ConfigConstants {
80
58
  'V-B-09',
81
59
  ];
82
60
  }
61
+
62
+ /** The placeholders a release template (`atlas.tagPattern`, `atlas.legacyTagPatterns`) knows; any other `<word>` would be read as literal text and match no tag. */
63
+ export class TemplatePlaceholders {
64
+ static readonly ALLOWED = ['dir', 'version', 'issue', 'date'];
65
+ private static readonly PATTERN = /<([^<>]*)>/g;
66
+
67
+ /** The `<word>` placeholders of the template that are not allowed, each once, in the order they appear. */
68
+ static unknownIn(opts: { template: string }): string[] {
69
+ const found = [...opts.template.matchAll(TemplatePlaceholders.PATTERN)].map(
70
+ (match) => match[1] ?? '',
71
+ );
72
+
73
+ return [...new Set(found)].filter((word) => !TemplatePlaceholders.ALLOWED.includes(word));
74
+ }
75
+
76
+ /** What the config error says: the placeholders it does not know, the ones it does, and what replaces `<package>`. */
77
+ static problemOf(opts: { unknown: string[] }): string {
78
+ const named = opts.unknown.map((word) => `<${word}>`).join(', ');
79
+ const hint = opts.unknown.includes('package')
80
+ ? ' <dir> replaces <package>: it is the package directory.'
81
+ : '';
82
+ const allowed = TemplatePlaceholders.ALLOWED.map((word) => `<${word}>`).join(', ');
83
+
84
+ const verb = opts.unknown.length === 1 ? 'is not a placeholder' : 'are not placeholders';
85
+
86
+ return `${named} ${verb} of a release template (${allowed}).${hint}`;
87
+ }
88
+ }
@@ -12,7 +12,29 @@ type TLoadResult =
12
12
  const describeError = (opts: { error: unknown }): string =>
13
13
  opts.error instanceof Error ? opts.error.message : String(opts.error);
14
14
 
15
+ /** Finds and loads the project `vulcan.config.*` file and reports an unreadable one; used by `vulcan sync`, `vulcan doctor` and the session hooks. */
15
16
  export class ConfigLoader {
17
+ /**
18
+ * What a hook says when the project has a config this VULCAN could not read (a key from a newer release, a
19
+ * failed import) and it falls back to defaults: the first problem and the way out. `undefined` when the config
20
+ * was read, or when the project has none (nothing was ignored).
21
+ */
22
+ static unreadableNote(opts: { loaded: TLoadResult }): string | undefined {
23
+ const { loaded } = opts;
24
+
25
+ if (loaded.ok || loaded.file === undefined) {
26
+ return undefined;
27
+ }
28
+
29
+ // A schema error is "<file>: invalid config" and then one line per issue: the first issue says more than the
30
+ // head. Any other failure (an import that threw, no default export) is told by its head line, whatever follows.
31
+ const [head = '', first = ''] = loaded.error.split('\n');
32
+ const problem =
33
+ head.endsWith('invalid config') && first.trim() !== '' ? first.trim() : head.trim();
34
+
35
+ return `the project config could not be read by this VULCAN, so its defaults apply (${problem}). Run \`vulcan doctor\`; a config newer than this VULCAN needs \`vulcan upgrade\``;
36
+ }
37
+
16
38
  /** `.configs/vulcan.config.mts` when the project has one. */
17
39
  static findFile(opts: { root: string }): string | undefined {
18
40
  const file = join(opts.root, ConfigConstants.DIRECTORY, ConfigConstants.FILE);