@venizia/vulcan 0.4.10-0 → 0.4.10-2

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 (64) hide show
  1. package/base/claude/events.json +0 -1
  2. package/base/hooks/event.ts +4 -3
  3. package/base/hooks/guard-outside.ts +34 -15
  4. package/base/hooks/guard-remote-hosts.ts +13 -4
  5. package/base/rules.md +1 -1
  6. package/base/skills/build-a-feature/SKILL.md +11 -2
  7. package/base/skills/review-a-change/SKILL.md +10 -6
  8. package/base/skills/ship/SKILL.md +9 -4
  9. package/base/templates/board.html +844 -4240
  10. package/base/templates/pull-request.md +31 -0
  11. package/base/templates/trusted-hosts.local.example +11 -0
  12. package/base/templates/vulcan.config.mts +1 -0
  13. package/package.json +6 -4
  14. package/src/board/agent-setting.ts +43 -0
  15. package/src/board/command.ts +138 -17
  16. package/src/board/common/constants.ts +38 -1
  17. package/src/board/common/types.ts +40 -1
  18. package/src/board/fold.ts +106 -12
  19. package/src/board/github.ts +6 -3
  20. package/src/board/index.ts +2 -0
  21. package/src/board/schema.ts +32 -0
  22. package/src/board/server.ts +325 -0
  23. package/src/board/settings.ts +99 -17
  24. package/src/board/watch.ts +88 -0
  25. package/src/commands/help.command.ts +4 -3
  26. package/src/commands/init.command.ts +26 -1
  27. package/src/common/constants.ts +8 -0
  28. package/src/common/git-files.ts +11 -0
  29. package/src/common/index.ts +1 -0
  30. package/src/common/layout-folder.ts +1 -1
  31. package/src/config/schema.ts +33 -19
  32. package/src/create/common/constants.ts +1 -0
  33. package/src/create/dockerignore.ts +5 -3
  34. package/src/create/init-monorepo.ts +28 -4
  35. package/src/create/project-key.ts +60 -0
  36. package/src/create/workspace.ts +2 -1
  37. package/src/doctor/checks.ts +89 -2
  38. package/src/doctor/common/constants.ts +48 -0
  39. package/src/doctor/common/types.ts +2 -1
  40. package/src/doctor/index.ts +2 -0
  41. package/src/doctor/private-values.ts +108 -0
  42. package/src/doctor/runner.ts +4 -0
  43. package/src/doctor/schema.ts +29 -0
  44. package/src/events/actor.ts +10 -5
  45. package/src/events/command.ts +225 -22
  46. package/src/events/common/constants.ts +100 -6
  47. package/src/events/common/types.ts +22 -0
  48. package/src/events/flow-id.ts +89 -0
  49. package/src/events/flow.ts +4 -4
  50. package/src/events/hook.ts +53 -6
  51. package/src/events/index.ts +2 -0
  52. package/src/events/log.ts +115 -7
  53. package/src/events/project-key.ts +22 -0
  54. package/src/events/retention.ts +2 -4
  55. package/src/events/settings.ts +16 -0
  56. package/src/events/text.ts +23 -0
  57. package/src/hooks/host-pattern.ts +17 -0
  58. package/src/hooks/remote-hosts.ts +39 -7
  59. package/src/init/common/constants.ts +1 -0
  60. package/src/init/scaffold.ts +39 -7
  61. package/src/manifest/render.ts +5 -1
  62. package/src/router.ts +11 -2
  63. package/src/sync/claude-launch.ts +62 -7
  64. package/src/wiki/source-links.ts +5 -4
