@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,8 +1,9 @@
1
- const ATLAS_BLOCK_START =
2
- '<!-- vulcan:atlas:start - generated by vulcan sync from .configs/vulcan.config.*; do not edit -->';
3
- const ATLAS_BLOCK_END = '<!-- vulcan:atlas:end -->';
4
- const START_PREFIX = '<!-- vulcan:atlas:start';
5
- const MUST_READ = '## Must read first';
1
+ import { GeneratedBlock } from './generated-block.ts';
2
+
3
+ const { start: ATLAS_BLOCK_START, end: ATLAS_BLOCK_END } = GeneratedBlock.markersOf({
4
+ name: 'atlas',
5
+ origin: '.configs/vulcan.config.*',
6
+ });
6
7
 
7
8
  export class AtlasBlock {
8
9
  /**
@@ -24,32 +25,8 @@ export class AtlasBlock {
24
25
  ].join('\n');
25
26
  }
26
27
 
27
- /**
28
- * Puts the block into AGENTS.md: rewritten between its markers when it is there, else inserted
29
- * before the section that follows "Must read first", else appended. Text outside is never touched.
30
- */
28
+ /** Puts the block into AGENTS.md; see `GeneratedBlock.merge`. */
31
29
  static merge(opts: { text: string; block: string }): { changed: boolean; text: string } {
32
- const start = opts.text.indexOf(START_PREFIX);
33
- const end = opts.text.indexOf(ATLAS_BLOCK_END);
34
- let text: string;
35
-
36
- if (opts.text === '') {
37
- text = opts.block;
38
- } else if (start !== -1 && end > start) {
39
- text = `${opts.text.slice(0, start)}${opts.block.trimEnd()}${opts.text.slice(end + ATLAS_BLOCK_END.length)}`;
40
- } else {
41
- const heading = opts.text.indexOf(MUST_READ);
42
- const next = heading === -1 ? -1 : opts.text.indexOf('\n## ', heading + MUST_READ.length);
43
-
44
- if (next === -1) {
45
- text = `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${opts.block}`;
46
- } else {
47
- const at = next + 1;
48
-
49
- text = `${opts.text.slice(0, at)}${opts.block}\n${opts.text.slice(at)}`;
50
- }
51
- }
52
-
53
- return { changed: text !== opts.text, text };
30
+ return GeneratedBlock.merge({ ...opts, name: 'atlas' });
54
31
  }
55
32
  }
