@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
@@ -1,17 +1,19 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { basename, join } from 'node:path';
3
- import { BunFormatter } from '../common/index.ts';
3
+ import { BunFormatter, EnvVariables } from '../common/index.ts';
4
4
  import { AgentSignaturePolicies } from '../commit/common/index.ts';
5
5
  import { ProjectPackages } from '../config/index.ts';
6
+ import { GuardDecisions } from '../hooks/common/index.ts';
6
7
  import type { TResolvedConfig } from '../config/index.ts';
7
8
  import { BaseRules } from '../rules/index.ts';
9
+ import { ThemeTokens } from '../theme/index.ts';
8
10
 
9
11
  export class ManifestConstants {
10
12
  /** Committed; what atlas reads from a project - local or fetched - and nothing else. */
11
13
  static readonly FILE = '.agents/vulcan.manifest.json';
12
14
  static readonly SCHEMA_VERSION = 1;
13
15
  static readonly PROJECT_RULES = '.agents/rules.md';
14
- static readonly ENV = 'VULCAN_MANIFEST';
16
+ static readonly ENV = EnvVariables.VULCAN_MANIFEST;
15
17
  /** The first key: a reader sees at once that the file is generated. Readers ignore it. */
16
18
  static readonly GENERATED_KEY = '$generated';
17
19
  static readonly GENERATED_NOTE = 'by vulcan sync from .configs/vulcan.config.* - do not edit';
@@ -19,11 +21,18 @@ export class ManifestConstants {
19
21
 
20
22
  const HASH_LENGTH = 8;
21
23
 
22
- /** The manifest's `guard` block: what the project adds to guard-writes and guard-git, as data a hook reads without the config (the read-only script entries of `trustedScripts` included). */
24
+ /**
25
+ * The manifest's `guard` block: what the project sets for the guards, as data a hook reads without the config, so a
26
+ * config this VULCAN cannot parse never changes a guard: `outside` (when it is not the default), `toolOwnedPaths`,
27
+ * the commands and trusted scripts of guard-writes, the push targets of guard-git.
28
+ */
23
29
  const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<string, unknown> } => {
24
30
  const { commands, trustedScripts } = opts.config.guard.writes;
25
31
  const { askPush } = opts.config.guard.git;
26
- // Only the object entries: a path string is read from the config by the hook, as before.
32
+ const { outside, toolOwnedPaths } = opts.config.guard;
33
+ const trustedPaths = trustedScripts.flatMap((entry) =>
34
+ typeof entry === 'string' ? [entry] : [],
35
+ );
27
36
  const readOnlyScripts = trustedScripts.flatMap((entry) =>
28
37
  typeof entry === 'string' ? [] : [{ script: entry.script, readOnly: entry.readOnly }],
29
38
  );
@@ -38,9 +47,12 @@ const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<strin
38
47
  ...(command.ignoreCase === true ? { ignoreCase: true } : {}),
39
48
  })),
40
49
  }),
50
+ ...(trustedPaths.length === 0 ? {} : { trustedScripts: trustedPaths }),
41
51
  ...(readOnlyScripts.length === 0 ? {} : { readOnlyScripts }),
42
52
  };
43
53
  const block = {
54
+ ...(outside === GuardDecisions.ASK ? {} : { outside }),
55
+ ...(toolOwnedPaths.length === 0 ? {} : { toolOwnedPaths }),
44
56
  ...(Object.keys(writes).length === 0 ? {} : { writes }),
45
57
  ...(askPush.length === 0 ? {} : { git: { askPush } }),
46
58
  };
@@ -70,6 +82,17 @@ const commitBlockOf = (opts: { config: TResolvedConfig }): { commit?: Record<str
70
82
  };
71
83
  };
72
84
 