@@ -0,0 +1,31 @@
1
+ ## What changed
2
+
3
+ <!-- The smallest visual that shows it: one table, one before and after, one screenshot. -->
4
+
5
+ ## Before and after
6
+
7
+ <!-- The behaviour, not the files. -->
8
+
9
+ ## Rules checked
10
+
11
+ <!-- A code change only. One row per rule id of the base rules (P, C and B) and the project's own that you checked: -->
12
+
13
+ | Rule | What was checked | What changed because of it |
14
+ |---|---|---|
15
+ | | | |
16
+
17
+ Kept out to stay small (V-C-11): <what you did not add, or removed, to keep the change small; or "nothing">
18
+
19
+ ## Checks
20
+
21
+ | Command | Result |
22
+ |---|---|
23
+ | | |
24
+
25
+ ## Door
26
+
27
+ <!-- One-way (a published package, a migration, a deleted branch) or two-way (revert and it is gone), and the blast radius if it is wrong. -->
28
+
29
+ ## Not verified
30
+
31
+ <!-- What did not run, what was not checked, every `SHORTCUT:` added, or "none". -->
@@ -0,0 +1,11 @@
1
+ # Your own hosts for the remote-host guard (remoteHosts in .configs/vulcan.config.*).
2
+ # Copy this file to .agents/hooks/trusted-hosts.local - git ignores that file - and list your hosts there.
3
+ # That keeps host names out of the committed config.
4
+ #
5
+ # One host per line. A plain line is trusted for any command.
6
+ # A line that starts with "readonly:" allows only read-only commands (uptime, cat, kubectl get ...).
7
+ # A host is a name or a pattern with * (at least one letter or digit), or a $VARIABLE. Not a user, a path or a port.
8
+ #
9
+ # my-laptop.example
10
+ # readonly: db-replica.example
11
+ # readonly: *.prod.example
@@ -1,6 +1,7 @@
1
1
  import type { VulcanConfig } from '@venizia/vulcan';
2
2
 
3
3
  export default {
4
+ project: { key: '{{key}}' },
4
5
  agents: ['claude'],
5
6
  rules: { 'V-W-01': 'on-user-word' },
6
7
  } satisfies VulcanConfig;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.10-0",
3
+ "version": "0.4.10-2",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "bugs": {
@@ -25,6 +25,7 @@
25
25
  "LICENSE.md",
26
26
  "src",
27
27
  "base",
28
+ "!src/board/ui",
28
29
  "!**/__tests__",
29
30
  "!**/*.tsbuildinfo"
30
31
  ],
@@ -44,8 +45,8 @@
44
45
  },
45
46
  "dependencies": {
46
47
  "@clack/prompts": "1.8.1",
47
- "@venizia/vulcan-atlas": "0.4.10-0",
48
- "@venizia/vulcan-okf": "0.4.10-0",
48
+ "@venizia/vulcan-atlas": "0.4.10-2",
49
+ "@venizia/vulcan-okf": "0.4.10-2",
49
50
  "zod": "^4.6.7"
50
51
  },
51
52
  "devDependencies": {
@@ -53,7 +54,8 @@
53
54
  "@venizia/dev-configs": "0.4.7-0",
54
55
  "eslint": "10.13.0",
55
56
  "oxlint": "1.89.0",
56
- "oxlint-tsgolint": "7.0.2004"
57
+ "oxlint-tsgolint": "7.0.2004",
58
+ "preact": "11.1.1"
57
59
  },