@@ -22,7 +22,7 @@ const GUARD_COMMAND = [
22
22
  'd=$(git rev-parse --show-toplevel 2>/dev/null || pwd);',
23
23
  `f="$d/node_modules/@venizia/vulcan/base/hooks/${GUARD_SCRIPT}";`,
24
24
  'if [ -f "$f" ] && command -v bun >/dev/null 2>&1; then',
25
- 'in=$(cat); out=$(printf \'%s\' "$in" | bun "$f"); s=$?;',
25
+ 'in=$(cat); out=$(printf \'%s\' "$in" | bun --no-env-file --config=/dev/null "$f"); s=$?;',
26
26
  `if [ "$s" -eq 0 ]; then printf '%s' "$out"; exit 0; fi;`,
27
27
  `printf '%s\\n' '${DENY_ON_CRASH}'; exit 0; fi;`,
28
28
  'cat >/dev/null; echo "vulcan: the guards cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes" >&2',
@@ -0,0 +1,52 @@
1
+ const MUST_READ = '## Must read first';
2
+
3
+ /** A block `vulcan sync` writes into AGENTS.md between its own markers, `<!-- vulcan:<name>:start ... -->` to `<!-- vulcan:<name>:end -->`. */
4
+ export class GeneratedBlock {
5
+ static markersOf(opts: { name: string; origin: string }): { start: string; end: string } {
6
+ return {
7
+ start: `<!-- vulcan:${opts.name}:start - generated by vulcan sync from ${opts.origin}; do not edit -->`,
8
+ end: `<!-- vulcan:${opts.name}:end -->`,
9
+ };
10
+ }
11
+
12
+ /**
13
+ * Puts the block into AGENTS.md: rewritten between its markers when it is there, else inserted
14
+ * before the section that follows "Must read first", else appended. Text outside is never touched.
15
+ */
16
+ static merge(opts: { text: string; block: string; name: string }): {
17
+ changed: boolean;
18
+ text: string;
19
+ } {
20
+ const startPrefix = `<!-- vulcan:${opts.name}:start`;
21
+ const endMarker = `<!-- vulcan:${opts.name}:end -->`;
22
+ const start = opts.text.indexOf(startPrefix);
23
+ const end = opts.text.indexOf(endMarker);
24
+ let text: string;
25
+
26
+ if (opts.text === '') {
27
+ text = opts.block;
28
+ } else if (start !== -1 && end > start) {
29
+ text = `${opts.text.slice(0, start)}${opts.block.trimEnd()}${opts.text.slice(end + endMarker.length)}`;
30
+ } else {
31
+ const heading = opts.text.indexOf(MUST_READ);
32
+ // The section that follows, or another generated block, whichever comes first.
33
+ const nexts =
34
+ heading === -1
35
+ ? []
36
+ : ['\n## ', '\n<!-- vulcan:']
37
+ .map((marker) => opts.text.indexOf(marker, heading + MUST_READ.length))
38
+ .filter((at) => at !== -1);
39
+ const next = nexts.length === 0 ? -1 : Math.min(...nexts);
40
+
41
+ if (next === -1) {
42
+ text = `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${opts.block}`;
43
+ } else {
44
+ const at = next + 1;
45
+
46
+ text = `${opts.text.slice(0, at)}${opts.block}\n${opts.text.slice(at)}`;
47
+ }
48
+ }
49
+
50
+ return { changed: text !== opts.text, text };
51
+ }
52
+ }
@@ -13,16 +13,35 @@ const ASK_ON_CRASH = JSON.stringify({
13
13
  'The VULCAN guard crashed, so this call was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.',
14
14
  });
15
15
 
16
+ /** The answer of a crashed adapter where every ask is a deny: `VULCAN_GUARD_ASKS=deny`, `guard.asks: 'deny'` or a manifest that cannot be read. */
17
+ const DENY_ON_CRASH = JSON.stringify({
18
+ decision: 'deny',
19
+ reason:
20
+ 'The VULCAN guard crashed, so this call was not checked, and every call that would need a human to confirm it is denied here (VULCAN_GUARD_ASKS=deny, guard.asks: deny, or a manifest that cannot be read). Nothing was run: hand this to the owner.',
21
+ });
22
+
23
+ /**
24
+ * Succeeds when the environment or the manifest (the hooks file's folder is `.agents`) holds every ask: `VULCAN_GUARD_ASKS=deny`,
25
+ * `guard.asks: 'deny'`, or a manifest that exists and does not parse as an object.
26
+ */
27
+ const IS_HELD = [
28
+ 'm="$PWD/vulcan.manifest.json";',
29
+ '[ "$VULCAN_GUARD_ASKS" = deny ]',
30
+ `|| { [ -f "$m" ] && ! M="$m" bun --no-env-file --config=/dev/null -e 'const v = JSON.parse(require("node:fs").readFileSync(process.env.M, "utf8")); if (typeof v !== "object" || v === null || Array.isArray(v)) process.exit(1)' >/dev/null 2>&1; }`,
31
+ `|| grep -Eq '"asks" *: *"deny"' "$m" 2>/dev/null;`,
32
+ ].join(' ');
33
+
16
34
  /**
17
35
  * The hook command. Antigravity runs it from the folder of the hooks file (`.agents`), so the install is
18
- * `../node_modules`. A missing package or bun passes with a note; a script that started and crashed asks.
36
+ * `../node_modules`. A missing package or bun passes with a note (unlike the Claude wrappers, which block); a script that started
37
+ * and crashed asks, or denies where every ask is held.
19
38
  */
20
39
  const GUARD_COMMAND = [
21
40
  'f="$PWD/../node_modules/@venizia/vulcan/base/hooks/antigravity-guards.ts";',
22
41
  'if [ -f "$f" ] && command -v bun >/dev/null 2>&1; then',
23
- 'in=$(cat); out=$(printf \'%s\' "$in" | bun "$f"); s=$?;',
42
+ 'in=$(cat); out=$(printf \'%s\' "$in" | bun --no-env-file --config=/dev/null "$f"); s=$?;',
24
43
  `if [ "$s" -eq 0 ]; then printf '%s' "$out"; exit 0; fi;`,
25
- `printf '%s\\n' '${ASK_ON_CRASH}'; exit 0; fi;`,
44
+ `${IS_HELD} if [ $? -eq 0 ]; then printf '%s\\n' '${DENY_ON_CRASH}'; else printf '%s\\n' '${ASK_ON_CRASH}'; fi; exit 0; fi;`,
26
45
  'cat >/dev/null; echo "vulcan: the guards cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes" >&2;',
27
46
  `printf '%s\\n' '{"decision":"allow"}'`,
28
47
  ].join(' ');
@@ -5,7 +5,9 @@ export * from './prompt.ts';
5
5
  export * from './resolve.ts';
6
6
  export * from './table.ts';
7
7
  export * from './render.ts';
8
+ export * from './generated-block.ts';
8
9
  export * from './atlas-block.ts';
10
+ export * from './rules-block.ts';
9
11
  export * from './exclude.ts';
10
12
  export * from './hooks-json.ts';
11
13
  export * from './codex-hooks.ts';
@@ -23,7 +23,10 @@ export class McpConfig {
23
23
  return false;
24
24
  }
25
25
 
26
- if (JSON.stringify(entry) === JSON.stringify(McpConfig.canonicalAtlasEntry())) {
26
+ if (
27
+ JSON.stringify(entry) === JSON.stringify(McpConfig.canonicalAtlasEntry()) ||
28
+ JSON.stringify(entry) === JSON.stringify(McpConfig.legacyAtlasEntry())
29
+ ) {
27
30
  return true;
28
31
  }
29
32
 
@@ -74,9 +77,19 @@ export class McpConfig {
74
77
 
75
78
  /**
76
79
  * The atlas server as the root `.mcp.json` starts it: the same for every developer, so it is relative.
77
- * Claude Code, omp and Copilot CLI launch a project server from the project root.
80
+ * Claude Code, omp and Copilot CLI launch a project server from the project root. It runs the bin the project
81
+ * links by its path: no package is fetched and no `$PATH` is searched (a bunx command would run a copy an earlier bunx
82
+ * saved when the bin is not linked, and npm gives the name `vulcan` to an unrelated package, V-S-08).
78
83
  */
79
84
  static canonicalAtlasEntry(): { command: string; args: string[] } {
85
+ return {
86
+ command: 'bun',
87
+ args: ['node_modules/.bin/vulcan', 'x', 'atlas', 'mcp', '--root', '.'],
88
+ };
89
+ }
90
+
91
+ /** The entry earlier versions wrote: recognised as sync's own, so a sync rewrites it, and named stale by `vulcan doctor`. */
92
+ static legacyAtlasEntry(): { command: string; args: string[] } {
80
93
  return {
81
94
  command: 'bun',
82
95
  args: ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'],
@@ -7,6 +7,7 @@ export const NO_TTY_HINT = `vulcan sync: no agents chosen on this machine - wrot
7
7
 
8
8
  type TParsed = { ok: true; agents: string[] } | { ok: false; error: string };
9
9
 
10
+ /** Parses and resolves the list of agent tools a project targets, from the flag, the config or a prompt; used by `vulcan agents`, `vulcan sync` and `vulcan doctor`. */
10
11
  export class AgentSelection {
11
12
  private static fromList(opts: {
12
13
  value: string;
@@ -0,0 +1,92 @@
1
+ import { RuleParser } from '../rules/index.ts';
2
+ import type { ISlot } from '../rules/index.ts';
3
+ import { GeneratedBlock } from './generated-block.ts';
4
+
5
+ const { start: RULES_BLOCK_START, end: RULES_BLOCK_END } = GeneratedBlock.markersOf({
6
+ name: 'rules',
7
+ origin: 'the base rules and .configs/vulcan.config.*',
8
+ });
9
+
10
+ /** A summary of a rule shorter than this takes the next sentence too (`Approval has a card.`). */
11
+ const SHORT_SUMMARY_CHARACTERS = 40;
12
+
13
+ export class RulesBlock {
14
+ /** What the block may weigh with its markers: Claude Code gives a hook's output whole up to about 10,000 bytes (measured), so 6 KB leaves room for the rest of the session's context, and each rule line carries its whole first sentence. */
15
+ static readonly MAX_BYTES = 6144;
16
+
17
+ /** A rule row as one line: its whole first sentence, plain, with the next one when the first is only a title. */
18
+ static summaryOf(opts: { row: string }): string {
19
+ const cell = (opts.row.split('|')[2] ?? '').replaceAll('**', '').replace(/\s+/g, ' ').trim();
20
+ const [first = '', second = ''] = cell.split(/(?<=[.!?])\s+/);
21
+ return first.length < SHORT_SUMMARY_CHARACTERS ? `${first} ${second}`.trim() : first;
22
+ }
23
+
24
+ /** One line for each slot of the base rules: the option this project chose, or that it has not chosen. */
25
+ static slotLinesOf(opts: {
26
+ slots: Record<string, ISlot>;
27
+ choices: Record<string, string | undefined>;
28
+ command: string;
29
+ }): string[] {
30
+ return Object.entries(opts.slots).map(([id, slot]) => {
31
+ const choice = opts.choices[id];
32
+
33
+ return choice === undefined
34
+ ? `- ${id}: this project has **not chosen** - run \`${opts.command} doctor\``
35
+ : `- ${id}: this project: \`${choice}\` - ${slot.options[choice]?.text ?? `unknown option - run \`${opts.command} doctor\``}`;
36
+ });
37
+ }
38
+
39
+ /**
40
+ * The rules an agent must not skip, from the rules themselves: this project's slot choices, the write
41
+ * boundaries, where scratch files go, and the rules sessions drop most (from the last, as many as fit
42
+ * `MAX_BYTES`). `rows` are the base and project rule rows.
43
+ */
44
+ static render(opts: {
45
+ rows: string[];
46
+ slotLines: string[];
47
+ /** The rule packs the project follows: each one's name, the path of its file and the IDs of its rules. */
48
+ packs?: { name: string; path: string; ids: string[] }[];
49
+ /** The project's temp folder, relative to its root: the block is committed, so it holds no path of one machine. */
50
+ tmp: string;
51
+ oftenDropped: string[];
52
+ }): string {
53
+ const bullet = (id: string): string | undefined => {
54
+ const row = opts.rows.find((item) => RuleParser.parseIds({ markdown: item })[0] === id);
55
+
56
+ return row === undefined ? undefined : `- ${id}: ${RulesBlock.summaryOf({ row })}`;
57
+ };
58
+ const dropped = opts.oftenDropped.map((id) => bullet(id)).filter((line) => line !== undefined);
59
+ const build = (count: number): string =>
60
+ [
61
+ RULES_BLOCK_START,
62
+ '## Rules that must not be skipped',
63
+ '',
64
+ 'Full text, cited by ID: `node_modules/@venizia/vulcan/base/rules.md` (V-*) and `.agents/rules.md`.',
65
+ '',
66
+ ...opts.slotLines,
67
+ ...(opts.packs ?? []).map(
68
+ (pack) =>
69
+ `- Pack \`${pack.name}\` (\`${pack.path}\`): this project follows it - ${pack.ids.join(', ')}.`,
70
+ ),
71
+ ...['V-W-02', 'V-W-03', 'V-W-06']
72
+ .map((id) => bullet(id))
73
+ .filter((line) => line !== undefined),
74
+ `- V-B-08: Scratch and temporary files go in \`${opts.tmp}\`, never /tmp or the scratchpad folder a tool offers. Claude Code sets \`TMPDIR\` to it; elsewhere \`export TMPDIR="$PWD/${opts.tmp}"\` from the project root.`,
75
+ ...dropped.slice(0, count),
76
+ RULES_BLOCK_END,
77
+ '',
78
+ ].join('\n');
79
+ let count = dropped.length;
80
+
81
+ while (count > 0 && Buffer.byteLength(build(count)) > RulesBlock.MAX_BYTES) {
82
+ count -= 1;
83
+ }
84
+
85
+ return build(count);
86
+ }
87
+
88
+ /** Puts the block into AGENTS.md; see `GeneratedBlock.merge`. */
89
+ static merge(opts: { text: string; block: string }): { changed: boolean; text: string } {
90
+ return GeneratedBlock.merge({ ...opts, name: 'rules' });
91
+ }
92
+ }
@@ -6,17 +6,29 @@ import type { ICommandContext } from '../common/index.ts';
6
6
  import { FlowId } from '../events/flow-id.ts';
