@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/owner/schema.ts
CHANGED
|
@@ -37,34 +37,45 @@ const DETAIL = choice({
|
|
|
37
37
|
set: OwnerDetails.SCHEME_SET,
|
|
38
38
|
});
|
|
39
39
|
|
|
40
|
-
/** A
|
|
41
|
-
const
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
.
|
|
46
|
-
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
97
|
-
claimWords:
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
140
|
-
shortReplyWords:
|
|
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
|
});
|
package/src/owner/survey.ts
CHANGED
|
@@ -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 {
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
6
|
-
import { ExitCodes, UpgradeFlags, VulcanCommands } from './common/index.ts';
|
|
7
|
-
import { CreateFlags } from './create/common/index.ts';
|
|
8
|
-
import { EventFlags } from './events/common/index.ts';
|
|
2
|
+
import { CommandTable } from './commands/table.ts';
|
|
3
|
+
import type { IAcceptedArgs } from './commands/table.ts';
|
|
4
|
+
import { ExitCodes, VulcanCommands } from './common/index.ts';
|
|
9
5
|
import { PipedInputRefusal } from './ui/keyboard.ts';
|
|
10
6
|
|
|
11
7
|
const HELP_ALIASES = new Set(['--help', '-h']);
|
|
12
8
|
const VERSION_ALIASES = new Set(['--version', '-v']);
|
|
13
9
|
|
|
14
|
-
interface IAcceptedArgs {
|
|
15
|
-
flags: string[];
|
|
16
|
-
/** The exit code for an argument the command does not take; `1` when absent. */
|
|
17
|
-
unknownExit?: number;
|
|
18
|
-
/** Flags that take the next argument as their value. */
|
|
19
|
-
values: string[];
|
|
20
|
-
positionals: number;
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
/** What each command takes; `x` hands everything to its tool, `help` and `version` take nothing. */
|
|
24
|
-
const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
|
|
25
|
-
[VulcanCommands.INIT]: {
|
|
26
|
-
flags: [CreateFlags.NO_API],
|
|
27
|
-
values: [
|
|
28
|
-
CreateFlags.PRESET,
|
|
29
|
-
CreateFlags.PROJECT,
|
|
30
|
-
CreateFlags.BACKEND_DIR,
|
|
31
|
-
CreateFlags.FRONTEND_DIR,
|
|
32
|
-
CreateFlags.SHARED_DIR,
|
|
33
|
-
CreateFlags.APP,
|
|
34
|
-
CreateFlags.API,
|
|
35
|
-
CreateFlags.SCOPE,
|
|
36
|
-
CreateFlags.KEY,
|
|
37
|
-
],
|
|
38
|
-
positionals: 0,
|
|
39
|
-
},
|
|
40
|
-
[VulcanCommands.ADD]: {
|
|
41
|
-
flags: [CreateFlags.NO_API],
|
|
42
|
-
values: [
|
|
43
|
-
CreateFlags.PRESET,
|
|
44
|
-
CreateFlags.BACKEND_DIR,
|
|
45
|
-
CreateFlags.FRONTEND_DIR,
|
|
46
|
-
CreateFlags.APP,
|
|
47
|
-
CreateFlags.API,
|
|
48
|
-
CreateFlags.LIB,
|
|
49
|
-
CreateFlags.SHARED,
|
|
50
|
-
CreateFlags.DIR,
|
|
51
|
-
CreateFlags.SCOPE,
|
|
52
|
-
],
|
|
53
|
-
positionals: 0,
|
|
54
|
-
},
|
|
55
|
-
[VulcanCommands.PRESET]: {
|
|
56
|
-
flags: [CreateFlags.NO_API, CreateFlags.FULL, CreateFlags.CHECK],
|
|
57
|
-
values: [CreateFlags.PRESET, CreateFlags.API],
|
|
58
|
-
positionals: 2,
|
|
59
|
-
},
|
|
60
|
-
[VulcanCommands.SYNC]: {
|
|
61
|
-
flags: ['--dry-run'],
|
|
62
|
-
values: [AgentConstants.FLAG],
|
|
63
|
-
positionals: 0,
|
|
64
|
-
},
|
|
65
|
-
[VulcanCommands.AGENTS]: { flags: ['--dry-run'], values: [], positionals: 2 },
|
|
66
|
-
[VulcanCommands.CLEAN]: {
|
|
67
|
-
flags: [
|
|
68
|
-
'--tmp',
|
|
69
|
-
'--worktrees',
|
|
70
|
-
'--clones',
|
|
71
|
-
'--cache',
|
|
72
|
-
'--reports',
|
|
73
|
-
'--prototypes',
|
|
74
|
-
'--profile',
|
|
75
|
-
'--events',
|
|
76
|
-
'--release-candidates',
|
|
77
|
-
'--all',
|
|
78
|
-
'--yes',
|
|
79
|
-
],
|
|
80
|
-
values: [],
|
|
81
|
-
positionals: 0,
|
|
82
|
-
},
|
|
83
|
-
[VulcanCommands.COMMIT_CHECK]: {
|
|
84
|
-
flags: [],
|
|
85
|
-
unknownExit: ExitCodes.USAGE,
|
|
86
|
-
values: [CommitCheckFlags.RANGE, CommitCheckFlags.TEXT],
|
|
87
|
-
positionals: 2,
|
|
88
|
-
},
|
|
89
|
-
[VulcanCommands.BOARD]: {
|
|
90
|
-
flags: [BoardFlags.OPEN, BoardFlags.NO_GITHUB],
|
|
91
|
-
unknownExit: ExitCodes.USAGE,
|
|
92
|
-
values: [BoardFlags.OUT, BoardFlags.PORT, BoardFlags.SINCE, BoardFlags.DIR, BoardFlags.REPO],
|
|
93
|
-
positionals: 1,
|
|
94
|
-
},
|
|
95
|
-
[VulcanCommands.CI]: {
|
|
96
|
-
flags: [CiFlags.JSON, CiFlags.NAMES],
|
|
97
|
-
unknownExit: ExitCodes.USAGE,
|
|
98
|
-
values: [CiFlags.BASE, CiFlags.HEAD, CiFlags.CHECK],
|
|
99
|
-
positionals: 2,
|
|
100
|
-
},
|
|
101
|
-
[VulcanCommands.EVENT]: {
|
|
102
|
-
flags: [EventFlags.JSON],
|
|
103
|
-
unknownExit: ExitCodes.USAGE,
|
|
104
|
-
values: [
|
|
105
|
-
EventFlags.KIND,
|
|
106
|
-
EventFlags.SUMMARY,
|
|
107
|
-
EventFlags.FLOW,
|
|
108
|
-
EventFlags.STEP,
|
|
109
|
-
EventFlags.STEP_DONE,
|
|
110
|
-
EventFlags.CHECK,
|
|
111
|
-
EventFlags.CHECK_DONE,
|
|
112
|
-
EventFlags.APP,
|
|
113
|
-
EventFlags.DUE,
|
|
114
|
-
EventFlags.REF,
|
|
115
|
-
EventFlags.STATUS,
|
|
116
|
-
EventFlags.TITLE,
|
|
117
|
-
EventFlags.WHY,
|
|
118
|
-
EventFlags.CONTEXT,
|
|
119
|
-
EventFlags.NEXT,
|
|
120
|
-
EventFlags.ACTOR,
|
|
121
|
-
EventFlags.DIR,
|
|
122
|
-
EventFlags.SINCE,
|
|
123
|
-
],
|
|
124
|
-
positionals: 1,
|
|
125
|
-
},
|
|
126
|
-
[VulcanCommands.DOCTOR]: { flags: [], values: [], positionals: 0 },
|
|
127
|
-
[VulcanCommands.PROFILE]: { flags: ['--yes'], values: [], positionals: 1 },
|
|
128
|
-
[VulcanCommands.VISUALIZE]: { flags: ['--schema'], values: ['--out'], positionals: 1 },
|
|
129
|
-
[VulcanCommands.UPGRADE]: {
|
|
130
|
-
flags: [UpgradeFlags.STABLE, UpgradeFlags.NIGHTLY],
|
|
131
|
-
values: [],
|
|
132
|
-
positionals: 1,
|
|
133
|
-
},
|
|
134
|
-
};
|
|
135
|
-
|
|
136
10
|
/** The command name an argv asks for: no argument or a help flag means help. */
|
|
137
11
|
const resolveCommandName = (opts: { first: string | undefined }): string => {
|
|
138
12
|
if (opts.first === undefined || HELP_ALIASES.has(opts.first)) {
|
|
@@ -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(
|
|
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 =
|
|
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
|
|
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.
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
|
|
16
|
-
|
|
18
|
+
return [id, row];
|
|
19
|
+
}),
|
|
20
|
+
),
|
|
21
|
+
...(opts.packs ?? []).map((name) => RulePacks.rowsOf({ name })),
|
|
17
22
|
);
|
|
18
23
|
}
|
|
19
24
|
}
|
package/src/rules/index.ts
CHANGED
|
@@ -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
|