@venizia/vulcan 0.4.10-2 → 0.4.10-4

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 (66) hide show
  1. package/README.md +26 -18
  2. package/base/hooks/guard-outside.ts +10 -19
  3. package/base/hooks/guard-writes.ts +3 -24
  4. package/base/make/vulcan.mk +1 -4
  5. package/base/rules.md +4 -4
  6. package/base/skills/visualize-work/SKILL.md +1 -1
  7. package/base/skills/visualize-work/references/spec.md +1 -1
  8. package/base/templates/board.html +10 -110
  9. package/package.json +3 -3
  10. package/src/agents/resolve.ts +1 -0
  11. package/src/board/command.ts +16 -1
  12. package/src/board/common/constants.ts +2 -0
  13. package/src/board/common/types.ts +2 -2
  14. package/src/board/page.ts +57 -5
  15. package/src/board/schema.ts +4 -1
  16. package/src/board/server.ts +13 -2
  17. package/src/board/settings.ts +1 -1
  18. package/src/commands/graph.command.ts +6 -0
  19. package/src/commands/help.command.ts +2 -63
  20. package/src/commands/index.ts +2 -0
  21. package/src/commands/sync.command.ts +5 -1
  22. package/src/commands/table.ts +327 -0
  23. package/src/commit/check.ts +1 -0
  24. package/src/commit/common/constants.ts +2 -0
  25. package/src/commit/hook.ts +44 -4
  26. package/src/common/constants.ts +7 -3
  27. package/src/common/env-variables.ts +37 -0
  28. package/src/common/index.ts +1 -0
  29. package/src/config/loader.ts +22 -0
  30. package/src/config/schema.ts +162 -20
  31. package/src/create/add-app.ts +5 -0
  32. package/src/create/common/constants.ts +5 -3
  33. package/src/create/preset.ts +1 -0
  34. package/src/create/scratch.ts +2 -1
  35. package/src/doctor/checks.ts +106 -4
  36. package/src/doctor/common/constants.ts +26 -0
  37. package/src/doctor/runner.ts +3 -0
  38. package/src/doctor/schema.ts +4 -0
  39. package/src/hooks/owner-reply.ts +5 -0
  40. package/src/hooks/project-guards.ts +28 -4
  41. package/src/hooks/project-tmp.ts +39 -4
  42. package/src/hooks/session-digest.ts +9 -0
  43. package/src/init/scaffold.ts +1 -0
  44. package/src/local/auto-clean.ts +2 -1
  45. package/src/local/browser-socket.ts +33 -0
  46. package/src/local/clean.ts +1 -0
  47. package/src/local/index.ts +1 -0
  48. package/src/local/scan.ts +33 -9
  49. package/src/manifest/render.ts +70 -9
  50. package/src/owner/constants.ts +3 -1
  51. package/src/owner/profile.ts +1 -0
  52. package/src/owner/schema.ts +37 -6
  53. package/src/router.ts +4 -130
  54. package/src/rules/base.ts +1 -0
  55. package/src/signals/loop.ts +1 -0
  56. package/src/skills/frontmatter.ts +1 -0
  57. package/src/sync/claude-launch.ts +12 -12
  58. package/src/sync/local-choice.ts +32 -3
  59. package/src/sync/planner.ts +1 -0
  60. package/src/theme/index.ts +1 -0
  61. package/src/theme/tokens.ts +410 -0
  62. package/src/ui/prompt.ts +1 -0
  63. package/src/visualize/page.ts +4 -4
  64. package/src/visualize/render.ts +2 -1
  65. package/src/visualize/theme.ts +43 -12
  66. package/src/wiki/anchors.ts +1 -0
@@ -6,6 +6,8 @@ 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 { ThemeTokens } from '../theme/index.ts';
10
+ import type { IThemeTokens } from '../theme/index.ts';
9
11
  import { BoardConstants, BoardFlags, BoardServe, BoardStates } from './common/index.ts';
10
12
  import type { IBoardData, IBoardEvent } from './common/index.ts';
11
13
  import { BoardFold } from './fold.ts';
