@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.
Files changed (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -37,34 +37,45 @@ const DETAIL = choice({
37
37
  set: OwnerDetails.SCHEME_SET,
38
38
  });
39
39
 
40
- /** A phrase, not a stray letter pair: at least three characters, one of them not a space. */
41
- const CLAIM_WORDS = z
42
- .array(
43
- z
44
- .string()
45
- .max(60)
46
- .regex(/^(?=.*\S).{3,}$/u),
47
- )
48
- .max(20);
49
- const SHORT_REPLY_WORDS = z.number().int().min(0).max(OwnerConstants.MAX_SHORT_REPLY_WORDS);
40
+ /** A key that was removed: optional, and refused when present with what to do, instead of a bare "unrecognized key". */
41
+ const REMOVED_KEY = (opts: { fix: string }) =>
42
+ z
43
+ .unknown()
44
+ .superRefine((_value, context) => {
45
+ context.addIssue({ code: 'custom', message: `removed: ${opts.fix}` });
46
+ })
47
+ .optional();
50
48
 
51
49
  const DEFAULTS = OwnerConstants.DEFAULT_LABELS;
52
50
 
53
51
  /** The words of one language: the minimap header, the six statuses and five labels. A closed list. */
54
52
  export const OWNER_LABEL_SET = z.strictObject({
53
+ /** Three column headers of the minimap table, in order; each one line of at most 80 characters. */
55
54
  minimapColumns: z.tuple([TEXT, TEXT, TEXT]),
55
+ /** Words for the six task statuses of the minimap. */
56
56
  status: z.strictObject({
57
+ /** Status word for finished work. */
57
58
  done: TEXT,
59
+ /** Status word for work under way. */
58
60
  doing: TEXT,
61
+ /** Status word for work waiting on someone. */
59
62
  waiting: TEXT,
63
+ /** Status word for work not yet started. */
60
64
  todo: TEXT,
65
+ /** Status word for work that cannot go on. */
61
66
  blocked: TEXT,
67
+ /** Status word for work that was dropped. */
62
68
  dropped: TEXT,
63
69
  }),
70
+ /** Labels for the blocked and decisions parts of a reply. */
64
71
  labels: z.strictObject({
72
+ /** Label that opens the blocked line of a reply. */
65
73
  blocked: TEXT,
74
+ /** Heading of the decisions part of a reply. */
66
75
  decisions: TEXT,
76
+ /** Text shown in the blocked line when nothing blocks. */
67
77
  noBlocker: TEXT,
78
+ /** Text shown in the decisions part when no decision is needed. */
68
79
  noDecision: TEXT,
69
80
  /** `{x}` is where the recommended answer goes. */
70
81
  recommend: TEXT.refine((value) => value.includes('{x}'), { message: 'must contain {x}' }),
@@ -73,35 +84,41 @@ export const OWNER_LABEL_SET = z.strictObject({
73
84
 
74
85
  /**
75
86
  * The project's report contract for answers to its owners: the shape, the status words, the labels and
76
- * how hard the shape is held. English and `advise` unless the project says otherwise. A person's own
87
+ * whether the shape card is shown. English and `advise` unless the project says otherwise. A person's own
77
88
  * language, address and tone live in their profile (`.agents/local/profile.json`), not here.
78
89
  */
79
90
  export const OWNER_SCHEMA = z
80
91
  .strictObject({
92
+ /** Language of the reply labels, a code such as `en` or `pt-BR`; default `en`. */
81
93
  language: LANGUAGE.default(OwnerConstants.DEFAULT_LANGUAGE),
94
+ /** How a reply is shaped: sections, minimap columns, status words, labels, headline length, path style and whether the shape card is shown. */
82
95
  report: z
83
96
  .strictObject({
97
+ /** Sections of a reply, in order: headline, minimap, blocked, detail, decisions; at least one, default all five in that order. */
84
98
  shape: z.array(SECTION).min(1).default(OwnerConstants.DEFAULT_SHAPE),
99
+ /** Three minimap column headers; default `#`, `Task`, `Status`. */
85
100
  minimapColumns: z.tuple([TEXT, TEXT, TEXT]).default(DEFAULTS.minimapColumns),
101
+ /** Status words of the minimap; default the English set (done, in progress, waiting, not started, blocked, dropped). */
86
102
  status: OWNER_LABEL_SET.shape.status.default(DEFAULTS.status),
103
+ /** Labels of the blocked and decisions parts; default the English set. */
87
104
  labels: OWNER_LABEL_SET.shape.labels.default(DEFAULTS.labels),
105
+ /** Most sentences the headline of a reply may have, 1 to 5; default 2. */
88
106
  headlineMaxSentences: z
89
107
  .number()
90
108
  .int()
91
109
  .min(1)
92
110
  .max(5)
93
111
  .default(OwnerConstants.DEFAULT_HEADLINE_MAX_SENTENCES),
112
+ /** Whether file paths in a reply must be absolute; default `true`. */
94
113
  absolutePaths: z.boolean().default(true),
114
+ /** Whether the session digest shows the shape card: `off` leaves it out, `advise` and `block` show it; default `advise`. */
95
115
  enforce: ENFORCE.default(OwnerEnforcement.ADVISE),
96
- /** Words that say something is in public state, or that the checks pass, in the owner's language, added to the English ones. */
97
- claimWords: z
98
- .strictObject({
99
- public: CLAIM_WORDS.default([]),
100
- done: CLAIM_WORDS.default([]),
101
- })
102
- .prefault({}),
103
- /** Replies under this many words are exempt from the shape; 0 holds every reply to it. */
104
- shortReplyWords: SHORT_REPLY_WORDS.default(OwnerConstants.DEFAULT_SHORT_REPLY_WORDS),
116
+ /** Removed with the reply check, the only thing that read it. */
117
+ claimWords: REMOVED_KEY({ fix: 'delete this key; the reply check that read it is gone' }),
118
+ /** Removed with the reply check, the only thing that read it. */
119
+ shortReplyWords: REMOVED_KEY({
120
+ fix: 'delete this key; the reply check that read it is gone',
121
+ }),
105
122
  })
106
123
  .prefault({}),
107
124
  })
@@ -109,35 +126,42 @@ export const OWNER_SCHEMA = z
109
126
 
110
127
  /** `.agents/local/profile.json`: what one developer told VULCAN about how to work with them. */
111
128
  export const PROFILE_SCHEMA = z.strictObject({
129
+ /** Version of the profile file format; must be `1`. */
112
130
  schemaVersion: z.literal(OwnerConstants.PROFILE_SCHEMA_VERSION),
113
131
  /** Reply language; labels for it come from `labels` below. A language that is not English with none has its labels written by the agent, and only the structure is checked. */
114
132
  language: LANGUAGE.optional(),
133
+ /** How the agent addresses the person: what it calls them, itself, and how formal; default neutral formality. */
115
134
  address: z
116
135
  .strictObject({
117
- /** How to address the person: a name, a pronoun, an honorific, or nothing. */
136
+ /** Form of address for the person: a name, pronoun or honorific, one line of at most 80 characters; absent means none. */
118
137
  you: TEXT.optional(),
119
- /** How the agent refers to itself. */
138
+ /** How the agent refers to itself, one line of at most 80 characters; absent means no fixed form. */
120
139
  self: TEXT.optional(),
140
+ /** How formal the address is: `informal`, `neutral` or `formal`; default `neutral`. */
121
141
  formality: FORMALITY.default(OwnerFormalities.NEUTRAL),
122
142
  })
123
143
  .prefault({}),
144
+ /** Tone of replies: `terse`, `neutral` or `friendly`; default `neutral`. */
124
145
  tone: TONE.default(OwnerTones.NEUTRAL),
146
+ /** How much a reply spells out: `headline` or `tables`; default `tables`. */
125
147
  reportDetail: DETAIL.default(OwnerDetails.TABLES),
148
+ /** Working habits the agent follows with this person; both default to `false`. */
126
149
  habits: z
127
150
  .strictObject({
128
151
  /** Ask before a reversible choice; false means state a default and continue (V-P-10). */
129
152
  askBeforeReversible: z.boolean().default(false),
153
+ /** Whether the agent is told to propose commits; default `false`. */
130
154
  proposeCommits: z.boolean().default(false),
131
155
  })
132
156
  .prefault({}),
133
- /** In the person's own words, never scored or used to infer traits. */
157
+ /** Free text in the person's own words, up to 2000 characters; the digest card shows the first 200, and it is never scored. */
134
158
  about: z.string().max(2000).optional(),
135
- /** Taste in code that no formatter or lint rule already enforces. */
159
+ /** Taste in code that no formatter or lint rule enforces, up to 1000 characters; absent means none. */
136
160
  codeTaste: z.string().max(1000).optional(),
137
- /** Stricter than the project's, never looser. */
161
+ /** Own enforcement level: `off`, `advise` or `block`; only counts when stricter than the project's, else the project's wins. */
138
162
  enforce: ENFORCE.optional(),
139
- /** Lower than the project's, never higher: 0 holds every reply to the shape. */
140
- shortReplyWords: SHORT_REPLY_WORDS.optional(),
163
+ /** Removed with the reply check, the only thing that read it. */
164
+ shortReplyWords: REMOVED_KEY({ fix: 'delete this key; the reply check that read it is gone' }),
141
165
  /** The label set of each language the person uses, keyed by language code. */
142
166
  labels: z.record(LANGUAGE, OWNER_LABEL_SET).default({}),
143
167
  });
@@ -292,9 +292,6 @@ export class OwnerSurvey {
292
292
  ...(about === '' || about === null ? {} : { about }),
293
293
  ...(codeTaste === '' || codeTaste === null ? {} : { codeTaste }),
294
294
  ...(existing?.enforce === undefined ? {} : { enforce: existing.enforce }),
295
- ...(existing?.shortReplyWords === undefined
296
- ? {}
297
- : { shortReplyWords: existing.shortReplyWords }),
298
295
  labels,
299
296
  });
300
297
  }
package/src/owner/view.ts CHANGED
@@ -12,10 +12,6 @@ export interface IOwnerView {
12
12
  headlineMaxSentences: number;
13
13
  absolutePaths: boolean;
14
14
  enforce: string;
15
- /** Replies under this many words are exempt from the shape: the lower of the project's and the person's. */
16
- shortReplyWords: number;
17
- /** Words that add to the English ones when a reply is checked for a claim its turn does not back. */
18
- claimWords: { public: string[]; done: string[] };
19
15
  /** Personal settings; absent when the person has no profile. */
20
16
  address: { you?: string; self?: string; formality: string } | undefined;
21
17
  tone: string | undefined;
@@ -79,11 +75,6 @@ export class OwnerView {
79
75
  first: owner.report.enforce,
80
76
  second: profile?.enforce,
81
77
  }),
82
- claimWords: owner.report.claimWords,
83
- shortReplyWords: Math.min(
84
- owner.report.shortReplyWords,
85
- profile?.shortReplyWords ?? owner.report.shortReplyWords,
86
- ),
87
78
  address: profile?.address,
88
79
  tone: profile?.tone,
89
80
  reportDetail: profile?.reportDetail,
package/src/router.ts CHANGED
@@ -1,138 +1,12 @@
1
- import { AgentConstants } from './agents/index.ts';
2
1
  import { COMMAND_LOADERS } from './commands/index.ts';
3
- import { BoardFlags } from './board/common/index.ts';
4
- import { CiFlags } from './ci/common/index.ts';
5
- import { CommitCheckFlags } from './commit/common/index.ts';
6
- import { ExitCodes, UpgradeFlags, VulcanCommands } from './common/index.ts';
7
- import { CreateFlags } from './create/common/index.ts';
8
- import { EventFlags } from './events/common/index.ts';
2
+ import { CommandTable } from './commands/table.ts';
3
+ import type { IAcceptedArgs } from './commands/table.ts';
4
+ import { ExitCodes, VulcanCommands } from './common/index.ts';
9
5
  import { PipedInputRefusal } from './ui/keyboard.ts';
10
6
 
11
7
  const HELP_ALIASES = new Set(['--help', '-h']);
12
8
  const VERSION_ALIASES = new Set(['--version', '-v']);
13
9
 
14
- interface IAcceptedArgs {
15
- flags: string[];
16
- /** The exit code for an argument the command does not take; `1` when absent. */
17
- unknownExit?: number;
18
- /** Flags that take the next argument as their value. */
19
- values: string[];
20
- positionals: number;
21
- }
22
-
23
- /** What each command takes; `x` hands everything to its tool, `help` and `version` take nothing. */
24
- const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
25
- [VulcanCommands.INIT]: {
26
- flags: [CreateFlags.NO_API],
27
- values: [
28
- CreateFlags.PRESET,
29
- CreateFlags.PROJECT,
30
- CreateFlags.BACKEND_DIR,
31
- CreateFlags.FRONTEND_DIR,
32
- CreateFlags.SHARED_DIR,
33
- CreateFlags.APP,
34
- CreateFlags.API,
35
- CreateFlags.SCOPE,
36
- CreateFlags.KEY,
37
- ],
38
- positionals: 0,
39
- },
40
- [VulcanCommands.ADD]: {
41
- flags: [CreateFlags.NO_API],
42
- values: [
43
- CreateFlags.PRESET,
44
- CreateFlags.BACKEND_DIR,
45
- CreateFlags.FRONTEND_DIR,
46
- CreateFlags.APP,
47
- CreateFlags.API,
48
- CreateFlags.LIB,
49
- CreateFlags.SHARED,
50
- CreateFlags.DIR,
51
- CreateFlags.SCOPE,
52
- ],
53
- positionals: 0,
54
- },
55
- [VulcanCommands.PRESET]: {
56
- flags: [CreateFlags.NO_API, CreateFlags.FULL, CreateFlags.CHECK],
57
- values: [CreateFlags.PRESET, CreateFlags.API],
58
- positionals: 2,
59
- },
60
- [VulcanCommands.SYNC]: {
61
- flags: ['--dry-run'],
62
- values: [AgentConstants.FLAG],
63
- positionals: 0,
64
- },
65
- [VulcanCommands.AGENTS]: { flags: ['--dry-run'], values: [], positionals: 2 },
66
- [VulcanCommands.CLEAN]: {
67
- flags: [
68
- '--tmp',
69
- '--worktrees',
70
- '--clones',
71
- '--cache',
72
- '--reports',
73
- '--prototypes',
74
- '--profile',
75
- '--events',
76
- '--release-candidates',
77
- '--all',
78
- '--yes',
79
- ],
80
- values: [],
81
- positionals: 0,
82
- },
83
- [VulcanCommands.COMMIT_CHECK]: {
84
- flags: [],
85
- unknownExit: ExitCodes.USAGE,
86
- values: [CommitCheckFlags.RANGE, CommitCheckFlags.TEXT],
87
- positionals: 2,
88
- },
89
- [VulcanCommands.BOARD]: {
90
- flags: [BoardFlags.OPEN, BoardFlags.NO_GITHUB],
91
- unknownExit: ExitCodes.USAGE,
92
- values: [BoardFlags.OUT, BoardFlags.PORT, BoardFlags.SINCE, BoardFlags.DIR, BoardFlags.REPO],
93
- positionals: 1,
94
- },
95
- [VulcanCommands.CI]: {
96
- flags: [CiFlags.JSON, CiFlags.NAMES],
97
- unknownExit: ExitCodes.USAGE,
98
- values: [CiFlags.BASE, CiFlags.HEAD, CiFlags.CHECK],
99
- positionals: 2,
100
- },
101
- [VulcanCommands.EVENT]: {
102
- flags: [EventFlags.JSON],
103
- unknownExit: ExitCodes.USAGE,
104
- values: [
105
- EventFlags.KIND,
106
- EventFlags.SUMMARY,
107
- EventFlags.FLOW,
108
- EventFlags.STEP,
109
- EventFlags.STEP_DONE,
110
- EventFlags.CHECK,
111
- EventFlags.CHECK_DONE,
112
- EventFlags.APP,
113
- EventFlags.DUE,
114
- EventFlags.REF,
115
- EventFlags.STATUS,
116
- EventFlags.TITLE,
117
- EventFlags.WHY,
118
- EventFlags.CONTEXT,
119
- EventFlags.NEXT,
120
- EventFlags.ACTOR,
121
- EventFlags.DIR,
122
- EventFlags.SINCE,
123
- ],
124
- positionals: 1,
125
- },
126
- [VulcanCommands.DOCTOR]: { flags: [], values: [], positionals: 0 },
127
- [VulcanCommands.PROFILE]: { flags: ['--yes'], values: [], positionals: 1 },
128
- [VulcanCommands.VISUALIZE]: { flags: ['--schema'], values: ['--out'], positionals: 1 },
129
- [VulcanCommands.UPGRADE]: {
130
- flags: [UpgradeFlags.STABLE, UpgradeFlags.NIGHTLY],
131
- values: [],
132
- positionals: 1,
133
- },
134
- };
135
-
136
10
  /** The command name an argv asks for: no argument or a help flag means help. */
137
11
  const resolveCommandName = (opts: { first: string | undefined }): string => {
138
12
  if (opts.first === undefined || HELP_ALIASES.has(opts.first)) {
@@ -180,7 +54,9 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
180
54
  const load = COMMAND_LOADERS[name];
181
55
 
182
56
  if (load === undefined) {
183
- process.stderr.write(`vulcan: unknown command '${name}' - run 'bun x vulcan help'\n`);
57
+ process.stderr.write(
58
+ `vulcan: unknown command '${name}' - run 'bun node_modules/.bin/vulcan help'\n`,
59
+ );
184
60
 
185
61
  return ExitCodes.FAILURE;
186
62
  }
@@ -190,7 +66,7 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
190
66
  return runHelp({ cwd: opts.cwd });
191
67
  }
192
68
 
193
- const accepted = ACCEPTED_ARGS[name];
69
+ const accepted = CommandTable.accepted({ name });
194
70
 
195
71
  if (accepted !== undefined) {
196
72
  if (args.some((arg) => HELP_ALIASES.has(arg))) {
@@ -201,7 +77,7 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
201
77
 
202
78
  if (unknown !== undefined) {
203
79
  process.stderr.write(
204
- `vulcan ${name}: unknown argument '${unknown}' - run 'bun x vulcan help'\n`,
80
+ `vulcan ${name}: unknown argument '${unknown}' - run 'bun node_modules/.bin/vulcan help'\n`,
205
81
  );
206
82
 
207
83
  return accepted.unknownExit ?? ExitCodes.FAILURE;
package/src/rules/base.ts CHANGED
@@ -1,19 +1,24 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { BASE_DIRECTORY } from '../common/index.ts';
4
+ import { RulePacks } from './packs.ts';
4
5
  import { RuleParser } from './parser.ts';
5
6
 
6
7
  const readBaseMarkdown = (): string => readFileSync(join(BASE_DIRECTORY, 'rules.md'), 'utf8');
7
8
 
9
+ /** Reads the base rule file shipped with the CLI as a map of rule ID to text; used by `vulcan sync` and `vulcan doctor`. */
8
10
  export class BaseRules {
9
- /** Each base rule's ID with its table row, verbatim. */
10
- static read(): Record<string, string> {
11
- return Object.fromEntries(
12
- RuleParser.extractRows({ markdown: readBaseMarkdown() }).map((row) => {
13
- const [id] = RuleParser.parseIds({ markdown: row });
11
+ /** Each base rule's ID with its table row, verbatim, and the rows of each rule pack named in `packs`. */
12
+ static read(opts: { packs?: string[] } = {}): Record<string, string> {
13
+ return Object.assign(
14
+ Object.fromEntries(
15
+ RuleParser.extractRows({ markdown: readBaseMarkdown() }).map((row) => {
16
+ const [id] = RuleParser.parseIds({ markdown: row });
14
17
 
15
- return [id, row];
16
- }),
18
+ return [id, row];
19
+ }),
20
+ ),
21
+ ...(opts.packs ?? []).map((name) => RulePacks.rowsOf({ name })),
17
22
  );
18
23
  }
19
24
  }
@@ -1,4 +1,5 @@
1
1
  export * from './common/index.ts';
2
2
  export * from './base.ts';
3
+ export * from './packs.ts';
3
4
  export * from './parser.ts';
4
5
  export * from './slots.ts';
@@ -0,0 +1,44 @@
1
+ import { existsSync, readdirSync, readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { BASE_DIRECTORY } from '../common/index.ts';
4
+ import { RuleParser } from './parser.ts';
5
+
6
+ const PACKS_DIRECTORY = join(BASE_DIRECTORY, 'packs');
7
+
8
+ /** The rule packs shipped with the CLI: a markdown file of rule rows for one stack, which a project turns on with `packs` in its config. */
9
+ export class RulePacks {
10
+ /** The shipped packs, by name. */
11
+ static names(): string[] {
12
+ return existsSync(PACKS_DIRECTORY)
13
+ ? readdirSync(PACKS_DIRECTORY)
14
+ .filter((file) => file.endsWith('.md'))
15
+ .map((file) => file.slice(0, -'.md'.length))
16
+ .sort()
17
+ : [];
18
+ }
19
+
20
+ /** Where a pack's rules are, from the project root's `node_modules`, as the rules block names it. */
21
+ static pathOf(opts: { name: string }): string {
22
+ return `node_modules/@venizia/vulcan/base/packs/${opts.name}.md`;
23
+ }
24
+
25
+ /** The rows of one pack, each rule's ID with its table row verbatim; a name that is no shipped pack has none. */
26
+ static rowsOf(opts: { name: string }): Record<string, string> {
27
+ const file = join(PACKS_DIRECTORY, `${opts.name}.md`);
28
+
29
+ // Only a name the folder lists: `../rules` is not a pack.
30
+ return RulePacks.names().includes(opts.name) && existsSync(file)
31
+ ? Object.fromEntries(
32
+ RuleParser.extractRows({ markdown: readFileSync(file, 'utf8') }).map((row) => [
33
+ RuleParser.parseIds({ markdown: row })[0],
34
+ row,
35
+ ]),
36
+ )
37
+ : {};
38
+ }
39
+
40
+ /** The shipped pack that holds rule `id`, or `undefined`: what `doctor` says when a project cites a rule of a pack it did not turn on. */
41
+ static holderOf(opts: { id: string }): string | undefined {
42
+ return RulePacks.names().find((name) => RulePacks.rowsOf({ name })[opts.id] !== undefined);
43
+ }
44
+ }
@@ -0,0 +1,130 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { ProjectGuards } from '../hooks/project-guards.ts';
4
+ import { RunnerScan } from '../hooks/runner-scan.ts';
5
+
6
+ /** One command in a tracked file that runs a package fetched by name. */
7
+ export interface IRunnerFinding {
8
+ /** Repository-relative path. */
9
+ file: string;
10
+ line: number;
11
+ /** The package or bin the command would fetch. */
12
+ name: string;
13
+ /** The runner as written. */
14
+ runner: string;
15
+ }
16
+
17
+ /** What a scan found: the commands to fix, and how many refused commands a Markdown file marked as examples. */
18
+ export interface IRunnersScan {
19
+ findings: IRunnerFinding[];
20
+ examples: number;
21
+ }
22
+
23
+ const MAX_BYTES = 1024 * 1024;
24
+ /** Not instructions: a lockfile, a build output, a vendored folder, a test, a fixture. */
25
+ const SKIPPED_PATH =
26
+ /(^|\/)(node_modules|dist|build|coverage|__tests__|__fixtures__|fixtures)\/|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(bun\.lockb?|package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$/;
27
+ /** A dated changelog file: history, frozen once written. */
28
+ const DATED_ENTRY = /(^|\/)changelogs?\/\d{4}-\d{2}-\d{2}-[^/]*\.md$/;
29
+ /** A file of a version folder, whose `log.md` says `released:` once the stable is out. */
30
+ const VERSION_FILE = /^(.*\/)?(\d+\.\d+\.\d+)\/(log\.md|migration\.yaml)$/;
31
+ /** The only files that may set a command apart as an example: prose. A script, a workflow or a Makefile never can. */
32
+ const MARKDOWN = /\.mdx?$/i;
33
+ const BINARY_EXTENSION = /\.(png|jpe?g|gif|webp|ico|pdf|woff2?|ttf|eot|zip|gz|tgz|wasm|mp4|mov)$/i;
34
+
35
+ /**
36
+ * `vulcan runners check`: no tracked file of the project may run an unscoped package through `bunx`, `bun x`, `npx`,
37
+ * `pnpm dlx`, `pnpx` or `yarn dlx`, with or without `--no-install`. A scoped package (`@scope/name`) passes. A name npm owns for somebody else would be fetched and run
38
+ * wherever the bin is not linked, and bun runs a copy an earlier bare bunx saved even under `--no-install`. The safe
39
+ * form is `bun node_modules/.bin/<bin>` from the project root (or a make target); `bun run <bin>` is a fallback.
40
+ */
41
+ export class RunnersCheck {
42
+ private static trackedFiles(opts: { root: string }): string[] {
43
+ const listed = Bun.spawnSync(['git', 'ls-files', '-z'], {
44
+ cwd: opts.root,
45
+ stdout: 'pipe',
46
+ stderr: 'pipe',
47
+ });
48
+
49
+ if (listed.exitCode !== 0) {
50
+ throw new Error(`git ls-files failed in ${opts.root}: ${listed.stderr.toString().trim()}`);
51
+ }
52
+
53
+ return listed.stdout
54
+ .toString()
55
+ .split('\0')
56
+ .filter((file) => file !== '');
57
+ }
58
+
59
+ /** Whether the history of the project owns `file`: a dated entry, or a file of a version folder already released. */
60
+ private static isFrozen(opts: { root: string; file: string }): boolean {
61
+ if (DATED_ENTRY.test(opts.file)) {
62
+ return true;
63
+ }
64
+
65
+ const version = VERSION_FILE.exec(opts.file);
66
+
67
+ if (version === null) {
68
+ return false;
69
+ }
70
+
71
+ try {
72
+ return /^released:/m.test(
73
+ readFileSync(join(opts.root, `${version[1] ?? ''}${version[2]}`, 'log.md'), 'utf8'),
74
+ );
75
+ } catch {
76
+ return false;
77
+ }
78
+ }
79
+
80
+ static scan(opts: { root: string }): IRunnersScan {
81
+ const { runnersAllow } = ProjectGuards.readPolicy({ root: opts.root });
82
+ const findings: IRunnerFinding[] = [];
83
+ let examples = 0;
84
+
85
+ for (const file of RunnersCheck.trackedFiles({ root: opts.root })) {
86
+ if (
87
+ SKIPPED_PATH.test(file) ||
88
+ BINARY_EXTENSION.test(file) ||
89
+ RunnersCheck.isFrozen({ root: opts.root, file })
90
+ ) {
91
+ continue;
92
+ }
93
+
94
+ let text: string;
95
+
96
+ try {
97
+ const buffer = readFileSync(join(opts.root, file));
98
+
99
+ if (buffer.length > MAX_BYTES || buffer.subarray(0, 8000).includes(0)) {
100
+ continue;
101
+ }
102
+
103
+ text = buffer.toString('utf8');
104
+ } catch {
105
+ continue;
106
+ }
107
+
108
+ for (const use of RunnerScan.find({ text, isMarkdown: MARKDOWN.test(file) })) {
109
+ const name = RunnerScan.refusedName({ use, allow: runnersAllow, isFile: true });
110
+
111
+ if (name === undefined) {
112
+ continue;
113
+ }
114
+
115
+ if (use.isExample) {
116
+ examples += 1;
117
+ } else {
118
+ findings.push({
119
+ file,
120
+ line: use.line,
121
+ name,
122
+ runner: `${use.runner}${use.hasNoInstall ? ' --no-install' : ''}`,
123
+ });
124
+ }
125
+ }
126
+ }
127
+
128
+ return { findings, examples };
129
+ }
130
+ }
@@ -8,6 +8,7 @@ const parseYaml = (opts: { text: string }): { value?: unknown; error?: string }
8
8
  }
9
9
  };
10
10
 
11
+ /** Extracts and validates the YAML frontmatter of a skill file; used by the doctor skill checks. */
11
12
  export class SkillFrontmatter {
12
13
  /**
13
14
  * The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line