7
7
  import { EventLog } from '../events/log.ts';
8
8
  import { EventSettings } from '../events/settings.ts';
9
- import { BoardConstants, BoardFlags, BoardServe, BoardStates } from './common/index.ts';
10
- import type { IBoardData, IBoardEvent } from './common/index.ts';
9
+ import { ProjectTmp } from '../hooks/project-tmp.ts';
10
+ import { ThemeTokens } from '../theme/index.ts';
11
+ import type { IThemeTokens } from '../theme/index.ts';
12
+ import {
13
+ BoardConstants,
14
+ BoardFlags,
15
+ BoardServe,
16
+ BoardStates,
17
+ ProviderTypes,
18
+ } from './common/index.ts';
19
+ import type { IBoardData, IBoardEvent, IBoardProvider } from './common/index.ts';
11
20
  import { BoardFold } from './fold.ts';
12
21
  import { BoardGithub } from './github.ts';
22
+ import { BoardGitlab } from './gitlab.ts';
13
23
  import { BoardSettings } from './settings.ts';
14
24
  import { BoardPage } from './page.ts';
15
25
  import { BoardServer } from './server.ts';
16
26
 
17
27
  const SHARED_FLAGS = `[${BoardFlags.OPEN}] [${BoardFlags.SINCE} <date>] [${BoardFlags.DIR} <events folder>] [${BoardFlags.REPO} owner/name]... [${BoardFlags.NO_GITHUB}]`;
