@venizia/vulcan 0.4.8 → 0.4.9-1
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/base/extensions/vulcan-guards.ts +48 -41
- package/base/hooks/antigravity-guards.ts +4 -3
- package/base/hooks/codex-guards.ts +17 -6
- package/base/hooks/guard-git.ts +8 -8
- package/base/hooks/guard-manifest.ts +5 -5
- package/base/hooks/guard-outside.ts +8 -8
- package/base/hooks/guard-package.ts +6 -6
- package/base/hooks/guard-remote-hosts.ts +14 -9
- package/base/hooks/guard-scripting.ts +6 -6
- package/base/hooks/guard-writes.ts +20 -11
- package/base/hooks/post-tool.ts +4 -3
- package/base/hooks/prompt-submit.ts +4 -3
- package/base/hooks/session-start.ts +5 -3
- package/base/hooks/stop.ts +4 -3
- package/base/hooks/subagent-start.ts +2 -2
- package/base/make/vulcan.mk +1 -4
- package/base/skills/build-a-feature/SKILL.md +1 -1
- package/base/skills/docs-update/SKILL.md +11 -5
- package/base/skills/docs-update/evals/evals.json +1 -1
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/plan-a-change/references/spec-card.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +29 -6
- package/base/skills/visualize-work/references/spec.md +16 -5
- package/package.json +5 -6
- package/src/agents/atlas-block.ts +43 -43
- package/src/agents/codex-hooks.ts +55 -52
- package/src/agents/common/types.ts +1 -1
- package/src/agents/detect.ts +19 -16
- package/src/agents/exclude.ts +97 -98
- package/src/agents/hooks-json.ts +41 -43
- package/src/agents/local.ts +46 -43
- package/src/agents/prompt.ts +45 -42
- package/src/agents/render.ts +203 -201
- package/src/agents/resolve.ts +133 -134
- package/src/agents/table.ts +12 -8
- package/src/cli.ts +3 -1
- package/src/commands/add.command.ts +2 -2
- package/src/commands/agents.command.ts +11 -17
- package/src/commands/clean.command.ts +6 -6
- package/src/commands/doctor.command.ts +6 -4
- package/src/commands/help.command.ts +11 -9
- package/src/commands/init.command.ts +14 -8
- package/src/commands/preset.command.ts +2 -2
- package/src/commands/profile.command.ts +43 -50
- package/src/commands/sync.command.ts +109 -111
- package/src/commands/upgrade.command.ts +85 -78
- package/src/commands/visualize.command.ts +20 -5
- package/src/commands/x.command.ts +55 -50
- package/src/common/format.ts +23 -21
- package/src/common/index.ts +2 -0
- package/src/common/json.ts +8 -5
- package/src/common/layout-folder.ts +96 -111
- package/src/common/paths.ts +14 -12
- package/src/common/record.ts +7 -0
- package/src/common/text.ts +7 -0
- package/src/config/common/constants.ts +13 -1
- package/src/config/common/types.ts +8 -1
- package/src/config/loader.ts +53 -48
- package/src/config/packages.ts +17 -11
- package/src/config/schema.ts +54 -7
- package/src/create/add-app.ts +604 -493
- package/src/create/add-lib.ts +249 -242
- package/src/create/bunfig.ts +26 -23
- package/src/create/checks.ts +36 -34
- package/src/create/common/constants.ts +1 -0
- package/src/create/common/failure.ts +10 -0
- package/src/create/common/index.ts +2 -0
- package/src/create/common/preset-path.ts +11 -0
- package/src/create/common/types.ts +7 -2
- package/src/create/diff.ts +21 -23
- package/src/create/dockerignore.ts +26 -24
- package/src/create/files.ts +7 -5
- package/src/create/init-monorepo.ts +78 -80
- package/src/create/lib-preset.ts +62 -61
- package/src/create/manifest-json.ts +10 -4
- package/src/create/names.ts +217 -210
- package/src/create/next.ts +27 -24
- package/src/create/plan.ts +15 -12
- package/src/create/preset-diff.ts +415 -240
- package/src/create/preset-menu.ts +40 -34
- package/src/create/preset.ts +207 -194
- package/src/create/process.ts +80 -71
- package/src/create/scratch.ts +49 -48
- package/src/create/workspace.ts +423 -398
- package/src/doctor/checks.ts +1069 -998
- package/src/doctor/makefile.ts +17 -13
- package/src/doctor/runner.ts +88 -116
- package/src/doctor/skills.ts +97 -95
- package/src/doctor/tags.ts +44 -41
- package/src/hooks/codex-patch.ts +27 -24
- package/src/hooks/command-view.ts +44 -39
- package/src/hooks/common/constants.ts +0 -3
- package/src/hooks/common/types.ts +15 -1
- package/src/hooks/decision.ts +38 -42
- package/src/hooks/guard-git.ts +52 -50
- package/src/hooks/guard-manifest.ts +58 -55
- package/src/hooks/guard-outside.ts +109 -88
- package/src/hooks/guard-package.ts +86 -77
- package/src/hooks/guard-scripting.ts +20 -15
- package/src/hooks/guard-writes.ts +169 -111
- package/src/hooks/owner-reply.ts +128 -128
- package/src/hooks/post-tool.ts +94 -93
- package/src/hooks/project-guards.ts +93 -55
- package/src/hooks/project-tmp.ts +27 -24
- package/src/hooks/remote-hosts.ts +157 -149
- package/src/hooks/session-digest.ts +99 -95
- package/src/hooks/shell.ts +519 -500
- package/src/hooks/subagent-card.ts +11 -7
- package/src/hooks/trusted-scripts.ts +158 -80
- package/src/init/common/types.ts +1 -1
- package/src/init/scaffold.ts +137 -134
- package/src/local/clean.ts +39 -37
- package/src/local/format.ts +21 -17
- package/src/local/scan.ts +146 -140
- package/src/manifest/render.ts +127 -112
- package/src/owner/card.ts +51 -46
- package/src/owner/profile.ts +100 -96
- package/src/owner/reply-switch.ts +9 -6
- package/src/owner/shape.ts +72 -70
- package/src/owner/survey.ts +175 -164
- package/src/owner/view.ts +62 -59
- package/src/owner/violations.ts +119 -123
- package/src/router.ts +4 -1
- package/src/rules/base.ts +15 -11
- package/src/rules/common/types.ts +1 -1
- package/src/rules/parser.ts +39 -32
- package/src/rules/slots.ts +8 -6
- package/src/signals/claims.ts +30 -28
- package/src/signals/classify.ts +36 -33
- package/src/signals/loop.ts +39 -37
- package/src/signals/state.ts +80 -85
- package/src/skills/frontmatter.ts +28 -28
- package/src/sync/agent-files.ts +217 -199
- package/src/sync/agent-removal.ts +62 -68
- package/src/sync/atlas-block.ts +45 -43
- package/src/sync/base-rules.ts +32 -30
- package/src/sync/claude-launch.ts +74 -37
- package/src/sync/common/constants.ts +4 -0
- package/src/sync/common/index.ts +1 -0
- package/src/sync/common/symlink.ts +9 -0
- package/src/sync/common/types.ts +2 -2
- package/src/sync/exclude.ts +77 -69
- package/src/sync/local-choice.ts +50 -47
- package/src/sync/planner.ts +64 -68
- package/src/sync/prune.ts +52 -48
- package/src/sync/settings.ts +167 -168
- package/src/ui/capability.ts +12 -7
- package/src/ui/keyboard.ts +35 -33
- package/src/ui/prompt.ts +81 -77
- package/src/visualize/assets.ts +379 -195
- package/src/visualize/charts.ts +188 -176
- package/src/visualize/compare-css.ts +31 -0
- package/src/visualize/compare-render.ts +196 -0
- package/src/visualize/compare-schema.ts +81 -0
- package/src/visualize/compare-validate.ts +126 -0
- package/src/visualize/constants.ts +29 -3
- package/src/visualize/diagrams.ts +189 -174
- package/src/visualize/gate.ts +136 -0
- package/src/visualize/grid-span.ts +34 -0
- package/src/visualize/icons.ts +9 -4
- package/src/visualize/index.ts +2 -0
- package/src/visualize/kinds-css.ts +54 -0
- package/src/visualize/kinds-render.ts +698 -0
- package/src/visualize/kinds-schema.ts +148 -0
- package/src/visualize/kinds-validate.ts +186 -0
- package/src/visualize/labels-vi.ts +109 -0
- package/src/visualize/labels.ts +53 -0
- package/src/visualize/layout.ts +112 -92
- package/src/visualize/page.ts +140 -114
- package/src/visualize/render.ts +158 -114
- package/src/visualize/schema.ts +21 -1
- package/src/visualize/sections.ts +401 -309
- package/src/visualize/sources.ts +270 -0
- package/src/visualize/theme.ts +474 -0
- package/src/visualize/validate.ts +15 -5
- package/src/wiki/anchors.ts +39 -37
- package/src/wiki/command.ts +4 -4
- package/src/wiki/source-links.ts +49 -49
package/src/doctor/checks.ts
CHANGED
|
@@ -1,61 +1,37 @@
|
|
|
1
1
|
import { Glob } from 'bun';
|
|
2
2
|
import { spawnSync } from 'node:child_process';
|
|
3
|
-
import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
|
|
3
|
+
import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
|
|
4
4
|
import { basename, dirname, join, relative, sep } from 'node:path';
|
|
5
|
-
import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
|
|
6
|
-
import { LayoutKeys,
|
|
7
|
-
import {
|
|
8
|
-
|
|
9
|
-
declaresWorkspaces,
|
|
10
|
-
MCP_SERVER_HINT,
|
|
11
|
-
readWorkspaceGlobs,
|
|
12
|
-
} from '../init/index.ts';
|
|
13
|
-
import { resolvePackages } from '../config/index.ts';
|
|
5
|
+
import { BASE_DIRECTORY, ProjectLayout, RecordValue } from '../common/index.ts';
|
|
6
|
+
import { LayoutKeys, LayoutFolder } from '../common/layout-folder.ts';
|
|
7
|
+
import { MCP_SERVER_HINT, ProjectScaffold } from '../init/index.ts';
|
|
8
|
+
import { ProjectPackages } from '../config/index.ts';
|
|
14
9
|
import type { TResolvedConfig } from '../config/index.ts';
|
|
10
|
+
import { BaseRules, RuleConstants, RuleParser, RuleSlots } from '../rules/index.ts';
|
|
11
|
+
import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
|
|
12
|
+
import { AgentScopes, AgentSelection, AgentTable, LocalChoice } from '../agents/index.ts';
|
|
15
13
|
import {
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
} from '../rules/index.ts';
|
|
22
|
-
import {
|
|
23
|
-
isManifestCurrent,
|
|
24
|
-
ManifestConstants,
|
|
25
|
-
projectNameOf,
|
|
26
|
-
renderManifest,
|
|
27
|
-
} from '../manifest/index.ts';
|
|
28
|
-
import {
|
|
29
|
-
AgentScopes,
|
|
30
|
-
readAgentTable,
|
|
31
|
-
readLocalChoice,
|
|
32
|
-
resolveAgentsQuietly,
|
|
33
|
-
} from '../agents/index.ts';
|
|
34
|
-
import {
|
|
35
|
-
isTracked,
|
|
36
|
-
mergedAtlasBlock,
|
|
37
|
-
planLocalWorkspace,
|
|
38
|
-
planManifest,
|
|
39
|
-
planPrune,
|
|
40
|
-
planSync,
|
|
14
|
+
AgentFiles,
|
|
15
|
+
AtlasBlockPlan,
|
|
16
|
+
LocalPlan,
|
|
17
|
+
PrunePlan,
|
|
18
|
+
SyncPlanner,
|
|
41
19
|
SyncStatuses,
|
|
42
20
|
} from '../sync/index.ts';
|
|
43
|
-
import {
|
|
21
|
+
import { LocalConstants, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
|
|
44
22
|
import {
|
|
45
|
-
|
|
23
|
+
ReplySwitch,
|
|
46
24
|
OwnerConstants,
|
|
47
25
|
OwnerReplySwitch,
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
readViolationCounts,
|
|
51
|
-
violationLogBytes,
|
|
26
|
+
OwnerProfile,
|
|
27
|
+
ViolationLog,
|
|
52
28
|
ViolationConstants,
|
|
53
29
|
} from '../owner/index.ts';
|
|
54
|
-
import {
|
|
55
|
-
import {
|
|
30
|
+
import { SkillCatalog } from '@venizia/vulcan-atlas';
|
|
31
|
+
import { ScriptTrust, TrustStates } from '../hooks/index.ts';
|
|
56
32
|
import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
|
|
57
33
|
import type { IViolation, TDoctorCheck } from './common/index.ts';
|
|
58
|
-
import {
|
|
34
|
+
import { Makefile } from './makefile.ts';
|
|
59
35
|
|
|
60
36
|
export interface ICheckContext {
|
|
61
37
|
root: string;
|
|
@@ -83,102 +59,6 @@ const listDirectories = (opts: { directory: string }): string[] =>
|
|
|
83
59
|
.map((entry) => entry.name)
|
|
84
60
|
: [];
|
|
85
61
|
|
|
86
|
-
export const checkLayout = (opts: ICheckContext): IViolation[] =>
|
|
87
|
-
['AGENTS.md', '.agents/rules.md', opts.config.knowledge.bundle]
|
|
88
|
-
.filter((path) => !existsSync(join(opts.root, path)))
|
|
89
|
-
.map((path) =>
|
|
90
|
-
createViolation({
|
|
91
|
-
check: DoctorChecks.LAYOUT,
|
|
92
|
-
file: path,
|
|
93
|
-
message: `missing - run '${ProjectLayout.VULCAN_COMMAND} init'`,
|
|
94
|
-
}),
|
|
95
|
-
);
|
|
96
|
-
|
|
97
|
-
/**
|
|
98
|
-
* The base owns the `V-` namespace: a project defines its rules with bare IDs, and a `V-` ID in its
|
|
99
|
-
* rules points at a base rule - one the base does not carry, or has retired, dangles.
|
|
100
|
-
*/
|
|
101
|
-
export const checkRuleIds = (opts: ICheckContext): IViolation[] => {
|
|
102
|
-
const base = readBaseRules();
|
|
103
|
-
const retired = new Set(readRetiredRuleIds());
|
|
104
|
-
|
|
105
|
-
return parseBaseReferences({
|
|
106
|
-
markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
|
|
107
|
-
})
|
|
108
|
-
.filter((id) => base[id] === undefined)
|
|
109
|
-
.map((id) =>
|
|
110
|
-
createViolation({
|
|
111
|
-
check: DoctorChecks.RULE_IDS,
|
|
112
|
-
file: '.agents/rules.md',
|
|
113
|
-
message: retired.has(id)
|
|
114
|
-
? `${id} is retired in the base - drop the reference`
|
|
115
|
-
: `${id} is not a base rule - give the extension a bare ID`,
|
|
116
|
-
}),
|
|
117
|
-
);
|
|
118
|
-
};
|
|
119
|
-
|
|
120
|
-
export const checkRuleSlots = (opts: ICheckContext): IViolation[] => {
|
|
121
|
-
const slots = readSlots();
|
|
122
|
-
const violations: IViolation[] = [];
|
|
123
|
-
|
|
124
|
-
for (const [id, slot] of Object.entries(slots)) {
|
|
125
|
-
const choice = opts.config.rules[id];
|
|
126
|
-
const options = Object.keys(slot.options).join(' | ');
|
|
127
|
-
|
|
128
|
-
if (choice === undefined) {
|
|
129
|
-
violations.push(
|
|
130
|
-
createViolation({
|
|
131
|
-
check: DoctorChecks.RULE_SLOTS,
|
|
132
|
-
file: opts.configFile,
|
|
133
|
-
message: `${id} needs a choice: rules: { '${id}': ${options} }`,
|
|
134
|
-
}),
|
|
135
|
-
);
|
|
136
|
-
continue;
|
|
137
|
-
}
|
|
138
|
-
|
|
139
|
-
if (slot.options[choice] === undefined) {
|
|
140
|
-
violations.push(
|
|
141
|
-
createViolation({
|
|
142
|
-
check: DoctorChecks.RULE_SLOTS,
|
|
143
|
-
file: opts.configFile,
|
|
144
|
-
message: `${id}: '${choice}' is not an option (${options})`,
|
|
145
|
-
}),
|
|
146
|
-
);
|
|
147
|
-
}
|
|
148
|
-
}
|
|
149
|
-
|
|
150
|
-
for (const id of Object.keys(opts.config.rules).filter((ruleId) => slots[ruleId] === undefined)) {
|
|
151
|
-
const namespaced = `${RuleConstants.BASE_NAMESPACE}${id}`;
|
|
152
|
-
|
|
153
|
-
violations.push(
|
|
154
|
-
createViolation({
|
|
155
|
-
check: DoctorChecks.RULE_SLOTS,
|
|
156
|
-
file: opts.configFile,
|
|
157
|
-
message:
|
|
158
|
-
slots[namespaced] === undefined
|
|
159
|
-
? `${id} is not a slot - only ${Object.keys(slots).join(', ')} take a choice`
|
|
160
|
-
: `'${id}' is not a slot - the base rule is now '${namespaced}'`,
|
|
161
|
-
}),
|
|
162
|
-
);
|
|
163
|
-
}
|
|
164
|
-
|
|
165
|
-
return violations;
|
|
166
|
-
};
|
|
167
|
-
|
|
168
|
-
export const checkSkills = (opts: ICheckContext): IViolation[] => {
|
|
169
|
-
const shipped = new Set(listDirectories({ directory: join(BASE_DIRECTORY, 'skills') }));
|
|
170
|
-
|
|
171
|
-
return listDirectories({ directory: join(opts.root, '.agents', 'skills') })
|
|
172
|
-
.filter((name) => shipped.has(name))
|
|
173
|
-
.map((name) =>
|
|
174
|
-
createViolation({
|
|
175
|
-
check: DoctorChecks.SKILLS,
|
|
176
|
-
file: `.agents/skills/${name}`,
|
|
177
|
-
message: `'${name}' is a shipped skill - rename the project skill, for example to '${projectNameOf({ root: opts.root, config: opts.config })}-${name}'`,
|
|
178
|
-
}),
|
|
179
|
-
);
|
|
180
|
-
};
|
|
181
|
-
|
|
182
62
|
/**
|
|
183
63
|
* The project's Makefile and every file it includes, recursively, relative to the root. Includes
|
|
184
64
|
* under node_modules are shipped (vulcan.mk), never project targets.
|
|
@@ -196,7 +76,7 @@ const findProjectMakefiles = (opts: { root: string }): string[] => {
|
|
|
196
76
|
|
|
197
77
|
found.push(file);
|
|
198
78
|
|
|
199
|
-
for (const pattern of parseMakeIncludes({
|
|
79
|
+
for (const pattern of Makefile.parseMakeIncludes({
|
|
200
80
|
makefile: readText({ file: join(opts.root, file) }),
|
|
201
81
|
})) {
|
|
202
82
|
const matches = [...new Glob(pattern).scanSync({ cwd: opts.root, onlyFiles: true })].sort();
|
|
@@ -208,132 +88,6 @@ const findProjectMakefiles = (opts: { root: string }): string[] => {
|
|
|
208
88
|
return found;
|
|
209
89
|
};
|
|
210
90
|
|
|
211
|
-
export const checkMake = (opts: ICheckContext): IViolation[] => {
|
|
212
|
-
const makefile = readText({ file: join(opts.root, 'Makefile') });
|
|
213
|
-
const violations: IViolation[] = [];
|
|
214
|
-
|
|
215
|
-
if (!DoctorConstants.MAKE_INCLUDE_PATTERN.test(makefile)) {
|
|
216
|
-
violations.push(
|
|
217
|
-
createViolation({
|
|
218
|
-
check: DoctorChecks.MAKE,
|
|
219
|
-
file: 'Makefile',
|
|
220
|
-
message: `add: ${ProjectLayout.MAKE_INCLUDE_LINE}`,
|
|
221
|
-
}),
|
|
222
|
-
);
|
|
223
|
-
}
|
|
224
|
-
|
|
225
|
-
const shipped = new Set(
|
|
226
|
-
parseMakeTargets({ makefile: readText({ file: join(BASE_DIRECTORY, 'make', 'vulcan.mk') }) }),
|
|
227
|
-
);
|
|
228
|
-
|
|
229
|
-
for (const file of findProjectMakefiles({ root: opts.root })) {
|
|
230
|
-
const targets = parseMakeTargets({ makefile: readText({ file: join(opts.root, file) }) });
|
|
231
|
-
|
|
232
|
-
for (const target of targets.filter((name) => shipped.has(name))) {
|
|
233
|
-
violations.push(
|
|
234
|
-
createViolation({
|
|
235
|
-
check: DoctorChecks.MAKE,
|
|
236
|
-
file,
|
|
237
|
-
message: `'${target}' is a shipped target - give the project target another name`,
|
|
238
|
-
}),
|
|
239
|
-
);
|
|
240
|
-
}
|
|
241
|
-
}
|
|
242
|
-
|
|
243
|
-
return violations;
|
|
244
|
-
};
|
|
245
|
-
|
|
246
|
-
export const checkHooks = (opts: ICheckContext): IViolation[] =>
|
|
247
|
-
opts.config.hooks
|
|
248
|
-
.filter((hook) => hook.command.includes(DoctorConstants.SHIPPED_HOOKS_PATH))
|
|
249
|
-
.map((hook) =>
|
|
250
|
-
createViolation({
|
|
251
|
-
check: DoctorChecks.HOOKS,
|
|
252
|
-
file: opts.configFile,
|
|
253
|
-
message: `the ${hook.event} hook runs a shipped hook - sync registers those, never the project`,
|
|
254
|
-
}),
|
|
255
|
-
);
|
|
256
|
-
|
|
257
|
-
export const checkAdapters = (opts: ICheckContext): IViolation[] => {
|
|
258
|
-
const pending = planSync({
|
|
259
|
-
root: opts.root,
|
|
260
|
-
config: opts.config,
|
|
261
|
-
agents: resolveAgentsQuietly({ root: opts.root, configAgents: opts.config.agents }),
|
|
262
|
-
})
|
|
263
|
-
.filter((action) => action.status !== SyncStatuses.UNCHANGED)
|
|
264
|
-
.filter((action) => action.path !== join(opts.root, ManifestConstants.FILE));
|
|
265
|
-
const absent = pending.filter((action) => action.status === SyncStatuses.CREATED);
|
|
266
|
-
const differing = pending.filter((action) => action.status !== SyncStatuses.CREATED);
|
|
267
|
-
|
|
268
|
-
// A clean checkout has none of the gitignored adapters: say so once, with the fix, not once per file.
|
|
269
|
-
const violations =
|
|
270
|
-
absent.length === 0
|
|
271
|
-
? []
|
|
272
|
-
: [
|
|
273
|
-
createViolation({
|
|
274
|
-
check: DoctorChecks.ADAPTERS,
|
|
275
|
-
file: relative(opts.root, absent[0].path),
|
|
276
|
-
message: `not synced yet - run '${ProjectLayout.VULCAN_COMMAND} sync' (make agent-setup) first`,
|
|
277
|
-
}),
|
|
278
|
-
];
|
|
279
|
-
|
|
280
|
-
return [
|
|
281
|
-
...violations,
|
|
282
|
-
...differing.map((action) =>
|
|
283
|
-
createViolation({
|
|
284
|
-
check: DoctorChecks.ADAPTERS,
|
|
285
|
-
file: relative(opts.root, action.path),
|
|
286
|
-
message:
|
|
287
|
-
action.status === SyncStatuses.SKIPPED
|
|
288
|
-
? (action.note ?? 'skipped by sync')
|
|
289
|
-
: `stale (${action.status}) - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
|
|
290
|
-
}),
|
|
291
|
-
),
|
|
292
|
-
];
|
|
293
|
-
};
|
|
294
|
-
|
|
295
|
-
/** What `sync --prune` would remove: an old VULCAN or plugin-era hook command, a dead skill link. */
|
|
296
|
-
export const checkPrune = (opts: ICheckContext): IViolation[] =>
|
|
297
|
-
planPrune({ root: opts.root }).map((action) =>
|
|
298
|
-
createViolation({
|
|
299
|
-
check: DoctorChecks.PRUNE,
|
|
300
|
-
file: relative(opts.root, action.path),
|
|
301
|
-
message: `${action.note ?? 'stale'} - run '${ProjectLayout.VULCAN_COMMAND} sync --prune'`,
|
|
302
|
-
}),
|
|
303
|
-
);
|
|
304
|
-
|
|
305
|
-
/**
|
|
306
|
-
* C1: the committed manifest is what the config renders - atlas reads the file, never the config.
|
|
307
|
-
* A file written before the `$generated` note existed is current; a hand-edited one is not.
|
|
308
|
-
*/
|
|
309
|
-
export const checkManifest = (opts: ICheckContext): IViolation[] => {
|
|
310
|
-
const action = planManifest({ root: opts.root, config: opts.config });
|
|
311
|
-
|
|
312
|
-
if (
|
|
313
|
-
action.status === SyncStatuses.UNCHANGED ||
|
|
314
|
-
(action.status === SyncStatuses.REPLACED &&
|
|
315
|
-
isManifestCurrent({
|
|
316
|
-
committed: readFileSync(join(opts.root, ManifestConstants.FILE), 'utf8'),
|
|
317
|
-
rendered: renderManifest({ root: opts.root, config: opts.config }),
|
|
318
|
-
}))
|
|
319
|
-
) {
|
|
320
|
-
return [];
|
|
321
|
-
}
|
|
322
|
-
|
|
323
|
-
const fix = `run '${ProjectLayout.VULCAN_COMMAND} sync' and commit it`;
|
|
324
|
-
|
|
325
|
-
return [
|
|
326
|
-
createViolation({
|
|
327
|
-
check: DoctorChecks.MANIFEST,
|
|
328
|
-
file: ManifestConstants.FILE,
|
|
329
|
-
message:
|
|
330
|
-
action.status === SyncStatuses.CREATED
|
|
331
|
-
? `missing - ${fix}`
|
|
332
|
-
: `stale against the config, or edited by hand - the manifest is generated, never edit it: edit .configs/vulcan.config.* and ${fix}`,
|
|
333
|
-
}),
|
|
334
|
-
];
|
|
335
|
-
};
|
|
336
|
-
|
|
337
91
|
const hasStylePackage = (opts: { directory: string }): boolean => {
|
|
338
92
|
const file = join(opts.directory, 'package.json');
|
|
339
93
|
|
|
@@ -349,198 +103,6 @@ const hasStylePackage = (opts: { directory: string }): boolean => {
|
|
|
349
103
|
return ProjectLayout.STYLE_PACKAGE in { ...manifest.dependencies, ...manifest.devDependencies };
|
|
350
104
|
};
|
|
351
105
|
|
|
352
|
-
/**
|
|
353
|
-
* D9: the shared coding style - every lint config builds on it, and the package whose `.configs/`
|
|
354
|
-
* holds the config declares it, or the root does. A project with no lint config declares it at the
|
|
355
|
-
* root. Owners are `packages/*` and every configured package's `path`, such as `umbras/kit`.
|
|
356
|
-
*/
|
|
357
|
-
export const checkStyle = (opts: ICheckContext): IViolation[] => {
|
|
358
|
-
const violations: IViolation[] = [];
|
|
359
|
-
const owners = [
|
|
360
|
-
...new Set([
|
|
361
|
-
'.',
|
|
362
|
-
...listDirectories({ directory: join(opts.root, 'packages') }).map((name) =>
|
|
363
|
-
join('packages', name),
|
|
364
|
-
),
|
|
365
|
-
...resolvePackages({ config: opts.config }).map(
|
|
366
|
-
(entry) => relative(opts.root, join(opts.root, entry.path)) || '.',
|
|
367
|
-
),
|
|
368
|
-
]),
|
|
369
|
-
];
|
|
370
|
-
const isRootDeclared = hasStylePackage({ directory: opts.root });
|
|
371
|
-
let lintConfigs = 0;
|
|
372
|
-
|
|
373
|
-
for (const owner of owners) {
|
|
374
|
-
const configs = join(owner, '.configs');
|
|
375
|
-
const found = ['.', ...new Set(Object.values(DoctorConstants.LINT_CONFIG_FOLDERS))].flatMap(
|
|
376
|
-
(folder) => {
|
|
377
|
-
const directory = join(configs, folder);
|
|
378
|
-
|
|
379
|
-
return existsSync(join(opts.root, directory))
|
|
380
|
-
? readdirSync(join(opts.root, directory))
|
|
381
|
-
.filter((file) => DoctorConstants.LINT_CONFIG_FILE.test(file))
|
|
382
|
-
.map((file) => ({ file: join(directory, file), name: file, legacy: folder === '.' }))
|
|
383
|
-
: [];
|
|
384
|
-
},
|
|
385
|
-
);
|
|
386
|
-
const names = found.map((item) => item.file);
|
|
387
|
-
|
|
388
|
-
lintConfigs += names.length;
|
|
389
|
-
|
|
390
|
-
if (
|
|
391
|
-
names.length > 0 &&
|
|
392
|
-
!isRootDeclared &&
|
|
393
|
-
!hasStylePackage({ directory: join(opts.root, owner) })
|
|
394
|
-
) {
|
|
395
|
-
violations.push(
|
|
396
|
-
createViolation({
|
|
397
|
-
check: DoctorChecks.STYLE,
|
|
398
|
-
file: join(owner, 'package.json'),
|
|
399
|
-
message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency - here, or at the root`,
|
|
400
|
-
}),
|
|
401
|
-
);
|
|
402
|
-
}
|
|
403
|
-
|
|
404
|
-
for (const item of found) {
|
|
405
|
-
const { file } = item;
|
|
406
|
-
|
|
407
|
-
if (item.legacy) {
|
|
408
|
-
const tool = item.name.split('.')[0];
|
|
409
|
-
|
|
410
|
-
violations.push(
|
|
411
|
-
createViolation({
|
|
412
|
-
check: DoctorChecks.STYLE,
|
|
413
|
-
file,
|
|
414
|
-
message: `move it to .configs/${DoctorConstants.LINT_CONFIG_FOLDERS[tool]}/${item.name}`,
|
|
415
|
-
}),
|
|
416
|
-
);
|
|
417
|
-
}
|
|
418
|
-
|
|
419
|
-
if (!readText({ file: join(opts.root, file) }).includes(ProjectLayout.STYLE_PACKAGE)) {
|
|
420
|
-
violations.push(
|
|
421
|
-
createViolation({
|
|
422
|
-
check: DoctorChecks.STYLE,
|
|
423
|
-
file,
|
|
424
|
-
message: `build on the shared style: import from ${ProjectLayout.STYLE_PACKAGE}`,
|
|
425
|
-
}),
|
|
426
|
-
);
|
|
427
|
-
}
|
|
428
|
-
}
|
|
429
|
-
}
|
|
430
|
-
|
|
431
|
-
if (lintConfigs === 0 && !isRootDeclared) {
|
|
432
|
-
violations.push(
|
|
433
|
-
createViolation({
|
|
434
|
-
check: DoctorChecks.STYLE,
|
|
435
|
-
file: 'package.json',
|
|
436
|
-
message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency`,
|
|
437
|
-
}),
|
|
438
|
-
);
|
|
439
|
-
}
|
|
440
|
-
|
|
441
|
-
return violations;
|
|
442
|
-
};
|
|
443
|
-
|
|
444
|
-
/**
|
|
445
|
-
* The scaffold is filled in: `init` writes a config and a knowledge index to be edited, and a
|
|
446
|
-
* project that never did would otherwise pass. A workspaces project declares its packages, and the
|
|
447
|
-
* knowledge index drops the scaffold marker once it describes the project.
|
|
448
|
-
*/
|
|
449
|
-
export const checkScaffold = (opts: ICheckContext): IViolation[] => {
|
|
450
|
-
const violations: IViolation[] = [];
|
|
451
|
-
|
|
452
|
-
if (
|
|
453
|
-
declaresWorkspaces({ root: opts.root }) &&
|
|
454
|
-
resolvePackages({ config: opts.config }).length === 0
|
|
455
|
-
) {
|
|
456
|
-
violations.push(
|
|
457
|
-
createViolation({
|
|
458
|
-
check: DoctorChecks.SCAFFOLD,
|
|
459
|
-
file: opts.configFile,
|
|
460
|
-
message:
|
|
461
|
-
'package.json declares workspaces but the config lists no packages - add packages: [{ dir, name, path }] in release order',
|
|
462
|
-
}),
|
|
463
|
-
);
|
|
464
|
-
}
|
|
465
|
-
|
|
466
|
-
const index = join(opts.config.knowledge.bundle, 'index.md');
|
|
467
|
-
|
|
468
|
-
if (readText({ file: join(opts.root, index) }).includes(ProjectLayout.SCAFFOLD_MARKER)) {
|
|
469
|
-
violations.push(
|
|
470
|
-
createViolation({
|
|
471
|
-
check: DoctorChecks.SCAFFOLD,
|
|
472
|
-
file: index,
|
|
473
|
-
message: `still the scaffold - describe the project, then delete the ${ProjectLayout.SCAFFOLD_MARKER} line`,
|
|
474
|
-
}),
|
|
475
|
-
);
|
|
476
|
-
}
|
|
477
|
-
|
|
478
|
-
return violations;
|
|
479
|
-
};
|
|
480
|
-
|
|
481
|
-
/** Apps sit in the folders the user named, and every named folder is a workspace. */
|
|
482
|
-
export const checkApps = (opts: ICheckContext): IViolation[] => {
|
|
483
|
-
const layout = opts.config.layout;
|
|
484
|
-
|
|
485
|
-
if (layout === undefined) {
|
|
486
|
-
return [];
|
|
487
|
-
}
|
|
488
|
-
|
|
489
|
-
const globs = readWorkspaceGlobs({ root: opts.root });
|
|
490
|
-
const folders = LayoutKeys.ALL.flatMap((key) =>
|
|
491
|
-
layoutFoldersOf({ value: layout[key] }).map((folder) => ({ side: key, folder })),
|
|
492
|
-
);
|
|
493
|
-
// A folder under `other` is deliberately not managed: it need not be a workspace, only a package in it is allowed.
|
|
494
|
-
const violations = folders
|
|
495
|
-
.filter(({ side, folder }) => side !== LayoutKeys.OTHER && !coversFolder({ globs, folder }))
|
|
496
|
-
.map(({ side, folder }) =>
|
|
497
|
-
createViolation({
|
|
498
|
-
check: DoctorChecks.APPS,
|
|
499
|
-
file: 'package.json',
|
|
500
|
-
message: `layout.${side} '${folder}' is not in package.json workspaces - add '${folder}/*'`,
|
|
501
|
-
}),
|
|
502
|
-
);
|
|
503
|
-
const names = folders.map(({ folder }) => folder);
|
|
504
|
-
// A package may be an `other` folder itself (a docs site at `docs`); a side folder only holds packages.
|
|
505
|
-
const otherNames = folders
|
|
506
|
-
.filter(({ side }) => side === LayoutKeys.OTHER)
|
|
507
|
-
.map(({ folder }) => folder);
|
|
508
|
-
|
|
509
|
-
for (const entry of resolvePackages({ config: opts.config }).filter((item) => !item.retired)) {
|
|
510
|
-
if (entry.kind === 'lib') {
|
|
511
|
-
const parent = dirname(entry.path);
|
|
512
|
-
|
|
513
|
-
// A library lives where the project keeps libraries; it only has to be a workspace.
|
|
514
|
-
if (!coversFolder({ globs, folder: parent })) {
|
|
515
|
-
violations.push(
|
|
516
|
-
createViolation({
|
|
517
|
-
check: DoctorChecks.APPS,
|
|
518
|
-
file: opts.configFile,
|
|
519
|
-
message: `package ${entry.dir} lives at ${entry.path}, which no workspace glob covers - add '${parent}/*' to workspaces`,
|
|
520
|
-
}),
|
|
521
|
-
);
|
|
522
|
-
}
|
|
523
|
-
|
|
524
|
-
continue;
|
|
525
|
-
}
|
|
526
|
-
|
|
527
|
-
if (
|
|
528
|
-
!names.some((folder) => entry.path.startsWith(`${folder}/`)) &&
|
|
529
|
-
!otherNames.includes(entry.path)
|
|
530
|
-
) {
|
|
531
|
-
violations.push(
|
|
532
|
-
createViolation({
|
|
533
|
-
check: DoctorChecks.APPS,
|
|
534
|
-
file: opts.configFile,
|
|
535
|
-
message: `package ${entry.dir} lives at ${entry.path}, outside every layout folder (${names.join(', ')})`,
|
|
536
|
-
}),
|
|
537
|
-
);
|
|
538
|
-
}
|
|
539
|
-
}
|
|
540
|
-
|
|
541
|
-
return violations;
|
|
542
|
-
};
|
|
543
|
-
|
|
544
106
|
const readScriptNames = (opts: { file: string }): string[] | undefined => {
|
|
545
107
|
if (!existsSync(opts.file)) {
|
|
546
108
|
return undefined;
|
|
@@ -561,75 +123,13 @@ const readScriptNames = (opts: { file: string }): string[] | undefined => {
|
|
|
561
123
|
}
|
|
562
124
|
};
|
|
563
125
|
|
|
564
|
-
/**
|
|
565
|
-
* Info only, never a failure: an app that lacks a standard script or carries a legacy one gets one
|
|
566
|
-
* line naming them. Apps are the live packages inside the backend and frontend folders.
|
|
567
|
-
*/
|
|
568
|
-
export const checkAppScripts = (opts: ICheckContext): IViolation[] => {
|
|
569
|
-
const layout = opts.config.layout;
|
|
570
|
-
|
|
571
|
-
if (layout === undefined) {
|
|
572
|
-
return [];
|
|
573
|
-
}
|
|
574
|
-
|
|
575
|
-
const appFolders = [
|
|
576
|
-
...layoutFoldersOf({ value: layout.backend }),
|
|
577
|
-
...layoutFoldersOf({ value: layout.frontend }),
|
|
578
|
-
];
|
|
579
|
-
const notes: IViolation[] = [];
|
|
580
|
-
|
|
581
|
-
for (const entry of resolvePackages({ config: opts.config }).filter((item) => !item.retired)) {
|
|
582
|
-
if (!appFolders.some((folder) => entry.path.startsWith(`${folder}/`))) {
|
|
583
|
-
continue;
|
|
584
|
-
}
|
|
585
|
-
|
|
586
|
-
const file = `${entry.path}/package.json`;
|
|
587
|
-
const names = readScriptNames({ file: join(opts.root, file) });
|
|
588
|
-
|
|
589
|
-
if (names === undefined) {
|
|
590
|
-
continue;
|
|
591
|
-
}
|
|
592
|
-
|
|
593
|
-
const missing = AppScripts.STANDARD.filter((name) => !names.includes(name));
|
|
594
|
-
const legacy = AppScripts.LEGACY.filter((name) => names.includes(name));
|
|
595
|
-
const parts = [
|
|
596
|
-
...(missing.length === 0 ? [] : [`missing ${missing.join(', ')}`]),
|
|
597
|
-
...(legacy.length === 0 ? [] : [`legacy ${legacy.join(', ')} (use the standard names)`]),
|
|
598
|
-
];
|
|
599
|
-
|
|
600
|
-
if (parts.length > 0) {
|
|
601
|
-
notes.push(
|
|
602
|
-
createViolation({
|
|
603
|
-
check: DoctorChecks.SCRIPTS,
|
|
604
|
-
file,
|
|
605
|
-
message: `app ${entry.dir}: ${parts.join('; ')}`,
|
|
606
|
-
}),
|
|
607
|
-
);
|
|
608
|
-
}
|
|
609
|
-
}
|
|
610
|
-
|
|
611
|
-
return notes;
|
|
612
|
-
};
|
|
613
|
-
|
|
614
|
-
/** The developer's stored agents must parse and name known agents; a broken file would otherwise hide as a default. */
|
|
615
|
-
export const checkAgents = (opts: ICheckContext): IViolation[] => {
|
|
616
|
-
const stored = readLocalChoice({ root: opts.root });
|
|
617
|
-
|
|
618
|
-
return stored.ok
|
|
619
|
-
? []
|
|
620
|
-
: [
|
|
621
|
-
createViolation({
|
|
622
|
-
check: DoctorChecks.AGENTS,
|
|
623
|
-
file: '.agents/vulcan.local.json',
|
|
624
|
-
message: stored.error,
|
|
625
|
-
}),
|
|
626
|
-
];
|
|
627
|
-
};
|
|
628
|
-
|
|
629
126
|
/** Info only: the Atlas block of AGENTS.md is missing or no longer matches the config. */
|
|
630
127
|
const CANONICAL_ATLAS_ARGS = ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'];
|
|
128
|
+
|
|
631
129
|
const MCP_FILE = '.mcp.json';
|
|
130
|
+
|
|
632
131
|
const CLAUDE_SETTINGS_FILE = '.claude/settings.json';
|
|
132
|
+
|
|
633
133
|
const ATLAS_SERVER = 'atlas';
|
|
634
134
|
|
|
635
135
|
const readJsonObject = (opts: { file: string }): Record<string, unknown> | undefined => {
|
|
@@ -644,9 +144,6 @@ const readJsonObject = (opts: { file: string }): Record<string, unknown> | undef
|
|
|
644
144
|
}
|
|
645
145
|
};
|
|
646
146
|
|
|
647
|
-
const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
|
|
648
|
-
typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
|
|
649
|
-
|
|
650
147
|
/** Whether git lists the file as untracked and not ignored: what a clean-tree check, such as a release, refuses on. */
|
|
651
148
|
const isUntrackedAndVisible = (opts: { root: string; path: string }): boolean => {
|
|
652
149
|
const listed = spawnSync('git', ['status', '--porcelain', '--', opts.path], {
|
|
@@ -661,601 +158,1175 @@ const isUntrackedAndVisible = (opts: { root: string; path: string }): boolean =>
|
|
|
661
158
|
const mcpWarning = (opts: { file: string; message: string }): IViolation =>
|
|
662
159
|
createViolation({ check: DoctorChecks.MCP, file: opts.file, message: opts.message });
|
|
663
160
|
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
*/
|
|
671
|
-
|
|
672
|
-
const
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
(
|
|
161
|
+
const DOCKERFILE = '.configs/builders/Dockerfile';
|
|
162
|
+
|
|
163
|
+
const SECRET_LINES = ['**/.env', '**/.env.*', '!**/.env.example'];
|
|
164
|
+
|
|
165
|
+
const ADD_SECRET_LINES = `add ${SECRET_LINES[0]}, ${SECRET_LINES[1]} and ${SECRET_LINES[2]} (in that order) to the root .dockerignore`;
|
|
166
|
+
|
|
167
|
+
/** Whether a `.dockerignore` pattern, as Docker reads it, names the file `opts.file` at any depth. */
|
|
168
|
+
const patternNames = (opts: { pattern: string; file: string }): boolean => {
|
|
169
|
+
const bare = opts.pattern.replace(/^\*\*\//, '').replace(/^\//, '');
|
|
170
|
+
|
|
171
|
+
return (
|
|
172
|
+
bare === opts.file ||
|
|
173
|
+
(bare.endsWith('*') && opts.file.startsWith(bare.slice(0, -1)) && bare.startsWith('.env'))
|
|
677
174
|
);
|
|
175
|
+
};
|
|
678
176
|
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
}),
|
|
689
|
-
);
|
|
690
|
-
} else if (isUntrackedAndVisible({ root: opts.root, path: MCP_FILE })) {
|
|
691
|
-
warnings.push(
|
|
692
|
-
mcpWarning({
|
|
693
|
-
file: MCP_FILE,
|
|
694
|
-
message:
|
|
695
|
-
'untracked and not ignored, so a clean-tree check (a release) refuses to run. Add `/.mcp.json` to .gitignore, or run `vulcan sync` at the top level of the repository, which lists it in .git/info/exclude.',
|
|
696
|
-
}),
|
|
697
|
-
);
|
|
177
|
+
/** Whether the last pattern that names `opts.file` excludes it: a later `!` line brings it back. */
|
|
178
|
+
const excludes = (opts: { lines: string[]; file: string }): boolean => {
|
|
179
|
+
let excluded = false;
|
|
180
|
+
|
|
181
|
+
for (const line of opts.lines) {
|
|
182
|
+
const negated = line.startsWith('!');
|
|
183
|
+
|
|
184
|
+
if (patternNames({ pattern: negated ? line.slice(1) : line, file: opts.file })) {
|
|
185
|
+
excluded = !negated;
|
|
698
186
|
}
|
|
187
|
+
}
|
|
699
188
|
|
|
700
|
-
|
|
189
|
+
return excluded;
|
|
190
|
+
};
|
|
701
191
|
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
192
|
+
const FMT_SECTION_ADVICE =
|
|
193
|
+
'add a [fmt] section (printWidth = 100, singleQuote = true, arrowParens = "always", flavor = "oxfmt"): without it bun fmt formats with Bun\'s defaults, not the shared style';
|
|
194
|
+
|
|
195
|
+
const FMT_FLAVOR_ADVICE =
|
|
196
|
+
'without it bun fmt uses its default style when oxfmt is not a dependency, and the output changes';
|
|
197
|
+
|
|
198
|
+
const OXFMT_LOADED_ADVICE =
|
|
199
|
+
'bun fmt loads it and it overrides the [fmt] section of bunfig.toml - delete it, or move its settings to [fmt]';
|
|
200
|
+
|
|
201
|
+
/** The folders that can hold a package.json and an oxfmt config: the root, `packages/*` and every configured package. */
|
|
202
|
+
const formatOwners = (opts: ICheckContext): string[] => [
|
|
203
|
+
...new Set([
|
|
204
|
+
'.',
|
|
205
|
+
...listDirectories({ directory: join(opts.root, 'packages') }).map((name) =>
|
|
206
|
+
join('packages', name),
|
|
207
|
+
),
|
|
208
|
+
...ProjectPackages.resolve({ config: opts.config })
|
|
209
|
+
.filter((entry) => !entry.retired)
|
|
210
|
+
.map((entry) => relative(opts.root, join(opts.root, entry.path)) || '.'),
|
|
211
|
+
]),
|
|
212
|
+
];
|
|
213
|
+
|
|
214
|
+
/** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
|
|
215
|
+
/** The states of a listed script worth a warning: a typo or a script nobody committed. A modified one is normal work, so it is only a note. */
|
|
216
|
+
const STALE_TRUST_STATES = new Set<string>([
|
|
217
|
+
TrustStates.MISSING,
|
|
218
|
+
TrustStates.UNTRACKED,
|
|
219
|
+
TrustStates.UNCOMMITTED,
|
|
220
|
+
TrustStates.SYMLINK,
|
|
221
|
+
TrustStates.UNKNOWN,
|
|
222
|
+
]);
|
|
223
|
+
|
|
224
|
+
/** The path of a `guard.writes.trustedScripts` entry, and the subcommands when it is the object form. */
|
|
225
|
+
const trustedScriptOf = (opts: {
|
|
226
|
+
entry: TResolvedConfig['guard']['writes']['trustedScripts'][number];
|
|
227
|
+
}): { script: string; readOnly: string[] | undefined } =>
|
|
228
|
+
typeof opts.entry === 'string'
|
|
229
|
+
? { script: opts.entry, readOnly: undefined }
|
|
230
|
+
: { script: opts.entry.script, readOnly: opts.entry.readOnly };
|
|
231
|
+
|
|
232
|
+
export class ProjectContract {
|
|
233
|
+
static checkLayout(opts: ICheckContext): IViolation[] {
|
|
234
|
+
return ['AGENTS.md', '.agents/rules.md', opts.config.knowledge.bundle]
|
|
235
|
+
.filter((path) => !existsSync(join(opts.root, path)))
|
|
236
|
+
.map((path) =>
|
|
237
|
+
createViolation({
|
|
238
|
+
check: DoctorChecks.LAYOUT,
|
|
239
|
+
file: path,
|
|
240
|
+
message: `missing - run '${ProjectLayout.VULCAN_COMMAND} init'`,
|
|
707
241
|
}),
|
|
708
242
|
);
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* The base owns the `V-` namespace: a project defines its rules with bare IDs, and a `V-` ID in its
|
|
247
|
+
* rules points at a base rule - one the base does not carry, or has retired, dangles.
|
|
248
|
+
*/
|
|
249
|
+
static checkRuleIds(opts: ICheckContext): IViolation[] {
|
|
250
|
+
const base = BaseRules.read();
|
|
251
|
+
const retired = new Set(BaseRules.readRetiredIds());
|
|
252
|
+
|
|
253
|
+
return RuleParser.parseBaseReferences({
|
|
254
|
+
markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
|
|
255
|
+
})
|
|
256
|
+
.filter((id) => base[id] === undefined)
|
|
257
|
+
.map((id) =>
|
|
258
|
+
createViolation({
|
|
259
|
+
check: DoctorChecks.RULE_IDS,
|
|
260
|
+
file: '.agents/rules.md',
|
|
261
|
+
message: retired.has(id)
|
|
262
|
+
? `${id} is retired in the base - drop the reference`
|
|
263
|
+
: `${id} is not a base rule - give the extension a bare ID`,
|
|
264
|
+
}),
|
|
265
|
+
);
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
static checkRuleSlots(opts: ICheckContext): IViolation[] {
|
|
269
|
+
const slots = RuleSlots.read();
|
|
270
|
+
const violations: IViolation[] = [];
|
|
271
|
+
|
|
272
|
+
for (const [id, slot] of Object.entries(slots)) {
|
|
273
|
+
const choice = opts.config.rules[id];
|
|
274
|
+
const options = Object.keys(slot.options).join(' | ');
|
|
275
|
+
|
|
276
|
+
if (choice === undefined) {
|
|
277
|
+
violations.push(
|
|
278
|
+
createViolation({
|
|
279
|
+
check: DoctorChecks.RULE_SLOTS,
|
|
280
|
+
file: opts.configFile,
|
|
281
|
+
message: `${id} needs a choice: rules: { '${id}': ${options} }`,
|
|
726
282
|
}),
|
|
727
283
|
);
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
.replace('{"command":', '{ "command": ')
|
|
731
|
-
.replace(',"args":[', ', "args": [')
|
|
732
|
-
.replaceAll('","', '", "')
|
|
733
|
-
.replace(/\]\}$/, '] }');
|
|
284
|
+
continue;
|
|
285
|
+
}
|
|
734
286
|
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
287
|
+
if (slot.options[choice] === undefined) {
|
|
288
|
+
violations.push(
|
|
289
|
+
createViolation({
|
|
290
|
+
check: DoctorChecks.RULE_SLOTS,
|
|
291
|
+
file: opts.configFile,
|
|
292
|
+
message: `${id}: '${choice}' is not an option (${options})`,
|
|
739
293
|
}),
|
|
740
294
|
);
|
|
741
295
|
}
|
|
742
296
|
}
|
|
297
|
+
|
|
298
|
+
for (const id of Object.keys(opts.config.rules).filter(
|
|
299
|
+
(ruleId) => slots[ruleId] === undefined,
|
|
300
|
+
)) {
|
|
301
|
+
const namespaced = `${RuleConstants.BASE_NAMESPACE}${id}`;
|
|
302
|
+
|
|
303
|
+
violations.push(
|
|
304
|
+
createViolation({
|
|
305
|
+
check: DoctorChecks.RULE_SLOTS,
|
|
306
|
+
file: opts.configFile,
|
|
307
|
+
message:
|
|
308
|
+
slots[namespaced] === undefined
|
|
309
|
+
? `${id} is not a slot - only ${Object.keys(slots).join(', ')} take a choice`
|
|
310
|
+
: `'${id}' is not a slot - the base rule is now '${namespaced}'`,
|
|
311
|
+
}),
|
|
312
|
+
);
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
return violations;
|
|
743
316
|
}
|
|
744
317
|
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
? readJsonObject({ file: settings })?.['enabledMcpjsonServers']
|
|
748
|
-
: undefined;
|
|
318
|
+
static checkSkills(opts: ICheckContext): IViolation[] {
|
|
319
|
+
const shipped = new Set(listDirectories({ directory: join(BASE_DIRECTORY, 'skills') }));
|
|
749
320
|
|
|
750
|
-
|
|
751
|
-
|
|
321
|
+
return listDirectories({ directory: join(opts.root, '.agents', 'skills') })
|
|
322
|
+
.filter((name) => shipped.has(name))
|
|
323
|
+
.map((name) =>
|
|
324
|
+
createViolation({
|
|
325
|
+
check: DoctorChecks.SKILLS,
|
|
326
|
+
file: `.agents/skills/${name}`,
|
|
327
|
+
message: `'${name}' is a shipped skill - rename the project skill, for example to '${ProjectManifest.projectNameOf({ root: opts.root, config: opts.config })}-${name}'`,
|
|
328
|
+
}),
|
|
329
|
+
);
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
static checkMake(opts: ICheckContext): IViolation[] {
|
|
333
|
+
const makefile = readText({ file: join(opts.root, 'Makefile') });
|
|
334
|
+
const violations: IViolation[] = [];
|
|
335
|
+
|
|
336
|
+
if (!DoctorConstants.MAKE_INCLUDE_PATTERN.test(makefile)) {
|
|
337
|
+
violations.push(
|
|
338
|
+
createViolation({
|
|
339
|
+
check: DoctorChecks.MAKE,
|
|
340
|
+
file: 'Makefile',
|
|
341
|
+
message: `add: ${ProjectLayout.MAKE_INCLUDE_LINE}`,
|
|
342
|
+
}),
|
|
343
|
+
);
|
|
344
|
+
}
|
|
752
345
|
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
file:
|
|
756
|
-
message: `enabledMcpjsonServers does not include atlas (has: ${has}): Claude asks before using the server - run vulcan sync`,
|
|
346
|
+
const shipped = new Set(
|
|
347
|
+
Makefile.parseMakeTargets({
|
|
348
|
+
makefile: readText({ file: join(BASE_DIRECTORY, 'make', 'vulcan.mk') }),
|
|
757
349
|
}),
|
|
758
350
|
);
|
|
351
|
+
|
|
352
|
+
for (const file of findProjectMakefiles({ root: opts.root })) {
|
|
353
|
+
const targets = Makefile.parseMakeTargets({
|
|
354
|
+
makefile: readText({ file: join(opts.root, file) }),
|
|
355
|
+
});
|
|
356
|
+
|
|
357
|
+
for (const target of targets.filter((name) => shipped.has(name))) {
|
|
358
|
+
violations.push(
|
|
359
|
+
createViolation({
|
|
360
|
+
check: DoctorChecks.MAKE,
|
|
361
|
+
file,
|
|
362
|
+
message: `'${target}' is a shipped target - give the project target another name`,
|
|
363
|
+
}),
|
|
364
|
+
);
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
return violations;
|
|
759
369
|
}
|
|
760
370
|
|
|
761
|
-
|
|
762
|
-
|
|
371
|
+
static checkHooks(opts: ICheckContext): IViolation[] {
|
|
372
|
+
return opts.config.hooks
|
|
373
|
+
.filter((hook) => hook.command.includes(DoctorConstants.SHIPPED_HOOKS_PATH))
|
|
374
|
+
.map((hook) =>
|
|
375
|
+
createViolation({
|
|
376
|
+
check: DoctorChecks.HOOKS,
|
|
377
|
+
file: opts.configFile,
|
|
378
|
+
message: `the ${hook.event} hook runs a shipped hook - sync registers those, never the project`,
|
|
379
|
+
}),
|
|
380
|
+
);
|
|
381
|
+
}
|
|
763
382
|
|
|
764
|
-
|
|
383
|
+
static checkAdapters(opts: ICheckContext): IViolation[] {
|
|
384
|
+
const pending = SyncPlanner.plan({
|
|
385
|
+
root: opts.root,
|
|
386
|
+
config: opts.config,
|
|
387
|
+
agents: AgentSelection.resolveQuietly({ root: opts.root, configAgents: opts.config.agents }),
|
|
388
|
+
})
|
|
389
|
+
.filter((action) => action.status !== SyncStatuses.UNCHANGED)
|
|
390
|
+
.filter((action) => action.path !== join(opts.root, ManifestConstants.FILE));
|
|
391
|
+
const absent = pending.filter((action) => action.status === SyncStatuses.CREATED);
|
|
392
|
+
const differing = pending.filter((action) => action.status !== SyncStatuses.CREATED);
|
|
393
|
+
|
|
394
|
+
// A clean checkout has none of the gitignored adapters: say so once, with the fix, not once per file.
|
|
395
|
+
const violations =
|
|
396
|
+
absent.length === 0
|
|
397
|
+
? []
|
|
398
|
+
: [
|
|
399
|
+
createViolation({
|
|
400
|
+
check: DoctorChecks.ADAPTERS,
|
|
401
|
+
file: relative(opts.root, absent[0].path),
|
|
402
|
+
message: `not synced yet - run '${ProjectLayout.VULCAN_COMMAND} sync' (make vulcan-sync) first`,
|
|
403
|
+
}),
|
|
404
|
+
];
|
|
405
|
+
|
|
406
|
+
return [
|
|
407
|
+
...violations,
|
|
408
|
+
...differing.map((action) =>
|
|
409
|
+
createViolation({
|
|
410
|
+
check: DoctorChecks.ADAPTERS,
|
|
411
|
+
file: relative(opts.root, action.path),
|
|
412
|
+
message:
|
|
413
|
+
action.status === SyncStatuses.SKIPPED
|
|
414
|
+
? (action.note ?? 'skipped by sync')
|
|
415
|
+
: `stale (${action.status}) - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
|
|
416
|
+
}),
|
|
417
|
+
),
|
|
418
|
+
];
|
|
419
|
+
}
|
|
765
420
|
|
|
766
|
-
|
|
767
|
-
|
|
421
|
+
/** What `sync --prune` would remove: an old VULCAN or plugin-era hook command, a dead skill link. */
|
|
422
|
+
static checkPrune(opts: ICheckContext): IViolation[] {
|
|
423
|
+
return PrunePlan.plan({ root: opts.root }).map((action) =>
|
|
424
|
+
createViolation({
|
|
425
|
+
check: DoctorChecks.PRUNE,
|
|
426
|
+
file: relative(opts.root, action.path),
|
|
427
|
+
message: `${action.note ?? 'stale'} - run '${ProjectLayout.VULCAN_COMMAND} sync --prune'`,
|
|
428
|
+
}),
|
|
429
|
+
);
|
|
430
|
+
}
|
|
768
431
|
|
|
769
|
-
/**
|
|
770
|
-
|
|
771
|
-
|
|
432
|
+
/**
|
|
433
|
+
* C1: the committed manifest is what the config renders - atlas reads the file, never the config.
|
|
434
|
+
* A file written before the `$generated` note existed is current; a hand-edited one is not.
|
|
435
|
+
*/
|
|
436
|
+
static checkManifest(opts: ICheckContext): IViolation[] {
|
|
437
|
+
const action = SyncPlanner.planManifest({ root: opts.root, config: opts.config });
|
|
772
438
|
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
439
|
+
if (
|
|
440
|
+
action.status === SyncStatuses.UNCHANGED ||
|
|
441
|
+
(action.status === SyncStatuses.REPLACED &&
|
|
442
|
+
ProjectManifest.isCurrent({
|
|
443
|
+
committed: readFileSync(join(opts.root, ManifestConstants.FILE), 'utf8'),
|
|
444
|
+
rendered: ProjectManifest.render({ root: opts.root, config: opts.config }),
|
|
445
|
+
}))
|
|
446
|
+
) {
|
|
447
|
+
return [];
|
|
448
|
+
}
|
|
778
449
|
|
|
779
|
-
|
|
780
|
-
const excludes = (opts: { lines: string[]; file: string }): boolean => {
|
|
781
|
-
let excluded = false;
|
|
450
|
+
const fix = `run '${ProjectLayout.VULCAN_COMMAND} sync' and commit it`;
|
|
782
451
|
|
|
783
|
-
|
|
784
|
-
|
|
452
|
+
return [
|
|
453
|
+
createViolation({
|
|
454
|
+
check: DoctorChecks.MANIFEST,
|
|
455
|
+
file: ManifestConstants.FILE,
|
|
456
|
+
message:
|
|
457
|
+
action.status === SyncStatuses.CREATED
|
|
458
|
+
? `missing - ${fix}`
|
|
459
|
+
: `stale against the config, or edited by hand - the manifest is generated, never edit it: edit .configs/vulcan.config.* and ${fix}`,
|
|
460
|
+
}),
|
|
461
|
+
];
|
|
462
|
+
}
|
|
785
463
|
|
|
786
|
-
|
|
787
|
-
|
|
464
|
+
/**
|
|
465
|
+
* D9: the shared coding style - every lint config builds on it, and the package whose `.configs/`
|
|
466
|
+
* holds the config declares it, or the root does. A project with no lint config declares it at the
|
|
467
|
+
* root. Owners are `packages/*` and every configured package's `path`, such as `umbras/kit`.
|
|
468
|
+
*/
|
|
469
|
+
static checkStyle(opts: ICheckContext): IViolation[] {
|
|
470
|
+
const violations: IViolation[] = [];
|
|
471
|
+
const owners = [
|
|
472
|
+
...new Set([
|
|
473
|
+
'.',
|
|
474
|
+
...listDirectories({ directory: join(opts.root, 'packages') }).map((name) =>
|
|
475
|
+
join('packages', name),
|
|
476
|
+
),
|
|
477
|
+
...ProjectPackages.resolve({ config: opts.config }).map(
|
|
478
|
+
(entry) => relative(opts.root, join(opts.root, entry.path)) || '.',
|
|
479
|
+
),
|
|
480
|
+
]),
|
|
481
|
+
];
|
|
482
|
+
const isRootDeclared = hasStylePackage({ directory: opts.root });
|
|
483
|
+
let lintConfigs = 0;
|
|
484
|
+
|
|
485
|
+
for (const owner of owners) {
|
|
486
|
+
const configs = join(owner, '.configs');
|
|
487
|
+
const found = ['.', ...new Set(Object.values(DoctorConstants.LINT_CONFIG_FOLDERS))].flatMap(
|
|
488
|
+
(folder) => {
|
|
489
|
+
const directory = join(configs, folder);
|
|
490
|
+
|
|
491
|
+
return existsSync(join(opts.root, directory))
|
|
492
|
+
? readdirSync(join(opts.root, directory))
|
|
493
|
+
.filter((file) => DoctorConstants.LINT_CONFIG_FILE.test(file))
|
|
494
|
+
.map((file) => ({
|
|
495
|
+
file: join(directory, file),
|
|
496
|
+
name: file,
|
|
497
|
+
legacy: folder === '.',
|
|
498
|
+
}))
|
|
499
|
+
: [];
|
|
500
|
+
},
|
|
501
|
+
);
|
|
502
|
+
const names = found.map((item) => item.file);
|
|
503
|
+
|
|
504
|
+
lintConfigs += names.length;
|
|
505
|
+
|
|
506
|
+
if (
|
|
507
|
+
names.length > 0 &&
|
|
508
|
+
!isRootDeclared &&
|
|
509
|
+
!hasStylePackage({ directory: join(opts.root, owner) })
|
|
510
|
+
) {
|
|
511
|
+
violations.push(
|
|
512
|
+
createViolation({
|
|
513
|
+
check: DoctorChecks.STYLE,
|
|
514
|
+
file: join(owner, 'package.json'),
|
|
515
|
+
message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency - here, or at the root`,
|
|
516
|
+
}),
|
|
517
|
+
);
|
|
518
|
+
}
|
|
519
|
+
|
|
520
|
+
for (const item of found) {
|
|
521
|
+
const { file } = item;
|
|
522
|
+
|
|
523
|
+
if (item.legacy) {
|
|
524
|
+
const tool = item.name.split('.')[0];
|
|
525
|
+
|
|
526
|
+
violations.push(
|
|
527
|
+
createViolation({
|
|
528
|
+
check: DoctorChecks.STYLE,
|
|
529
|
+
file,
|
|
530
|
+
message: `move it to .configs/${DoctorConstants.LINT_CONFIG_FOLDERS[tool]}/${item.name}`,
|
|
531
|
+
}),
|
|
532
|
+
);
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
if (!readText({ file: join(opts.root, file) }).includes(ProjectLayout.STYLE_PACKAGE)) {
|
|
536
|
+
violations.push(
|
|
537
|
+
createViolation({
|
|
538
|
+
check: DoctorChecks.STYLE,
|
|
539
|
+
file,
|
|
540
|
+
message: `build on the shared style: import from ${ProjectLayout.STYLE_PACKAGE}`,
|
|
541
|
+
}),
|
|
542
|
+
);
|
|
543
|
+
}
|
|
544
|
+
}
|
|
788
545
|
}
|
|
546
|
+
|
|
547
|
+
if (lintConfigs === 0 && !isRootDeclared) {
|
|
548
|
+
violations.push(
|
|
549
|
+
createViolation({
|
|
550
|
+
check: DoctorChecks.STYLE,
|
|
551
|
+
file: 'package.json',
|
|
552
|
+
message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency`,
|
|
553
|
+
}),
|
|
554
|
+
);
|
|
555
|
+
}
|
|
556
|
+
|
|
557
|
+
return violations;
|
|
789
558
|
}
|
|
790
559
|
|
|
791
|
-
|
|
792
|
-
|
|
560
|
+
/**
|
|
561
|
+
* The scaffold is filled in: `init` writes a config and a knowledge index to be edited, and a
|
|
562
|
+
* project that never did would otherwise pass. A workspaces project declares its packages, and the
|
|
563
|
+
* knowledge index drops the scaffold marker once it describes the project.
|
|
564
|
+
*/
|
|
565
|
+
static checkScaffold(opts: ICheckContext): IViolation[] {
|
|
566
|
+
const violations: IViolation[] = [];
|
|
793
567
|
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
568
|
+
if (
|
|
569
|
+
ProjectScaffold.declaresWorkspaces({ root: opts.root }) &&
|
|
570
|
+
ProjectPackages.resolve({ config: opts.config }).length === 0
|
|
571
|
+
) {
|
|
572
|
+
violations.push(
|
|
573
|
+
createViolation({
|
|
574
|
+
check: DoctorChecks.SCAFFOLD,
|
|
575
|
+
file: opts.configFile,
|
|
576
|
+
message:
|
|
577
|
+
'package.json declares workspaces but the config lists no packages - add packages: [{ dir, name, path }] in release order',
|
|
578
|
+
}),
|
|
579
|
+
);
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
const index = join(opts.config.knowledge.bundle, 'index.md');
|
|
583
|
+
|
|
584
|
+
if (readText({ file: join(opts.root, index) }).includes(ProjectLayout.SCAFFOLD_MARKER)) {
|
|
585
|
+
violations.push(
|
|
586
|
+
createViolation({
|
|
587
|
+
check: DoctorChecks.SCAFFOLD,
|
|
588
|
+
file: index,
|
|
589
|
+
message: `still the scaffold - describe the project, then delete the ${ProjectLayout.SCAFFOLD_MARKER} line`,
|
|
590
|
+
}),
|
|
591
|
+
);
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
return violations;
|
|
816
595
|
}
|
|
817
596
|
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
597
|
+
/** Apps sit in the folders the user named, and every named folder is a workspace. */
|
|
598
|
+
static checkApps(opts: ICheckContext): IViolation[] {
|
|
599
|
+
const layout = opts.config.layout;
|
|
600
|
+
|
|
601
|
+
if (layout === undefined) {
|
|
602
|
+
return [];
|
|
603
|
+
}
|
|
604
|
+
|
|
605
|
+
const globs = ProjectScaffold.readWorkspaceGlobs({ root: opts.root });
|
|
606
|
+
const folders = LayoutKeys.ALL.flatMap((key) =>
|
|
607
|
+
LayoutFolder.layoutFoldersOf({ value: layout[key] }).map((folder) => ({ side: key, folder })),
|
|
608
|
+
);
|
|
609
|
+
// A folder under `other` is deliberately not managed: it need not be a workspace, only a package in it is allowed.
|
|
610
|
+
const violations = folders
|
|
611
|
+
.filter(
|
|
612
|
+
({ side, folder }) =>
|
|
613
|
+
side !== LayoutKeys.OTHER && !ProjectScaffold.coversFolder({ globs, folder }),
|
|
614
|
+
)
|
|
615
|
+
.map(({ side, folder }) =>
|
|
616
|
+
createViolation({
|
|
617
|
+
check: DoctorChecks.APPS,
|
|
618
|
+
file: 'package.json',
|
|
619
|
+
message: `layout.${side} '${folder}' is not in package.json workspaces - add '${folder}/*'`,
|
|
620
|
+
}),
|
|
621
|
+
);
|
|
622
|
+
const names = folders.map(({ folder }) => folder);
|
|
623
|
+
// A package may be an `other` folder itself (a docs site at `docs`); a side folder only holds packages.
|
|
624
|
+
const otherNames = folders
|
|
625
|
+
.filter(({ side }) => side === LayoutKeys.OTHER)
|
|
626
|
+
.map(({ folder }) => folder);
|
|
627
|
+
|
|
628
|
+
for (const entry of ProjectPackages.resolve({ config: opts.config }).filter(
|
|
629
|
+
(item) => !item.retired,
|
|
630
|
+
)) {
|
|
631
|
+
if (entry.kind === 'lib') {
|
|
632
|
+
const parent = dirname(entry.path);
|
|
633
|
+
|
|
634
|
+
// A library lives where the project keeps libraries; it only has to be a workspace.
|
|
635
|
+
if (!ProjectScaffold.coversFolder({ globs, folder: parent })) {
|
|
636
|
+
violations.push(
|
|
637
|
+
createViolation({
|
|
638
|
+
check: DoctorChecks.APPS,
|
|
639
|
+
file: opts.configFile,
|
|
640
|
+
message: `package ${entry.dir} lives at ${entry.path}, which no workspace glob covers - add '${parent}/*' to workspaces`,
|
|
641
|
+
}),
|
|
642
|
+
);
|
|
643
|
+
}
|
|
644
|
+
|
|
645
|
+
continue;
|
|
646
|
+
}
|
|
647
|
+
|
|
648
|
+
if (
|
|
649
|
+
!names.some((folder) => entry.path.startsWith(`${folder}/`)) &&
|
|
650
|
+
!otherNames.includes(entry.path)
|
|
651
|
+
) {
|
|
652
|
+
violations.push(
|
|
653
|
+
createViolation({
|
|
654
|
+
check: DoctorChecks.APPS,
|
|
655
|
+
file: opts.configFile,
|
|
656
|
+
message: `package ${entry.dir} lives at ${entry.path}, outside every layout folder (${names.join(', ')})`,
|
|
657
|
+
}),
|
|
658
|
+
);
|
|
659
|
+
}
|
|
660
|
+
}
|
|
821
661
|
|
|
822
|
-
|
|
823
|
-
return [];
|
|
662
|
+
return violations;
|
|
824
663
|
}
|
|
825
664
|
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
message:
|
|
833
|
-
lines === undefined
|
|
834
|
-
? `${subject} a Dockerfile and the root has no .dockerignore: the build context would carry node_modules, dist, .git and every .env file (secrets) - create it, then ${ADD_SECRET_LINES}`
|
|
835
|
-
: `${subject} a Dockerfile and the root .dockerignore does not exclude .env files, which hold secrets and would land in the image layer: ${ADD_SECRET_LINES}`,
|
|
836
|
-
}),
|
|
837
|
-
];
|
|
838
|
-
};
|
|
665
|
+
/**
|
|
666
|
+
* Info only, never a failure: an app that lacks a standard script or carries a legacy one gets one
|
|
667
|
+
* line naming them. Apps are the live packages inside the backend and frontend folders.
|
|
668
|
+
*/
|
|
669
|
+
static checkAppScripts(opts: ICheckContext): IViolation[] {
|
|
670
|
+
const layout = opts.config.layout;
|
|
839
671
|
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
'without it bun fmt uses its default style when oxfmt is not a dependency, and the output changes';
|
|
844
|
-
const OXFMT_LOADED_ADVICE =
|
|
845
|
-
'bun fmt loads it and it overrides the [fmt] section of bunfig.toml - delete it, or move its settings to [fmt]';
|
|
672
|
+
if (layout === undefined) {
|
|
673
|
+
return [];
|
|
674
|
+
}
|
|
846
675
|
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
join('packages', name),
|
|
853
|
-
),
|
|
854
|
-
...resolvePackages({ config: opts.config })
|
|
855
|
-
.filter((entry) => !entry.retired)
|
|
856
|
-
.map((entry) => relative(opts.root, join(opts.root, entry.path)) || '.'),
|
|
857
|
-
]),
|
|
858
|
-
];
|
|
676
|
+
const appFolders = [
|
|
677
|
+
...LayoutFolder.layoutFoldersOf({ value: layout.backend }),
|
|
678
|
+
...LayoutFolder.layoutFoldersOf({ value: layout.frontend }),
|
|
679
|
+
];
|
|
680
|
+
const notes: IViolation[] = [];
|
|
859
681
|
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
* nothing. Warnings, never failures: a project made before `bun fmt` does not start failing.
|
|
867
|
-
*/
|
|
868
|
-
export const checkFormat = (opts: ICheckContext): IViolation[] => {
|
|
869
|
-
const warnings: IViolation[] = [];
|
|
870
|
-
const bunfig = join(opts.root, 'bunfig.toml');
|
|
871
|
-
const bunfigText = readText({ file: bunfig });
|
|
682
|
+
for (const entry of ProjectPackages.resolve({ config: opts.config }).filter(
|
|
683
|
+
(item) => !item.retired,
|
|
684
|
+
)) {
|
|
685
|
+
if (!appFolders.some((folder) => entry.path.startsWith(`${folder}/`))) {
|
|
686
|
+
continue;
|
|
687
|
+
}
|
|
872
688
|
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
}
|
|
896
|
-
|
|
689
|
+
const file = `${entry.path}/package.json`;
|
|
690
|
+
const names = readScriptNames({ file: join(opts.root, file) });
|
|
691
|
+
|
|
692
|
+
if (names === undefined) {
|
|
693
|
+
continue;
|
|
694
|
+
}
|
|
695
|
+
|
|
696
|
+
const missing = AppScripts.STANDARD.filter((name) => !names.includes(name));
|
|
697
|
+
const legacy = AppScripts.LEGACY.filter((name) => names.includes(name));
|
|
698
|
+
const parts = [
|
|
699
|
+
...(missing.length === 0 ? [] : [`missing ${missing.join(', ')}`]),
|
|
700
|
+
...(legacy.length === 0 ? [] : [`legacy ${legacy.join(', ')} (use the standard names)`]),
|
|
701
|
+
];
|
|
702
|
+
|
|
703
|
+
if (parts.length > 0) {
|
|
704
|
+
notes.push(
|
|
705
|
+
createViolation({
|
|
706
|
+
check: DoctorChecks.SCRIPTS,
|
|
707
|
+
file,
|
|
708
|
+
message: `app ${entry.dir}: ${parts.join('; ')}`,
|
|
709
|
+
}),
|
|
710
|
+
);
|
|
711
|
+
}
|
|
712
|
+
}
|
|
713
|
+
|
|
714
|
+
return notes;
|
|
715
|
+
}
|
|
716
|
+
|
|
717
|
+
/** The developer's stored agents must parse and name known agents; a broken file would otherwise hide as a default. */
|
|
718
|
+
static checkAgents(opts: ICheckContext): IViolation[] {
|
|
719
|
+
const stored = LocalChoice.read({ root: opts.root });
|
|
720
|
+
|
|
721
|
+
return stored.ok
|
|
722
|
+
? []
|
|
723
|
+
: [
|
|
724
|
+
createViolation({
|
|
725
|
+
check: DoctorChecks.AGENTS,
|
|
726
|
+
file: '.agents/vulcan.local.json',
|
|
727
|
+
message: stored.error,
|
|
728
|
+
}),
|
|
729
|
+
];
|
|
897
730
|
}
|
|
898
731
|
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
732
|
+
/**
|
|
733
|
+
* The atlas server is registered the one way every project does: the root `.mcp.json` (a per-machine
|
|
734
|
+
* file `sync` writes for the agents that read it) holds an `atlas` entry that runs the project's own
|
|
735
|
+
* atlas (`--root .`), and the managed Claude settings enable `atlas` by that name. A server under
|
|
736
|
+
* another name, or one that serves another folder, is never enabled automatically or serves the wrong
|
|
737
|
+
* knowledge. A `.mcp.json` git still tracks is told how to hand over to `sync`; one that is untracked and not ignored is told how to hide it. Warnings, not violations.
|
|
738
|
+
*/
|
|
739
|
+
static checkMcpAtlas(opts: ICheckContext): IViolation[] {
|
|
740
|
+
const warnings: IViolation[] = [];
|
|
741
|
+
const file = join(opts.root, MCP_FILE);
|
|
742
|
+
const chosen = AgentSelection.resolveQuietly({
|
|
743
|
+
root: opts.root,
|
|
744
|
+
configAgents: opts.config.agents,
|
|
745
|
+
});
|
|
746
|
+
const readsMcpFile = AgentTable.read().some(
|
|
747
|
+
(entry) => chosen.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
|
|
748
|
+
);
|
|
749
|
+
|
|
750
|
+
// The root `.mcp.json` is a per-machine file of the agents that read it; a missing one is the
|
|
751
|
+
// `adapters` check's (not synced yet), so only an existing file is looked at.
|
|
752
|
+
if (readsMcpFile && existsSync(file)) {
|
|
753
|
+
if (AgentFiles.isTracked({ root: opts.root, path: MCP_FILE })) {
|
|
754
|
+
warnings.push(
|
|
755
|
+
mcpWarning({
|
|
756
|
+
file: MCP_FILE,
|
|
757
|
+
message:
|
|
758
|
+
'tracked by git; VULCAN now writes it per machine. Run `git rm --cached .mcp.json` and let sync manage it.',
|
|
759
|
+
}),
|
|
760
|
+
);
|
|
761
|
+
} else if (isUntrackedAndVisible({ root: opts.root, path: MCP_FILE })) {
|
|
762
|
+
warnings.push(
|
|
763
|
+
mcpWarning({
|
|
764
|
+
file: MCP_FILE,
|
|
765
|
+
message:
|
|
766
|
+
'untracked and not ignored, so a clean-tree check (a release) refuses to run. Add `/.mcp.json` to .gitignore, or run `vulcan sync` at the top level of the repository, which lists it in .git/info/exclude.',
|
|
767
|
+
}),
|
|
768
|
+
);
|
|
769
|
+
}
|
|
770
|
+
|
|
771
|
+
const parsed = readJsonObject({ file });
|
|
772
|
+
|
|
773
|
+
if (parsed === undefined) {
|
|
774
|
+
warnings.push(
|
|
775
|
+
mcpWarning({
|
|
776
|
+
file: MCP_FILE,
|
|
777
|
+
message: `not valid JSON - it must hold ${MCP_SERVER_HINT} under mcpServers`,
|
|
778
|
+
}),
|
|
779
|
+
);
|
|
780
|
+
} else {
|
|
781
|
+
const holder = { value: parsed['mcpServers'] };
|
|
782
|
+
const servers = RecordValue.isRecord(holder.value) ? holder.value : {};
|
|
783
|
+
const entry = { value: servers[ATLAS_SERVER] };
|
|
784
|
+
const args = RecordValue.isRecord(entry.value) ? entry.value['args'] : undefined;
|
|
785
|
+
const isCanonical =
|
|
786
|
+
RecordValue.isRecord(entry.value) &&
|
|
787
|
+
entry.value['command'] === 'bun' &&
|
|
788
|
+
Array.isArray(args) &&
|
|
789
|
+
args.length === CANONICAL_ATLAS_ARGS.length &&
|
|
790
|
+
args.every((arg, index) => arg === CANONICAL_ATLAS_ARGS[index]);
|
|
791
|
+
|
|
792
|
+
if (!RecordValue.isRecord(entry.value)) {
|
|
793
|
+
warnings.push(
|
|
794
|
+
mcpWarning({
|
|
795
|
+
file: MCP_FILE,
|
|
796
|
+
message: `no server named atlas (found: ${Object.keys(servers).join(', ') || 'none'}): a differently named server is not enabled automatically - use ${MCP_SERVER_HINT}`,
|
|
797
|
+
}),
|
|
798
|
+
);
|
|
799
|
+
} else if (!isCanonical) {
|
|
800
|
+
const shown = JSON.stringify(entry.value)
|
|
801
|
+
.replace('{"command":', '{ "command": ')
|
|
802
|
+
.replace(',"args":[', ', "args": [')
|
|
803
|
+
.replaceAll('","', '", "')
|
|
804
|
+
.replace(/\]\}$/, '] }');
|
|
805
|
+
|
|
806
|
+
warnings.push(
|
|
807
|
+
mcpWarning({
|
|
808
|
+
file: MCP_FILE,
|
|
809
|
+
message: `the atlas entry is ${shown}, expected ${MCP_SERVER_HINT}`,
|
|
810
|
+
}),
|
|
811
|
+
);
|
|
812
|
+
}
|
|
813
|
+
}
|
|
814
|
+
}
|
|
815
|
+
|
|
816
|
+
const settings = join(opts.root, CLAUDE_SETTINGS_FILE);
|
|
817
|
+
const enabled = existsSync(settings)
|
|
818
|
+
? readJsonObject({ file: settings })?.['enabledMcpjsonServers']
|
|
819
|
+
: undefined;
|
|
820
|
+
|
|
821
|
+
if (existsSync(settings) && !(Array.isArray(enabled) && enabled.includes(ATLAS_SERVER))) {
|
|
822
|
+
const has = Array.isArray(enabled) ? enabled.map(String).join(', ') : 'none';
|
|
902
823
|
|
|
903
|
-
if (readScriptNames({ file: join(opts.root, manifest) })?.includes('fmt')) {
|
|
904
824
|
warnings.push(
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
message:
|
|
909
|
-
'defines a "fmt" script: bun fmt runs it instead of formatting - rename it (the standard names are lint and lint:fix)',
|
|
825
|
+
mcpWarning({
|
|
826
|
+
file: CLAUDE_SETTINGS_FILE,
|
|
827
|
+
message: `enabledMcpjsonServers does not include atlas (has: ${has}): Claude asks before using the server - run vulcan sync`,
|
|
910
828
|
}),
|
|
911
829
|
);
|
|
912
830
|
}
|
|
913
831
|
|
|
914
|
-
|
|
832
|
+
return warnings;
|
|
833
|
+
}
|
|
834
|
+
|
|
835
|
+
/**
|
|
836
|
+
* A Dockerfile is built from the project root. Without a root `.dockerignore` the context carries
|
|
837
|
+
* node_modules, dist, .git and every `.env` (secrets that would land in an image layer a CI cache
|
|
838
|
+
* can keep); with one that does not exclude `.env` and `.env.*` the secrets are still copied.
|
|
839
|
+
* A warning, not a violation: the exit code is unchanged, so a project made before this check
|
|
840
|
+
* does not start failing.
|
|
841
|
+
*/
|
|
842
|
+
static checkDockerignore(opts: ICheckContext): IViolation[] {
|
|
843
|
+
const file = join(opts.root, '.dockerignore');
|
|
844
|
+
const lines = existsSync(file)
|
|
845
|
+
? readText({ file })
|
|
846
|
+
.split('\n')
|
|
847
|
+
.map((line) => line.trim())
|
|
848
|
+
.filter((line) => line !== '' && !line.startsWith('#'))
|
|
849
|
+
: undefined;
|
|
915
850
|
|
|
916
851
|
if (
|
|
917
|
-
|
|
918
|
-
|
|
852
|
+
lines !== undefined &&
|
|
853
|
+
excludes({ lines, file: '.env' }) &&
|
|
854
|
+
excludes({ lines, file: '.env.production' })
|
|
919
855
|
) {
|
|
856
|
+
return [];
|
|
857
|
+
}
|
|
858
|
+
|
|
859
|
+
const apps = ProjectPackages.resolve({ config: opts.config })
|
|
860
|
+
.filter((entry) => !entry.retired && existsSync(join(opts.root, entry.path, DOCKERFILE)))
|
|
861
|
+
.map((entry) => entry.dir);
|
|
862
|
+
|
|
863
|
+
if (apps.length === 0) {
|
|
864
|
+
return [];
|
|
865
|
+
}
|
|
866
|
+
|
|
867
|
+
const subject = apps.length === 1 ? `app ${apps[0]} has` : `apps ${apps.join(', ')} have`;
|
|
868
|
+
|
|
869
|
+
return [
|
|
870
|
+
createViolation({
|
|
871
|
+
check: DoctorChecks.DOCKERIGNORE,
|
|
872
|
+
file: '.dockerignore',
|
|
873
|
+
message:
|
|
874
|
+
lines === undefined
|
|
875
|
+
? `${subject} a Dockerfile and the root has no .dockerignore: the build context would carry node_modules, dist, .git and every .env file (secrets) - create it, then ${ADD_SECRET_LINES}`
|
|
876
|
+
: `${subject} a Dockerfile and the root .dockerignore does not exclude .env files, which hold secrets and would land in the image layer: ${ADD_SECRET_LINES}`,
|
|
877
|
+
}),
|
|
878
|
+
];
|
|
879
|
+
}
|
|
880
|
+
|
|
881
|
+
/**
|
|
882
|
+
* `bun fmt` reads the `[fmt]` section of `bunfig.toml`; without it, it formats with Bun's defaults
|
|
883
|
+
* (width 80, double quotes) and rewrites a tree the shared style formatted, and without
|
|
884
|
+
* `flavor = "oxfmt"` it formats like Prettier once oxfmt is not a dependency. A `fmt` script in a
|
|
885
|
+
* `package.json` runs instead of the formatter, and an oxfmt config `bun fmt` finds by itself
|
|
886
|
+
* overrides `[fmt]`; the `oxfmt.config.*` init used to write in `.configs/formatters/` is read by
|
|
887
|
+
* nothing. Warnings, never failures: a project made before `bun fmt` does not start failing.
|
|
888
|
+
*/
|
|
889
|
+
static checkFormat(opts: ICheckContext): IViolation[] {
|
|
890
|
+
const warnings: IViolation[] = [];
|
|
891
|
+
const bunfig = join(opts.root, 'bunfig.toml');
|
|
892
|
+
const bunfigText = readText({ file: bunfig });
|
|
893
|
+
|
|
894
|
+
if (!existsSync(bunfig)) {
|
|
920
895
|
warnings.push(
|
|
921
896
|
createViolation({
|
|
922
897
|
check: DoctorChecks.FORMAT,
|
|
923
|
-
file:
|
|
924
|
-
message:
|
|
925
|
-
|
|
898
|
+
file: 'bunfig.toml',
|
|
899
|
+
message: `missing - ${FMT_SECTION_ADVICE}`,
|
|
900
|
+
}),
|
|
901
|
+
);
|
|
902
|
+
} else if (!DoctorConstants.BUNFIG_FMT_SECTION.test(bunfigText)) {
|
|
903
|
+
warnings.push(
|
|
904
|
+
createViolation({
|
|
905
|
+
check: DoctorChecks.FORMAT,
|
|
906
|
+
file: 'bunfig.toml',
|
|
907
|
+
message: `no [fmt] section - ${FMT_SECTION_ADVICE}`,
|
|
908
|
+
}),
|
|
909
|
+
);
|
|
910
|
+
} else if (!DoctorConstants.BUNFIG_FMT_FLAVOR.test(bunfigText)) {
|
|
911
|
+
warnings.push(
|
|
912
|
+
createViolation({
|
|
913
|
+
check: DoctorChecks.FORMAT,
|
|
914
|
+
file: 'bunfig.toml',
|
|
915
|
+
message: `[fmt] has no flavor = "oxfmt" - ${FMT_FLAVOR_ADVICE}`,
|
|
926
916
|
}),
|
|
927
917
|
);
|
|
928
918
|
}
|
|
929
919
|
|
|
930
|
-
for (const
|
|
931
|
-
|
|
920
|
+
for (const owner of formatOwners(opts)) {
|
|
921
|
+
const manifest = join(owner, 'package.json');
|
|
922
|
+
const formatters = join(owner, '.configs', 'formatters');
|
|
923
|
+
|
|
924
|
+
if (readScriptNames({ file: join(opts.root, manifest) })?.includes('fmt')) {
|
|
932
925
|
warnings.push(
|
|
933
926
|
createViolation({
|
|
934
927
|
check: DoctorChecks.FORMAT,
|
|
935
|
-
file:
|
|
936
|
-
message:
|
|
928
|
+
file: manifest,
|
|
929
|
+
message:
|
|
930
|
+
'defines a "fmt" script: bun fmt runs it instead of formatting - rename it (the standard names are lint and lint:fix)',
|
|
937
931
|
}),
|
|
938
932
|
);
|
|
939
933
|
}
|
|
940
|
-
}
|
|
941
934
|
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
935
|
+
const copy = join(owner, 'bunfig.toml');
|
|
936
|
+
|
|
937
|
+
if (
|
|
938
|
+
owner !== '.' &&
|
|
939
|
+
DoctorConstants.BUNFIG_FMT_SECTION.test(readText({ file: join(opts.root, copy) }))
|
|
940
|
+
) {
|
|
946
941
|
warnings.push(
|
|
947
942
|
createViolation({
|
|
948
943
|
check: DoctorChecks.FORMAT,
|
|
949
|
-
file:
|
|
944
|
+
file: copy,
|
|
950
945
|
message:
|
|
951
|
-
'
|
|
946
|
+
'a [fmt] copy: bun fmt inherits the root bunfig.toml, and a copy here can drift from it - delete the section',
|
|
952
947
|
}),
|
|
953
948
|
);
|
|
954
949
|
}
|
|
950
|
+
|
|
951
|
+
for (const file of DoctorConstants.OXFMT_AUTOLOADED_FILES) {
|
|
952
|
+
if (existsSync(join(opts.root, owner, file))) {
|
|
953
|
+
warnings.push(
|
|
954
|
+
createViolation({
|
|
955
|
+
check: DoctorChecks.FORMAT,
|
|
956
|
+
file: join(owner, file),
|
|
957
|
+
message: OXFMT_LOADED_ADVICE,
|
|
958
|
+
}),
|
|
959
|
+
);
|
|
960
|
+
}
|
|
961
|
+
}
|
|
962
|
+
|
|
963
|
+
if (existsSync(join(opts.root, formatters))) {
|
|
964
|
+
for (const file of readdirSync(join(opts.root, formatters)).filter((name) =>
|
|
965
|
+
DoctorConstants.OXFMT_CONFIG_FILE.test(name),
|
|
966
|
+
)) {
|
|
967
|
+
warnings.push(
|
|
968
|
+
createViolation({
|
|
969
|
+
check: DoctorChecks.FORMAT,
|
|
970
|
+
file: join(formatters, file),
|
|
971
|
+
message:
|
|
972
|
+
'not used any more: bun fmt formats with the [fmt] section of bunfig.toml - delete it',
|
|
973
|
+
}),
|
|
974
|
+
);
|
|
975
|
+
}
|
|
976
|
+
}
|
|
955
977
|
}
|
|
978
|
+
|
|
979
|
+
return warnings;
|
|
956
980
|
}
|
|
957
981
|
|
|
958
|
-
|
|
959
|
-
};
|
|
982
|
+
static checkAtlasBlock(opts: ICheckContext): IViolation[] {
|
|
983
|
+
const merged = AtlasBlockPlan.merged({ root: opts.root, config: opts.config });
|
|
960
984
|
|
|
961
|
-
|
|
962
|
-
|
|
985
|
+
return merged === undefined || !merged.changed
|
|
986
|
+
? []
|
|
987
|
+
: [
|
|
988
|
+
createViolation({
|
|
989
|
+
check: DoctorChecks.AGENTS,
|
|
990
|
+
file: 'AGENTS.md',
|
|
991
|
+
message: `the Atlas block is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
|
|
992
|
+
}),
|
|
993
|
+
];
|
|
994
|
+
}
|
|
963
995
|
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
:
|
|
996
|
+
/** A skill with no "Use when" part gives the atlas server's instructions nothing to say when to load it: a warning, never a failure. */
|
|
997
|
+
static checkSkillTriggers(opts: ICheckContext): IViolation[] {
|
|
998
|
+
return SkillCatalog.catalogOf({ root: opts.root })
|
|
999
|
+
.filter((entry) => !SkillCatalog.triggerOf({ description: entry.description }).hasUseWhen)
|
|
1000
|
+
.map((entry) =>
|
|
967
1001
|
createViolation({
|
|
968
|
-
check: DoctorChecks.
|
|
969
|
-
file: '
|
|
970
|
-
message: `
|
|
1002
|
+
check: DoctorChecks.SKILLS,
|
|
1003
|
+
file: entry.source === 'project' ? `.agents/skills/${entry.name}/SKILL.md` : entry.name,
|
|
1004
|
+
message: `'${entry.name}' has no "Use when" part in its description - atlas cannot say when to load it`,
|
|
971
1005
|
}),
|
|
972
|
-
|
|
973
|
-
}
|
|
1006
|
+
);
|
|
1007
|
+
}
|
|
974
1008
|
|
|
975
|
-
/**
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
1009
|
+
/** `.agents/local/` exists with its subdirectories and is gitignored: `sync` does both, so an upgraded project that has not synced yet is told here. */
|
|
1010
|
+
static checkLocalWorkspace(opts: ICheckContext): IViolation[] {
|
|
1011
|
+
return LocalPlan.planWorkspace({ root: opts.root })
|
|
1012
|
+
.filter((action) => action.status !== SyncStatuses.UNCHANGED)
|
|
1013
|
+
.map((action) =>
|
|
1014
|
+
createViolation({
|
|
1015
|
+
check: DoctorChecks.LOCAL,
|
|
1016
|
+
file: relative(opts.root, action.path) || '.',
|
|
1017
|
+
message: `${action.note ?? 'out of date'} - run 'bun x --no-install vulcan sync'`,
|
|
1018
|
+
}),
|
|
1019
|
+
);
|
|
1020
|
+
}
|
|
986
1021
|
|
|
987
|
-
/**
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
);
|
|
1022
|
+
/**
|
|
1023
|
+
* A worktree of this repository that lives outside it: the repository's own `git worktree list` names it
|
|
1024
|
+
* (git metadata is inside the project), and the exact command moves it in. Nothing is moved or removed.
|
|
1025
|
+
*/
|
|
1026
|
+
static checkOutsideWorktrees(opts: ICheckContext): IViolation[] {
|
|
1027
|
+
const listed = spawnSync('git', ['worktree', 'list', '--porcelain'], {
|
|
1028
|
+
cwd: opts.root,
|
|
1029
|
+
encoding: 'utf8',
|
|
1030
|
+
timeout: 5000,
|
|
1031
|
+
});
|
|
998
1032
|
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
*/
|
|
1003
|
-
export const checkOutsideWorktrees = (opts: ICheckContext): IViolation[] => {
|
|
1004
|
-
const listed = spawnSync('git', ['worktree', 'list', '--porcelain'], {
|
|
1005
|
-
cwd: opts.root,
|
|
1006
|
-
encoding: 'utf8',
|
|
1007
|
-
timeout: 5000,
|
|
1008
|
-
});
|
|
1033
|
+
if (listed.status !== 0) {
|
|
1034
|
+
return [];
|
|
1035
|
+
}
|
|
1009
1036
|
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1037
|
+
const [boundary, ...linked] = listed.stdout
|
|
1038
|
+
.split('\n')
|
|
1039
|
+
.filter((line) => line.startsWith('worktree '))
|
|
1040
|
+
.map((line) => line.slice('worktree '.length));
|
|
1041
|
+
|
|
1042
|
+
if (boundary === undefined) {
|
|
1043
|
+
return [];
|
|
1044
|
+
}
|
|
1045
|
+
|
|
1046
|
+
const inside = (path: string): boolean => {
|
|
1047
|
+
const real = existsSync(path) ? realpathSync(path) : path;
|
|
1013
1048
|
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
.filter((line) => line.startsWith('worktree '))
|
|
1017
|
-
.map((line) => line.slice('worktree '.length));
|
|
1049
|
+
return real === boundary || real.startsWith(`${boundary}${sep}`);
|
|
1050
|
+
};
|
|
1018
1051
|
|
|
1019
|
-
|
|
1020
|
-
|
|
1052
|
+
return linked
|
|
1053
|
+
.filter((path) => !inside(path))
|
|
1054
|
+
.map((path) =>
|
|
1055
|
+
createViolation({
|
|
1056
|
+
check: DoctorChecks.LOCAL,
|
|
1057
|
+
file: path,
|
|
1058
|
+
message: `a git worktree outside the project - move it in: git worktree move '${path}' '${join(boundary, ProjectLayout.LOCAL_DIRECTORY, 'worktrees', basename(path))}'`,
|
|
1059
|
+
}),
|
|
1060
|
+
);
|
|
1021
1061
|
}
|
|
1022
1062
|
|
|
1023
|
-
|
|
1024
|
-
|
|
1063
|
+
/** The personal profile: a file that cannot be read is named, and one git tracks is a personal file about to be shared. */
|
|
1064
|
+
static checkProfile(opts: ICheckContext): IViolation[] {
|
|
1065
|
+
const read = OwnerProfile.read({ root: opts.root });
|
|
1066
|
+
const violations: IViolation[] = [];
|
|
1025
1067
|
|
|
1026
|
-
|
|
1027
|
-
|
|
1068
|
+
if (!read.ok) {
|
|
1069
|
+
violations.push(
|
|
1070
|
+
createViolation({
|
|
1071
|
+
check: DoctorChecks.PROFILE,
|
|
1072
|
+
file: OwnerConstants.PROFILE_FILE,
|
|
1073
|
+
message: `${read.error} - fix it or delete it and run the profile form again`,
|
|
1074
|
+
}),
|
|
1075
|
+
);
|
|
1076
|
+
}
|
|
1028
1077
|
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1078
|
+
if (
|
|
1079
|
+
existsSync(join(opts.root, OwnerConstants.PROFILE_FILE)) &&
|
|
1080
|
+
!OwnerProfile.profileIsIgnored({ root: opts.root })
|
|
1081
|
+
) {
|
|
1082
|
+
violations.push(
|
|
1083
|
+
createViolation({
|
|
1084
|
+
check: DoctorChecks.PROFILE,
|
|
1085
|
+
file: OwnerConstants.PROFILE_FILE,
|
|
1086
|
+
message:
|
|
1087
|
+
'git does not ignore this personal file - add .agents/local/ to .gitignore (vulcan sync does it)',
|
|
1088
|
+
}),
|
|
1089
|
+
);
|
|
1090
|
+
}
|
|
1039
1091
|
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1092
|
+
if (
|
|
1093
|
+
existsSync(join(opts.root, OwnerConstants.PROFILE_FILE)) &&
|
|
1094
|
+
AgentFiles.isTracked({ root: opts.root, path: OwnerConstants.PROFILE_FILE })
|
|
1095
|
+
) {
|
|
1096
|
+
violations.push(
|
|
1097
|
+
createViolation({
|
|
1098
|
+
check: DoctorChecks.PROFILE,
|
|
1099
|
+
file: OwnerConstants.PROFILE_FILE,
|
|
1100
|
+
message:
|
|
1101
|
+
'git tracks this personal file - run: git rm --cached .agents/local/profile.json (and keep .agents/local/ in .gitignore)',
|
|
1102
|
+
}),
|
|
1103
|
+
);
|
|
1104
|
+
}
|
|
1044
1105
|
|
|
1045
|
-
|
|
1046
|
-
violations.push(
|
|
1047
|
-
createViolation({
|
|
1048
|
-
check: DoctorChecks.PROFILE,
|
|
1049
|
-
file: OwnerConstants.PROFILE_FILE,
|
|
1050
|
-
message: `${read.error} - fix it or delete it and run the profile form again`,
|
|
1051
|
-
}),
|
|
1052
|
-
);
|
|
1106
|
+
return violations;
|
|
1053
1107
|
}
|
|
1054
1108
|
|
|
1055
|
-
|
|
1056
|
-
|
|
1057
|
-
|
|
1058
|
-
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1109
|
+
/** What an agent left under `.agents/local/` that has outlived its use, one line each with the command that clears it. */
|
|
1110
|
+
static checkStaleLocal(opts: ICheckContext): IViolation[] {
|
|
1111
|
+
return LocalScan.scan({ root: opts.root })
|
|
1112
|
+
.filter((entry) =>
|
|
1113
|
+
[LocalStates.STALE, LocalStates.MERGED, LocalStates.GONE, LocalStates.ORPHAN].includes(
|
|
1114
|
+
entry.state,
|
|
1115
|
+
),
|
|
1116
|
+
)
|
|
1117
|
+
.map((entry) =>
|
|
1118
|
+
createViolation({
|
|
1119
|
+
check: DoctorChecks.LOCAL,
|
|
1120
|
+
file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.scope}/${entry.name}`,
|
|
1121
|
+
message: `${entry.state === LocalStates.STALE ? `left ${LocalFormat.formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${LocalFormat.formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
|
|
1122
|
+
}),
|
|
1123
|
+
);
|
|
1067
1124
|
}
|
|
1068
1125
|
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
) {
|
|
1073
|
-
violations.push(
|
|
1074
|
-
createViolation({
|
|
1075
|
-
check: DoctorChecks.PROFILE,
|
|
1076
|
-
file: OwnerConstants.PROFILE_FILE,
|
|
1077
|
-
message:
|
|
1078
|
-
'git tracks this personal file - run: git rm --cached .agents/local/profile.json (and keep .agents/local/ in .gitignore)',
|
|
1079
|
-
}),
|
|
1080
|
-
);
|
|
1081
|
-
}
|
|
1126
|
+
/** How often replies to the owner were flagged (the report shape, or a claim the turn did not back), from the log the Stop hook keeps; a note, never a failure. */
|
|
1127
|
+
static checkReplyShape(opts: ICheckContext): IViolation[] {
|
|
1128
|
+
const { byClass, replies, days } = ViolationLog.readCounts({ root: opts.root });
|
|
1082
1129
|
|
|
1083
|
-
|
|
1084
|
-
|
|
1130
|
+
if (replies === 0) {
|
|
1131
|
+
return [];
|
|
1132
|
+
}
|
|
1085
1133
|
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1093
|
-
|
|
1094
|
-
|
|
1134
|
+
const parts = [...byClass.entries()]
|
|
1135
|
+
.sort((first, second) => second[1] - first[1])
|
|
1136
|
+
.map(([name, count]) => `${name} ${count}`);
|
|
1137
|
+
|
|
1138
|
+
const isFull =
|
|
1139
|
+
ViolationLog.violationBytes({ root: opts.root }) > ViolationConstants.LOG_MAX_BYTES;
|
|
1140
|
+
|
|
1141
|
+
return [
|
|
1142
|
+
...(isFull
|
|
1143
|
+
? [
|
|
1144
|
+
createViolation({
|
|
1145
|
+
check: DoctorChecks.LOCAL,
|
|
1146
|
+
file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
|
|
1147
|
+
message: `the log is full (${LocalFormat.formatBytes({ bytes: ViolationConstants.LOG_MAX_BYTES })}) and no longer grows; keep or delete it, and a new one starts`,
|
|
1148
|
+
}),
|
|
1149
|
+
]
|
|
1150
|
+
: []),
|
|
1095
1151
|
createViolation({
|
|
1096
1152
|
check: DoctorChecks.LOCAL,
|
|
1097
|
-
file: `${ProjectLayout.LOCAL_DIRECTORY}/${
|
|
1098
|
-
message: `${
|
|
1153
|
+
file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
|
|
1154
|
+
message: `${replies} repl${replies === 1 ? 'y was' : 'ies were'} flagged on ${days} day${days === 1 ? '' : 's'} (${parts.join(', ')}); the retro skill turns a pattern into a check`,
|
|
1099
1155
|
}),
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
/** How often replies to the owner were flagged (the report shape, or a claim the turn did not back), from the log the Stop hook keeps; a note, never a failure. */
|
|
1103
|
-
export const checkReplyShape = (opts: ICheckContext): IViolation[] => {
|
|
1104
|
-
const { byClass, replies, days } = readViolationCounts({ root: opts.root });
|
|
1105
|
-
|
|
1106
|
-
if (replies === 0) {
|
|
1107
|
-
return [];
|
|
1156
|
+
];
|
|
1108
1157
|
}
|
|
1109
1158
|
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
.
|
|
1113
|
-
|
|
1114
|
-
const isFull = violationLogBytes({ root: opts.root }) > ViolationConstants.LOG_MAX_BYTES;
|
|
1115
|
-
|
|
1116
|
-
return [
|
|
1117
|
-
...(isFull
|
|
1159
|
+
/** The owner reply shape is off for this shell (`VULCAN_OWNER_REPLY=off`): a session an agent starts sets it, an owner who exported it by mistake sees why nothing is checked; a note, never a failure. */
|
|
1160
|
+
static checkOwnerReplySwitch(opts: { env: Record<string, string | undefined> }): IViolation[] {
|
|
1161
|
+
return ReplySwitch.isOwnerOff({ env: opts.env })
|
|
1118
1162
|
? [
|
|
1119
1163
|
createViolation({
|
|
1120
1164
|
check: DoctorChecks.LOCAL,
|
|
1121
|
-
file:
|
|
1122
|
-
message: `
|
|
1165
|
+
file: OwnerReplySwitch.ENV,
|
|
1166
|
+
message: `set to ${OwnerReplySwitch.OFF} in this shell: a session started from here is not held to the owner reply shape and its replies are not logged. Unset it for a session whose reader is the owner`,
|
|
1123
1167
|
}),
|
|
1124
1168
|
]
|
|
1125
|
-
: []
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1169
|
+
: [];
|
|
1170
|
+
}
|
|
1171
|
+
|
|
1172
|
+
/** A Claude Code settings file of the project sets `VULCAN_OWNER_REPLY=off` in `env`: every session of the project then skips the owner reply shape. A warning, never a failure. */
|
|
1173
|
+
static checkOwnerReplySettings(opts: { root: string }): IViolation[] {
|
|
1174
|
+
return ['.claude/settings.json', '.claude/settings.local.json'].flatMap((file) => {
|
|
1175
|
+
const env = readJsonObject({ file: join(opts.root, file) })?.['env'];
|
|
1176
|
+
|
|
1177
|
+
return typeof env === 'object' &&
|
|
1178
|
+
env !== null &&
|
|
1179
|
+
Reflect.get(env, OwnerReplySwitch.ENV) === OwnerReplySwitch.OFF
|
|
1180
|
+
? [
|
|
1181
|
+
createViolation({
|
|
1182
|
+
check: DoctorChecks.LOCAL,
|
|
1183
|
+
file,
|
|
1184
|
+
message: `env sets ${OwnerReplySwitch.ENV}=${OwnerReplySwitch.OFF}: every session of this project skips the owner reply shape. Remove it and set the variable on the command that starts a session whose reader is an agent`,
|
|
1185
|
+
}),
|
|
1186
|
+
]
|
|
1187
|
+
: [];
|
|
1188
|
+
});
|
|
1189
|
+
}
|
|
1190
|
+
|
|
1191
|
+
/** One line per script in `guard.writes.trustedScripts` with what git says about it now (a note). */
|
|
1192
|
+
static checkTrustedScripts(opts: ICheckContext): IViolation[] {
|
|
1193
|
+
return opts.config.guard.writes.trustedScripts.map((entry) => {
|
|
1194
|
+
const { script, readOnly } = trustedScriptOf({ entry });
|
|
1195
|
+
const trust = ScriptTrust.trustOf({ root: opts.root, script });
|
|
1196
|
+
const scope = readOnly === undefined ? 'mutating calls' : `the calls ${readOnly.join(', ')}`;
|
|
1197
|
+
|
|
1198
|
+
return createViolation({
|
|
1199
|
+
check: DoctorChecks.GUARDS,
|
|
1200
|
+
file: script,
|
|
1201
|
+
message:
|
|
1202
|
+
trust.state === TrustStates.TRUSTED
|
|
1203
|
+
? `guard-writes does not read this script for ${scope} (guard.writes.trustedScripts); it is ` +
|
|
1204
|
+
trust.reason
|
|
1205
|
+
: `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
|
|
1206
|
+
});
|
|
1207
|
+
});
|
|
1208
|
+
}
|
|
1209
|
+
|
|
1210
|
+
/** A listed script that does not exist or is not committed: the exemption never applies (a warning). */
|
|
1211
|
+
static checkStaleTrustedScripts(opts: ICheckContext): IViolation[] {
|
|
1212
|
+
return opts.config.guard.writes.trustedScripts.flatMap((entry) => {
|
|
1213
|
+
const { script } = trustedScriptOf({ entry });
|
|
1214
|
+
const trust = ScriptTrust.trustOf({ root: opts.root, script });
|
|
1215
|
+
|
|
1216
|
+
return STALE_TRUST_STATES.has(trust.state)
|
|
1217
|
+
? [
|
|
1218
|
+
createViolation({
|
|
1219
|
+
check: DoctorChecks.GUARDS,
|
|
1220
|
+
file: script,
|
|
1221
|
+
message: `guard.writes.trustedScripts lists it, but it never takes effect: ${trust.reason}; fix the path, or commit the script`,
|
|
1222
|
+
}),
|
|
1223
|
+
]
|
|
1224
|
+
: [];
|
|
1225
|
+
});
|
|
1226
|
+
}
|
|
1227
|
+
|
|
1228
|
+
/**
|
|
1229
|
+
* The commands and push targets the project adds to guard-writes and guard-git, one note each: so the
|
|
1230
|
+
* guards' reach beyond their own list is visible where a person looks, with the rule and the pattern.
|
|
1231
|
+
*/
|
|
1232
|
+
static checkGuardPatterns(opts: ICheckContext): IViolation[] {
|
|
1233
|
+
const { commands } = opts.config.guard.writes;
|
|
1234
|
+
const { askPush } = opts.config.guard.git;
|
|
1133
1235
|
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
env: Record<string, string | undefined>;
|
|
1137
|
-
}): IViolation[] =>
|
|
1138
|
-
isOwnerReplyOff({ env: opts.env })
|
|
1139
|
-
? [
|
|
1236
|
+
return [
|
|
1237
|
+
...commands.map((command) =>
|
|
1140
1238
|
createViolation({
|
|
1141
|
-
check: DoctorChecks.
|
|
1142
|
-
file:
|
|
1143
|
-
message: `
|
|
1239
|
+
check: DoctorChecks.GUARDS,
|
|
1240
|
+
file: opts.configFile,
|
|
1241
|
+
message: `guard.writes.commands: ${command.rule} '${command.what}' asks when a command matches /${command.pattern}/${command.ignoreCase === true ? 'i' : ''}`,
|
|
1144
1242
|
}),
|
|
1145
|
-
|
|
1146
|
-
|
|
1243
|
+
),
|
|
1244
|
+
...(askPush.length === 0
|
|
1245
|
+
? []
|
|
1246
|
+
: [
|
|
1247
|
+
createViolation({
|
|
1248
|
+
check: DoctorChecks.GUARDS,
|
|
1249
|
+
file: opts.configFile,
|
|
1250
|
+
message: `guard.git.askPush: a plain git push asks for ${askPush.join(', ')}`,
|
|
1251
|
+
}),
|
|
1252
|
+
]),
|
|
1253
|
+
];
|
|
1254
|
+
}
|
|
1147
1255
|
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
const env = readJsonObject({ file: join(opts.root, file) })?.['env'];
|
|
1256
|
+
static checkLocalSize(opts: ICheckContext): IViolation[] {
|
|
1257
|
+
const entries = LocalScan.scan({ root: opts.root });
|
|
1258
|
+
const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
|
|
1152
1259
|
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
? [
|
|
1157
|
-
createViolation({
|
|
1158
|
-
check: DoctorChecks.LOCAL,
|
|
1159
|
-
file,
|
|
1160
|
-
message: `env sets ${OwnerReplySwitch.ENV}=${OwnerReplySwitch.OFF}: every session of this project skips the owner reply shape. Remove it and set the variable on the command that starts a session whose reader is an agent`,
|
|
1161
|
-
}),
|
|
1162
|
-
]
|
|
1163
|
-
: [];
|
|
1164
|
-
});
|
|
1260
|
+
if (total < LocalConstants.NOTE_BYTES) {
|
|
1261
|
+
return [];
|
|
1262
|
+
}
|
|
1165
1263
|
|
|
1166
|
-
|
|
1167
|
-
/** The states of a listed script worth a warning: a typo or a script nobody committed. A modified one is normal work, so it is only a note. */
|
|
1168
|
-
const STALE_TRUST_STATES = new Set<string>([
|
|
1169
|
-
TrustStates.MISSING,
|
|
1170
|
-
TrustStates.UNTRACKED,
|
|
1171
|
-
TrustStates.UNCOMMITTED,
|
|
1172
|
-
TrustStates.SYMLINK,
|
|
1173
|
-
TrustStates.UNKNOWN,
|
|
1174
|
-
]);
|
|
1264
|
+
const byScope = new Map<string, number>();
|
|
1175
1265
|
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
const trust = trustOf({ root: opts.root, script });
|
|
1180
|
-
|
|
1181
|
-
return createViolation({
|
|
1182
|
-
check: DoctorChecks.GUARDS,
|
|
1183
|
-
file: script,
|
|
1184
|
-
message:
|
|
1185
|
-
trust.state === TrustStates.TRUSTED
|
|
1186
|
-
? 'guard-writes does not read this script for mutating calls (guard.writes.trustedScripts); it is ' +
|
|
1187
|
-
trust.reason
|
|
1188
|
-
: `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
|
|
1189
|
-
});
|
|
1190
|
-
});
|
|
1266
|
+
for (const entry of entries) {
|
|
1267
|
+
byScope.set(entry.scope, (byScope.get(entry.scope) ?? 0) + entry.bytes);
|
|
1268
|
+
}
|
|
1191
1269
|
|
|
1192
|
-
|
|
1193
|
-
|
|
1194
|
-
|
|
1195
|
-
const trust = trustOf({ root: opts.root, script });
|
|
1270
|
+
const parts = [...byScope.entries()]
|
|
1271
|
+
.sort((first, second) => second[1] - first[1])
|
|
1272
|
+
.map(([scope, bytes]) => `${scope} ${LocalFormat.formatBytes({ bytes })}`);
|
|
1196
1273
|
|
|
1197
|
-
return
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
|
-
|
|
1203
|
-
|
|
1204
|
-
|
|
1205
|
-
|
|
1206
|
-
|
|
1274
|
+
return [
|
|
1275
|
+
createViolation({
|
|
1276
|
+
check: DoctorChecks.LOCAL,
|
|
1277
|
+
file: ProjectLayout.LOCAL_DIRECTORY,
|
|
1278
|
+
message: `holds ${LocalFormat.formatBytes({ bytes: total })} (${parts.join(', ')}); vulcan clean lists what an agent left and --yes removes it`,
|
|
1279
|
+
}),
|
|
1280
|
+
];
|
|
1281
|
+
}
|
|
1282
|
+
}
|
|
1283
|
+
|
|
1284
|
+
const QUOTES = ["'", '"', '`'];
|
|
1207
1285
|
|
|
1208
1286
|
/**
|
|
1209
|
-
*
|
|
1210
|
-
*
|
|
1287
|
+
* A subcommand an object entry lists that its script never holds as a quoted string (a note). It reads the
|
|
1288
|
+
* text of the file, so it cannot tell a subcommand the script handles another way from a typo.
|
|
1211
1289
|
*/
|
|
1212
|
-
export
|
|
1213
|
-
|
|
1214
|
-
|
|
1290
|
+
export class ReadOnlySubcommandChecks {
|
|
1291
|
+
static readonly MAX_SOURCE_BYTES = 1_000_000;
|
|
1292
|
+
|
|
1293
|
+
static sourceOf(opts: { path: string }): string | undefined {
|
|
1294
|
+
try {
|
|
1295
|
+
const stat = lstatSync(opts.path);
|
|
1296
|
+
|
|
1297
|
+
return stat.isFile() && stat.size <= ReadOnlySubcommandChecks.MAX_SOURCE_BYTES
|
|
1298
|
+
? readFileSync(opts.path, 'utf8')
|
|
1299
|
+
: undefined;
|
|
1300
|
+
} catch {
|
|
1301
|
+
return undefined;
|
|
1302
|
+
}
|
|
1303
|
+
}
|
|
1215
1304
|
|
|
1216
|
-
|
|
1217
|
-
|
|
1218
|
-
|
|
1219
|
-
|
|
1220
|
-
file: opts.configFile,
|
|
1221
|
-
message: `guard.writes.commands: ${command.rule} '${command.what}' asks when a command matches /${command.pattern}/${command.ignoreCase === true ? 'i' : ''}`,
|
|
1222
|
-
}),
|
|
1223
|
-
),
|
|
1224
|
-
...(askPush.length === 0
|
|
1225
|
-
? []
|
|
1226
|
-
: [
|
|
1227
|
-
createViolation({
|
|
1228
|
-
check: DoctorChecks.GUARDS,
|
|
1229
|
-
file: opts.configFile,
|
|
1230
|
-
message: `guard.git.askPush: a plain git push asks for ${askPush.join(', ')}`,
|
|
1231
|
-
}),
|
|
1232
|
-
]),
|
|
1233
|
-
];
|
|
1234
|
-
};
|
|
1305
|
+
static check(opts: ICheckContext): IViolation[] {
|
|
1306
|
+
return opts.config.guard.writes.trustedScripts.flatMap((entry) => {
|
|
1307
|
+
const { script, readOnly } = trustedScriptOf({ entry });
|
|
1308
|
+
const path = join(opts.root, script);
|
|
1235
1309
|
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1310
|
+
if (readOnly === undefined) {
|
|
1311
|
+
return [];
|
|
1312
|
+
}
|
|
1239
1313
|
|
|
1240
|
-
|
|
1241
|
-
|
|
1242
|
-
}
|
|
1314
|
+
// Only a plain, small file inside the repo is read: a link, a folder or a device is skipped, never followed.
|
|
1315
|
+
const source = ReadOnlySubcommandChecks.sourceOf({ path });
|
|
1243
1316
|
|
|
1244
|
-
|
|
1317
|
+
if (source === undefined) {
|
|
1318
|
+
return [];
|
|
1319
|
+
}
|
|
1245
1320
|
|
|
1246
|
-
|
|
1247
|
-
|
|
1321
|
+
return readOnly
|
|
1322
|
+
.filter((word) => !QUOTES.some((quote) => source.includes(`${quote}${word}${quote}`)))
|
|
1323
|
+
.map((word) =>
|
|
1324
|
+
createViolation({
|
|
1325
|
+
check: DoctorChecks.GUARDS,
|
|
1326
|
+
file: script,
|
|
1327
|
+
message: `guard.writes.trustedScripts lists the subcommand '${word}' for this script, but the script does not hold it as a quoted string; this is a check of the text of the file, not what the script does`,
|
|
1328
|
+
}),
|
|
1329
|
+
);
|
|
1330
|
+
});
|
|
1248
1331
|
}
|
|
1249
|
-
|
|
1250
|
-
const parts = [...byScope.entries()]
|
|
1251
|
-
.sort((first, second) => second[1] - first[1])
|
|
1252
|
-
.map(([scope, bytes]) => `${scope} ${formatBytes({ bytes })}`);
|
|
1253
|
-
|
|
1254
|
-
return [
|
|
1255
|
-
createViolation({
|
|
1256
|
-
check: DoctorChecks.LOCAL,
|
|
1257
|
-
file: ProjectLayout.LOCAL_DIRECTORY,
|
|
1258
|
-
message: `holds ${formatBytes({ bytes: total })} (${parts.join(', ')}); vulcan clean lists what an agent left and --yes removes it`,
|
|
1259
|
-
}),
|
|
1260
|
-
];
|
|
1261
|
-
};
|
|
1332
|
+
}
|