58
60
  "engines": {
59
61
  "bun": ">=1.4.4"
@@ -0,0 +1,43 @@
1
+ import type { TBoardAgentSetting } from './schema.ts';
2
+
3
+ /** What one `board.agents` entry says: its face, its lane, and why a lane cannot be honoured. */
4
+ export class BoardAgentSetting {
5
+ static shapeOf(opts: { setting: TBoardAgentSetting }): string | undefined {
6
+ return typeof opts.setting === 'string' ? opts.setting : opts.setting.shape;
7
+ }
8
+
9
+ static laneOf(opts: { setting: TBoardAgentSetting }): string | undefined {
10
+ return typeof opts.setting === 'string' ? undefined : opts.setting.lane;
11
+ }
12
+
13
+ static roleOf(opts: { setting: TBoardAgentSetting }): string | undefined {
14
+ return typeof opts.setting === 'string' ? undefined : opts.setting.role;
15
+ }
16
+
17
+ /** Why the lane of `name` cannot be honoured, or `undefined`. A lane names a listed agent with no lane of its own, so there is no chain and no cycle. */
18
+ static problemOf(opts: {
19
+ settings: Record<string, TBoardAgentSetting>;
20
+ name: string;
21
+ }): string | undefined {
22
+ const { settings, name } = opts;
23
+ const lane = BoardAgentSetting.laneOf({ setting: settings[name] });
24
+
25
+ if (lane === undefined) {
26
+ return undefined;
27
+ }
28
+
29
+ if (lane === name) {
30
+ return `'${name}' cannot be its own lane`;
31
+ }
32
+
33
+ const target = settings[lane];
34
+
35
+ if (target === undefined) {
36
+ return `lane '${lane}' of '${name}' is not a key of board.agents`;
37
+ }
38
+
39
+ return BoardAgentSetting.laneOf({ setting: target }) === undefined
40
+ ? undefined
41
+ : `lane '${lane}' of '${name}' has a lane of its own: a lane cannot be a helper`;
42
+ }
43
+ }
@@ -3,19 +3,24 @@ import { mkdirSync, writeFileSync } from 'node:fs';
3
3
  import { dirname, resolve } from 'node:path';
4
4
  import { ExitCodes } from '../common/index.ts';
5
5
  import type { ICommandContext } from '../common/index.ts';
6
+ import { FlowId } from '../events/flow-id.ts';
6
7
  import { EventLog } from '../events/log.ts';
7
8
  import { EventSettings } from '../events/settings.ts';
8
- import { BoardConstants, BoardFlags, BoardStates } from './common/index.ts';
9
- import type { IBoardData } from './common/index.ts';
9
+ import { BoardConstants, BoardFlags, BoardServe, BoardStates } from './common/index.ts';
10
+ import type { IBoardData, IBoardEvent } from './common/index.ts';
10
11
  import { BoardFold } from './fold.ts';
11
12
  import { BoardGithub } from './github.ts';
12
13
  import { BoardSettings } from './settings.ts';
13
14
  import { BoardPage } from './page.ts';
15
+ import { BoardServer } from './server.ts';
14
16
 
15
- const USAGE = `usage: vulcan board [${BoardFlags.OUT} <file>] [${BoardFlags.OPEN}] [${BoardFlags.SINCE} <date>] [${BoardFlags.DIR} <events folder>] [${BoardFlags.REPO} owner/name]... [${BoardFlags.NO_GITHUB}]`;
17
+ const SHARED_FLAGS = `[${BoardFlags.OPEN}] [${BoardFlags.SINCE} <date>] [${BoardFlags.DIR} <events folder>] [${BoardFlags.REPO} owner/name]... [${BoardFlags.NO_GITHUB}]`;
18
+ const USAGE = `usage: vulcan board [${BoardFlags.OUT} <file>] ${SHARED_FLAGS}\n vulcan board ${BoardServe.COMMAND} [${BoardFlags.PORT} <n>] ${SHARED_FLAGS}`;
16
19
  const REPO_NAME = /^[\w.-]+\/[\w.-]+$/;
17
20
 
18
21
  interface IBoardArgs {
22
+ serve: boolean;
23
+ port: string | undefined;
19
24
  out: string | undefined;
20
25
  open: boolean;
21
26
  since: string | undefined;
@@ -35,10 +40,11 @@ export class BoardCommand {
35
40
  return ExitCodes.USAGE;
36
41
  }
37
42
 
38
- const since =
43
+ const sinceOf = (): number =>
39
44
  args.since === undefined
40
45
  ? Date.now() - BoardConstants.DEFAULT_DAYS * BoardConstants.DAY_MS
41
46
  : Date.parse(args.since);
47
+ const since = sinceOf();
42
48
 
43
49
  if (!Number.isFinite(since)) {
44
50
  process.stderr.write(
@@ -53,6 +59,10 @@ export class BoardCommand {
53
59
  root,
54
60
  ...(args.dir === undefined ? {} : { dir: resolve(opts.cwd, args.dir) }),
55
61
  });
62
+ if (args.serve) {
63
+ return BoardCommand.serve({ args, root, dir, sinceOf });
64
+ }
65
+
56
66
  const data = BoardCommand.collect({ root, dir, since, args });
57
67
  const file = resolve(root, args.out ?? BoardConstants.DEFAULT_OUT);
58
68
 
@@ -74,7 +84,7 @@ export class BoardCommand {
74
84
  process.stdout.write(`${file}\n`);
75
85
 
76
86
  if (args.open) {
77
- BoardCommand.open({ file });
87
+ BoardCommand.open({ target: file });
78
88
  }
79
89
 
80
90
  return ExitCodes.OK;
@@ -86,15 +96,29 @@ export class BoardCommand {
86
96
  dir: string;
87
97
  since: number;
88
98
  args: Pick<IBoardArgs, 'repos' | 'noGithub'>;
99
+ /** The GitHub lines to use; with none, they are read here (unless `noGithub`). */
100
+ github?: { events: IBoardEvent[]; note: string };
101
+ /** The git user name, when the caller already has it; otherwise it is read from git. */
102
+ readGitUser?: () => string | undefined;
89
103
  }): IBoardData {
90
104
  const read = EventLog.read({ dir: opts.dir, since: opts.since });
91
105
  const fromLog = BoardFold.fromLog({ events: read.events });
92
- const github = opts.args.noGithub
93
- ? { events: [], note: 'github: left out (--no-github)' }
94
- : BoardGithub.read({ repos: opts.args.repos, cwd: opts.root, since: opts.since });
95
- const settings = BoardSettings.read({ root: opts.root });
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
+ const settings = BoardSettings.read({
112
+ root: opts.root,
113
+ ...(opts.readGitUser === undefined ? {} : { readGitUser: opts.readGitUser }),
114
+ });
115
+ // An older `F-n` is shown as `VULZ-<key>-n`; the log itself is never rewritten.
116
+ const key = EventSettings.keyOf({ root: opts.root });
96
117
  const { flows, decisions } = BoardFold.fold({
97
- events: [...fromLog.events, ...github.events],
118
+ events: [...fromLog.events, ...github.events].map((event) => ({
119
+ ...event,
120
+ flowId: FlowId.canon({ id: event.flowId, key }),
121
+ })),
98
122
  owner: settings.owner,
99
123
  });
100
124
 
@@ -104,6 +128,9 @@ export class BoardCommand {
104
128
  ...(settings.logo === undefined ? {} : { logo: settings.logo }),
105
129
  key: settings.key,
106
130
  shapes: settings.shapes,
131
+ ...(settings.roster.length === 0 ? {} : { roster: settings.roster }),
132
+ ...(Object.keys(settings.lanes).length === 0 ? {} : { lanes: settings.lanes }),
133
+ ...(Object.keys(settings.roles).length === 0 ? {} : { roles: settings.roles }),
107
134
  generatedAt: new Date().toISOString(),
108
135
  since: new Date(opts.since).toISOString(),
109
136
  flows: flows.sort(
@@ -121,8 +148,78 @@ export class BoardCommand {
121
148
  };
122
149
  }
123
150
 
151
+ /** `vulcan board serve`: the board on 127.0.0.1 that updates when the log does, until Ctrl+C. */
152
+ private static async serve(opts: {
153
+ args: IBoardArgs;
154
+ root: string;
155
+ dir: string;
156
+ sinceOf: () => number;
157
+ }): Promise<number> {
158
+ const { args } = opts;
159
+ const gitUser = BoardSettings.gitUserOf({ root: opts.root });
160
+ let github: { events: IBoardEvent[]; note: string } | undefined;
161
+ let readAt = 0;
162
+ const collect = (): IBoardData => {
163
+ const since = opts.sinceOf();
164
+
165
+ if (!args.noGithub && Date.now() - readAt >= BoardServe.REFRESH_MS) {
166
+ github = BoardGithub.read({ repos: args.repos, cwd: opts.root, since });
167
+ readAt = Date.now();
168
+ }
169
+
170
+ return BoardCommand.collect({
171
+ root: opts.root,
172
+ dir: opts.dir,
173
+ since,
174
+ args,
175
+ ...(github === undefined ? {} : { github }),
176
+ readGitUser: () => gitUser,
177
+ });
178
+ };
179
+ const port = args.port === undefined ? BoardServe.DEFAULT_PORT : Number(args.port);
180
+
181
+ try {
182
+ const { hostname } = BoardSettings.read({ root: opts.root, readGitUser: () => gitUser });
183
+ const { url, fallback, note } = await BoardServer.start({
184
+ port,
185
+ dir: opts.dir,
186
+ hostname,
187
+ collect,
188
+ });
189
+
190
+ if (note !== undefined) {
191
+ process.stderr.write(`board: ${note}\n`);
192
+ }
193
+
194
+ process.stderr.write(
195
+ `board: serving; press Ctrl+C to stop. If your browser does not open ${hostname}, use ${fallback}\n`,
196
+ );
197
+ process.stdout.write(`${url}\n`);
198
+
199
+ if (args.open) {
200
+ BoardCommand.open({ target: url });
201
+ }
202
+ } catch (error) {
203
+ process.stderr.write(
204
+ `board: cannot serve: ${error instanceof Error ? error.message : String(error)}\n`,
205
+ );
206
+
207
+ return ExitCodes.FAILURE;
208
+ }
209
+
210
+ await new Promise<void>((done) => {
211
+ process.once('SIGINT', () => done());
212
+ process.once('SIGTERM', () => done());
213
+ });
214
+ await BoardServer.stop();
215
+
216
+ return ExitCodes.OK;
217
+ }
218
+
124
219
  private static parse(opts: { args: string[] }): IBoardArgs | string {
125
220
  const parsed: IBoardArgs = {
221
+ serve: false,
222
+ port: undefined,
126
223
  out: undefined,
127
224
  open: false,
128
225
  since: undefined,
@@ -130,14 +227,19 @@ export class BoardCommand {
130
227
  repos: [],
131
228
  noGithub: false,
132
229
  };
133
- const keys: Record<string, 'out' | 'since' | 'dir'> = {
230
+ const keys: Record<string, 'out' | 'port' | 'since' | 'dir'> = {
134
231
  [BoardFlags.OUT]: 'out',
232
+ [BoardFlags.PORT]: 'port',
135
233
  [BoardFlags.SINCE]: 'since',
136
234
  [BoardFlags.DIR]: 'dir',
137
235
  };
138
236
 
139
- for (let index = 0; index < opts.args.length; index++) {
140
- const arg = opts.args[index];
237
+ const words = opts.args[0] === BoardServe.COMMAND ? opts.args.slice(1) : opts.args;
238
+
239
+ parsed.serve = words !== opts.args;
240
+
241
+ for (let index = 0; index < words.length; index++) {
242
+ const arg = words[index];
141
243
 
142
244
  if (arg === BoardFlags.OPEN) {
143
245
  parsed.open = true;
@@ -149,7 +251,11 @@ export class BoardCommand {
149
251
  continue;
150
252
  }
151
253
 
152
- const value = opts.args[index + 1];
254
+ if (!arg.startsWith('-')) {
255
+ return `unknown argument '${arg}'`;
256
+ }
257
+
258
+ const value = words[index + 1];
153
259
 
154
260
  if (value === undefined || value.startsWith('-')) {
155
261
  return `${arg} needs a value`;
@@ -175,18 +281,33 @@ export class BoardCommand {
175
281
  parsed[key] = value;
176
282
  }
177
283
 
284
+ if (parsed.serve && parsed.out !== undefined) {
285
+ return `${BoardFlags.OUT} writes the static file; ${BoardServe.COMMAND} serves the board`;
286
+ }
287
+
288
+ if (!parsed.serve && parsed.port !== undefined) {
289
+ return `${BoardFlags.PORT} belongs to ${BoardServe.COMMAND}`;
290
+ }
291
+
292
+ if (
293
+ parsed.port !== undefined &&
294
+ !(/^\d{1,5}$/.test(parsed.port) && Number(parsed.port) <= 65_535)
295
+ ) {
296
+ return `${BoardFlags.PORT} must be a number from 0 to 65535, got '${parsed.port}'`;
297
+ }
298
+
178
299
  return parsed;
179
300
  }
180
301
 
181
- private static open(opts: { file: string }): void {
302
+ private static open(opts: { target: string }): void {
182
303
  const program =
183
304
  process.platform === 'darwin'
184
305
  ? 'open'
185
306
  : process.platform === 'win32'
186
307
  ? 'explorer.exe'
187
308
  : 'xdg-open';
188
- const args = [opts.file];
189
- const hint = `board: could not open the file; open ${opts.file} yourself\n`;
309
+ const args = [opts.target];
310
+ const hint = `board: could not open it; open ${opts.target} yourself\n`;
190
311
 
191
312
  try {
192
313
  const child = spawn(program, args, { detached: true, stdio: 'ignore' });
@@ -64,6 +64,36 @@ export class BoardFlags {
64
64
  static readonly REPO = '--repo';
65
65
  /** Leave GitHub out, for a project that is not on it. */
66
66
  static readonly NO_GITHUB = '--no-github';
67
+ static readonly PORT = '--port';
68
+ }
69
+
70
+ /** The two routes `vulcan board serve` answers. */
71
+ export class BoardRoutes {
72
+ static readonly PAGE = 'page';
73
+ static readonly STREAM = 'stream';
74
+ }
75
+
76
+ /** `vulcan board serve`: where it listens and how much it keeps open. */
77
+ export class BoardServe {
78
+ static readonly COMMAND = 'serve';
79
+ static readonly HOST = '127.0.0.1';
80
+ /** The name the address uses: a browser resolves any `.localhost` name to loopback by itself (RFC 6761), so no DNS entry is needed. */
81
+ static readonly DEFAULT_HOSTNAME = 'vulz-board.venizia.ai.localhost';
82
+ /** A `board.hostname` must be one the browser resolves itself: a name that only resolves to loopback through DNS is what a rebinding page uses. */
83
+ static readonly HOSTNAME =
84
+ /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*\.localhost$/;
85
+ static readonly DEFAULT_PORT = 4317;
86
+ static readonly TOKEN_BYTES = 16;
87
+ static readonly TOKEN_PARAM = 't';
88
+ static readonly PAGE_PATH = '/';
89
+ static readonly STREAM_PATH = '/stream';
90
+ static readonly MAX_STREAMS = 8;
91
+ static readonly MAX_SNAPSHOT_BYTES = 20_000_000;
92
+ static readonly HEARTBEAT_MS = 15_000;
93
+ static readonly DEBOUNCE_MS = 250;
94
+ static readonly POLL_MS = 2000;
95
+ /** The page gets a fresh snapshot this often even when the log is quiet; GitHub is read at most this often. */
96
+ static readonly REFRESH_MS = 60_000;
67
97
  }
68
98
 
69
99
  /** The faces the page can draw for an agent. `bun` is the default; the others are chosen by name in `board.agents`. */
@@ -92,15 +122,22 @@ export class BoardSources {
92
122
  }
93
123
 
94
124
  export class BoardConstants {
125
+ /** The longest role a `board.agents` value may give an agent. */
126
+ static readonly ROLE_MAX = 60;
127
+ /** What the Claude Code hook is called on a card. */
128
+ static readonly HARNESS_CLAUDE = 'Claude Code';
95
129
  /** Who an ask waits on when neither `board.owner` nor `git config user.name` says. */
96
130
  static readonly DEFAULT_OWNER = 'Owner';
97
131
  static readonly LOGO_MAX_BYTES = 100 * 1024;
98
132
  static readonly MANIFEST_FILE = '.agents/vulcan.manifest.json';
99
133
  static readonly CI_ACTOR = 'CI';
134
+ /** A quiet spell this long ends a stretch of work: the next line starts a new one. */
135
+ static readonly ACTIVE_GAP_MS = 30 * 60 * 1000;
100
136
  static readonly UNSORTED = 'Unsorted';
101
137
  static readonly DEFAULT_OUT = '.agents/local/reports/board.html';
102
138
  static readonly DEFAULT_DAYS = 7;
103
- static readonly DAY_MS = 24 * 60 * 60 * 1000;
139
+ static readonly HOUR_MS = 60 * 60 * 1000;
140
+ static readonly DAY_MS = 24 * BoardConstants.HOUR_MS;
104
141
  static readonly TEMPLATE = 'templates/board.html';
105
142
  static readonly DATA_MARKER = '<!--BOARD_DATA-->';
106
143
  static readonly GH_TIMEOUT_MS = 15_000;
@@ -1,7 +1,9 @@
1
1
  import type { TConstValue } from '../../common/index.ts';
2
- import type { BoardStates } from './constants.ts';
2
+ import type { IEventItem } from '../../events/common/index.ts';
3
+ import type { BoardRoutes, BoardStates } from './constants.ts';
3
4
 
4
5
  export type TBoardState = TConstValue<typeof BoardStates>;
6
+ export type TBoardRoute = TConstValue<typeof BoardRoutes>;
5
7
 
6
8
  export interface IBoardRef {
7
9
  repo?: string;
@@ -19,6 +21,10 @@ export interface IBoardEvent {
19
21
  stage: number;
20
22
  actor: string;
21
23
  to?: string;
24
+ /** A message the actor got, not sent (`msg-received`). */
25
+ incoming?: boolean;
26
+ /** Who sent a message the actor got, from a `from:<name>` ref. */
27
+ from?: string;
22
28
  status?: string;
23
29
  /** What a decision decided: `approve`, `park` or `reject`. */
24
30
  choice?: string;
@@ -29,16 +35,28 @@ export interface IBoardEvent {
29
35
  isTitle?: boolean;
30
36
  /** Only a title line has one: why the flow exists. */
31
37
  why?: string;
38
+ /** Only a title line has them: what the flow is and what is left, and the next step. */
39
+ context?: string;
40
+ next?: string;
32
41
  /** Which attempt this is: the nth run of one check, the nth review round. */
33
42
  attempt?: number;
34
43
  /** The check a CI line is about. */
35
44
  check?: string;
36
45
  ref?: IBoardRef;
37
46
  link?: string;
47
+ /** Only a title line has them: the lists, the due day and the tracker id the flow line gave. */
48
+ steps?: IBoardItem[];
49
+ checks?: IBoardItem[];
50
+ apps?: string[];
51
+ due?: string;
52
+ tracker?: string;
38
53
  summary: string;
39
54
  source: string;
40
55
  }
41
56
 
57
+ /** One step or acceptance check of a flow, and whether it is done: the same thing the event log carries. */
58
+ export type IBoardItem = IEventItem;
59
+
42
60
  export interface IBoardFlow {
43
61
  id: string;
44
62
  title: string;
@@ -46,6 +64,16 @@ export interface IBoardFlow {
46
64
  named: boolean;
47
65
  /** Why the flow exists, from the newest `flow` line that has one. */
48
66
  why?: string;
67
+ /** What the flow is, what is done and what is left; from the same line as the title. */
68
+ context?: string;
69
+ /** The next step and who does it; from the same line as the title. */
70
+ next?: string;
71
+ /** The steps, the acceptance checks, the apps, the due day and the tracker id, from the same line as the title: the line lists them in full. */
72
+ steps?: IBoardItem[];
73
+ checks?: IBoardItem[];
74
+ apps?: string[];
75
+ due?: string;
76
+ tracker?: string;
49
77
  repo?: string;
50
78
  state: TBoardState;
51
79
  /** Who has it now. */
@@ -73,6 +101,9 @@ export interface IBoardAgent {
73
101
  current: string;
74
102
  since: string;
75
103
  checkedAt: string;
104
+ /** What the session start said of the session: the model, and the harness that wrote it. Never made up. */
105
+ model?: string;
106
+ harness?: string;
76
107
  }
77
108
 
78
109
  export interface IBoardData {
@@ -86,6 +117,14 @@ export interface IBoardData {
86
117
  key: string;
87
118
  /** Agent name to face, from `board.agents`; any other agent has the default face. */
88
119
  shapes: Record<string, string>;
120
+ /** The `board.agents` keys with no lane; absent when none is listed, and then every agent shows. */
121
+ roster?: string[];
122
+ /** A helper to the lane it rolls into. */
123
+ lanes?: Record<string, string>;
124
+ /** What `board.agents` says an agent is, by name: `Backend`. */
125
+ roles?: Record<string, string>;
126
+ /** Set by `vulcan board serve`: where the page reads new snapshots from. The static file has none. */
127
+ live?: { stream: string };
89
128
  generatedAt: string;
90
129
  since: string;
91
130
  flows: IBoardFlow[];