@venizia/vulcan 0.4.10-2 → 0.4.10-21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -23
- package/base/checks/wiki-source-links.ts +17 -1
- package/base/claude/events.json +1 -11
- package/base/claude/settings.json +5 -76
- package/base/extensions/vulcan-guards.ts +81 -18
- package/base/hooks/guard-git.ts +95 -19
- package/base/hooks/guard-outside.ts +163 -43
- package/base/hooks/guard-writes.ts +15 -36
- package/base/hooks/session-start.ts +1 -1
- package/base/make/vulcan.mk +8 -5
- package/base/packs/venizia.md +16 -0
- package/base/references/delegation-brief.md +3 -5
- package/base/references/testing.md +1 -9
- package/base/rules.md +33 -38
- package/base/skills/build-a-feature/SKILL.md +4 -4
- package/base/skills/docs-update/SKILL.md +19 -8
- package/base/skills/fix-a-bug/SKILL.md +4 -2
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/research/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +2 -2
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +3 -3
- package/base/skills/visualize-work/references/spec.md +6 -3
- package/base/templates/AGENTS.md +9 -7
- package/base/templates/board.html +10 -110
- package/package.json +3 -3
- package/src/agents/atlas-block.ts +8 -31
- package/src/agents/codex-hooks.ts +1 -1
- package/src/agents/generated-block.ts +52 -0
- package/src/agents/hooks-json.ts +22 -3
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +15 -2
- package/src/agents/resolve.ts +1 -0
- package/src/agents/rules-block.ts +92 -0
- package/src/board/command.ts +92 -30
- package/src/board/common/constants.ts +26 -0
- package/src/board/common/types.ts +10 -3
- package/src/board/fold.ts +1 -1
- package/src/board/github.ts +1 -2
- package/src/board/gitlab.ts +436 -0
- package/src/board/index.ts +1 -0
- package/src/board/logo.ts +49 -0
- package/src/board/open-file.ts +110 -0
- package/src/board/page.ts +57 -5
- package/src/board/schema.ts +4 -1
- package/src/board/server.ts +87 -3
- package/src/board/settings.ts +21 -24
- package/src/commands/changelog.command.ts +40 -0
- package/src/commands/clean.command.ts +6 -1
- package/src/commands/help.command.ts +2 -63
- package/src/commands/index.ts +6 -1
- package/src/commands/migrate.command.ts +71 -0
- package/src/commands/profile.command.ts +1 -1
- package/src/commands/runners.command.ts +43 -0
- package/src/commands/sync.command.ts +8 -4
- package/src/commands/table.ts +362 -0
- package/src/commit/check.ts +1 -0
- package/src/commit/common/constants.ts +4 -0
- package/src/commit/hook.ts +112 -8
- package/src/common/constants.ts +11 -9
- package/src/common/env-variables.ts +41 -0
- package/src/common/index.ts +1 -0
- package/src/common/layout-folder.ts +3 -4
- package/src/common/record.ts +5 -0
- package/src/config/common/constants.ts +28 -22
- package/src/config/loader.ts +22 -0
- package/src/config/schema.ts +330 -146
- package/src/create/add-app.ts +7 -2
- package/src/create/add-lib.ts +2 -4
- package/src/create/common/constants.ts +5 -3
- package/src/create/preset.ts +1 -0
- package/src/create/scratch.ts +2 -1
- package/src/doctor/checks.ts +277 -448
- package/src/doctor/common/constants.ts +27 -19
- package/src/doctor/private-values.ts +4 -1
- package/src/doctor/runner.ts +5 -12
- package/src/doctor/schema.ts +4 -0
- package/src/events/common/actor-names.ts +12 -0
- package/src/events/common/constants.ts +65 -38
- package/src/events/common/index.ts +1 -0
- package/src/events/hook.ts +5 -56
- package/src/events/text.ts +41 -6
- package/src/hooks/command-view.ts +80 -19
- package/src/hooks/common/constants.ts +26 -17
- package/src/hooks/common/types.ts +13 -24
- package/src/hooks/decision.ts +30 -12
- package/src/hooks/git-queries.ts +113 -0
- package/src/hooks/guard-git.ts +76 -24
- package/src/hooks/guard-outside.ts +334 -311
- package/src/hooks/guard-runner.ts +206 -0
- package/src/hooks/guard-writes.ts +87 -184
- package/src/hooks/hook-input.ts +57 -0
- package/src/hooks/index.ts +3 -6
- package/src/hooks/link-makers.ts +315 -0
- package/src/hooks/package-runners.ts +268 -0
- package/src/hooks/project-guards.ts +81 -44
- package/src/hooks/project-tmp.ts +39 -4
- package/src/hooks/runner-scan.ts +257 -0
- package/src/hooks/script-runners.ts +400 -0
- package/src/hooks/session-digest.ts +27 -117
- package/src/hooks/shell-folders.ts +760 -0
- package/src/hooks/shell-writes.ts +646 -0
- package/src/hooks/shell.ts +1421 -194
- package/src/hooks/subagent-card.ts +2 -2
- package/src/hooks/write-commands.ts +898 -0
- package/src/init/scaffold.ts +2 -3
- package/src/local/auto-clean.ts +2 -1
- package/src/local/browser-socket.ts +33 -0
- package/src/local/clean.ts +37 -6
- package/src/local/constants.ts +15 -1
- package/src/local/index.ts +1 -0
- package/src/local/scan.ts +41 -10
- package/src/manifest/render.ts +84 -30
- package/src/owner/constants.ts +4 -5
- package/src/owner/index.ts +0 -2
- package/src/owner/profile.ts +1 -0
- package/src/owner/schema.ts +51 -27
- package/src/owner/survey.ts +0 -3
- package/src/owner/view.ts +0 -9
- package/src/router.ts +8 -132
- package/src/rules/base.ts +12 -7
- package/src/rules/index.ts +1 -0
- package/src/rules/packs.ts +44 -0
- package/src/runners/check.ts +130 -0
- package/src/skills/frontmatter.ts +1 -0
- package/src/sync/agents-block.ts +104 -0
- package/src/sync/base-rules.ts +3 -3
- package/src/sync/claude-launch.ts +12 -12
- package/src/sync/common/constants.ts +0 -2
- package/src/sync/index.ts +1 -1
- package/src/sync/local-choice.ts +32 -3
- package/src/sync/planner.ts +2 -15
- package/src/sync/settings.ts +0 -17
- package/src/theme/index.ts +1 -0
- package/src/theme/tokens.ts +410 -0
- package/src/ui/prompt.ts +1 -0
- package/src/visualize/architecture.ts +504 -0
- package/src/visualize/assets.ts +41 -30
- package/src/visualize/compare-render.ts +22 -24
- package/src/visualize/constants.ts +27 -0
- package/src/visualize/diagrams.ts +13 -121
- package/src/visualize/kinds-render.ts +2 -2
- package/src/visualize/kinds-schema.ts +49 -0
- package/src/visualize/labels-vi.ts +25 -0
- package/src/visualize/labels.ts +2 -0
- package/src/visualize/layout.ts +415 -66
- package/src/visualize/page.ts +82 -15
- package/src/visualize/render.ts +2 -1
- package/src/visualize/schema.ts +29 -1
- package/src/visualize/sections.ts +78 -9
- package/src/visualize/theme.ts +49 -18
- package/src/wiki/anchors.ts +1 -0
- package/src/wiki/command.ts +10 -3
- package/src/wiki/source-links.ts +57 -18
- package/base/ci-global.json +0 -13
- package/base/claude/remote-hosts.json +0 -15
- package/base/hooks/guard-manifest.ts +0 -27
- package/base/hooks/guard-package.ts +0 -30
- package/base/hooks/guard-remote-hosts.ts +0 -70
- package/base/hooks/guard-scripting.ts +0 -32
- package/base/hooks/post-tool.ts +0 -37
- package/base/hooks/prompt-submit.ts +0 -54
- package/base/hooks/stop.ts +0 -40
- package/base/skills/build-a-feature/evals/evals.json +0 -29
- package/base/skills/docs-update/evals/evals.json +0 -23
- package/base/skills/docs-writing/evals/evals.json +0 -17
- package/base/skills/fix-a-bug/evals/evals.json +0 -17
- package/base/skills/knowledge-sync/SKILL.md +0 -81
- package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
- package/base/skills/knowledge-sync/references/workflow.md +0 -44
- package/base/skills/plan-a-change/evals/evals.json +0 -47
- package/base/skills/report-back/evals/evals.json +0 -23
- package/base/skills/research/evals/evals.json +0 -17
- package/base/skills/retro/evals/evals.json +0 -17
- package/base/skills/review-a-change/evals/evals.json +0 -17
- package/base/skills/ship/evals/evals.json +0 -23
- package/base/skills/visualize-work/evals/evals.json +0 -17
- package/base/templates/ci/github-actions.yml +0 -75
- package/base/templates/ci/gitlab-ci.yml +0 -52
- package/base/templates/trusted-hosts.local.example +0 -11
- package/src/ci/affected.ts +0 -176
- package/src/ci/command.ts +0 -166
- package/src/ci/common/constants.ts +0 -76
- package/src/ci/common/index.ts +0 -2
- package/src/ci/common/types.ts +0 -37
- package/src/ci/git.ts +0 -72
- package/src/ci/global.ts +0 -48
- package/src/ci/graph.ts +0 -43
- package/src/ci/index.ts +0 -7
- package/src/ci/workspace.ts +0 -119
- package/src/commands/ci.command.ts +0 -4
- package/src/hooks/guard-manifest.ts +0 -109
- package/src/hooks/guard-package.ts +0 -226
- package/src/hooks/guard-scripting.ts +0 -36
- package/src/hooks/host-pattern.ts +0 -17
- package/src/hooks/owner-reply.ts +0 -162
- package/src/hooks/post-tool.ts +0 -138
- package/src/hooks/remote-hosts.ts +0 -1013
- package/src/hooks/trusted-scripts.ts +0 -212
- package/src/owner/shape.ts +0 -496
- package/src/owner/violations.ts +0 -332
- package/src/signals/claims.ts +0 -73
- package/src/signals/classify.ts +0 -137
- package/src/signals/constants.ts +0 -88
- package/src/signals/index.ts +0 -5
- package/src/signals/loop.ts +0 -48
- package/src/signals/state.ts +0 -271
- package/src/sync/atlas-block.ts +0 -56
package/src/doctor/checks.ts
CHANGED
|
@@ -4,41 +4,39 @@ import {
|
|
|
4
4
|
accessSync,
|
|
5
5
|
constants,
|
|
6
6
|
existsSync,
|
|
7
|
-
lstatSync,
|
|
8
7
|
readdirSync,
|
|
9
8
|
readFileSync,
|
|
10
9
|
realpathSync,
|
|
11
10
|
statSync,
|
|
12
11
|
} from 'node:fs';
|
|
13
|
-
import {
|
|
12
|
+
import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
|
|
14
13
|
import { BASE_DIRECTORY, ProjectLayout, RecordValue } from '../common/index.ts';
|
|
15
14
|
import { LayoutKeys, LayoutFolder } from '../common/layout-folder.ts';
|
|
16
15
|
import { MCP_SERVER_HINT, ProjectScaffold } from '../init/index.ts';
|
|
17
16
|
import { ProjectPackages } from '../config/index.ts';
|
|
18
17
|
import { ProjectKey } from '../events/project-key.ts';
|
|
19
18
|
import type { TResolvedConfig } from '../config/index.ts';
|
|
20
|
-
import { BaseRules, RuleParser, RuleSlots } from '../rules/index.ts';
|
|
19
|
+
import { BaseRules, RulePacks, RuleParser, RuleSlots } from '../rules/index.ts';
|
|
21
20
|
import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
|
|
22
21
|
import { AgentScopes, AgentSelection, AgentTable, LocalChoice } from '../agents/index.ts';
|
|
23
22
|
import { CommitHook, CommitHookStates } from '../commit/index.ts';
|
|
24
23
|
import { EventConstants } from '../events/common/index.ts';
|
|
25
24
|
import { EventRetention } from '../events/retention.ts';
|
|
26
25
|
import { EventSettings } from '../events/settings.ts';
|
|
27
|
-
import { AgentFiles, AtlasBlockPlan, LocalPlan, SyncPlanner, SyncStatuses } from '../sync/index.ts';
|
|
28
|
-
import { LocalConstants, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
|
|
29
|
-
import { CLAUDE_LAUNCH_FILE, ClaudeLaunch } from '../sync/claude-launch.ts';
|
|
30
|
-
import { PrivateValues } from './private-values.ts';
|
|
31
26
|
import {
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
} from '../
|
|
39
|
-
import {
|
|
40
|
-
import {
|
|
41
|
-
import {
|
|
27
|
+
AgentFiles,
|
|
28
|
+
AgentsBlockPlan,
|
|
29
|
+
LocalPlan,
|
|
30
|
+
SyncPlanner,
|
|
31
|
+
SyncStatuses,
|
|
32
|
+
} from '../sync/index.ts';
|
|
33
|
+
import { BrowserSocket, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
|
|
34
|
+
import { CLAUDE_LAUNCH_FILE } from '../sync/claude-launch.ts';
|
|
35
|
+
import { PrivateValues } from './private-values.ts';
|
|
36
|
+
import { ReplySwitch, OwnerConstants, OwnerReplySwitch, OwnerProfile } from '../owner/index.ts';
|
|
37
|
+
import { SkillCatalog, VersionFolders } from '@venizia/vulcan-atlas';
|
|
38
|
+
import { HookConstants, ProjectTmp } from '../hooks/index.ts';
|
|
39
|
+
import { DoctorChecks, DoctorConstants, PrivateValueKinds } from './common/index.ts';
|
|
42
40
|
import type { IViolation, TDoctorCheck } from './common/index.ts';
|
|
43
41
|
import { Makefile } from './makefile.ts';
|
|
44
42
|
|
|
@@ -132,7 +130,9 @@ const readScriptNames = (opts: { file: string }): string[] | undefined => {
|
|
|
132
130
|
}
|
|
133
131
|
};
|
|
134
132
|
|
|
135
|
-
const CANONICAL_ATLAS_ARGS = ['
|
|
133
|
+
const CANONICAL_ATLAS_ARGS = ['node_modules/.bin/vulcan', 'x', 'atlas', 'mcp', '--root', '.'];
|
|
134
|
+
/** What sync wrote before V-S-08: it can run a copy bunx cached, so it is stale and not merely different. */
|
|
135
|
+
const LEGACY_ATLAS_ARGS = ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'];
|
|
136
136
|
|
|
137
137
|
const MCP_FILE = '.mcp.json';
|
|
138
138
|
|
|
@@ -166,37 +166,6 @@ const isUntrackedAndVisible = (opts: { root: string; path: string }): boolean =>
|
|
|
166
166
|
const mcpWarning = (opts: { file: string; message: string }): IViolation =>
|
|
167
167
|
createViolation({ check: DoctorChecks.MCP, file: opts.file, message: opts.message });
|
|
168
168
|
|
|
169
|
-
const DOCKERFILE = '.configs/builders/Dockerfile';
|
|
170
|
-
|
|
171
|
-
const SECRET_LINES = ['**/.env', '**/.env.*', '!**/.env.example'];
|
|
172
|
-
|
|
173
|
-
const ADD_SECRET_LINES = `add ${SECRET_LINES[0]}, ${SECRET_LINES[1]} and ${SECRET_LINES[2]} (in that order) to the root .dockerignore`;
|
|
174
|
-
|
|
175
|
-
/** Whether a `.dockerignore` pattern, as Docker reads it, names the file `opts.file` at any depth. */
|
|
176
|
-
const patternNames = (opts: { pattern: string; file: string }): boolean => {
|
|
177
|
-
const bare = opts.pattern.replace(/^\*\*\//, '').replace(/^\//, '');
|
|
178
|
-
|
|
179
|
-
return (
|
|
180
|
-
bare === opts.file ||
|
|
181
|
-
(bare.endsWith('*') && opts.file.startsWith(bare.slice(0, -1)) && bare.startsWith('.env'))
|
|
182
|
-
);
|
|
183
|
-
};
|
|
184
|
-
|
|
185
|
-
/** Whether the last pattern that names `opts.file` excludes it: a later `!` line brings it back. */
|
|
186
|
-
const excludes = (opts: { lines: string[]; file: string }): boolean => {
|
|
187
|
-
let excluded = false;
|
|
188
|
-
|
|
189
|
-
for (const line of opts.lines) {
|
|
190
|
-
const negated = line.startsWith('!');
|
|
191
|
-
|
|
192
|
-
if (patternNames({ pattern: negated ? line.slice(1) : line, file: opts.file })) {
|
|
193
|
-
excluded = !negated;
|
|
194
|
-
}
|
|
195
|
-
}
|
|
196
|
-
|
|
197
|
-
return excluded;
|
|
198
|
-
};
|
|
199
|
-
|
|
200
169
|
const FMT_SECTION_ADVICE =
|
|
201
170
|
'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';
|
|
202
171
|
|
|
@@ -219,23 +188,6 @@ const formatOwners = (opts: ICheckContext): string[] => [
|
|
|
219
188
|
]),
|
|
220
189
|
];
|
|
221
190
|
|
|
222
|
-
/** 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. */
|
|
223
|
-
const STALE_TRUST_STATES = new Set<string>([
|
|
224
|
-
TrustStates.MISSING,
|
|
225
|
-
TrustStates.UNTRACKED,
|
|
226
|
-
TrustStates.UNCOMMITTED,
|
|
227
|
-
TrustStates.SYMLINK,
|
|
228
|
-
TrustStates.UNKNOWN,
|
|
229
|
-
]);
|
|
230
|
-
|
|
231
|
-
/** The path of a `guard.writes.trustedScripts` entry, and the subcommands when it is the object form. */
|
|
232
|
-
const trustedScriptOf = (opts: {
|
|
233
|
-
entry: TResolvedConfig['guard']['writes']['trustedScripts'][number];
|
|
234
|
-
}): { script: string; readOnly: string[] | undefined } =>
|
|
235
|
-
typeof opts.entry === 'string'
|
|
236
|
-
? { script: opts.entry, readOnly: undefined }
|
|
237
|
-
: { script: opts.entry.script, readOnly: opts.entry.readOnly };
|
|
238
|
-
|
|
239
191
|
export class ProjectContract {
|
|
240
192
|
static checkLayout(opts: ICheckContext): IViolation[] {
|
|
241
193
|
return ['AGENTS.md', '.agents/rules.md', opts.config.knowledge.bundle]
|
|
@@ -254,19 +206,24 @@ export class ProjectContract {
|
|
|
254
206
|
* rules points at a base rule - one the base does not carry dangles.
|
|
255
207
|
*/
|
|
256
208
|
static checkRuleIds(opts: ICheckContext): IViolation[] {
|
|
257
|
-
const base = BaseRules.read();
|
|
209
|
+
const base = BaseRules.read({ packs: opts.config.packs });
|
|
258
210
|
|
|
259
211
|
return RuleParser.parseBaseReferences({
|
|
260
212
|
markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
|
|
261
213
|
})
|
|
262
214
|
.filter((id) => base[id] === undefined)
|
|
263
|
-
.map((id) =>
|
|
264
|
-
|
|
215
|
+
.map((id) => {
|
|
216
|
+
const pack = RulePacks.holderOf({ id });
|
|
217
|
+
|
|
218
|
+
return createViolation({
|
|
265
219
|
check: DoctorChecks.RULE_IDS,
|
|
266
220
|
file: '.agents/rules.md',
|
|
267
|
-
message:
|
|
268
|
-
|
|
269
|
-
|
|
221
|
+
message:
|
|
222
|
+
pack === undefined
|
|
223
|
+
? `${id} is not a base rule - give the extension a bare ID`
|
|
224
|
+
: `${id} is in the ${pack} pack - add '${pack}' to packs in the config`,
|
|
225
|
+
});
|
|
226
|
+
});
|
|
270
227
|
}
|
|
271
228
|
|
|
272
229
|
static checkRuleSlots(opts: ICheckContext): IViolation[] {
|
|
@@ -367,18 +324,6 @@ export class ProjectContract {
|
|
|
367
324
|
return violations;
|
|
368
325
|
}
|
|
369
326
|
|
|
370
|
-
static checkHooks(opts: ICheckContext): IViolation[] {
|
|
371
|
-
return opts.config.hooks
|
|
372
|
-
.filter((hook) => hook.command.includes(DoctorConstants.SHIPPED_HOOKS_PATH))
|
|
373
|
-
.map((hook) =>
|
|
374
|
-
createViolation({
|
|
375
|
-
check: DoctorChecks.HOOKS,
|
|
376
|
-
file: opts.configFile,
|
|
377
|
-
message: `the ${hook.event} hook runs a shipped hook - sync registers those, never the project`,
|
|
378
|
-
}),
|
|
379
|
-
);
|
|
380
|
-
}
|
|
381
|
-
|
|
382
327
|
static checkAdapters(opts: ICheckContext): IViolation[] {
|
|
383
328
|
const pending = SyncPlanner.plan({
|
|
384
329
|
root: opts.root,
|
|
@@ -442,6 +387,59 @@ export class ProjectContract {
|
|
|
442
387
|
];
|
|
443
388
|
}
|
|
444
389
|
|
|
390
|
+
/**
|
|
391
|
+
* The changelog folders `changelogs/<X.Y.Z>/` are read by the atlas of VULCAN `CHANGELOG_FOLDERS_FROM` and later;
|
|
392
|
+
* an older one ignores them and answers with no changelog at all. A project that holds a folder with a `log.md`
|
|
393
|
+
* and has an older vulcan installed is told which to install. The version is compared whole: a prerelease of
|
|
394
|
+
* the line before the one that carries the reader still ignores the folders.
|
|
395
|
+
*/
|
|
396
|
+
static checkChangelogFolders(opts: ICheckContext): IViolation[] {
|
|
397
|
+
const { changelogs } = opts.config.knowledge;
|
|
398
|
+
|
|
399
|
+
if (changelogs === undefined) {
|
|
400
|
+
return [];
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
const directory = resolve(opts.root, changelogs);
|
|
404
|
+
const hasFolder =
|
|
405
|
+
existsSync(directory) &&
|
|
406
|
+
readdirSync(directory).some(
|
|
407
|
+
(name) => VersionFolders.isName({ name }) && existsSync(join(directory, name, 'log.md')),
|
|
408
|
+
);
|
|
409
|
+
const installedAt = join(opts.root, 'node_modules', '@venizia', 'vulcan');
|
|
410
|
+
const installed = readJsonObject({ file: join(installedAt, 'package.json') })?.['version'];
|
|
411
|
+
|
|
412
|
+
if (!hasFolder || typeof installed !== 'string') {
|
|
413
|
+
return [];
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
// VULCAN's own repository links its workspace package there: that is the source of this project, not an older release.
|
|
417
|
+
try {
|
|
418
|
+
const real = realpathSync(installedAt);
|
|
419
|
+
const fromRoot = relative(realpathSync(opts.root), real);
|
|
420
|
+
|
|
421
|
+
if (
|
|
422
|
+
!isAbsolute(fromRoot) &&
|
|
423
|
+
!fromRoot.startsWith('..') &&
|
|
424
|
+
!fromRoot.split(sep).includes('node_modules')
|
|
425
|
+
) {
|
|
426
|
+
return [];
|
|
427
|
+
}
|
|
428
|
+
} catch {
|
|
429
|
+
// A link that does not resolve is judged by the version it names.
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
return Bun.semver.order(installed, DoctorConstants.CHANGELOG_FOLDERS_FROM) >= 0
|
|
433
|
+
? []
|
|
434
|
+
: [
|
|
435
|
+
createViolation({
|
|
436
|
+
check: DoctorChecks.CHANGELOG_FOLDERS,
|
|
437
|
+
file: changelogs,
|
|
438
|
+
message: `holds version folders, but the installed @venizia/vulcan is ${installed}: its atlas ignores them. Install ${DoctorConstants.CHANGELOG_FOLDERS_FROM} or later`,
|
|
439
|
+
}),
|
|
440
|
+
];
|
|
441
|
+
}
|
|
442
|
+
|
|
445
443
|
/**
|
|
446
444
|
* D9: the shared coding style - every lint config builds on it, and the package whose `.configs/`
|
|
447
445
|
* holds the config declares it, or the root does. A project with no lint config declares it at the
|
|
@@ -619,58 +617,6 @@ export class ProjectContract {
|
|
|
619
617
|
return violations;
|
|
620
618
|
}
|
|
621
619
|
|
|
622
|
-
/**
|
|
623
|
-
* Info only, never a failure: an app that lacks a standard script or carries a legacy one gets one
|
|
624
|
-
* line naming them. Apps are the live packages inside the backend and frontend folders.
|
|
625
|
-
*/
|
|
626
|
-
static checkAppScripts(opts: ICheckContext): IViolation[] {
|
|
627
|
-
const layout = opts.config.layout;
|
|
628
|
-
|
|
629
|
-
if (layout === undefined) {
|
|
630
|
-
return [];
|
|
631
|
-
}
|
|
632
|
-
|
|
633
|
-
const appFolders = [
|
|
634
|
-
...LayoutFolder.layoutFoldersOf({ value: layout.backend }),
|
|
635
|
-
...LayoutFolder.layoutFoldersOf({ value: layout.frontend }),
|
|
636
|
-
];
|
|
637
|
-
const notes: IViolation[] = [];
|
|
638
|
-
|
|
639
|
-
for (const entry of ProjectPackages.resolve({ config: opts.config }).filter(
|
|
640
|
-
(item) => !item.retired,
|
|
641
|
-
)) {
|
|
642
|
-
if (!appFolders.some((folder) => entry.path.startsWith(`${folder}/`))) {
|
|
643
|
-
continue;
|
|
644
|
-
}
|
|
645
|
-
|
|
646
|
-
const file = `${entry.path}/package.json`;
|
|
647
|
-
const names = readScriptNames({ file: join(opts.root, file) });
|
|
648
|
-
|
|
649
|
-
if (names === undefined) {
|
|
650
|
-
continue;
|
|
651
|
-
}
|
|
652
|
-
|
|
653
|
-
const missing = AppScripts.STANDARD.filter((name) => !names.includes(name));
|
|
654
|
-
const legacy = AppScripts.LEGACY.filter((name) => names.includes(name));
|
|
655
|
-
const parts = [
|
|
656
|
-
...(missing.length === 0 ? [] : [`missing ${missing.join(', ')}`]),
|
|
657
|
-
...(legacy.length === 0 ? [] : [`legacy ${legacy.join(', ')} (use the standard names)`]),
|
|
658
|
-
];
|
|
659
|
-
|
|
660
|
-
if (parts.length > 0) {
|
|
661
|
-
notes.push(
|
|
662
|
-
createViolation({
|
|
663
|
-
check: DoctorChecks.SCRIPTS,
|
|
664
|
-
file,
|
|
665
|
-
message: `app ${entry.dir}: ${parts.join('; ')}`,
|
|
666
|
-
}),
|
|
667
|
-
);
|
|
668
|
-
}
|
|
669
|
-
}
|
|
670
|
-
|
|
671
|
-
return notes;
|
|
672
|
-
}
|
|
673
|
-
|
|
674
620
|
/** The developer's stored agents must parse and name known agents; a broken file would otherwise hide as a default. */
|
|
675
621
|
static checkAgents(opts: ICheckContext): IViolation[] {
|
|
676
622
|
const stored = LocalChoice.read({ root: opts.root });
|
|
@@ -717,6 +663,16 @@ export class ProjectContract {
|
|
|
717
663
|
];
|
|
718
664
|
}
|
|
719
665
|
|
|
666
|
+
case CommitHookStates.LEGACY: {
|
|
667
|
+
return [
|
|
668
|
+
createViolation({
|
|
669
|
+
check: DoctorChecks.COMMIT_HOOK,
|
|
670
|
+
file,
|
|
671
|
+
message: `the commit-msg hook is out of date: ${status.note ?? fix}`,
|
|
672
|
+
}),
|
|
673
|
+
];
|
|
674
|
+
}
|
|
675
|
+
|
|
720
676
|
case CommitHookStates.UNWIRED: {
|
|
721
677
|
return [
|
|
722
678
|
createViolation({
|
|
@@ -727,6 +683,16 @@ export class ProjectContract {
|
|
|
727
683
|
];
|
|
728
684
|
}
|
|
729
685
|
|
|
686
|
+
case CommitHookStates.OTHER_PROJECT: {
|
|
687
|
+
return [
|
|
688
|
+
createViolation({
|
|
689
|
+
check: DoctorChecks.COMMIT_HOOK,
|
|
690
|
+
file,
|
|
691
|
+
message: `this project's commit check is not installed: ${status.note ?? fix}`,
|
|
692
|
+
}),
|
|
693
|
+
];
|
|
694
|
+
}
|
|
695
|
+
|
|
730
696
|
default: {
|
|
731
697
|
return [];
|
|
732
698
|
}
|
|
@@ -865,6 +831,17 @@ export class ProjectContract {
|
|
|
865
831
|
message: `no server named atlas (found: ${Object.keys(servers).join(', ') || 'none'}): a differently named server is not enabled automatically - use ${MCP_SERVER_HINT}`,
|
|
866
832
|
}),
|
|
867
833
|
);
|
|
834
|
+
} else if (
|
|
835
|
+
Array.isArray(args) &&
|
|
836
|
+
args.length === LEGACY_ATLAS_ARGS.length &&
|
|
837
|
+
args.every((arg, index) => arg === LEGACY_ATLAS_ARGS[index])
|
|
838
|
+
) {
|
|
839
|
+
warnings.push(
|
|
840
|
+
mcpWarning({
|
|
841
|
+
file: MCP_FILE,
|
|
842
|
+
message: `the atlas entry is out of date: it starts the server through bunx, which can run a copy it cached when the bin is not linked there - run '${ProjectLayout.VULCAN_COMMAND} sync' to rewrite it as ${MCP_SERVER_HINT}`,
|
|
843
|
+
}),
|
|
844
|
+
);
|
|
868
845
|
} else if (!isCanonical) {
|
|
869
846
|
const shown = JSON.stringify(entry.value)
|
|
870
847
|
.replace('{"command":', '{ "command": ')
|
|
@@ -901,52 +878,6 @@ export class ProjectContract {
|
|
|
901
878
|
return warnings;
|
|
902
879
|
}
|
|
903
880
|
|
|
904
|
-
/**
|
|
905
|
-
* A Dockerfile is built from the project root. Without a root `.dockerignore` the context carries
|
|
906
|
-
* node_modules, dist, .git and every `.env` (secrets that would land in an image layer a CI cache
|
|
907
|
-
* can keep); with one that does not exclude `.env` and `.env.*` the secrets are still copied.
|
|
908
|
-
* A warning, not a violation: the exit code is unchanged, so a project made before this check
|
|
909
|
-
* does not start failing.
|
|
910
|
-
*/
|
|
911
|
-
static checkDockerignore(opts: ICheckContext): IViolation[] {
|
|
912
|
-
const file = join(opts.root, '.dockerignore');
|
|
913
|
-
const lines = existsSync(file)
|
|
914
|
-
? readText({ file })
|
|
915
|
-
.split('\n')
|
|
916
|
-
.map((line) => line.trim())
|
|
917
|
-
.filter((line) => line !== '' && !line.startsWith('#'))
|
|
918
|
-
: undefined;
|
|
919
|
-
|
|
920
|
-
if (
|
|
921
|
-
lines !== undefined &&
|
|
922
|
-
excludes({ lines, file: '.env' }) &&
|
|
923
|
-
excludes({ lines, file: '.env.production' })
|
|
924
|
-
) {
|
|
925
|
-
return [];
|
|
926
|
-
}
|
|
927
|
-
|
|
928
|
-
const apps = ProjectPackages.resolve({ config: opts.config })
|
|
929
|
-
.filter((entry) => !entry.retired && existsSync(join(opts.root, entry.path, DOCKERFILE)))
|
|
930
|
-
.map((entry) => entry.dir);
|
|
931
|
-
|
|
932
|
-
if (apps.length === 0) {
|
|
933
|
-
return [];
|
|
934
|
-
}
|
|
935
|
-
|
|
936
|
-
const subject = apps.length === 1 ? `app ${apps[0]} has` : `apps ${apps.join(', ')} have`;
|
|
937
|
-
|
|
938
|
-
return [
|
|
939
|
-
createViolation({
|
|
940
|
-
check: DoctorChecks.DOCKERIGNORE,
|
|
941
|
-
file: '.dockerignore',
|
|
942
|
-
message:
|
|
943
|
-
lines === undefined
|
|
944
|
-
? `${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}`
|
|
945
|
-
: `${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}`,
|
|
946
|
-
}),
|
|
947
|
-
];
|
|
948
|
-
}
|
|
949
|
-
|
|
950
881
|
/**
|
|
951
882
|
* `bun fmt` reads the `[fmt]` section of `bunfig.toml`; without it, it formats with Bun's defaults
|
|
952
883
|
* (width 80, double quotes) and rewrites a tree the shared style formatted, and without
|
|
@@ -1048,9 +979,9 @@ export class ProjectContract {
|
|
|
1048
979
|
return warnings;
|
|
1049
980
|
}
|
|
1050
981
|
|
|
1051
|
-
/** Info only: the Atlas block of AGENTS.md is missing or no longer matches the config. */
|
|
982
|
+
/** Info only: the Atlas or rules block of AGENTS.md is missing or no longer matches the config. */
|
|
1052
983
|
static checkAtlasBlock(opts: ICheckContext): IViolation[] {
|
|
1053
|
-
const merged =
|
|
984
|
+
const merged = AgentsBlockPlan.merged({ root: opts.root, config: opts.config });
|
|
1054
985
|
|
|
1055
986
|
return merged === undefined || !merged.changed
|
|
1056
987
|
? []
|
|
@@ -1058,7 +989,7 @@ export class ProjectContract {
|
|
|
1058
989
|
createViolation({
|
|
1059
990
|
check: DoctorChecks.AGENTS,
|
|
1060
991
|
file: 'AGENTS.md',
|
|
1061
|
-
message: `the Atlas block is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
|
|
992
|
+
message: `the Atlas or rules block of AGENTS.md is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
|
|
1062
993
|
}),
|
|
1063
994
|
];
|
|
1064
995
|
}
|
|
@@ -1078,54 +1009,16 @@ export class ProjectContract {
|
|
|
1078
1009
|
|
|
1079
1010
|
/** `.agents/local/` exists with its subdirectories and is gitignored: `sync` does both, so an upgraded project that has not synced yet is told here. */
|
|
1080
1011
|
static checkLocalWorkspace(opts: ICheckContext): IViolation[] {
|
|
1081
|
-
return LocalPlan.planWorkspace({
|
|
1012
|
+
return LocalPlan.planWorkspace({
|
|
1013
|
+
root: opts.root,
|
|
1014
|
+
tmp: ProjectTmp.configuredOf({ tmp: opts.config.local.tmp }),
|
|
1015
|
+
})
|
|
1082
1016
|
.filter((action) => action.status !== SyncStatuses.UNCHANGED)
|
|
1083
1017
|
.map((action) =>
|
|
1084
1018
|
createViolation({
|
|
1085
1019
|
check: DoctorChecks.LOCAL,
|
|
1086
1020
|
file: relative(opts.root, action.path) || '.',
|
|
1087
|
-
message: `${action.note ?? 'out of date'} - run 'bun
|
|
1088
|
-
}),
|
|
1089
|
-
);
|
|
1090
|
-
}
|
|
1091
|
-
|
|
1092
|
-
/**
|
|
1093
|
-
* A worktree of this repository that lives outside it: the repository's own `git worktree list` names it
|
|
1094
|
-
* (git metadata is inside the project), and the exact command moves it in. Nothing is moved or removed.
|
|
1095
|
-
*/
|
|
1096
|
-
static checkOutsideWorktrees(opts: ICheckContext): IViolation[] {
|
|
1097
|
-
const listed = spawnSync('git', ['worktree', 'list', '--porcelain'], {
|
|
1098
|
-
cwd: opts.root,
|
|
1099
|
-
encoding: 'utf8',
|
|
1100
|
-
timeout: 5000,
|
|
1101
|
-
});
|
|
1102
|
-
|
|
1103
|
-
if (listed.status !== 0) {
|
|
1104
|
-
return [];
|
|
1105
|
-
}
|
|
1106
|
-
|
|
1107
|
-
const [boundary, ...linked] = listed.stdout
|
|
1108
|
-
.split('\n')
|
|
1109
|
-
.filter((line) => line.startsWith('worktree '))
|
|
1110
|
-
.map((line) => line.slice('worktree '.length));
|
|
1111
|
-
|
|
1112
|
-
if (boundary === undefined) {
|
|
1113
|
-
return [];
|
|
1114
|
-
}
|
|
1115
|
-
|
|
1116
|
-
const inside = (path: string): boolean => {
|
|
1117
|
-
const real = existsSync(path) ? realpathSync(path) : path;
|
|
1118
|
-
|
|
1119
|
-
return real === boundary || real.startsWith(`${boundary}${sep}`);
|
|
1120
|
-
};
|
|
1121
|
-
|
|
1122
|
-
return linked
|
|
1123
|
-
.filter((path) => !inside(path))
|
|
1124
|
-
.map((path) =>
|
|
1125
|
-
createViolation({
|
|
1126
|
-
check: DoctorChecks.LOCAL,
|
|
1127
|
-
file: path,
|
|
1128
|
-
message: `a git worktree outside the project - move it in: git worktree move '${path}' '${join(boundary, ProjectLayout.LOCAL_DIRECTORY, 'worktrees', basename(path))}'`,
|
|
1021
|
+
message: `${action.note ?? 'out of date'} - run 'bun node_modules/.bin/vulcan sync'`,
|
|
1129
1022
|
}),
|
|
1130
1023
|
);
|
|
1131
1024
|
}
|
|
@@ -1177,105 +1070,162 @@ export class ProjectContract {
|
|
|
1177
1070
|
}
|
|
1178
1071
|
|
|
1179
1072
|
/**
|
|
1180
|
-
*
|
|
1181
|
-
*
|
|
1073
|
+
* What is directly under `.agents/local/` and is not a folder of the layout, a file VULCAN writes, or a browser's
|
|
1074
|
+
* scratch folder, in one warning: how many, how big, and their names. Nothing removes them.
|
|
1182
1075
|
*/
|
|
1183
1076
|
static checkUnknownLocal(opts: ICheckContext): IViolation[] {
|
|
1184
|
-
|
|
1185
|
-
createViolation({
|
|
1186
|
-
check: DoctorChecks.LOCAL,
|
|
1187
|
-
file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.name}`,
|
|
1188
|
-
message: `not an entry VULCAN knows (${LocalFormat.formatBytes({ bytes: entry.bytes })}): put scratch in tmp/ and what you want to keep in reports/, what one agent keeps for itself in agents/<name>/; a script the team relies on belongs in the tracked tree (scripts/), where it gets review and history; nothing removes it`,
|
|
1189
|
-
}),
|
|
1190
|
-
);
|
|
1191
|
-
}
|
|
1077
|
+
const unknown = LocalScan.unknown({ root: opts.root });
|
|
1192
1078
|
|
|
1193
|
-
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
|
-
|
|
1203
|
-
|
|
1204
|
-
|
|
1205
|
-
|
|
1206
|
-
|
|
1207
|
-
check: DoctorChecks.LOCAL,
|
|
1208
|
-
file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.where}`,
|
|
1209
|
-
message: `${entry.state === LocalStates.STALE && entry.note === '' ? `left ${LocalFormat.formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${LocalFormat.formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
|
|
1210
|
-
}),
|
|
1211
|
-
);
|
|
1079
|
+
return unknown.length === 0
|
|
1080
|
+
? []
|
|
1081
|
+
: [
|
|
1082
|
+
createViolation({
|
|
1083
|
+
check: DoctorChecks.LOCAL,
|
|
1084
|
+
file: ProjectLayout.LOCAL_DIRECTORY,
|
|
1085
|
+
message: `${unknown.length} ${unknown.length === 1 ? 'entry is' : 'entries are'} not ${unknown.length === 1 ? 'one' : 'ones'} VULCAN knows: ${unknown
|
|
1086
|
+
.slice(0, 10)
|
|
1087
|
+
.map((entry) => `${entry.name} (${LocalFormat.formatBytes({ bytes: entry.bytes })})`)
|
|
1088
|
+
.join(
|
|
1089
|
+
', ',
|
|
1090
|
+
)}${unknown.length > 10 ? `, and ${unknown.length - 10} more` : ''}; put scratch in tmp/ and what you want to keep in reports/, what one agent keeps for itself in agents/<name>/; a script the team relies on belongs in the tracked tree (scripts/), where it gets review and history; nothing removes ${unknown.length === 1 ? 'it' : 'them'}`,
|
|
1091
|
+
}),
|
|
1092
|
+
];
|
|
1212
1093
|
}
|
|
1213
1094
|
|
|
1214
|
-
/**
|
|
1215
|
-
|
|
1216
|
-
|
|
1095
|
+
/**
|
|
1096
|
+
* What an agent left under `.agents/local/` that has outlived its use, in one warning: how many in each scope, how
|
|
1097
|
+
* big, and the command that clears them (which, without `--yes`, lists each one).
|
|
1098
|
+
*/
|
|
1099
|
+
static checkStaleLocal(opts: ICheckContext): IViolation[] {
|
|
1100
|
+
const stale = LocalScan.scan({ root: opts.root }).filter((entry) =>
|
|
1101
|
+
[
|
|
1102
|
+
LocalStates.STALE,
|
|
1103
|
+
LocalStates.MERGED,
|
|
1104
|
+
LocalStates.GONE,
|
|
1105
|
+
LocalStates.ORPHAN,
|
|
1106
|
+
LocalStates.SHIPPED,
|
|
1107
|
+
].includes(entry.state),
|
|
1108
|
+
);
|
|
1217
1109
|
|
|
1218
|
-
if (
|
|
1110
|
+
if (stale.length === 0) {
|
|
1219
1111
|
return [];
|
|
1220
1112
|
}
|
|
1221
1113
|
|
|
1222
|
-
const
|
|
1223
|
-
|
|
1224
|
-
|
|
1114
|
+
const scopes = [...new Set(stale.map((entry) => entry.scope))];
|
|
1115
|
+
const counts = new Map<string, number>();
|
|
1116
|
+
|
|
1117
|
+
for (const entry of stale) {
|
|
1118
|
+
const group = `${entry.state} in ${entry.scope}`;
|
|
1119
|
+
|
|
1120
|
+
counts.set(group, (counts.get(group) ?? 0) + 1);
|
|
1121
|
+
}
|
|
1225
1122
|
|
|
1226
|
-
const
|
|
1227
|
-
|
|
1123
|
+
const groups = [...counts.entries()];
|
|
1124
|
+
const bytes = stale.reduce((total, entry) => total + entry.bytes, 0);
|
|
1228
1125
|
|
|
1229
1126
|
return [
|
|
1230
|
-
...(isFull
|
|
1231
|
-
? [
|
|
1232
|
-
createViolation({
|
|
1233
|
-
check: DoctorChecks.LOCAL,
|
|
1234
|
-
file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
|
|
1235
|
-
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`,
|
|
1236
|
-
}),
|
|
1237
|
-
]
|
|
1238
|
-
: []),
|
|
1239
1127
|
createViolation({
|
|
1240
1128
|
check: DoctorChecks.LOCAL,
|
|
1241
|
-
file:
|
|
1242
|
-
message: `${
|
|
1129
|
+
file: ProjectLayout.LOCAL_DIRECTORY,
|
|
1130
|
+
message: `${stale.length} ${stale.length === 1 ? 'entry has' : 'entries have'} outlived ${stale.length === 1 ? 'its' : 'their'} use (${LocalFormat.formatBytes({ bytes })}): ${groups.map(([group, count]) => `${count} ${group}`).join(', ')}; run: vulcan clean ${scopes.map((scope) => `--${scope}`).join(' ')} --yes (without --yes it lists each one)`,
|
|
1243
1131
|
}),
|
|
1244
1132
|
];
|
|
1245
1133
|
}
|
|
1246
1134
|
|
|
1247
|
-
/** The owner
|
|
1135
|
+
/** The owner cards are off for this shell (`VULCAN_OWNER_REPLY=off`): a session an agent starts sets it, an owner who exported it by mistake sees why the rules carry no shape card; a note, never a failure. */
|
|
1248
1136
|
static checkOwnerReplySwitch(opts: { env: Record<string, string | undefined> }): IViolation[] {
|
|
1249
1137
|
return ReplySwitch.isOwnerOff({ env: opts.env })
|
|
1250
1138
|
? [
|
|
1251
1139
|
createViolation({
|
|
1252
1140
|
check: DoctorChecks.LOCAL,
|
|
1253
1141
|
file: OwnerReplySwitch.ENV,
|
|
1254
|
-
message: `set to ${OwnerReplySwitch.OFF} in this shell: a session started from here
|
|
1142
|
+
message: `set to ${OwnerReplySwitch.OFF} in this shell: a session started from here gets no owner shape card and no profile card in its rules. Unset it for a session whose reader is the owner`,
|
|
1255
1143
|
}),
|
|
1256
1144
|
]
|
|
1257
1145
|
: [];
|
|
1258
1146
|
}
|
|
1259
1147
|
|
|
1260
1148
|
/**
|
|
1261
|
-
*
|
|
1262
|
-
*
|
|
1149
|
+
* What `local.tmp` must hold for `clean` and the hooks to be safe with it, and for a browser to start: it is not a folder
|
|
1150
|
+
* of the `layout` (or inside one) and holds no tracked file, because `clean` removes what is old in it; and its browser
|
|
1151
|
+
* socket path fits, so the key does what it exists for. Each is a failure here, not a surprise later. A project that does
|
|
1152
|
+
* not set the key gets the warning of `checkBrowserSocket`.
|
|
1263
1153
|
*/
|
|
1264
|
-
static
|
|
1265
|
-
|
|
1266
|
-
env: Record<string, string | undefined>;
|
|
1267
|
-
}): IViolation[] {
|
|
1268
|
-
const tmp = ClaudeLaunch.tmpOf(opts);
|
|
1154
|
+
static checkTmpFolder(opts: ICheckContext): IViolation[] {
|
|
1155
|
+
const { tmp } = opts.config.local;
|
|
1269
1156
|
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1157
|
+
if (tmp === undefined) {
|
|
1158
|
+
return [];
|
|
1159
|
+
}
|
|
1160
|
+
|
|
1161
|
+
const folder = ProjectTmp.projectOf({ root: resolve(opts.root), tmp });
|
|
1162
|
+
const layoutFolders = Object.values(opts.config.layout ?? {}).flatMap((value) =>
|
|
1163
|
+
LayoutFolder.layoutFoldersOf({ value }),
|
|
1164
|
+
);
|
|
1165
|
+
const clash = layoutFolders.find(
|
|
1166
|
+
(entry) => entry === tmp || entry.startsWith(`${tmp}/`) || tmp.startsWith(`${entry}/`),
|
|
1167
|
+
);
|
|
1168
|
+
const tracked = spawnSync('git', ['ls-files', '--', tmp], {
|
|
1169
|
+
cwd: opts.root,
|
|
1170
|
+
encoding: 'utf8',
|
|
1171
|
+
timeout: 5000,
|
|
1172
|
+
});
|
|
1173
|
+
const hasTracked = tracked.status === 0 && tracked.stdout.trim() !== '';
|
|
1174
|
+
const length = BrowserSocket.lengthOf({ folder });
|
|
1175
|
+
const problems = [
|
|
1176
|
+
...(clash === undefined
|
|
1177
|
+
? []
|
|
1178
|
+
: [`it is, or holds, the layout folder '${clash}': \`clean\` removes old files from it`]),
|
|
1179
|
+
...(hasTracked
|
|
1180
|
+
? [
|
|
1181
|
+
`git tracks files in it: \`clean\` removes old files from it. Pick a folder that only holds scratch`,
|
|
1182
|
+
]
|
|
1183
|
+
: []),
|
|
1184
|
+
...(BrowserSocket.fits({ folder })
|
|
1185
|
+
? []
|
|
1186
|
+
: [
|
|
1187
|
+
`its socket path for a browser would be ${length} characters in ${folder} and the limit is ${BrowserSocket.PATH_MAX}. Use a shorter folder name or a shorter checkout path`,
|
|
1188
|
+
]),
|
|
1189
|
+
];
|
|
1190
|
+
|
|
1191
|
+
return problems.map((problem) =>
|
|
1192
|
+
createViolation({
|
|
1193
|
+
check: DoctorChecks.LOCAL,
|
|
1194
|
+
file: opts.configFile,
|
|
1195
|
+
message: `local.tmp '${tmp}': ${problem}`,
|
|
1196
|
+
}),
|
|
1197
|
+
);
|
|
1198
|
+
}
|
|
1199
|
+
|
|
1200
|
+
/**
|
|
1201
|
+
* The project's tmp folder is too deep for a browser: Chrome and Chromium put a socket below the temp folder
|
|
1202
|
+
* and exit with "Socket path too long" past the limit of a unix socket path (`BrowserSocket.PATH_MAX`, the Linux
|
|
1203
|
+
* value; macOS allows 104). The launch file points a session's `TMPDIR` at that folder, so a browser it starts
|
|
1204
|
+
* (Playwright MCP, a headless Chrome) fails; a project with no launch file is not asked. A warning, because only a
|
|
1205
|
+
* project that starts a browser meets it; the way out is a shorter checkout path. The root is made absolute first.
|
|
1206
|
+
*/
|
|
1207
|
+
static checkBrowserSocket(opts: { root: string; tmp?: string }): IViolation[] {
|
|
1208
|
+
if (opts.tmp !== undefined) {
|
|
1209
|
+
return [];
|
|
1210
|
+
}
|
|
1211
|
+
|
|
1212
|
+
const root = resolve(opts.root);
|
|
1213
|
+
const folder = ProjectTmp.projectOf({ root, tmp: HookConstants.PROJECT_TMP });
|
|
1214
|
+
const length = BrowserSocket.lengthOf({ folder });
|
|
1215
|
+
|
|
1216
|
+
if (BrowserSocket.fits({ folder }) || !existsSync(join(root, CLAUDE_LAUNCH_FILE))) {
|
|
1217
|
+
return [];
|
|
1218
|
+
}
|
|
1219
|
+
|
|
1220
|
+
const spare = BrowserSocket.PATH_MAX - (length - root.length);
|
|
1221
|
+
|
|
1222
|
+
return [
|
|
1223
|
+
createViolation({
|
|
1224
|
+
check: DoctorChecks.LOCAL,
|
|
1225
|
+
file: CLAUDE_LAUNCH_FILE,
|
|
1226
|
+
message: `the temp folder ${folder} is too deep for a browser: Chrome's socket path would be ${length} characters (${BrowserSocket.longest()} below it) and the limit is ${BrowserSocket.PATH_MAX}, so a browser started with this folder exits with "${BrowserSocket.ERROR}". Set \`local.tmp\` in the config to a short folder of the project (for example \`tmp\`) and run \`vulcan sync\`, or move the checkout to a path of ${spare} characters or fewer`,
|
|
1227
|
+
}),
|
|
1228
|
+
];
|
|
1279
1229
|
}
|
|
1280
1230
|
|
|
1281
1231
|
/**
|
|
@@ -1294,7 +1244,7 @@ export class ProjectContract {
|
|
|
1294
1244
|
: [];
|
|
1295
1245
|
}
|
|
1296
1246
|
|
|
1297
|
-
/** A Claude Code settings file of the project sets `VULCAN_OWNER_REPLY=off` in `env`: every session of the project then
|
|
1247
|
+
/** A Claude Code settings file of the project sets `VULCAN_OWNER_REPLY=off` in `env`: every session of the project then gets no owner shape card. A warning, never a failure. */
|
|
1298
1248
|
static checkOwnerReplySettings(opts: { root: string }): IViolation[] {
|
|
1299
1249
|
return ['.claude/settings.json', '.claude/settings.local.json'].flatMap((file) => {
|
|
1300
1250
|
const env = readJsonObject({ file: join(opts.root, file) })?.['env'];
|
|
@@ -1306,44 +1256,7 @@ export class ProjectContract {
|
|
|
1306
1256
|
createViolation({
|
|
1307
1257
|
check: DoctorChecks.LOCAL,
|
|
1308
1258
|
file,
|
|
1309
|
-
message: `env sets ${OwnerReplySwitch.ENV}=${OwnerReplySwitch.OFF}: every session of this project
|
|
1310
|
-
}),
|
|
1311
|
-
]
|
|
1312
|
-
: [];
|
|
1313
|
-
});
|
|
1314
|
-
}
|
|
1315
|
-
|
|
1316
|
-
/** One line per script in `guard.writes.trustedScripts` with what git says about it now (a note). */
|
|
1317
|
-
static checkTrustedScripts(opts: ICheckContext): IViolation[] {
|
|
1318
|
-
return opts.config.guard.writes.trustedScripts.map((entry) => {
|
|
1319
|
-
const { script, readOnly } = trustedScriptOf({ entry });
|
|
1320
|
-
const trust = ScriptTrust.trustOf({ root: opts.root, script });
|
|
1321
|
-
const scope = readOnly === undefined ? 'mutating calls' : `the calls ${readOnly.join(', ')}`;
|
|
1322
|
-
|
|
1323
|
-
return createViolation({
|
|
1324
|
-
check: DoctorChecks.GUARDS,
|
|
1325
|
-
file: script,
|
|
1326
|
-
message:
|
|
1327
|
-
trust.state === TrustStates.TRUSTED
|
|
1328
|
-
? `guard-writes does not read this script for ${scope} (guard.writes.trustedScripts); it is ` +
|
|
1329
|
-
trust.reason
|
|
1330
|
-
: `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
|
|
1331
|
-
});
|
|
1332
|
-
});
|
|
1333
|
-
}
|
|
1334
|
-
|
|
1335
|
-
/** A listed script that does not exist or is not committed: the exemption never applies (a warning). */
|
|
1336
|
-
static checkStaleTrustedScripts(opts: ICheckContext): IViolation[] {
|
|
1337
|
-
return opts.config.guard.writes.trustedScripts.flatMap((entry) => {
|
|
1338
|
-
const { script } = trustedScriptOf({ entry });
|
|
1339
|
-
const trust = ScriptTrust.trustOf({ root: opts.root, script });
|
|
1340
|
-
|
|
1341
|
-
return STALE_TRUST_STATES.has(trust.state)
|
|
1342
|
-
? [
|
|
1343
|
-
createViolation({
|
|
1344
|
-
check: DoctorChecks.GUARDS,
|
|
1345
|
-
file: script,
|
|
1346
|
-
message: `guard.writes.trustedScripts lists it, but it never takes effect: ${trust.reason}; fix the path, or commit the script`,
|
|
1259
|
+
message: `env sets ${OwnerReplySwitch.ENV}=${OwnerReplySwitch.OFF}: every session of this project gets no owner shape card and no profile card. Remove it and set the variable on the command that starts a session whose reader is an agent`,
|
|
1347
1260
|
}),
|
|
1348
1261
|
]
|
|
1349
1262
|
: [];
|
|
@@ -1351,51 +1264,45 @@ export class ProjectContract {
|
|
|
1351
1264
|
}
|
|
1352
1265
|
|
|
1353
1266
|
/**
|
|
1354
|
-
*
|
|
1355
|
-
*
|
|
1267
|
+
* Private values in committed files, never the text: one warning per file that holds a key, a token or a URL
|
|
1268
|
+
* credential, with the kinds and counts; the files that hold only addresses or machine paths (an example IP in a
|
|
1269
|
+
* policy file, a path in a doc) in one warning; and one per acknowledgment that covered nothing.
|
|
1356
1270
|
*/
|
|
1357
|
-
static checkGuardPatterns(opts: ICheckContext): IViolation[] {
|
|
1358
|
-
const { commands } = opts.config.guard.writes;
|
|
1359
|
-
const { askPush } = opts.config.guard.git;
|
|
1360
|
-
|
|
1361
|
-
return [
|
|
1362
|
-
...commands.map((command) =>
|
|
1363
|
-
createViolation({
|
|
1364
|
-
check: DoctorChecks.GUARDS,
|
|
1365
|
-
file: opts.configFile,
|
|
1366
|
-
message: `guard.writes.commands: ${command.rule} '${command.what}' asks when a command matches /${command.pattern}/${command.ignoreCase === true ? 'i' : ''}`,
|
|
1367
|
-
}),
|
|
1368
|
-
),
|
|
1369
|
-
...(askPush.length === 0
|
|
1370
|
-
? []
|
|
1371
|
-
: [
|
|
1372
|
-
createViolation({
|
|
1373
|
-
check: DoctorChecks.GUARDS,
|
|
1374
|
-
file: opts.configFile,
|
|
1375
|
-
message: `guard.git.askPush: a plain git push asks for ${askPush.join(', ')}`,
|
|
1376
|
-
}),
|
|
1377
|
-
]),
|
|
1378
|
-
];
|
|
1379
|
-
}
|
|
1380
|
-
|
|
1381
|
-
/** Private values in committed files: one warning per file with the kinds and counts, never the text, and one per acknowledgment that covered nothing. */
|
|
1382
1271
|
static checkPrivateValues(opts: ICheckContext): IViolation[] {
|
|
1383
1272
|
const { findings, unmatched } = PrivateValues.scan({
|
|
1384
1273
|
root: opts.root,
|
|
1385
1274
|
acknowledged: opts.config.doctor.privateValues.acknowledged,
|
|
1386
1275
|
});
|
|
1387
1276
|
const where = 'doctor.privateValues.acknowledged';
|
|
1277
|
+
const kindsOf = (counts: Record<string, number | undefined>): string =>
|
|
1278
|
+
Object.entries(counts)
|
|
1279
|
+
.map(([kind, count]) => `${count} ${kind}`)
|
|
1280
|
+
.join(', ');
|
|
1281
|
+
const isMild = (finding: { counts: Record<string, number | undefined> }): boolean =>
|
|
1282
|
+
Object.keys(finding.counts).every((kind) =>
|
|
1283
|
+
[PrivateValueKinds.IPV4, PrivateValueKinds.MACHINE_PATH].includes(kind),
|
|
1284
|
+
);
|
|
1285
|
+
const mild = findings.filter((finding) => isMild(finding));
|
|
1388
1286
|
|
|
1389
1287
|
return [
|
|
1390
|
-
...findings
|
|
1391
|
-
|
|
1392
|
-
|
|
1393
|
-
|
|
1394
|
-
|
|
1395
|
-
.
|
|
1396
|
-
.
|
|
1397
|
-
|
|
1398
|
-
|
|
1288
|
+
...findings
|
|
1289
|
+
.filter((finding) => !isMild(finding))
|
|
1290
|
+
.map((finding) =>
|
|
1291
|
+
createViolation({
|
|
1292
|
+
check: DoctorChecks.PRIVATE_VALUES,
|
|
1293
|
+
file: finding.file,
|
|
1294
|
+
message: `holds private values: ${kindsOf(finding.counts)} (not shown); remove them, or record the decision in ${where}`,
|
|
1295
|
+
}),
|
|
1296
|
+
),
|
|
1297
|
+
...(mild.length === 0
|
|
1298
|
+
? []
|
|
1299
|
+
: [
|
|
1300
|
+
createViolation({
|
|
1301
|
+
check: DoctorChecks.PRIVATE_VALUES,
|
|
1302
|
+
file: mild.length === 1 ? mild[0].file : `${mild.length} files`,
|
|
1303
|
+
message: `${mild.length === 1 ? 'holds' : `${mild.length} files hold`} only addresses or machine paths: ${mild.map((finding) => `${finding.file} (${kindsOf(finding.counts)})`).join(', ')} (not shown); remove them, or record the decision in ${where}`,
|
|
1304
|
+
}),
|
|
1305
|
+
]),
|
|
1399
1306
|
...unmatched.map((entry) =>
|
|
1400
1307
|
createViolation({
|
|
1401
1308
|
check: DoctorChecks.PRIVATE_VALUES,
|
|
@@ -1424,82 +1331,4 @@ export class ProjectContract {
|
|
|
1424
1331
|
}),
|
|
1425
1332
|
];
|
|
1426
1333
|
}
|
|
1427
|
-
|
|
1428
|
-
/** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
|
|
1429
|
-
static checkLocalSize(opts: ICheckContext): IViolation[] {
|
|
1430
|
-
const entries = LocalScan.scan({ root: opts.root });
|
|
1431
|
-
const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
|
|
1432
|
-
|
|
1433
|
-
if (total < LocalConstants.NOTE_BYTES) {
|
|
1434
|
-
return [];
|
|
1435
|
-
}
|
|
1436
|
-
|
|
1437
|
-
const byScope = new Map<string, number>();
|
|
1438
|
-
|
|
1439
|
-
for (const entry of entries) {
|
|
1440
|
-
byScope.set(entry.scope, (byScope.get(entry.scope) ?? 0) + entry.bytes);
|
|
1441
|
-
}
|
|
1442
|
-
|
|
1443
|
-
const parts = [...byScope.entries()]
|
|
1444
|
-
.sort((first, second) => second[1] - first[1])
|
|
1445
|
-
.map(([scope, bytes]) => `${scope} ${LocalFormat.formatBytes({ bytes })}`);
|
|
1446
|
-
|
|
1447
|
-
return [
|
|
1448
|
-
createViolation({
|
|
1449
|
-
check: DoctorChecks.LOCAL,
|
|
1450
|
-
file: ProjectLayout.LOCAL_DIRECTORY,
|
|
1451
|
-
message: `holds ${LocalFormat.formatBytes({ bytes: total })} (${parts.join(', ')}); vulcan clean lists what an agent left and --yes removes it`,
|
|
1452
|
-
}),
|
|
1453
|
-
];
|
|
1454
|
-
}
|
|
1455
|
-
}
|
|
1456
|
-
|
|
1457
|
-
const QUOTES = ["'", '"', '`'];
|
|
1458
|
-
|
|
1459
|
-
/**
|
|
1460
|
-
* A subcommand an object entry lists that its script never holds as a quoted string (a note). It reads the
|
|
1461
|
-
* text of the file, so it cannot tell a subcommand the script handles another way from a typo.
|
|
1462
|
-
*/
|
|
1463
|
-
export class ReadOnlySubcommandChecks {
|
|
1464
|
-
static readonly MAX_SOURCE_BYTES = 1_000_000;
|
|
1465
|
-
|
|
1466
|
-
static sourceOf(opts: { path: string }): string | undefined {
|
|
1467
|
-
try {
|
|
1468
|
-
const stat = lstatSync(opts.path);
|
|
1469
|
-
|
|
1470
|
-
return stat.isFile() && stat.size <= ReadOnlySubcommandChecks.MAX_SOURCE_BYTES
|
|
1471
|
-
? readFileSync(opts.path, 'utf8')
|
|
1472
|
-
: undefined;
|
|
1473
|
-
} catch {
|
|
1474
|
-
return undefined;
|
|
1475
|
-
}
|
|
1476
|
-
}
|
|
1477
|
-
|
|
1478
|
-
static check(opts: ICheckContext): IViolation[] {
|
|
1479
|
-
return opts.config.guard.writes.trustedScripts.flatMap((entry) => {
|
|
1480
|
-
const { script, readOnly } = trustedScriptOf({ entry });
|
|
1481
|
-
const path = join(opts.root, script);
|
|
1482
|
-
|
|
1483
|
-
if (readOnly === undefined) {
|
|
1484
|
-
return [];
|
|
1485
|
-
}
|
|
1486
|
-
|
|
1487
|
-
// Only a plain, small file inside the repo is read: a link, a folder or a device is skipped, never followed.
|
|
1488
|
-
const source = ReadOnlySubcommandChecks.sourceOf({ path });
|
|
1489
|
-
|
|
1490
|
-
if (source === undefined) {
|
|
1491
|
-
return [];
|
|
1492
|
-
}
|
|
1493
|
-
|
|
1494
|
-
return readOnly
|
|
1495
|
-
.filter((word) => !QUOTES.some((quote) => source.includes(`${quote}${word}${quote}`)))
|
|
1496
|
-
.map((word) =>
|
|
1497
|
-
createViolation({
|
|
1498
|
-
check: DoctorChecks.GUARDS,
|
|
1499
|
-
file: script,
|
|
1500
|
-
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`,
|
|
1501
|
-
}),
|
|
1502
|
-
);
|
|
1503
|
-
});
|
|
1504
|
-
}
|
|
1505
1334
|
}
|