@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.
- package/README.md +26 -18
- package/base/hooks/guard-outside.ts +10 -19
- package/base/hooks/guard-writes.ts +3 -24
- package/base/make/vulcan.mk +1 -4
- package/base/rules.md +4 -4
- package/base/skills/visualize-work/SKILL.md +1 -1
- package/base/skills/visualize-work/references/spec.md +1 -1
- package/base/templates/board.html +10 -110
- package/package.json +3 -3
- package/src/agents/resolve.ts +1 -0
- package/src/board/command.ts +16 -1
- package/src/board/common/constants.ts +2 -0
- package/src/board/common/types.ts +2 -2
- package/src/board/page.ts +57 -5
- package/src/board/schema.ts +4 -1
- package/src/board/server.ts +13 -2
- package/src/board/settings.ts +1 -1
- package/src/commands/graph.command.ts +6 -0
- package/src/commands/help.command.ts +2 -63
- package/src/commands/index.ts +2 -0
- package/src/commands/sync.command.ts +5 -1
- package/src/commands/table.ts +327 -0
- package/src/commit/check.ts +1 -0
- package/src/commit/common/constants.ts +2 -0
- package/src/commit/hook.ts +44 -4
- package/src/common/constants.ts +7 -3
- package/src/common/env-variables.ts +37 -0
- package/src/common/index.ts +1 -0
- package/src/config/loader.ts +22 -0
- package/src/config/schema.ts +162 -20
- package/src/create/add-app.ts +5 -0
- package/src/create/common/constants.ts +5 -3
- package/src/create/preset.ts +1 -0
- package/src/create/scratch.ts +2 -1
- package/src/doctor/checks.ts +106 -4
- package/src/doctor/common/constants.ts +26 -0
- package/src/doctor/runner.ts +3 -0
- package/src/doctor/schema.ts +4 -0
- package/src/hooks/owner-reply.ts +5 -0
- package/src/hooks/project-guards.ts +28 -4
- package/src/hooks/project-tmp.ts +39 -4
- package/src/hooks/session-digest.ts +9 -0
- package/src/init/scaffold.ts +1 -0
- package/src/local/auto-clean.ts +2 -1
- package/src/local/browser-socket.ts +33 -0
- package/src/local/clean.ts +1 -0
- package/src/local/index.ts +1 -0
- package/src/local/scan.ts +33 -9
- package/src/manifest/render.ts +70 -9
- package/src/owner/constants.ts +3 -1
- package/src/owner/profile.ts +1 -0
- package/src/owner/schema.ts +37 -6
- package/src/router.ts +4 -130
- package/src/rules/base.ts +1 -0
- package/src/signals/loop.ts +1 -0
- package/src/skills/frontmatter.ts +1 -0
- package/src/sync/claude-launch.ts +12 -12
- package/src/sync/local-choice.ts +32 -3
- package/src/sync/planner.ts +1 -0
- package/src/theme/index.ts +1 -0
- package/src/theme/tokens.ts +410 -0
- package/src/ui/prompt.ts +1 -0
- package/src/visualize/page.ts +4 -4
- package/src/visualize/render.ts +2 -1
- package/src/visualize/theme.ts +43 -12
- package/src/wiki/anchors.ts +1 -0
package/src/manifest/render.ts
CHANGED
|
@@ -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 =
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
|
95
|
-
const localBlockOf = (opts: { config: TResolvedConfig }): { local?: Record<string, unknown> } =>
|
|
96
|
-
|
|
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
|
|
211
|
-
...(
|
|
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.
|
package/src/owner/constants.ts
CHANGED
|
@@ -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 =
|
|
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
|
}
|
package/src/owner/profile.ts
CHANGED
|
@@ -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 {
|
package/src/owner/schema.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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 {
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
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 =
|
|
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> {
|
package/src/signals/loop.ts
CHANGED
|
@@ -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(
|
|
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(
|
|
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
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
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
|
/**
|
package/src/sync/local-choice.ts
CHANGED
|
@@ -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
|
-
...
|
|
105
|
+
...LocalPlan.planTmp(opts),
|
|
106
|
+
...LaunchSettings.planClaude(opts),
|
|
78
107
|
{
|
|
79
108
|
path: directory,
|
|
80
109
|
status: missing.length === 0 ? SyncStatuses.UNCHANGED : SyncStatuses.CREATED,
|
package/src/sync/planner.ts
CHANGED
|
@@ -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';
|