@@ -65,10 +67,11 @@ export class BoardCommand {
65
67
 
66
68
  const data = BoardCommand.collect({ root, dir, since, args });
67
69
  const file = resolve(root, args.out ?? BoardConstants.DEFAULT_OUT);
70
+ const tokens = BoardCommand.tokensOf({ root });
68
71
 
69
72
  try {
70
73
  mkdirSync(dirname(file), { recursive: true });
71
- writeFileSync(file, BoardPage.render({ data }));
74
+ writeFileSync(file, BoardPage.render({ data, tokens }));
72
75
  } catch (error) {
73
76
  process.stderr.write(
74
77
  `board: cannot write ${file}: ${error instanceof Error ? error.message : String(error)}\n`,
@@ -90,6 +93,17 @@ export class BoardCommand {
90
93
  return ExitCodes.OK;
91
94
  }
92
95
 
96
+ /** The design tokens of the project's manifest; a manifest the board cannot read says so on stderr and the default preset is used. */
97
+ private static tokensOf(opts: { root: string }): IThemeTokens {
98
+ const { tokens, warning } = ThemeTokens.read({ root: opts.root });
99
+
100
+ if (warning !== undefined) {
101
+ process.stderr.write(`board: ${warning}\n`);
102
+ }
103
+
104
+ return tokens;
105
+ }
106
+
93
107
  /** The folded data of a project: its log since `since`, and GitHub unless it is left out or cannot be read. */
94
108
  static collect(opts: {
95
109
  root: string;
@@ -185,6 +199,7 @@ export class BoardCommand {
185
199
  dir: opts.dir,
186
200
  hostname,
187
201
  collect,
202
+ tokens: BoardCommand.tokensOf({ root: opts.root }),
188
203
  });
189
204
 
190
205
  if (note !== undefined) {
@@ -140,6 +140,8 @@ export class BoardConstants {
140
140
  static readonly DAY_MS = 24 * BoardConstants.HOUR_MS;
141
141
  static readonly TEMPLATE = 'templates/board.html';
142
142
  static readonly DATA_MARKER = '<!--BOARD_DATA-->';
143
+ /** Where the page takes the design tokens of the project (a `style` with the custom properties). */
144
+ static readonly TOKENS_MARKER = '<!--BOARD_TOKENS-->';
143
145
  static readonly GH_TIMEOUT_MS = 15_000;
144
146
  static readonly GH_LIMIT = 30;
145
147
  /** A `needs-owner` line whose whole summary is one of these is the harness waiting, not a person asking. */
@@ -60,7 +60,7 @@ export type IBoardItem = IEventItem;
60
60
  export interface IBoardFlow {
61
61
  id: string;
62
62
  title: string;
63
- /** The title came from a `flow` line; a flow without one shows its first line and "no title yet". */
63
+ /** 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
64
  named: boolean;
65
65
  /** Why the flow exists, from the newest `flow` line that has one. */
66
66
  why?: string;
@@ -119,7 +119,7 @@ export interface IBoardData {
119
119
  shapes: Record<string, string>;
120
120
  /** The `board.agents` keys with no lane; absent when none is listed, and then every agent shows. */
121
121
  roster?: string[];
122
- /** A helper to the lane it rolls into. */
122
+ /** A helper to the listed name it works under; shown as a label on its own card. */
123
123
  lanes?: Record<string, string>;
124
124
  /** What `board.agents` says an agent is, by name: `Backend`. */
125
125
  roles?: Record<string, string>;
package/src/board/page.ts CHANGED
@@ -2,15 +2,42 @@ import { readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { BASE_DIRECTORY } from '../common/paths.ts';
4
4
  import { BoardConstants } from './common/index.ts';
5
+ import { ThemeTokens } from '../theme/index.ts';
6
+ import type { IThemeTokens } from '../theme/index.ts';
5
7
  import type { IBoardData } from './common/index.ts';
6
8
 
9
+ /** The token the board calls by another name: the custom properties of its shell. `--focus` and `--r` follow below. */
10
+ const TOKEN_PROPERTIES: Record<string, string> = {
11
+ ground: 'ground',
12
+ bg: 'bg',
13
+ line: 'line',
14
+ 'line-strong': 'stroke-strong',
15
+ ink: 'ink',
16
+ body: 'body',
17
+ muted: 'muted',
18
+ accent: 'accent',
19
+ 'accent-ink': 'accent-ink',
20
+ 'accent-soft': 'accent-soft',
21
+ 'accent-text': 'accent-text',
22
+ ok: 'ok',
23
+ 'ok-soft': 'ok-soft',
24
+ wait: 'wait',
25
+ 'wait-soft': 'wait-soft',
26
+ fail: 'fail',
27
+ 'fail-soft': 'fail-soft',
28
+ // The greys of the board's panes (ThemeTokens.SURFACES), written beside the tokens.
29
+ head: 'head',
30
+ soft: 'soft',
31
+ sunk: 'sunk',
32
+ };
33
+
7
34
  /** The board as one HTML file: the page of `base/templates/board.html` with the data inside it. */
8
35
  export class BoardPage {
9
36
  /**
10
37
  * The page with `data` embedded as JSON in a `script` of type `application/json`. `<` and the two line separators
11
38
  * are escaped, so no text in the data can close the script or break it. Nothing is fetched when the page opens.
12
39
  */
13
- static render(opts: { data: IBoardData; template?: string }): string {
40
+ static render(opts: { data: IBoardData; template?: string; tokens?: IThemeTokens }): string {
14
41
  const template =
15
42
  opts.template ?? readFileSync(join(BASE_DIRECTORY, BoardConstants.TEMPLATE), 'utf8');
16
43
  const json = JSON.stringify(opts.data)
@@ -18,9 +45,34 @@ export class BoardPage {
18
45
  .replaceAll('
', '\\u2028')
19
46
  .replaceAll('
', '\\u2029');
20
47
 
21
- return template.replace(
22
- BoardConstants.DATA_MARKER,
23
- () => `<script type="application/json" id="board-data">${json}</script>`,
24
- );
48
+ return template
49
+ .replace(BoardConstants.TOKENS_MARKER, () => BoardPage.tokensStyle({ tokens: opts.tokens }))
50
+ .replace(
51
+ BoardConstants.DATA_MARKER,
52
+ () => `<script type="application/json" id="board-data">${json}</script>`,
53
+ );
54
+ }
55
+
56
+ /**
57
+ * The `style` with the tokens as the shell names them: light on `:root`, the system dark setting unless the page
58
+ * was set to light, then each explicit setting (the embedding wiki's `data-theme` and the board's own). The default
59
+ * preset when no tokens are given.
60
+ */
61
+ static tokensStyle(opts: { tokens?: IThemeTokens }): string {
62
+ const tokens = opts.tokens ?? ThemeTokens.defaults();
63
+ const declare = (mode: 'light' | 'dark'): string =>
64
+ `${ThemeTokens.declarations({ mode: { ...tokens[mode], ...ThemeTokens.SURFACES[mode] }, names: TOKEN_PROPERTIES })};--focus:${tokens[mode].accent}`;
65
+ const light = `${declare('light')};--r:${tokens.radius}`;
66
+ const dark = declare('dark');
67
+
68
+ return [
69
+ '<style id="board-tokens">',
70
+ `:root{${light}}`,
71
+ `@media (prefers-color-scheme: dark){:root:not([data-theme='light']):not([data-board-theme='light']){${dark}}}`,
72
+ `:root[data-theme='dark']{${dark}}`,
73
+ `:root[data-board-theme='dark']{${dark}}`,
74
+ `:root[data-board-theme='light']{${light}}`,
75
+ '</style>',
76
+ ].join('\n');
25
77
  }
26
78
  }
@@ -6,12 +6,15 @@ const SHAPE = z.custom<string>((value) => typeof value === 'string' && BoardShap
6
6
  message: `one of ${[...BoardShapes.SCHEME_SET].join(', ')}`,
7
7
  });
8
8
 
9
- /** A face, or `{ shape?, lane?, role? }`: the lane rolls the agent into the row of another listed agent; the role is what the card says it is. */
9
+ /** A face, or `{ shape?, lane?, role? }`: the lane labels the agent "under" another listed agent on its own card; the role is what the card says it is. */
10
10
  export const BOARD_AGENT = z.union([
11
11
  SHAPE,
12
12
  z.strictObject({
13
+ /** Face of the agent: `bun`, `flame`, `ember`, `rock` or `banana`. */
13
14
  shape: SHAPE.optional(),
15
+ /** Name of another listed agent this one is shown under on its card; at least one character, and that agent has no lane of its own. */
14
16
  lane: z.string().min(1).optional(),
17
+ /** What the card says the agent is; trimmed, 1 to 60 characters. */
15
18
  role: z.string().trim().min(1).max(BoardConstants.ROLE_MAX).optional(),
16
19
  }),
17
20
  ]);
@@ -1,6 +1,7 @@
1
1
  import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
2
2
  import type { Server } from 'bun';
3
3
  import { BoardRoutes, BoardServe } from './common/index.ts';
4
+ import type { IThemeTokens } from '../theme/index.ts';
4
5
  import type { IBoardData, TBoardRoute } from './common/index.ts';
5
6
  import { BoardPage } from './page.ts';
6
7
  import { BoardWatch } from './watch.ts';
@@ -13,6 +14,8 @@ interface IBoardServerOptions {
13
14
  dir: string;
14
15
  /** The folded board, as `vulcan board` makes it. */
15
16
  collect: () => IBoardData;
17
+ /** The design tokens of the page; default the default preset. */
18
+ tokens?: IThemeTokens;
16
19
  maxSnapshotBytes?: number;
17
20
  }
18
21
 
@@ -110,7 +113,14 @@ export class BoardServer {
110
113
  port,
111
114
  development: false,
112
115
  fetch: (request, server) =>
113
- BoardServer.answer({ request, server, token, hostname, collect: opts.collect }),
116
+ BoardServer.answer({
117
+ request,
118
+ server,
119
+ token,
120
+ hostname,
121
+ collect: opts.collect,
122
+ tokens: opts.tokens,
123
+ }),
114
124
  error: (error) => {
115
125
  process.stderr.write(`board: a request failed: ${error.message}\n`);
116
126
 
@@ -257,6 +267,7 @@ export class BoardServer {
257
267
  token: string;
258
268
  hostname: string;
259
269
  collect: () => IBoardData;
270
+ tokens?: IThemeTokens;
260
271
  }): Response {
261
272
  const { request, server, token } = opts;
262
273
  const verdict = BoardServer.check({
@@ -278,7 +289,7 @@ export class BoardServer {
278
289
 
279
290
  const live = { stream: BoardServer.pathWithToken({ path: BoardServe.STREAM_PATH, token }) };
280
291
 
281
- return new Response(BoardPage.render({ data: { ...data, live } }), {
292
+ return new Response(BoardPage.render({ data: { ...data, live }, tokens: opts.tokens }), {
282
293
  headers: PAGE_HEADERS,
283
294
  });
284
295
  }
@@ -17,7 +17,7 @@ export interface IBoardSettings {
17
17
  hostname: string;
18
18
  /** The listed `board.agents` keys with no lane; empty when none is listed, and then every agent shows. */
19
19
  roster: string[];
20
- /** A helper to the lane it rolls into. */
20
+ /** A helper to the listed name it works under; shown as a label on its own card. */
21
21
  lanes: Record<string, string>;
22
22
  /** What `board.agents` says each agent is. */
23
23
  roles: Record<string, string>;
@@ -0,0 +1,6 @@
1
+ import type { ICommandContext } from '../common/index.ts';
2
+ import { runXCommand } from './x.command.ts';
3
+
4
+ /** `vulcan graph <build|status>` is `vulcan x atlas graph <build|status>`: atlas owns the graph, this is the short name. */
5
+ export const runGraphCommand = async (opts: ICommandContext): Promise<number> =>
6
+ runXCommand({ ...opts, args: ['atlas', 'graph', ...opts.args] });
@@ -1,69 +1,8 @@
1
1
  import { ExitCodes, VULCAN_VERSION } from '../common/index.ts';
2
-
3
- const HELP = `vulcan ${VULCAN_VERSION} - one setup, one workflow for every project
4
-
5
- Usage: bun x vulcan <command>
6
-
7
- init [--key <KEY>] Scaffold the project layer (never overwrites); --key is the project's flow key
8
- (2 to 8 uppercase letters or digits; a terminal asks, else it is made from the name)
9
- init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <path>]
10
- [--shared-dir <path>] [--scope <@scope>] [--key <KEY>]
11
- Create a monorepo with its first app, from a framework preset
12
- (a name missing from the flags is asked in a terminal)
13
- add --preset <name|file:path> (--app <name> | --lib <name> | --shared <name>) [--dir <folder>]
14
- [--scope <@scope>] [--backend-dir|--frontend-dir <path>] [--api <app> | --no-api]
15
- Add an app, a library other apps import (--lib) or a side-neutral package
16
- other apps import (--shared) to the monorepo (a frontend says which
17
- backend to proxy to; --dir is for a library or a shared package;
18
- --scope names the package @scope/<name>; a terminal asks for the kind
19
- and every name the flags leave out)
20
- preset diff <package> [--preset <name|file:path>] [--api <app> | --no-api] [--full] [--check]
21
- Read-only: set each file the preset makes now (for an app, a library or
22
- a shared package) against the file the package has (same, differs,
23
- missing); --full prints the unified diffs, --check exits 1 when
24
- anything differs or is missing
25
- sync [--agents <list>|list] [--dry-run]
26
- Write the adapters of the agents you chose (--agents claude,omp or none,
27
- stored in .agents/vulcan.local.json; --agents list shows the table)
28
- agents [list|add <ids>|remove <ids>|setup] [--dry-run]
29
- See, add, remove or re-choose the coding agents you use on this machine
30
- doctor Check the project follows VULCAN; exit 1 on any violation
31
- commit-check <message-file> | --range <revs> | --text <message>
32
- Check a commit message against the commit.message checks of the config (an
33
- agent in a trailer or a "generated with" line, the project's subject shape);
34
- sync installs it as the commit-msg hook; exit 1 on a problem, 2 on bad input
35
- board [--out <file>] [--open] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]
36
- Fold the event log (and GitHub pull requests, checks and reviews when gh
37
- can read them) into flows and write one HTML file, by default
38
- .agents/local/reports/board.html; read-only; exit 2 on bad input
39
- ci affected --base <ref> [--head <ref>] [--check <check>] [--json | --names] | template <github|gitlab>
40
- List the workspace packages a change touches (changed ones and what
41
- depends on them) with the checks each has; template prints a CI file that
42
- runs exactly those; exit 2 on bad input
43
- event add --kind <k> --summary <text> [--flow <flow id>] [--ref <r>] [--status approve|park|reject] | add --kind flow [--flow <flow id>] --title <text> [--why <text>] [--context <text>] [--next <text>] [--step|--step-done <text>]... [--check|--check-done <text>]... [--app <name>]... [--due YYYY-MM-DD] | tail [--since <time>] [--json] [--dir <folder>]
44
- Write a line to the agent event log (.agents/local/events/<day>.jsonl) or
45
- read it; with events.log on, sync installs the Claude Code hooks that
46
- write it; exit 2 on bad input
47
- visualize <spec.json> [--out <name>] | --schema
48
- Make one small static HTML page (a flow, a status, a before and after) from
49
- a JSON spec, in .agents/local/prototypes/; --schema prints the spec's schema
50
- profile [show|edit|reset [--yes]]
51
- Tell VULCAN how you like to work (reply language, how to address you,
52
- tone, habits) in .agents/local/profile.json; no argument runs the form,
53
- show prints it, reset deletes it
54
- clean [--tmp|--worktrees|--clones|--cache|--all] [--reports|--prototypes|--events|--release-candidates|--profile] [--yes]
55
- List what an agent left under .agents/local/ (a dry run) and, with
56
- --yes, remove it; --tmp is the default, --worktrees takes merged or
57
- gone branches only, --all never touches reports, prototypes, events, release candidates or the profile
58
- upgrade [--stable | --nightly] [<version|tag>]
59
- Bump the pinned @venizia/vulcan, then sync; --stable (default)
60
- takes the latest tag, --nightly the newest of latest and next
61
- x <tool> [args...] Run a shipped tool at the pinned version: okf, atlas
62
- help · version
63
- `;
2
+ import { CommandTable } from './table.ts';
64
3
 
65
4
  export const runHelpCommand = async (): Promise<number> => {
66
- process.stdout.write(HELP);
5
+ process.stdout.write(CommandTable.helpText());
67
6
 
68
7
  return ExitCodes.OK;
69
8
  };
@@ -17,6 +17,8 @@ export const COMMAND_LOADERS: Record<string, () => Promise<TCommandHandler>> = {
17
17
  import('./doctor.command.ts').then((module) => module.runDoctorCommand),
18
18
  [VulcanCommands.EVENT]: () =>
19
19
  import('./event.command.ts').then((module) => module.runEventCommand),
20
+ [VulcanCommands.GRAPH]: () =>
21
+ import('./graph.command.ts').then((module) => module.runGraphCommand),
20
22
  [VulcanCommands.HELP]: () => import('./help.command.ts').then((module) => module.runHelpCommand),
21
23
  [VulcanCommands.INIT]: () => import('./init.command.ts').then((module) => module.runInitCommand),
22
24
  [VulcanCommands.PRESET]: () =>
@@ -1,3 +1,4 @@
1
+ import { ProjectTmp } from '../hooks/project-tmp.ts';
1
2
  import { relative } from 'node:path';
2
3
  import { ExitCodes } from '../common/index.ts';
3
4
  import type { ICommandContext } from '../common/index.ts';
@@ -118,7 +119,10 @@ export class SyncFlow {
118
119
  ...SyncPlanner.plan({ root: opts.cwd, config: loaded.config, agents: resolved.agents }),
119
120
  ...AtlasBlockPlan.plan({ root: opts.cwd, config: loaded.config }),
120
121
  ...stored,
121
- ...LocalPlan.planWorkspace({ root: opts.cwd }),
122
+ ...LocalPlan.planWorkspace({
123
+ root: opts.cwd,
124
+ tmp: ProjectTmp.configuredOf({ tmp: loaded.config.local.tmp }),
125
+ }),
122
126
  ...ExcludePlan.plan({ root: opts.cwd, agents: resolved.agents }),
123
127
  ...CommitHookPlan.plan({ root: opts.cwd, config: loaded.config }),
124
128
  ];