18
28
  const USAGE = `usage: vulcan board [${BoardFlags.OUT} <file>] ${SHARED_FLAGS}\n vulcan board ${BoardServe.COMMAND} [${BoardFlags.PORT} <n>] ${SHARED_FLAGS}`;
19
- const REPO_NAME = /^[\w.-]+\/[\w.-]+$/;
29
+
30
+ /** Starts the program that opens the browser; `target` is what it is given, `fallback` what a person is told to open if it fails. */
31
+ type TBoardOpener = (opts: { target: string; fallback: string }) => void;
20
32
 
21
33
  interface IBoardArgs {
22
34
  serve: boolean;
@@ -29,9 +41,9 @@ interface IBoardArgs {
29
41
  noGithub: boolean;
30
42
  }
31
43
 
32
- /** `vulcan board`: the flows of a project, from its event log and, when `gh` can read them, its pull requests, as one HTML file. */
44
+ /** `vulcan board`: the flows of a project, from its event log and, when `gh` or `glab` can read them, its pull requests, as one HTML file. */
33
45
  export class BoardCommand {
34
- static async run(opts: ICommandContext): Promise<number> {
46
+ static async run(opts: ICommandContext & { opener?: TBoardOpener }): Promise<number> {
35
47
  const args = BoardCommand.parse({ args: opts.args });
36
48
 
37
49
  if (typeof args === 'string') {
@@ -60,15 +72,22 @@ export class BoardCommand {
60
72
  ...(args.dir === undefined ? {} : { dir: resolve(opts.cwd, args.dir) }),
61
73
  });
62
74
  if (args.serve) {
63
- return BoardCommand.serve({ args, root, dir, sinceOf });
75
+ return BoardCommand.serve({
76
+ args,
77
+ root,
78
+ dir,
79
+ sinceOf,
80
+ opener: opts.opener ?? BoardCommand.open,
81
+ });
64
82
  }
65
83
 
66
84
  const data = BoardCommand.collect({ root, dir, since, args });
67
85
  const file = resolve(root, args.out ?? BoardConstants.DEFAULT_OUT);
86
+ const tokens = BoardCommand.tokensOf({ root });
68
87
 
69
88
  try {
70
89
  mkdirSync(dirname(file), { recursive: true });
71
- writeFileSync(file, BoardPage.render({ data }));
90
+ writeFileSync(file, BoardPage.render({ data, tokens }));
72
91
  } catch (error) {
73
92
  process.stderr.write(
74
93
  `board: cannot write ${file}: ${error instanceof Error ? error.message : String(error)}\n`,
@@ -84,34 +103,50 @@ export class BoardCommand {
84
103
  process.stdout.write(`${file}\n`);
85
104
 
86
105
  if (args.open) {
87
- BoardCommand.open({ target: file });
106
+ (opts.opener ?? BoardCommand.open)({ target: file, fallback: file });
88
107
  }
89
108
 
90
109
  return ExitCodes.OK;
91
110
  }
92
111
 
93
- /** The folded data of a project: its log since `since`, and GitHub unless it is left out or cannot be read. */
112
+ /** The design tokens of the project's manifest; a manifest the board cannot read says so on stderr and the default preset is used. */
113
+ private static tokensOf(opts: { root: string }): IThemeTokens {
114
+ const { tokens, warning } = ThemeTokens.read({ root: opts.root });
115
+
116
+ if (warning !== undefined) {
117
+ process.stderr.write(`board: ${warning}\n`);
118
+ }
119
+
120
+ return tokens;
121
+ }
122
+
123
+ /** The folded data of a project: its log since `since`, and GitHub or GitLab (by `provider`) unless it is left out or cannot be read. */
94
124
  static collect(opts: {
95
125
  root: string;
96
126
  dir: string;
97
127
  since: number;
98
128
  args: Pick<IBoardArgs, 'repos' | 'noGithub'>;
99
- /** The GitHub lines to use; with none, they are read here (unless `noGithub`). */
129
+ /** The GitHub or GitLab lines to use; with none, they are read here (unless `noGithub`). */
100
130
  github?: { events: IBoardEvent[]; note: string };
101
131
  /** The git user name, when the caller already has it; otherwise it is read from git. */
102
132
  readGitUser?: () => string | undefined;
103
133
  }): IBoardData {
104
134
  const read = EventLog.read({ dir: opts.dir, since: opts.since });
105
135
  const fromLog = BoardFold.fromLog({ events: read.events });
106
- const github =
107
- opts.github ??
108
- (opts.args.noGithub
109
- ? { events: [], note: 'github: left out (--no-github)' }
110
- : BoardGithub.read({ repos: opts.args.repos, cwd: opts.root, since: opts.since }));
111
136
  const settings = BoardSettings.read({
112
137
  root: opts.root,
113
138
  ...(opts.readGitUser === undefined ? {} : { readGitUser: opts.readGitUser }),
114
139
  });
140
+ const github =
141
+ opts.github ??
142
+ (opts.args.noGithub
143
+ ? { events: [], note: `${settings.provider.type}: left out (--no-github)` }
144
+ : BoardCommand.readHost({
145
+ repos: opts.args.repos,
146
+ cwd: opts.root,
147
+ since: opts.since,
148
+ provider: settings.provider,
149
+ }));
115
150
  // An older `F-n` is shown as `VULZ-<key>-n`; the log itself is never rewritten.
116
151
  const key = EventSettings.keyOf({ root: opts.root });
117
152
  const { flows, decisions } = BoardFold.fold({
@@ -148,22 +183,38 @@ export class BoardCommand {
148
183
  };
149
184
  }
150
185
 
186
+ private static readHost(opts: {
187
+ repos: string[];
188
+ cwd: string;
189
+ since: number;
190
+ provider: IBoardProvider;
191
+ }): { events: IBoardEvent[]; note: string } {
192
+ return opts.provider.type === ProviderTypes.GITLAB
193
+ ? BoardGitlab.read({ ...opts, host: opts.provider.host })
194
+ : BoardGithub.read(opts);
195
+ }
196
+
151
197
  /** `vulcan board serve`: the board on 127.0.0.1 that updates when the log does, until Ctrl+C. */
152
198
  private static async serve(opts: {
153
199
  args: IBoardArgs;
154
200
  root: string;
155
201
  dir: string;
156
202
  sinceOf: () => number;
203
+ opener: TBoardOpener;
157
204
  }): Promise<number> {
158
205
  const { args } = opts;
159
206
  const gitUser = BoardSettings.gitUserOf({ root: opts.root });
207
+ const { provider, hostname } = BoardSettings.read({
208
+ root: opts.root,
209
+ readGitUser: () => gitUser,
210
+ });
160
211
  let github: { events: IBoardEvent[]; note: string } | undefined;
161
212
  let readAt = 0;
162
213
  const collect = (): IBoardData => {
163
214
  const since = opts.sinceOf();
164
215
 
165
216
  if (!args.noGithub && Date.now() - readAt >= BoardServe.REFRESH_MS) {
166
- github = BoardGithub.read({ repos: args.repos, cwd: opts.root, since });
217
+ github = BoardCommand.readHost({ repos: args.repos, cwd: opts.root, since, provider });
167
218
  readAt = Date.now();
168
219
  }
169
220
 
@@ -179,12 +230,13 @@ export class BoardCommand {
179
230
  const port = args.port === undefined ? BoardServe.DEFAULT_PORT : Number(args.port);
180
231
 
181
232
  try {
182
- const { hostname } = BoardSettings.read({ root: opts.root, readGitUser: () => gitUser });
183
233
  const { url, fallback, note } = await BoardServer.start({
184
234
  port,
185
235
  dir: opts.dir,
186
236
  hostname,
187
237
  collect,
238
+ tokens: BoardCommand.tokensOf({ root: opts.root }),
239
+ openFolder: ProjectTmp.projectOf({ root: opts.root }),
188
240
  });
189
241
 
190
242
  if (note !== undefined) {
@@ -196,8 +248,14 @@ export class BoardCommand {
196
248
  );
197
249
  process.stdout.write(`${url}\n`);
198
250
 
199
- if (args.open) {
200
- BoardCommand.open({ target: url });
251
+ // The program that opens the browser gets a page that only the owner can read and that holds the
252
+ // token, never the token itself: its arguments are visible to other users of the machine.
253
+ const target = args.open ? BoardServer.openFile() : undefined;
254
+
255
+ if (target !== undefined) {
256
+ opts.opener({ target, fallback: url });
257
+ } else if (args.open) {
258
+ process.stderr.write(`board: could not open it; open ${url} yourself\n`);
201
259
  }
202
260
  } catch (error) {
203
261
  process.stderr.write(
@@ -264,7 +322,7 @@ export class BoardCommand {
264
322
  index++;
265
323
 
266
324
  if (arg === BoardFlags.REPO) {
267
- if (!REPO_NAME.test(value)) {
325
+ if (!BoardConstants.PROJECT_PATH.test(value)) {
268
326
  return `${BoardFlags.REPO} must look like owner/name, got '${value}'`;
269
327
  }
270
328
 
@@ -299,18 +357,22 @@ export class BoardCommand {
299
357
  return parsed;
300
358
  }
301
359
 
302
- private static open(opts: { target: string }): void {
303
- const program =
304
- process.platform === 'darwin'
305
- ? 'open'
306
- : process.platform === 'win32'
307
- ? 'explorer.exe'
308
- : 'xdg-open';
309
- const args = [opts.target];
310
- const hint = `board: could not open it; open ${opts.target} yourself\n`;
360
+ private static programOf(): string {
361
+ if (process.platform === 'darwin') {
362
+ return 'open';
363
+ }
364
+
365
+ return process.platform === 'win32' ? 'explorer.exe' : 'xdg-open';
366
+ }
367
+
368
+ private static open(opts: { target: string; fallback: string }): void {
369
+ const hint = `board: could not open it; open ${opts.fallback} yourself\n`;
311
370
 
312
371
  try {
313
- const child = spawn(program, args, { detached: true, stdio: 'ignore' });
372
+ const child = spawn(BoardCommand.programOf(), [opts.target], {
373
+ detached: true,
374
+ stdio: 'ignore',
375
+ });
314
376
 
315
377
  child.on('error', () => process.stderr.write(hint));
316
378
  child.unref();
@@ -87,6 +87,13 @@ export class BoardServe {
87
87
  static readonly TOKEN_PARAM = 't';
88
88
  static readonly PAGE_PATH = '/';
89
89
  static readonly STREAM_PATH = '/stream';
90
+ /** `--open` writes its page into a new folder whose name starts with this. */
91
+ static readonly OPEN_DIRECTORY_PREFIX = 'board-open-';
92
+ static readonly OPEN_FILE_NAME = 'index.html';
93
+ /** A folder of that kind this old was left by a run that did not stop, and is removed by the next. */
94
+ static readonly OPEN_STALE_MS = 60_000;
95
+ /** The longest the page stays when nothing reads the board. */
96
+ static readonly OPEN_FILE_TTL_MS = 15_000;
90
97
  static readonly MAX_STREAMS = 8;
91
98
  static readonly MAX_SNAPSHOT_BYTES = 20_000_000;
92
99
  static readonly HEARTBEAT_MS = 15_000;
@@ -119,6 +126,15 @@ export class BoardShapes {
119
126
 
120
127
  export class BoardSources {
121
128
  static readonly GITHUB = 'github';
129
+ static readonly GITLAB = 'gitlab';
130
+ /** The sources that are a code host: their lines carry people and bots that are no agent of the project. */
131
+ static readonly HOSTS = new Set<string>([this.GITHUB, this.GITLAB]);
132
+ }
133
+
134
+ /** The code host the board reads pull requests and checks from (`provider.type`). */
135
+ export class ProviderTypes {
136
+ static readonly GITHUB = 'github';
137
+ static readonly GITLAB = 'gitlab';
122
138
  }
123
139
 
124
140
  export class BoardConstants {
@@ -140,8 +156,18 @@ export class BoardConstants {
140
156
  static readonly DAY_MS = 24 * BoardConstants.HOUR_MS;
141
157
  static readonly TEMPLATE = 'templates/board.html';
142
158
  static readonly DATA_MARKER = '<!--BOARD_DATA-->';
159
+ /** Where the page takes the design tokens of the project (a `style` with the custom properties). */
160
+ static readonly TOKENS_MARKER = '<!--BOARD_TOKENS-->';
143
161
  static readonly GH_TIMEOUT_MS = 15_000;
144
162
  static readonly GH_LIMIT = 30;
163
+ /** `owner/name` on GitHub, `group/sub/name` of any depth on GitLab. */
164
+ static readonly PROJECT_PATH = /^[\w.-]+(?:\/[\w.-]+)+$/;
165
+ static readonly GITLAB_DEFAULT_HOST = 'gitlab.com';
166
+ /** A bare host name with an optional port: no scheme, path or credentials, so it can never carry a token elsewhere. */
167
+ static readonly GITLAB_HOST =
168
+ /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)*(?::\d{1,5})?$/;
169
+ /** How many pipelines have their jobs read. */
170
+ static readonly GITLAB_JOB_PIPELINES = 10;
145
171
  /** A `needs-owner` line whose whole summary is one of these is the harness waiting, not a person asking. */
146
172
  static readonly HARNESS_ASKS = new Set<string>([
147
173
  'idle_prompt',
@@ -1,8 +1,15 @@
1
1
  import type { TConstValue } from '../../common/index.ts';
2
2
  import type { IEventItem } from '../../events/common/index.ts';
3
- import type { BoardRoutes, BoardStates } from './constants.ts';
3
+ import type { BoardRoutes, BoardStates, ProviderTypes } from './constants.ts';
4
4
 
5
5
  export type TBoardState = TConstValue<typeof BoardStates>;
6
+ export type TProviderType = TConstValue<typeof ProviderTypes>;
7
+
8
+ /** The code host the board reads, with the host name GitLab is asked at. */
9
+ export interface IBoardProvider {
10
+ type: TProviderType;
11
+ host: string;
12
+ }
6
13
  export type TBoardRoute = TConstValue<typeof BoardRoutes>;
7
14
 
8
15
  export interface IBoardRef {
@@ -60,7 +67,7 @@ export type IBoardItem = IEventItem;
60
67
  export interface IBoardFlow {
61
68
  id: string;
62
69
  title: string;
63
- /** The title came from a `flow` line; a flow without one shows its first line and "no title yet". */
70
+ /** The title came from a `flow` line; a flow without one shows the words of its pull request or its first line, with no marker. */
64
71
  named: boolean;
65
72
  /** Why the flow exists, from the newest `flow` line that has one. */
66
73
  why?: string;
@@ -119,7 +126,7 @@ export interface IBoardData {
119
126
  shapes: Record<string, string>;
120
127
  /** The `board.agents` keys with no lane; absent when none is listed, and then every agent shows. */
121
128
  roster?: string[];
122
- /** A helper to the lane it rolls into. */
129
+ /** A helper to the listed name it works under; shown as a label on its own card. */
123
130
  lanes?: Record<string, string>;
124
131
  /** What `board.agents` says an agent is, by name: `Backend`. */
125
132
  roles?: Record<string, string>;
package/src/board/fold.ts CHANGED
@@ -623,7 +623,7 @@ export class BoardFold {
623
623
  }
624
624
 
625
625
  const pr = opts.events.find(
626
- (event) => event.kind === BoardKinds.PR && event.source === BoardSources.GITHUB,
626
+ (event) => event.kind === BoardKinds.PR && BoardSources.HOSTS.has(event.source),
627
627
  );
628
628
 
629
629
  return (pr ?? opts.events[0]).summary;
@@ -23,8 +23,7 @@ const FAILED = new Set([
23
23
  'ERROR',
24
24
  ]);
25
25
 
26
- const text = (opts: { value: unknown }): string =>
27
- typeof opts.value === 'string' ? opts.value : '';
26
+ const text = RecordValue.textOf;
28
27
 
29
28
  /** Pull requests, their checks and their reviews, read through `gh`: an extra for projects on GitHub. */
30
29
  export class BoardGithub {