85
+ /** The manifest's `graph` block, which atlas reads: only what the project sets. */
86
+ const graphBlockOf = (opts: { config: TResolvedConfig }): { graph?: Record<string, unknown> } => {
87
+ const { exclude, aliases } = opts.config.graph;
88
+ const block = {
89
+ ...(exclude.length === 0 ? {} : { exclude }),
90
+ ...(Object.keys(aliases).length === 0 ? {} : { aliases }),
91
+ };
92
+
93
+ return Object.keys(block).length === 0 ? {} : { graph: block };
94
+ };
95
+
73
96
  /** The manifest's `ci` block, which `vulcan ci affected` reads: only the globs the project adds. */
74
97
  const ciBlockOf = (opts: { config: TResolvedConfig }): { ci?: Record<string, unknown> } => {
75
98
  const { global } = opts.config.ci.affected;
@@ -91,9 +114,45 @@ const eventsBlockOf = (opts: { config: TResolvedConfig }): { events?: Record<str
91
114
  : {};
92
115
  };
93
116
 
94
- /** The manifest's `local` block: only when the project turns the automatic clean off, which the hook reads. */
95
- const localBlockOf = (opts: { config: TResolvedConfig }): { local?: Record<string, unknown> } =>
96
- opts.config.local.autoClean ? {} : { local: { autoClean: false } };
117
+ /** The manifest's `local` block, which the hooks and `vulcan clean` read: when the automatic clean is off or the project names its tmp folder. */
118
+ const localBlockOf = (opts: { config: TResolvedConfig }): { local?: Record<string, unknown> } => {
119
+ const { autoClean, tmp } = opts.config.local;
120
+ const block = {
121
+ ...(autoClean ? {} : { autoClean: false }),
122
+ ...(tmp === undefined ? {} : { tmp }),
123
+ };
124
+
125
+ return Object.keys(block).length === 0 ? {} : { local: block };
126
+ };
127
+
128
+ /**
129
+ * The manifest's `theme` block: the accent seeds the project gave, its preset, and the resolved design tokens (both
130
+ * modes, font, mono, radius) that the board, the pages and the wiki read. Always written: a project with no `theme`
131
+ * gets the default preset. A theme the check refused never reaches here (the config does not load).
132
+ */
133
+ const themeBlockOf = (opts: { config: TResolvedConfig }): { theme?: Record<string, unknown> } => {
134
+ const resolved = ThemeTokens.resolve({ theme: opts.config.theme });
135
+
136
+ if (!resolved.ok) {
137
+ return {};
138
+ }
139
+
140
+ const { preset, light, dark, font, mono, radius } = resolved.tokens;
141
+ const { accent, accentDark, accentText } = opts.config.theme ?? {};
142
+
143
+ return {
144
+ theme: {
145
+ ...(accent === undefined ? {} : { accent }),
146
+ ...(accentDark === undefined ? {} : { accentDark }),
147
+ ...(accentText === undefined ? {} : { accentText }),
148
+ preset,
149
+ tokens: { light, dark },
150
+ font,
151
+ mono,
152
+ radius,
153
+ },
154
+ };
155
+ };
97
156
 
98
157
  /** The manifest's `board` block, which `vulcan board` reads: only what the project sets. */
99
158
  const boardBlockOf = (opts: { config: TResolvedConfig }): { board?: Record<string, unknown> } => {
@@ -127,6 +186,7 @@ const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<strin
127
186
  return Object.keys(block).length === 0 ? {} : { atlas: block };
128
187
  };
129
188
 
189
+ /** Renders `.agents/vulcan.manifest.json` from the config and the base rule hashes; written by `vulcan sync`. */
130
190
  export class ProjectManifest {
131
191
  /** `@acme/shop-workspace` gives `shop`; a project with no package name takes its directory's. */
132
192
  static projectNameOf(opts: { root: string; config: TResolvedConfig }): string {
@@ -207,8 +267,8 @@ export class ProjectManifest {
207
267
  ...guardBlockOf({ config }),
208
268
  // The remote-host guard reads its policy here; a project without the key has no guard.
209
269
  ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
210
- // The colour `vulcan visualize` takes for its pages; a project without the key gets the neutral default.
211
- ...(config.theme === undefined ? {} : { theme: config.theme }),
270
+ // The design tokens: the preset, the seeds the project gave and the resolved set every consumer reads.
271
+ ...themeBlockOf({ config }),
212
272
  ...commitBlockOf({ config }),
213
273
  // The files the project adds to the ones that make every package affected; none added, nothing is written.
214
274
  ...ciBlockOf({ config }),
@@ -216,6 +276,7 @@ export class ProjectManifest {
216
276
  ...boardBlockOf({ config }),
217
277
  // The automatic clean of .agents/local is on unless the project turns it off here.
218
278
  ...localBlockOf({ config }),
279
+ ...graphBlockOf({ config }),
219
280
  // Whether the Claude Code hooks write the agent event log, and the folder it goes to.
220
281
  ...eventsBlockOf({ config }),
221
282
  // The key a flow is named by; the hooks and `vulcan event` read it here, not from the config.
@@ -1,3 +1,5 @@
1
+ import { EnvVariables } from '../common/env-variables.ts';
2
+
1
3
  /** The sections of a reply to the owner; a project picks which appear and in what order. */
2
4
  export class OwnerSections {
3
5
  static readonly HEADLINE = 'headline';
@@ -106,7 +108,7 @@ export class OwnerConstants {
106
108
 
107
109
  /** The launcher of a session whose replies an agent reads sets this; the owner's own sessions never have it. */
108
110
  export class OwnerReplySwitch {
109
- static readonly ENV = 'VULCAN_OWNER_REPLY';
111
+ static readonly ENV = EnvVariables.VULCAN_OWNER_REPLY;
110
112
  /** The only value that counts: anything else is ignored, so a stray value never switches the check off. */
111
113
  static readonly OFF = 'off';
112
114
  }
@@ -9,6 +9,7 @@ type TProfileRead = { ok: true; profile: TProfile | undefined } | { ok: false; e
9
9
 
10
10
  const SYMLINK_ERROR = `${OwnerConstants.PROFILE_FILE} (or .agents/local) is a symlink - it must be a regular file inside the project`;
11
11
 
12
+ /** Reads, renders and writes the per-person owner profile file inside `.agents/local`; used by `vulcan profile`, `vulcan doctor` and the session digest. */
12
13
  export class OwnerProfile {
13
14
  /** A symlink at the profile's place, or at `.agents/local`, would read or write a file outside the project. */
14
15
  static linkedAt(opts: { root: string }): string | undefined {
@@ -52,19 +52,32 @@ const DEFAULTS = OwnerConstants.DEFAULT_LABELS;
52
52
 
53
53
  /** The words of one language: the minimap header, the six statuses and five labels. A closed list. */
54
54
  export const OWNER_LABEL_SET = z.strictObject({
55
+ /** Three column headers of the minimap table, in order; each one line of at most 80 characters. */
55
56
  minimapColumns: z.tuple([TEXT, TEXT, TEXT]),
57
+ /** Words for the six task statuses of the minimap. */
56
58
  status: z.strictObject({
59
+ /** Status word for finished work. */
57
60
  done: TEXT,
61
+ /** Status word for work under way. */
58
62
  doing: TEXT,
63
+ /** Status word for work waiting on someone. */
59
64
  waiting: TEXT,
65
+ /** Status word for work not yet started. */
60
66
  todo: TEXT,
67
+ /** Status word for work that cannot go on. */
61
68
  blocked: TEXT,
69
+ /** Status word for work that was dropped. */
62
70
  dropped: TEXT,
63
71
  }),
72
+ /** Labels for the blocked and decisions parts of a reply. */
64
73
  labels: z.strictObject({
74
+ /** Label that opens the blocked line of a reply. */
65
75
  blocked: TEXT,
76
+ /** Heading of the decisions part of a reply. */
66
77
  decisions: TEXT,
78
+ /** Text shown in the blocked line when nothing blocks. */
67
79
  noBlocker: TEXT,
80
+ /** Text shown in the decisions part when no decision is needed. */
68
81
  noDecision: TEXT,
69
82
  /** `{x}` is where the recommended answer goes. */
70
83
  recommend: TEXT.refine((value) => value.includes('{x}'), { message: 'must contain {x}' }),
@@ -78,25 +91,36 @@ export const OWNER_LABEL_SET = z.strictObject({
78
91
  */
79
92
  export const OWNER_SCHEMA = z
80
93
  .strictObject({
94
+ /** Language of the reply labels, a code such as `en` or `pt-BR`; default `en`. */
81
95
  language: LANGUAGE.default(OwnerConstants.DEFAULT_LANGUAGE),
96
+ /** How a reply is shaped: sections, minimap columns, status words, labels, headline length, path style, enforcement and claim words. */
82
97
  report: z
83
98
  .strictObject({
99
+ /** Sections of a reply, in order: headline, minimap, blocked, detail, decisions; at least one, default all five in that order. */
84
100
  shape: z.array(SECTION).min(1).default(OwnerConstants.DEFAULT_SHAPE),
101
+ /** Three minimap column headers; default `#`, `Task`, `Status`. */
85
102
  minimapColumns: z.tuple([TEXT, TEXT, TEXT]).default(DEFAULTS.minimapColumns),
103
+ /** Status words of the minimap; default the English set (done, in progress, waiting, not started, blocked, dropped). */
86
104
  status: OWNER_LABEL_SET.shape.status.default(DEFAULTS.status),
105
+ /** Labels of the blocked and decisions parts; default the English set. */
87
106
  labels: OWNER_LABEL_SET.shape.labels.default(DEFAULTS.labels),
107
+ /** Most sentences the headline of a reply may have, 1 to 5; default 2. */
88
108
  headlineMaxSentences: z
89
109
  .number()
90
110
  .int()
91
111
  .min(1)
92
112
  .max(5)
93
113
  .default(OwnerConstants.DEFAULT_HEADLINE_MAX_SENTENCES),
114
+ /** Whether file paths in a reply must be absolute; default `true`. */
94
115
  absolutePaths: z.boolean().default(true),
116
+ /** How hard the reply shape is held: `off`, `advise` or `block`; default `advise`. */
95
117
  enforce: ENFORCE.default(OwnerEnforcement.ADVISE),
96
118
  /** Words that say something is in public state, or that the checks pass, in the owner's language, added to the English ones. */
97
119
  claimWords: z
98
120
  .strictObject({
121
+ /** Extra phrases, besides the English ones, that claim something is in public state; up to 20, each 3 to 60 characters; default none. */
99
122
  public: CLAIM_WORDS.default([]),
123
+ /** Extra phrases, besides the English ones, that claim the checks pass; up to 20, each 3 to 60 characters; default none. */
100
124
  done: CLAIM_WORDS.default([]),
101
125
  })
102
126
  .prefault({}),
@@ -109,34 +133,41 @@ export const OWNER_SCHEMA = z
109
133
 
110
134
  /** `.agents/local/profile.json`: what one developer told VULCAN about how to work with them. */
111
135
  export const PROFILE_SCHEMA = z.strictObject({
136
+ /** Version of the profile file format; must be `1`. */
112
137
  schemaVersion: z.literal(OwnerConstants.PROFILE_SCHEMA_VERSION),
113
138
  /** Reply language; labels for it come from `labels` below. A language that is not English with none has its labels written by the agent, and only the structure is checked. */
114
139
  language: LANGUAGE.optional(),
140
+ /** How the agent addresses the person: what it calls them, itself, and how formal; default neutral formality. */
115
141
  address: z
116
142
  .strictObject({
117
- /** How to address the person: a name, a pronoun, an honorific, or nothing. */
143
+ /** Form of address for the person: a name, pronoun or honorific, one line of at most 80 characters; absent means none. */
118
144
  you: TEXT.optional(),
119
- /** How the agent refers to itself. */
145
+ /** How the agent refers to itself, one line of at most 80 characters; absent means no fixed form. */
120
146
  self: TEXT.optional(),
147
+ /** How formal the address is: `informal`, `neutral` or `formal`; default `neutral`. */
121
148
  formality: FORMALITY.default(OwnerFormalities.NEUTRAL),
122
149
  })
123
150
  .prefault({}),
151
+ /** Tone of replies: `terse`, `neutral` or `friendly`; default `neutral`. */
124
152
  tone: TONE.default(OwnerTones.NEUTRAL),
153
+ /** How much a reply spells out: `headline` or `tables`; default `tables`. */
125
154
  reportDetail: DETAIL.default(OwnerDetails.TABLES),
155
+ /** Working habits the agent follows with this person; both default to `false`. */
126
156
  habits: z
127
157
  .strictObject({
128
158
  /** Ask before a reversible choice; false means state a default and continue (V-P-10). */
129
159
  askBeforeReversible: z.boolean().default(false),
160
+ /** Whether the agent is told to propose commits; default `false`. */
130
161
  proposeCommits: z.boolean().default(false),
131
162
  })
132
163
  .prefault({}),
133
- /** In the person's own words, never scored or used to infer traits. */
164
+ /** Free text in the person's own words, up to 2000 characters; the digest card shows the first 200, and it is never scored. */
134
165
  about: z.string().max(2000).optional(),
135
- /** Taste in code that no formatter or lint rule already enforces. */
166
+ /** Taste in code that no formatter or lint rule enforces, up to 1000 characters; absent means none. */
136
167
  codeTaste: z.string().max(1000).optional(),
137
- /** Stricter than the project's, never looser. */
168
+ /** Own enforcement level: `off`, `advise` or `block`; only counts when stricter than the project's, else the project's wins. */
138
169
  enforce: ENFORCE.optional(),
139
- /** Lower than the project's, never higher: 0 holds every reply to the shape. */
170
+ /** Own short-reply limit, 0 to 200 words; only counts when lower than the project's, and 0 holds every reply to the shape. */
140
171
  shortReplyWords: SHORT_REPLY_WORDS.optional(),
141
172
  /** The label set of each language the person uses, keyed by language code. */
142
173
  labels: z.record(LANGUAGE, OWNER_LABEL_SET).default({}),
package/src/router.ts CHANGED
@@ -1,138 +1,12 @@
1
- import { AgentConstants } from './agents/index.ts';
2
1
  import { COMMAND_LOADERS } from './commands/index.ts';
3
- import { BoardFlags } from './board/common/index.ts';
4
- import { CiFlags } from './ci/common/index.ts';
5
- import { CommitCheckFlags } from './commit/common/index.ts';
6
- import { ExitCodes, UpgradeFlags, VulcanCommands } from './common/index.ts';
7
- import { CreateFlags } from './create/common/index.ts';
8
- import { EventFlags } from './events/common/index.ts';
2
+ import { CommandTable } from './commands/table.ts';
3
+ import type { IAcceptedArgs } from './commands/table.ts';
4
+ import { ExitCodes, VulcanCommands } from './common/index.ts';
9
5
  import { PipedInputRefusal } from './ui/keyboard.ts';
10
6
 
11
7
  const HELP_ALIASES = new Set(['--help', '-h']);
12
8
  const VERSION_ALIASES = new Set(['--version', '-v']);
13
9
 
14
- interface IAcceptedArgs {
15
- flags: string[];
16
- /** The exit code for an argument the command does not take; `1` when absent. */
17
- unknownExit?: number;
18
- /** Flags that take the next argument as their value. */
19
- values: string[];
20
- positionals: number;
21
- }
22
-
23
- /** What each command takes; `x` hands everything to its tool, `help` and `version` take nothing. */
24
- const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
25
- [VulcanCommands.INIT]: {
26
- flags: [CreateFlags.NO_API],
27
- values: [
28
- CreateFlags.PRESET,
29
- CreateFlags.PROJECT,
30
- CreateFlags.BACKEND_DIR,
31
- CreateFlags.FRONTEND_DIR,
32
- CreateFlags.SHARED_DIR,
33
- CreateFlags.APP,
34
- CreateFlags.API,
35
- CreateFlags.SCOPE,
36
- CreateFlags.KEY,
37
- ],
38
- positionals: 0,
39
- },
40
- [VulcanCommands.ADD]: {
41
- flags: [CreateFlags.NO_API],
42
- values: [
43
- CreateFlags.PRESET,
44
- CreateFlags.BACKEND_DIR,
45
- CreateFlags.FRONTEND_DIR,
46
- CreateFlags.APP,
47
- CreateFlags.API,
48
- CreateFlags.LIB,
49
- CreateFlags.SHARED,
50
- CreateFlags.DIR,
51
- CreateFlags.SCOPE,
52
- ],
53
- positionals: 0,
54
- },
55
- [VulcanCommands.PRESET]: {
56
- flags: [CreateFlags.NO_API, CreateFlags.FULL, CreateFlags.CHECK],
57
- values: [CreateFlags.PRESET, CreateFlags.API],
58
- positionals: 2,
59
- },
60
- [VulcanCommands.SYNC]: {
61
- flags: ['--dry-run'],
62
- values: [AgentConstants.FLAG],
63
- positionals: 0,
64
- },
65
- [VulcanCommands.AGENTS]: { flags: ['--dry-run'], values: [], positionals: 2 },
66
- [VulcanCommands.CLEAN]: {
67
- flags: [
68
- '--tmp',
69
- '--worktrees',
70
- '--clones',
71
- '--cache',
72
- '--reports',
73
- '--prototypes',
74
- '--profile',
75
- '--events',
76
- '--release-candidates',
77
- '--all',
78
- '--yes',
79
- ],
80
- values: [],
81
- positionals: 0,
82
- },
83
- [VulcanCommands.COMMIT_CHECK]: {
84
- flags: [],
85
- unknownExit: ExitCodes.USAGE,
86
- values: [CommitCheckFlags.RANGE, CommitCheckFlags.TEXT],
87
- positionals: 2,
88
- },
89
- [VulcanCommands.BOARD]: {
90
- flags: [BoardFlags.OPEN, BoardFlags.NO_GITHUB],
91
- unknownExit: ExitCodes.USAGE,
92
- values: [BoardFlags.OUT, BoardFlags.PORT, BoardFlags.SINCE, BoardFlags.DIR, BoardFlags.REPO],
93
- positionals: 1,
94
- },
95
- [VulcanCommands.CI]: {
96
- flags: [CiFlags.JSON, CiFlags.NAMES],
97
- unknownExit: ExitCodes.USAGE,
98
- values: [CiFlags.BASE, CiFlags.HEAD, CiFlags.CHECK],
99
- positionals: 2,
100
- },
101
- [VulcanCommands.EVENT]: {
102
- flags: [EventFlags.JSON],
103
- unknownExit: ExitCodes.USAGE,
104
- values: [
105
- EventFlags.KIND,
106
- EventFlags.SUMMARY,
107
- EventFlags.FLOW,
108
- EventFlags.STEP,
109
- EventFlags.STEP_DONE,
110
- EventFlags.CHECK,
111
- EventFlags.CHECK_DONE,
112
- EventFlags.APP,
113
- EventFlags.DUE,
114
- EventFlags.REF,
115
- EventFlags.STATUS,
116
- EventFlags.TITLE,
117
- EventFlags.WHY,
118
- EventFlags.CONTEXT,
119
- EventFlags.NEXT,
120
- EventFlags.ACTOR,
121
- EventFlags.DIR,
122
- EventFlags.SINCE,
123
- ],
124
- positionals: 1,
125
- },
126
- [VulcanCommands.DOCTOR]: { flags: [], values: [], positionals: 0 },
127
- [VulcanCommands.PROFILE]: { flags: ['--yes'], values: [], positionals: 1 },
128
- [VulcanCommands.VISUALIZE]: { flags: ['--schema'], values: ['--out'], positionals: 1 },
129
- [VulcanCommands.UPGRADE]: {
130
- flags: [UpgradeFlags.STABLE, UpgradeFlags.NIGHTLY],
131
- values: [],
132
- positionals: 1,
133
- },
134
- };
135
-
136
10
  /** The command name an argv asks for: no argument or a help flag means help. */
137
11
  const resolveCommandName = (opts: { first: string | undefined }): string => {
138
12
  if (opts.first === undefined || HELP_ALIASES.has(opts.first)) {
@@ -190,7 +64,7 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
190
64
  return runHelp({ cwd: opts.cwd });
191
65
  }
192
66
 
193
- const accepted = ACCEPTED_ARGS[name];
67
+ const accepted = CommandTable.accepted({ name });
194
68
 
195
69
  if (accepted !== undefined) {
196
70
  if (args.some((arg) => HELP_ALIASES.has(arg))) {
package/src/rules/base.ts CHANGED
@@ -5,6 +5,7 @@ import { RuleParser } from './parser.ts';
5
5
 
6
6
  const readBaseMarkdown = (): string => readFileSync(join(BASE_DIRECTORY, 'rules.md'), 'utf8');
7
7
 
8
+ /** Reads the base rule file shipped with the CLI as a map of rule ID to text; used by `vulcan sync` and `vulcan doctor`. */
8
9
  export class BaseRules {
9
10
  /** Each base rule's ID with its table row, verbatim. */
10
11
  static read(): Record<string, string> {
@@ -1,6 +1,7 @@
1
1
  import { SignalConstants } from './constants.ts';
2
2
  import type { ISignalEvent } from './state.ts';
3
3
 
4
+ /** Detects an agent going in circles from its recent tool calls; used by the post-tool hook. */
4
5
  export class SignalLoop {
5
6
  /**
6
7
  * What the last calls look like when an agent is going round in circles: the same call three times within
@@ -8,6 +8,7 @@ const parseYaml = (opts: { text: string }): { value?: unknown; error?: string }
8
8
  }
9
9
  };
10
10
 
11
+ /** Extracts and validates the YAML frontmatter of a skill file; used by the doctor skill checks. */
11
12
  export class SkillFrontmatter {
12
13
  /**
13
14
  * The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
@@ -16,16 +16,16 @@ export class LaunchSettings {
16
16
  * moves its own task-output files and its MCP servers into the project. Absolute paths: the file belongs
17
17
  * to one checkout of one developer.
18
18
  */
19
- static renderClaude(opts: { root: string }): string {
20
- const folder = ProjectTmp.projectOf({ root: opts.root });
19
+ static renderClaude(opts: { root: string; tmp?: string }): string {
20
+ const folder = ProjectTmp.projectOf(opts);
21
21
 
22
22
  return `${JSON.stringify({ env: { TMPDIR: folder, CLAUDE_CODE_TMPDIR: folder } }, null, 2)}\n`;
23
23
  }
24
24
 
25
25
  /** The launch file when it is missing or written for another folder; nothing to do when it is current. */
26
- static planClaude(opts: { root: string }): ISyncAction[] {
26
+ static planClaude(opts: { root: string; tmp?: string }): ISyncAction[] {
27
27
  const path = join(opts.root, CLAUDE_LAUNCH_FILE);
28
- const text = LaunchSettings.renderClaude({ root: opts.root });
28
+ const text = LaunchSettings.renderClaude(opts);
29
29
  const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
30
30
 
31
31
  if (before === text) {
@@ -100,14 +100,14 @@ export class ClaudeLaunch {
100
100
  }
101
101
  }
102
102
 
103
- return {
104
- state: homes.some((home) =>
105
- inside({ folder: real, base: join(home, ProjectLayout.LOCAL_DIRECTORY) }),
106
- )
107
- ? 'inside'
108
- : 'outside',
109
- folder,
110
- };
103
+ const isInProjectTmp = [opts.root, ...homes].some((home) =>
104
+ inside({ folder: real, base: realOf({ path: ProjectTmp.projectOf({ root: home }) }) }),
105
+ );
106
+ const isInLocal = homes.some((home) =>
107
+ inside({ folder: real, base: join(home, ProjectLayout.LOCAL_DIRECTORY) }),
108
+ );
109
+
110
+ return { state: isInProjectTmp || isInLocal ? 'inside' : 'outside', folder };
111
111
  }
112
112
 
113
113
  /**
@@ -1,7 +1,9 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
- import { dirname, join } from 'node:path';
2
+ import { dirname, join, relative } from 'node:path';
3
3
  import { LOCAL_AGENTS_FILE, LocalChoice } from '../agents/index.ts';
4
4
  import { ProjectLayout } from '../common/index.ts';
5
+ import { HookConstants } from '../hooks/common/index.ts';
6
+ import { ProjectTmp } from '../hooks/project-tmp.ts';
5
7
  import { LaunchSettings } from './claude-launch.ts';
6
8
  import { SyncStatuses } from './common/index.ts';
7
9
  import type { ISyncAction } from './common/index.ts';
@@ -62,11 +64,37 @@ export class LocalPlan {
62
64
  return planIgnoreLine({ root: opts.root, line: LOCAL_AGENTS_FILE });
63
65
  }
64
66
 
67
+ /**
68
+ * The folder `local.tmp` names, when it is not the default one: made and gitignored (a name is never hidden, so
69
+ * it is never under the `.agents/local/` that is ignored whole). The default folder is one of the layout's.
70
+ */
71
+ static planTmp(opts: { root: string; tmp?: string }): ISyncAction[] {
72
+ const tmp = ProjectTmp.projectOf(opts);
73
+
74
+ if (tmp === join(opts.root, HookConstants.PROJECT_TMP)) {
75
+ return [];
76
+ }
77
+
78
+ const isMade = existsSync(tmp);
79
+
80
+ return [
81
+ ...planIgnoreLine({ root: opts.root, line: `/${relative(opts.root, tmp)}/` }),
82
+ {
83
+ path: tmp,
84
+ status: isMade ? SyncStatuses.UNCHANGED : SyncStatuses.CREATED,
85
+ ...(isMade ? {} : { note: 'the project tmp folder, local.tmp' }),
86
+ apply: () => {
87
+ mkdirSync(tmp, { recursive: true });
88
+ },
89
+ },
90
+ ];
91
+ }
92
+
65
93
  /**
66
94
  * The project's local workspace: `.agents/local/` is gitignored and holds what an agent creates while
67
95
  * it works (scratch, worktrees, clones, cache, prototypes), so nothing lands outside the project.
68
96
  */
69
- static planWorkspace(opts: { root: string }): ISyncAction[] {
97
+ static planWorkspace(opts: { root: string; tmp?: string }): ISyncAction[] {
70
98
  const directory = join(opts.root, ProjectLayout.LOCAL_DIRECTORY);
71
99
  const missing = ProjectLayout.LOCAL_LAYOUT.filter((entry) => !('onDemand' in entry))
72
100
  .map((entry) => entry.name)
@@ -74,7 +102,8 @@ export class LocalPlan {
74
102
 
75
103
  return [
76
104
  ...planIgnoreLine({ root: opts.root, line: `${ProjectLayout.LOCAL_DIRECTORY}/` }),
77
- ...LaunchSettings.planClaude({ root: opts.root }),
105
+ ...LocalPlan.planTmp(opts),
106
+ ...LaunchSettings.planClaude(opts),
78
107
  {
79
108
  path: directory,
80
109
  status: missing.length === 0 ? SyncStatuses.UNCHANGED : SyncStatuses.CREATED,
@@ -287,6 +287,7 @@ const skillDirectoriesOf = (opts: { agents: string[] }): string[] => [
287
287
  ),
288
288
  ];
289
289
 
290
+ /** Plans the files `vulcan sync` writes, as a list of actions, without touching disk; also used by `vulcan doctor` to find drift. */
290
291
  export class SyncPlanner {
291
292
  /** The committed project manifest (Project Contract v1, C1), rendered from the config. */
292
293
  static planManifest(opts: { root: string; config: TResolvedConfig }): ISyncAction {
@@ -0,0 +1 @@
1
+ export * from './tokens.ts';