@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.
Files changed (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -1,17 +1,21 @@
1
1
  const RULE_TARGET = /^([A-Za-z0-9][A-Za-z0-9_.-]*)\s*:(?!=)/;
2
2
 
3
- /** Explicit rule targets: `name:` at column 0 - no recipes, assignments, specials or `$(...)` rules. */
4
- export const parseMakeTargets = (opts: { makefile: string }): string[] =>
5
- opts.makefile
6
- .split('\n')
7
- .map((line) => RULE_TARGET.exec(line)?.[1])
8
- .filter((target): target is string => target !== undefined);
9
-
10
3
  const INCLUDE_LINE = /^\s*(?:-include|sinclude|include)\s+(.+?)\s*$/;
11
4
 
12
- /** The paths and globs an `include`, `-include` or `sinclude` line names; one built from a variable is skipped. */
13
- export const parseMakeIncludes = (opts: { makefile: string }): string[] =>
14
- opts.makefile
15
- .split('\n')
16
- .flatMap((line) => INCLUDE_LINE.exec(line)?.[1].split(/\s+/) ?? [])
17
- .filter((path) => !path.includes('$('));
5
+ export class Makefile {
6
+ /** Explicit rule targets: `name:` at column 0 - no recipes, assignments, specials or `$(...)` rules. */
7
+ static parseMakeTargets(opts: { makefile: string }): string[] {
8
+ return opts.makefile
9
+ .split('\n')
10
+ .map((line) => RULE_TARGET.exec(line)?.[1])
11
+ .filter((target): target is string => target !== undefined);
12
+ }
13
+
14
+ /** The paths and globs an `include`, `-include` or `sinclude` line names; one built from a variable is skipped. */
15
+ static parseMakeIncludes(opts: { makefile: string }): string[] {
16
+ return opts.makefile
17
+ .split('\n')
18
+ .flatMap((line) => INCLUDE_LINE.exec(line)?.[1].split(/\s+/) ?? [])
19
+ .filter((path) => !path.includes('$('));
20
+ }
21
+ }
@@ -1,134 +1,106 @@
1
1
  import { relative } from 'node:path';
2
- import { loadConfig } from '../config/index.ts';
3
- import {
4
- checkAdapters,
5
- checkAgents,
6
- checkAppScripts,
7
- checkAtlasBlock,
8
- checkSkillTriggers,
9
- checkDockerignore,
10
- checkFormat,
11
- checkMcpAtlas,
12
- checkApps,
13
- checkManifest,
14
- checkLocalSize,
15
- checkProfile,
16
- checkOwnerReplySettings,
17
- checkOwnerReplySwitch,
18
- checkReplyShape,
19
- checkPrune,
20
- checkStaleLocal,
21
- checkStaleTrustedScripts,
22
- checkTrustedScripts,
23
- checkHooks,
24
- checkLayout,
25
- checkGuardPatterns,
26
- checkLocalWorkspace,
27
- checkMake,
28
- checkOutsideWorktrees,
29
- checkRuleIds,
30
- checkRuleSlots,
31
- checkScaffold,
32
- checkSkills,
33
- checkStyle,
34
- } from './checks.ts';
35
- import { checkSkillLint } from './skills.ts';
36
- import { checkTags } from './tags.ts';
2
+ import { ConfigLoader } from '../config/index.ts';
3
+ import { ProjectContract, ReadOnlySubcommandChecks } from './checks.ts';
4
+ import { SkillLint } from './skills.ts';
5
+ import { TagCheck } from './tags.ts';
37
6
  import { DoctorChecks } from './common/index.ts';
38
7
  import type { IViolation } from './common/index.ts';
39
8
 
40
- /** Every violation of the VULCAN contract in the project at `root`; empty means conformant. */
41
- export const runDoctorChecks = async (opts: { root: string }): Promise<IViolation[]> => {
42
- const loaded = await loadConfig({ root: opts.root });
9
+ export class DoctorRunner {
10
+ /** Every violation of the VULCAN contract in the project at `root`; empty means conformant. */
11
+ static async runChecks(opts: { root: string }): Promise<IViolation[]> {
12
+ const loaded = await ConfigLoader.load({ root: opts.root });
13
+
14
+ if (!loaded.ok) {
15
+ return [
16
+ {
17
+ check: DoctorChecks.CONFIG,
18
+ file: loaded.file === undefined ? '.configs/' : relative(opts.root, loaded.file),
19
+ message: loaded.error,
20
+ },
21
+ ];
22
+ }
23
+
24
+ const context = {
25
+ root: opts.root,
26
+ config: loaded.config,
27
+ configFile: relative(opts.root, loaded.file),
28
+ };
43
29
 
44
- if (!loaded.ok) {
45
30
  return [
46
- {
47
- check: DoctorChecks.CONFIG,
48
- file: loaded.file === undefined ? '.configs/' : relative(opts.root, loaded.file),
49
- message: loaded.error,
50
- },
31
+ ...ProjectContract.checkLayout(context),
32
+ ...ProjectContract.checkRuleIds(context),
33
+ ...ProjectContract.checkRuleSlots(context),
34
+ ...ProjectContract.checkSkills(context),
35
+ ...ProjectContract.checkMake(context),
36
+ ...ProjectContract.checkHooks(context),
37
+ ...ProjectContract.checkAdapters(context),
38
+ ...ProjectContract.checkAgents(context),
39
+ ...ProjectContract.checkPrune(context),
40
+ ...ProjectContract.checkManifest(context),
41
+ ...TagCheck.check(context),
42
+ ...SkillLint.check(context),
43
+ ...ProjectContract.checkStyle(context),
44
+ ...ProjectContract.checkScaffold(context),
45
+ ...ProjectContract.checkApps(context),
51
46
  ];
52
47
  }
53
48
 
54
- const context = {
55
- root: opts.root,
56
- config: loaded.config,
57
- configFile: relative(opts.root, loaded.file),
58
- };
49
+ /** Notes that never fail the doctor: what a project could change, one line each. */
50
+ static async runNotes(opts: {
51
+ root: string;
52
+ /** The environment of the shell running doctor; defaults to the process environment. */
53
+ env?: Record<string, string | undefined>;
54
+ }): Promise<IViolation[]> {
55
+ const loaded = await ConfigLoader.load({ root: opts.root });
59
56
 
60
- return [
61
- ...checkLayout(context),
62
- ...checkRuleIds(context),
63
- ...checkRuleSlots(context),
64
- ...checkSkills(context),
65
- ...checkMake(context),
66
- ...checkHooks(context),
67
- ...checkAdapters(context),
68
- ...checkAgents(context),
69
- ...checkPrune(context),
70
- ...checkManifest(context),
71
- ...checkTags(context),
72
- ...checkSkillLint(context),
73
- ...checkStyle(context),
74
- ...checkScaffold(context),
75
- ...checkApps(context),
76
- ];
77
- };
57
+ if (!loaded.ok) {
58
+ return [];
59
+ }
78
60
 
79
- /** Notes that never fail the doctor: what a project could change, one line each. */
80
- export const runDoctorNotes = async (opts: {
81
- root: string;
82
- /** The environment of the shell running doctor; defaults to the process environment. */
83
- env?: Record<string, string | undefined>;
84
- }): Promise<IViolation[]> => {
85
- const loaded = await loadConfig({ root: opts.root });
61
+ const context = {
62
+ root: opts.root,
63
+ config: loaded.config,
64
+ configFile: relative(opts.root, loaded.file),
65
+ };
86
66
 
87
- if (!loaded.ok) {
88
- return [];
67
+ return [
68
+ ...ProjectContract.checkAppScripts(context),
69
+ ...ProjectContract.checkAtlasBlock(context),
70
+ ...ProjectContract.checkLocalSize(context),
71
+ ...ProjectContract.checkGuardPatterns(context),
72
+ ...ProjectContract.checkReplyShape(context),
73
+ ...ProjectContract.checkOwnerReplySwitch({ env: opts.env ?? process.env }),
74
+ ...ProjectContract.checkTrustedScripts(context),
75
+ ...ReadOnlySubcommandChecks.check(context),
76
+ ];
89
77
  }
90
78
 
91
- const context = {
92
- root: opts.root,
93
- config: loaded.config,
94
- configFile: relative(opts.root, loaded.file),
95
- };
79
+ /** Warnings: louder than a note, still never a failure - a security gap a project made earlier may carry. */
80
+ static async runWarnings(opts: { root: string }): Promise<IViolation[]> {
81
+ const loaded = await ConfigLoader.load({ root: opts.root });
96
82
 
97
- return [
98
- ...checkAppScripts(context),
99
- ...checkAtlasBlock(context),
100
- ...checkLocalSize(context),
101
- ...checkGuardPatterns(context),
102
- ...checkReplyShape(context),
103
- ...checkOwnerReplySwitch({ env: opts.env ?? process.env }),
104
- ...checkTrustedScripts(context),
105
- ];
106
- };
83
+ if (!loaded.ok) {
84
+ return [];
85
+ }
107
86
 
108
- /** Warnings: louder than a note, still never a failure - a security gap a project made earlier may carry. */
109
- export const runDoctorWarnings = async (opts: { root: string }): Promise<IViolation[]> => {
110
- const loaded = await loadConfig({ root: opts.root });
87
+ const context = {
88
+ root: opts.root,
89
+ config: loaded.config,
90
+ configFile: relative(opts.root, loaded.file),
91
+ };
111
92
 
112
- if (!loaded.ok) {
113
- return [];
93
+ return [
94
+ ...ProjectContract.checkMcpAtlas(context),
95
+ ...ProjectContract.checkDockerignore(context),
96
+ ...ProjectContract.checkSkillTriggers(context),
97
+ ...ProjectContract.checkFormat(context),
98
+ ...ProjectContract.checkLocalWorkspace(context),
99
+ ...ProjectContract.checkOutsideWorktrees(context),
100
+ ...ProjectContract.checkProfile(context),
101
+ ...ProjectContract.checkOwnerReplySettings(context),
102
+ ...ProjectContract.checkStaleLocal(context),
103
+ ...ProjectContract.checkStaleTrustedScripts(context),
104
+ ];
114
105
  }
115
-
116
- const context = {
117
- root: opts.root,
118
- config: loaded.config,
119
- configFile: relative(opts.root, loaded.file),
120
- };
121
-
122
- return [
123
- ...checkMcpAtlas(context),
124
- ...checkDockerignore(context),
125
- ...checkSkillTriggers(context),
126
- ...checkFormat(context),
127
- ...checkLocalWorkspace(context),
128
- ...checkOutsideWorktrees(context),
129
- ...checkProfile(context),
130
- ...checkOwnerReplySettings(context),
131
- ...checkStaleLocal(context),
132
- ...checkStaleTrustedScripts(context),
133
- ];
134
- };
106
+ }
@@ -3,7 +3,7 @@ import { dirname, join, relative, resolve } from 'node:path';
3
3
  import type { ICheckContext } from './checks.ts';
4
4
  import { DoctorChecks } from './common/index.ts';
5
5
  import type { IViolation } from './common/index.ts';
6
- import { frontmatterOf } from '../skills/index.ts';
6
+ import { SkillFrontmatter } from '../skills/index.ts';
7
7
 
8
8
  /**
9
9
  * Anthropic's skill-authoring rules (platform.claude.com, Agent Skills best practices), as checks:
@@ -34,120 +34,122 @@ const filesOf = (opts: { directory: string }): string[] =>
34
34
  const lineCountOf = (opts: { text: string }): number =>
35
35
  opts.text.replace(/\n$/, '').split('\n').length;
36
36
 
37
- /** Every rule one skill directory breaks, each a message naming the file. */
38
- export const lintSkill = (opts: { directory: string }): string[] => {
39
- const skillFile = join(opts.directory, 'SKILL.md');
37
+ export class SkillLint {
38
+ /** Every rule one skill directory breaks, each a message naming the file. */
39
+ static lint(opts: { directory: string }): string[] {
40
+ const skillFile = join(opts.directory, 'SKILL.md');
40
41
 
41
- if (!existsSync(skillFile)) {
42
- return ['SKILL.md is missing'];
43
- }
44
-
45
- const problems: string[] = [];
46
- const text = readFileSync(skillFile, 'utf8');
47
- const frontmatter = frontmatterOf({ text });
48
- const { name, description } = frontmatter.data;
49
-
50
- // One file a project cannot parse is a finding about that file - the other checks still run.
51
- if (frontmatter.error !== undefined) {
52
- problems.push(`SKILL.md: ${frontmatter.error}`);
53
- } else if (typeof name !== 'string' || !NAME_PATTERN.test(name) || RESERVED_NAME.test(name)) {
54
- problems.push(
55
- `SKILL.md: name '${String(name)}' - at most 64 characters of a-z, 0-9 and hyphens, never 'claude' or 'anthropic'`,
56
- );
57
- }
58
-
59
- if (
60
- frontmatter.error === undefined &&
61
- (typeof description !== 'string' ||
62
- description.trim().length === 0 ||
63
- description.length > MAX_DESCRIPTION ||
64
- XML_TAG.test(description))
65
- ) {
66
- problems.push('SKILL.md: the description must be 1-1024 characters with no XML tags');
67
- }
42
+ if (!existsSync(skillFile)) {
43
+ return ['SKILL.md is missing'];
44
+ }
68
45
 
69
- const body = text.slice(FRONTMATTER.exec(text)?.[0].length ?? 0);
70
- const bodyLines = lineCountOf({ text: body });
46
+ const problems: string[] = [];
47
+ const text = readFileSync(skillFile, 'utf8');
48
+ const frontmatter = SkillFrontmatter.frontmatterOf({ text });
49
+ const { name, description } = frontmatter.data;
71
50
 
72
- if (bodyLines >= MAX_BODY_LINES) {
73
- problems.push(
74
- `SKILL.md: the body is ${bodyLines} lines - keep it under ${MAX_BODY_LINES}, move detail into reference files`,
75
- );
76
- }
51
+ // One file a project cannot parse is a finding about that file - the other checks still run.
52
+ if (frontmatter.error !== undefined) {
53
+ problems.push(`SKILL.md: ${frontmatter.error}`);
54
+ } else if (typeof name !== 'string' || !NAME_PATTERN.test(name) || RESERVED_NAME.test(name)) {
55
+ problems.push(
56
+ `SKILL.md: name '${String(name)}' - at most 64 characters of a-z, 0-9 and hyphens, never 'claude' or 'anthropic'`,
57
+ );
58
+ }
77
59
 
78
- const files = filesOf({ directory: opts.directory }).sort();
79
- const shown = (path: string): string => relative(opts.directory, path);
60
+ if (
61
+ frontmatter.error === undefined &&
62
+ (typeof description !== 'string' ||
63
+ description.trim().length === 0 ||
64
+ description.length > MAX_DESCRIPTION ||
65
+ XML_TAG.test(description))
66
+ ) {
67
+ problems.push('SKILL.md: the description must be 1-1024 characters with no XML tags');
68
+ }
80
69
 
81
- for (const file of files.filter((path) => path.endsWith('.md'))) {
82
- const content = readFileSync(file, 'utf8');
83
- const count = lineCountOf({ text: content });
84
- const opening = content.split('\n').slice(0, CONTENTS_WITHIN_LINES);
70
+ const body = text.slice(FRONTMATTER.exec(text)?.[0].length ?? 0);
71
+ const bodyLines = lineCountOf({ text: body });
85
72
 
86
- if (count > CONTENTS_AFTER_LINES && !opening.some((line) => CONTENTS_MARK.test(line))) {
73
+ if (bodyLines >= MAX_BODY_LINES) {
87
74
  problems.push(
88
- `${shown(file)}: ${count} lines and no contents list in its first ${CONTENTS_WITHIN_LINES} lines - an agent may read only the first lines`,
75
+ `SKILL.md: the body is ${bodyLines} lines - keep it under ${MAX_BODY_LINES}, move detail into reference files`,
89
76
  );
90
77
  }
91
78
 
92
- if (file === skillFile) {
93
- continue;
94
- }
79
+ const files = filesOf({ directory: opts.directory }).sort();
80
+ const shown = (path: string): string => relative(opts.directory, path);
95
81
 
96
- for (const match of content.matchAll(MARKDOWN_LINK)) {
97
- const target = resolve(dirname(file), match[1]);
82
+ for (const file of files.filter((path) => path.endsWith('.md'))) {
83
+ const content = readFileSync(file, 'utf8');
84
+ const count = lineCountOf({ text: content });
85
+ const opening = content.split('\n').slice(0, CONTENTS_WITHIN_LINES);
98
86
 
99
- if (target !== skillFile && target.startsWith(`${opts.directory}/`) && existsSync(target)) {
87
+ if (count > CONTENTS_AFTER_LINES && !opening.some((line) => CONTENTS_MARK.test(line))) {
100
88
  problems.push(
101
- `${shown(file)} links ${shown(target)} - link every reference from SKILL.md, one level deep`,
89
+ `${shown(file)}: ${count} lines and no contents list in its first ${CONTENTS_WITHIN_LINES} lines - an agent may read only the first lines`,
102
90
  );
103
91
  }
104
- }
105
- }
106
92
 
107
- if (files.some((path) => SCRIPT.test(path)) && !REQUIREMENTS.test(text)) {
108
- problems.push(
109
- 'SKILL.md: the skill runs scripts and has no ## Requirements section - name what they need',
110
- );
111
- }
93
+ if (file === skillFile) {
94
+ continue;
95
+ }
112
96
 
113
- return problems;
114
- };
97
+ for (const match of content.matchAll(MARKDOWN_LINK)) {
98
+ const target = resolve(dirname(file), match[1]);
115
99
 
116
- /** The project's own skills, linted; a nested one is reported - sync links flat skills only. */
117
- export const checkSkillLint = (opts: ICheckContext): IViolation[] => {
118
- const skills = join(opts.root, '.agents', 'skills');
100
+ if (target !== skillFile && target.startsWith(`${opts.directory}/`) && existsSync(target)) {
101
+ problems.push(
102
+ `${shown(file)} links ${shown(target)} - link every reference from SKILL.md, one level deep`,
103
+ );
104
+ }
105
+ }
106
+ }
119
107
 
120
- if (!existsSync(skills)) {
121
- return [];
122
- }
108
+ if (files.some((path) => SCRIPT.test(path)) && !REQUIREMENTS.test(text)) {
109
+ problems.push(
110
+ 'SKILL.md: the skill runs scripts and has no ## Requirements section - name what they need',
111
+ );
112
+ }
123
113
 
124
- return readdirSync(skills)
125
- .filter((name) => statSync(join(skills, name)).isDirectory())
126
- .sort()
127
- .flatMap((name) => {
128
- const directory = join(skills, name);
129
- const file = `.agents/skills/${name}`;
114
+ return problems;
115
+ }
130
116
 
131
- if (!existsSync(join(directory, 'SKILL.md'))) {
132
- const inner = readdirSync(directory).find((child) =>
133
- existsSync(join(directory, child, 'SKILL.md')),
134
- );
117
+ /** The project's own skills, linted; a nested one is reported - sync links flat skills only. */
118
+ static check(opts: ICheckContext): IViolation[] {
119
+ const skills = join(opts.root, '.agents', 'skills');
135
120
 
136
- return inner === undefined
137
- ? []
138
- : [
139
- {
140
- check: DoctorChecks.SKILLS,
141
- file,
142
- message: `skills are flat - sync links .agents/skills/<name> only; move ${name}/${inner} up to .agents/skills/${inner}`,
143
- },
144
- ];
145
- }
121
+ if (!existsSync(skills)) {
122
+ return [];
123
+ }
146
124
 
147
- return lintSkill({ directory }).map((message) => ({
148
- check: DoctorChecks.SKILLS,
149
- file,
150
- message,
151
- }));
152
- });
153
- };
125
+ return readdirSync(skills)
126
+ .filter((name) => statSync(join(skills, name)).isDirectory())
127
+ .sort()
128
+ .flatMap((name) => {
129
+ const directory = join(skills, name);
130
+ const file = `.agents/skills/${name}`;
131
+
132
+ if (!existsSync(join(directory, 'SKILL.md'))) {
133
+ const inner = readdirSync(directory).find((child) =>
134
+ existsSync(join(directory, child, 'SKILL.md')),
135
+ );
136
+
137
+ return inner === undefined
138
+ ? []
139
+ : [
140
+ {
141
+ check: DoctorChecks.SKILLS,
142
+ file,
143
+ message: `skills are flat - sync links .agents/skills/<name> only; move ${name}/${inner} up to .agents/skills/${inner}`,
144
+ },
145
+ ];
146
+ }
147
+
148
+ return SkillLint.lint({ directory }).map((message) => ({
149
+ check: DoctorChecks.SKILLS,
150
+ file,
151
+ message,
152
+ }));
153
+ });
154
+ }
155
+ }
@@ -1,12 +1,10 @@
1
1
  import { spawnSync } from 'node:child_process';
2
- import { resolvePackages } from '../config/index.ts';
2
+ import { TextValue } from '../common/text.ts';
3
+ import { ProjectPackages } from '../config/index.ts';
3
4
  import type { ICheckContext } from './checks.ts';
4
5
  import { DoctorChecks } from './common/index.ts';
5
6
  import type { IViolation } from './common/index.ts';
6
7
 
7
- const escapeLiteral = (opts: { text: string }): string =>
8
- opts.text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
9
-
10
8
  /** The tag pattern as a regular expression that captures `<dir>` (or `<package>`). */
11
9
  const tagPatternOf = (opts: { template: string }): RegExp =>
12
10
  new RegExp(
@@ -28,52 +26,57 @@ const tagPatternOf = (opts: { template: string }): RegExp =>
28
26
  }
29
27
 
30
28
  default: {
31
- return escapeLiteral({ text: part });
29
+ return TextValue.escapeLiteral({ text: part });
32
30
  }
33
31
  }
34
32
  })
35
33
  .join('')}$`,
36
34
  );
37
35
 
38
- /**
39
- * Project Contract v1, C4: every tag `atlas.tagPattern` reads names a declared package - by
40
- * directory or alias, retired ones included - because atlas computes releases from the tags. A tag
41
- * of an old layout is ignored through `atlas.ignoreTags`. A repo-level pattern (no `<dir>`) has
42
- * nothing to check; a directory that is not a git repository has no tags.
43
- */
44
- export const checkTags = (opts: ICheckContext): IViolation[] => {
45
- const template = opts.config.atlas.tagPattern;
36
+ export class TagCheck {
37
+ /**
38
+ * Project Contract v1, C4: every tag `atlas.tagPattern` reads names a declared package - by
39
+ * directory or alias, retired ones included - because atlas computes releases from the tags. A tag
40
+ * of an old layout is ignored through `atlas.ignoreTags`. A repo-level pattern (no `<dir>`) has
41
+ * nothing to check; a directory that is not a git repository has no tags.
42
+ */
43
+ static check(opts: ICheckContext): IViolation[] {
44
+ const template = opts.config.atlas.tagPattern;
46
45
 
47
- if (!/<(?:dir|package)>/.test(template)) {
48
- return [];
49
- }
46
+ if (!/<(?:dir|package)>/.test(template)) {
47
+ return [];
48
+ }
50
49
 
51
- const listed = spawnSync('git', ['tag', '--list'], { cwd: opts.root, encoding: 'utf8' });
50
+ const listed = spawnSync('git', ['tag', '--list'], { cwd: opts.root, encoding: 'utf8' });
52
51
 
53
- if (listed.status !== 0) {
54
- return [];
55
- }
52
+ if (listed.status !== 0) {
53
+ return [];
54
+ }
56
55
 
57
- const pattern = tagPatternOf({ template });
58
- const ignored = (opts.config.atlas.ignoreTags ?? []).map((glob) => new Bun.Glob(glob));
59
- const names = new Set(
60
- resolvePackages({ config: opts.config }).flatMap((entry) => [entry.dir, ...entry.aliases]),
61
- );
56
+ const pattern = tagPatternOf({ template });
57
+ const ignored = (opts.config.atlas.ignoreTags ?? []).map((glob) => new Bun.Glob(glob));
58
+ const names = new Set(
59
+ ProjectPackages.resolve({ config: opts.config }).flatMap((entry) => [
60
+ entry.dir,
61
+ ...entry.aliases,
62
+ ]),
63
+ );
62
64
 
63
- return listed.stdout
64
- .split('\n')
65
- .filter((tag) => tag.length > 0 && !ignored.some((glob) => glob.match(tag)))
66
- .flatMap((tag) => {
67
- const dir = pattern.exec(tag)?.groups?.dir;
65
+ return listed.stdout
66
+ .split('\n')
67
+ .filter((tag) => tag.length > 0 && !ignored.some((glob) => glob.match(tag)))
68
+ .flatMap((tag) => {
69
+ const dir = pattern.exec(tag)?.groups?.dir;
68
70
 
69
- return dir === undefined || names.has(dir)
70
- ? []
71
- : [
72
- {
73
- check: DoctorChecks.TAGS,
74
- file: 'git tags',
75
- message: `tag ${tag} reads as a release of '${dir}', which no package declares - declare it (retired: true if it is gone), add it as an alias, or ignore the tag (atlas.ignoreTags)`,
76
- },
77
- ];
78
- });
79
- };
71
+ return dir === undefined || names.has(dir)
72
+ ? []
73
+ : [
74
+ {
75
+ check: DoctorChecks.TAGS,
76
+ file: 'git tags',
77
+ message: `tag ${tag} reads as a release of '${dir}', which no package declares - declare it (retired: true if it is gone), add it as an alias, or ignore the tag (atlas.ignoreTags)`,
78
+ },
79
+ ];
80
+ });
81
+ }
82
+ }
@@ -13,9 +13,9 @@ export class PatchedTools {
13
13
  }
14
14
  }
15
15
 
16
- export type TPatchedTool = TConstValue<typeof PatchedTools>;
16
+ type TPatchedTool = TConstValue<typeof PatchedTools>;
17
17
 
18
- export interface IPatchedFile {
18
+ interface IPatchedFile {
19
19
  path: string;
20
20
  tool: TPatchedTool;
21
21
  }
@@ -23,25 +23,28 @@ export interface IPatchedFile {
23
23
  const HEADER = /^\*\*\* (Add|Update|Delete) File: (.+)$/;
24
24
  const MOVE = /^\*\*\* Move to: (.+)$/;
25
25
 
26
- /**
27
- * The files an `apply_patch` touches, from the patch text Codex sends as `tool_input.command`: the
28
- * `*** Add File:`, `*** Update File:`, `*** Delete File:` and `*** Move to:` lines, made absolute against `cwd`.
29
- */
30
- export const patchedFilesOf = (opts: { patch: string; cwd: string }): IPatchedFile[] =>
31
- opts.patch.split('\n').flatMap((line): IPatchedFile[] => {
32
- const header = HEADER.exec(line);
33
- const target = header?.[2] ?? MOVE.exec(line)?.[1];
34
-
35
- if (target === undefined) {
36
- return [];
37
- }
38
-
39
- const path = target.trim();
40
-
41
- return [
42
- {
43
- path: isAbsolute(path) ? path : resolve(opts.cwd, path),
44
- tool: header?.[1] === 'Add' ? PatchedTools.WRITE : PatchedTools.EDIT,
45
- },
46
- ];
47
- });
26
+ export class CodexPatch {
27
+ /**
28
+ * The files an `apply_patch` touches, from the patch text Codex sends as `tool_input.command`: the
29
+ * `*** Add File:`, `*** Update File:`, `*** Delete File:` and `*** Move to:` lines, made absolute against `cwd`.
30
+ */
31
+ static patchedFilesOf(opts: { patch: string; cwd: string }): IPatchedFile[] {
32
+ return opts.patch.split('\n').flatMap((line): IPatchedFile[] => {
33
+ const header = HEADER.exec(line);
34
+ const target = header?.[2] ?? MOVE.exec(line)?.[1];
35
+
36
+ if (target === undefined) {
37
+ return [];
38
+ }
39
+
40
+ const path = target.trim();
41
+
42
+ return [
43
+ {
44
+ path: isAbsolute(path) ? path : resolve(opts.cwd, path),
45
+ tool: header?.[1] === 'Add' ? PatchedTools.WRITE : PatchedTools.EDIT,
46
+ },
47
+ ];
48
+ });
49
+ }
50
+ }