@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
@@ -23,10 +23,14 @@ export const SUBAGENT_CARD = [
23
23
  '',
24
24
  ].join('\n');
25
25
 
26
- /** The SubagentStart answer: the card as the subagent's added context. */
27
- export const buildSubagentStartOutput = () => ({
28
- hookSpecificOutput: {
29
- hookEventName: HookConstants.SUBAGENT_START,
30
- additionalContext: SUBAGENT_CARD,
31
- },
32
- });
26
+ export class SubagentCard {
27
+ /** The SubagentStart answer: the card as the subagent's added context. */
28
+ static buildStartOutput() {
29
+ return {
30
+ hookSpecificOutput: {
31
+ hookEventName: HookConstants.SUBAGENT_START,
32
+ additionalContext: SUBAGENT_CARD,
33
+ },
34
+ };
35
+ }
36
+ }
@@ -2,7 +2,8 @@ import { spawnSync } from 'node:child_process';
2
2
  import { existsSync, realpathSync } from 'node:fs';
3
3
  import { isAbsolute, join, relative, resolve, sep } from 'node:path';
4
4
  import { HookConstants, TrustStates } from './common/index.ts';
5
- import type { IScriptTrust } from './common/index.ts';
5
+ import type { IReadOnlyScript, IScriptInvocation, IScriptTrust } from './common/index.ts';
6
+ import { ShellParser } from './shell.ts';
6
7
 
7
8
  /** Variables that point git at another repository or index than the one in `cwd`. */
8
9
  const REDIRECTING_VARIABLES = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE'];
@@ -33,102 +34,179 @@ const gitQuery = (opts: { cwd: string; args: string[] }): string | undefined =>
33
34
 
34
35
  const untrusted = (opts: { state: IScriptTrust['state']; reason: string }): IScriptTrust => opts;
35
36
 
36
- /**
37
- * Whether the listed script `script` (repo-relative) may skip the script checks of guard-writes: only
38
- * while git tracks it and its worktree file, its index entry and HEAD hold the same bytes. A script an
39
- * agent edited and then runs is therefore checked like any other; so is one that was never committed.
40
- * The blobs are compared, not `git status`, so `--assume-unchanged` and `--skip-worktree` hide nothing.
41
- */
42
- export const trustOf = (opts: { root: string; script: string }): IScriptTrust => {
43
- const path = resolve(opts.root, opts.script);
44
-
45
- if (!existsSync(path)) {
46
- return untrusted({ state: TrustStates.MISSING, reason: 'the file does not exist' });
37
+ export class ScriptPaths {
38
+ /**
39
+ * The script word as the shell opens it: joined to the working folder without folding `..`, so a link
40
+ * before a `..` is followed the way the shell follows it.
41
+ */
42
+ static targetPath(opts: { target: string; cwd: string }): string {
43
+ return isAbsolute(opts.target) ? opts.target : `${opts.cwd}${sep}${opts.target}`;
47
44
  }
48
45
 
49
- const root = realpathSync(opts.root);
50
- const real = realpathSync(path);
51
-
52
- // A link could point at an untracked file that git never looks at.
53
- if (real !== join(root, relative(resolve(opts.root), path))) {
54
- return untrusted({
55
- state: TrustStates.SYMLINK,
56
- reason: 'its path goes through a symlink, which git does not follow',
57
- });
46
+ /** The file `path` is on disk, links followed by the OS; the path folded as written when nothing is there. */
47
+ static physicalOf(opts: { path: string }): string {
48
+ try {
49
+ return realpathSync.native(opts.path);
50
+ } catch {
51
+ return resolve(opts.path);
52
+ }
58
53
  }
54
+ }
55
+
56
+ export class ScriptTrust {
57
+ /**
58
+ * Whether the listed script `script` (repo-relative) may skip the script checks of guard-writes: only
59
+ * while git tracks it and its worktree file, its index entry and HEAD hold the same bytes. A script an
60
+ * agent edited and then runs is therefore checked like any other; so is one that was never committed.
61
+ * The blobs are compared, not `git status`, so `--assume-unchanged` and `--skip-worktree` hide nothing.
62
+ */
63
+ static trustOf(opts: { root: string; script: string }): IScriptTrust {
64
+ const path = resolve(opts.root, opts.script);
65
+
66
+ if (!existsSync(path)) {
67
+ return untrusted({ state: TrustStates.MISSING, reason: 'the file does not exist' });
68
+ }
69
+
70
+ const root = realpathSync(opts.root);
71
+ const real = realpathSync(path);
72
+
73
+ // A link could point at an untracked file that git never looks at.
74
+ if (real !== join(root, relative(resolve(opts.root), path))) {
75
+ return untrusted({
76
+ state: TrustStates.SYMLINK,
77
+ reason: 'its path goes through a symlink, which git does not follow',
78
+ });
79
+ }
80
+
81
+ const repoPath = relative(root, real).split(sep).join('/');
82
+ const entry = gitQuery({
83
+ cwd: root,
84
+ args: ['ls-files', '--stage', '--', `:(literal)${repoPath}`],
85
+ });
59
86
 
60
- const repoPath = relative(root, real).split(sep).join('/');
61
- const entry = gitQuery({
62
- cwd: root,
63
- args: ['ls-files', '--stage', '--', `:(literal)${repoPath}`],
64
- });
65
-
66
- if (entry === undefined) {
67
- return untrusted({
68
- state: TrustStates.UNKNOWN,
69
- reason: 'git could not say whether it is tracked',
87
+ if (entry === undefined) {
88
+ return untrusted({
89
+ state: TrustStates.UNKNOWN,
90
+ reason: 'git could not say whether it is tracked',
91
+ });
92
+ }
93
+
94
+ if (entry === '') {
95
+ return untrusted({ state: TrustStates.UNTRACKED, reason: 'it is not tracked by git' });
96
+ }
97
+
98
+ const [mode, indexBlob, stage] = entry.split('\n')[0].split(/\s+/);
99
+
100
+ if (mode === SYMLINK_MODE) {
101
+ return untrusted({
102
+ state: TrustStates.SYMLINK,
103
+ reason: 'it is a symlink, which git does not follow',
104
+ });
105
+ }
106
+
107
+ if (stage !== '0') {
108
+ return untrusted({
109
+ state: TrustStates.MODIFIED,
110
+ reason: 'modified trusted script (it has an unresolved merge)',
111
+ });
112
+ }
113
+
114
+ const headBlob = gitQuery({
115
+ cwd: root,
116
+ args: ['rev-parse', '--verify', '--quiet', `HEAD:./${repoPath}`],
70
117
  });
71
- }
72
118
 
73
- if (entry === '') {
74
- return untrusted({ state: TrustStates.UNTRACKED, reason: 'it is not tracked by git' });
119
+ if (headBlob === undefined) {
120
+ return untrusted({
121
+ state: TrustStates.UNCOMMITTED,
122
+ reason: 'it is not in the last commit yet',
123
+ });
124
+ }
125
+
126
+ const workBlob = gitQuery({ cwd: root, args: ['hash-object', '--', real] });
127
+
128
+ if (workBlob === undefined) {
129
+ return untrusted({
130
+ state: TrustStates.UNKNOWN,
131
+ reason: 'git could not read the file',
132
+ });
133
+ }
134
+
135
+ if (workBlob !== headBlob || indexBlob !== headBlob) {
136
+ return untrusted({
137
+ state: TrustStates.MODIFIED,
138
+ reason: `modified trusted script (${workBlob === headBlob ? 'the index' : 'the working tree'} differs from the last commit)`,
139
+ });
140
+ }
141
+
142
+ return { state: TrustStates.TRUSTED, reason: 'tracked, and identical to the last commit' };
75
143
  }
76
144
 
77
- const [mode, indexBlob, stage] = entry.split('\n')[0].split(/\s+/);
78
-
79
- if (mode === SYMLINK_MODE) {
80
- return untrusted({
81
- state: TrustStates.SYMLINK,
82
- reason: 'it is a symlink, which git does not follow',
145
+ /** The listed script `target` names, if any: both resolved to the file on disk, an exact match. */
146
+ static listedOf(opts: {
147
+ target: string;
148
+ cwd: string;
149
+ root: string;
150
+ scripts: string[];
151
+ }): string | undefined {
152
+ const path = ScriptPaths.physicalOf({
153
+ path: ScriptPaths.targetPath({ target: opts.target, cwd: opts.cwd }),
83
154
  });
84
- }
85
155
 
86
- if (stage !== '0') {
87
- return untrusted({
88
- state: TrustStates.MODIFIED,
89
- reason: 'modified trusted script (it has an unresolved merge)',
90
- });
156
+ return opts.scripts.find(
157
+ (script) => ScriptPaths.physicalOf({ path: resolve(opts.root, script) }) === path,
158
+ );
91
159
  }
160
+ }
92
161
 
93
- const headBlob = gitQuery({
94
- cwd: root,
95
- args: ['rev-parse', '--verify', '--quiet', `HEAD:./${repoPath}`],
96
- });
162
+ export class ReadOnlyScripts {
163
+ /**
164
+ * The `bun x.ts` calls of a command line, in order, one per simple command: the script word and the word
165
+ * right after it. The words are the shell's own, so a quoted `"plan x"` stays one word and a `;` or `&&`
166
+ * ends the command and is never part of one.
167
+ */
168
+ static extractInvocations(opts: { command: string }): IScriptInvocation[] {
169
+ let moved = false;
97
170
 
98
- if (headBlob === undefined) {
99
- return untrusted({
100
- state: TrustStates.UNCOMMITTED,
101
- reason: 'it is not in the last commit yet',
102
- });
103
- }
171
+ return ShellParser.parse({ command: opts.command }).flatMap((command) => {
172
+ const { name, args } = ShellParser.programOf({ command });
173
+ const program = ShellParser.basenameOf({ word: name });
174
+
175
+ if (ReadOnlyScripts.MOVING_COMMANDS.has(program)) {
176
+ moved = true;
177
+ }
178
+
179
+ if (program !== 'bun') {
180
+ return [];
181
+ }
104
182
 
105
- const workBlob = gitQuery({ cwd: root, args: ['hash-object', '--', real] });
183
+ const [script, subcommand] = args[0] === 'run' ? args.slice(1) : args;
106
184
 
107
- if (workBlob === undefined) {
108
- return untrusted({
109
- state: TrustStates.UNKNOWN,
110
- reason: 'git could not read the file',
185
+ return script !== undefined && script.endsWith('.ts') ? [{ script, subcommand, moved }] : [];
111
186
  });
112
187
  }
113
188
 
114
- if (workBlob !== headBlob || indexBlob !== headBlob) {
115
- return untrusted({
116
- state: TrustStates.MODIFIED,
117
- reason: `modified trusted script (${workBlob === headBlob ? 'the index' : 'the working tree'} differs from the last commit)`,
189
+ /** Commands that change the folder the next commands of the line run in, which the hook does not follow. */
190
+ static readonly MOVING_COMMANDS = new Set(['cd', 'pushd', 'popd']);
191
+
192
+ /**
193
+ * The listed script a call to `target` with `subcommand` is read-only for: both resolved to absolute
194
+ * paths, the subcommand matched as one whole word. `undefined` when no entry covers this call.
195
+ */
196
+ static find(opts: {
197
+ target: string;
198
+ subcommand: string;
199
+ cwd: string;
200
+ root: string;
201
+ entries: IReadOnlyScript[];
202
+ }): string | undefined {
203
+ return ScriptTrust.listedOf({
204
+ target: opts.target,
205
+ cwd: opts.cwd,
206
+ root: opts.root,
207
+ scripts: opts.entries
208
+ .filter((entry) => entry.readOnly.includes(opts.subcommand))
209
+ .map((entry) => entry.script),
118
210
  });
119
211
  }
120
-
121
- return { state: TrustStates.TRUSTED, reason: 'tracked, and identical to the last commit' };
122
- };
123
-
124
- /** The listed script `target` names, if any: both resolved to absolute paths, an exact match. */
125
- export const listedScriptOf = (opts: {
126
- target: string;
127
- cwd: string;
128
- root: string;
129
- scripts: string[];
130
- }): string | undefined => {
131
- const path = isAbsolute(opts.target) ? resolve(opts.target) : resolve(opts.cwd, opts.target);
132
-
133
- return opts.scripts.find((script) => resolve(opts.root, script) === path);
134
- };
212
+ }
@@ -1,7 +1,7 @@
1
1
  import type { TConstValue } from '../../common/index.ts';
2
2
  import type { InitStatuses } from './constants.ts';
3
3
 
4
- export type TInitStatus = TConstValue<typeof InitStatuses>;
4
+ type TInitStatus = TConstValue<typeof InitStatuses>;
5
5
 
6
6
  /** One line of the init report: a file created or kept, or a line the user should add by hand. */
7
7
  export interface IInitEntry {
@@ -1,12 +1,12 @@
1
1
  import { Glob } from 'bun';
2
2
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
3
3
  import { basename, dirname, join, relative } from 'node:path';
4
- import { BASE_DIRECTORY, ProjectLayout, readProperty } from '../common/index.ts';
5
- import { ConfigConstants, findConfigFiles } from '../config/index.ts';
4
+ import { BASE_DIRECTORY, JsonValue, ProjectLayout } from '../common/index.ts';
5
+ import { ConfigConstants, ConfigLoader } from '../config/index.ts';
6
6
  import type { TConfigExtension } from '../config/index.ts';
7
7
  import { InitConstants, InitStatuses } from './common/index.ts';
8
- import { renderBunfig } from '../create/bunfig.ts';
9
- import { renderDockerignore } from '../create/dockerignore.ts';
8
+ import { Bunfig } from '../create/bunfig.ts';
9
+ import { Dockerignore } from '../create/dockerignore.ts';
10
10
  import type { IInitEntry, IScaffoldFile } from './common/index.ts';
11
11
 
12
12
  /** The atlas entry of the root `.mcp.json`, as `sync` writes it and `doctor` shows it. */
@@ -26,7 +26,7 @@ const LINT_CONFIG_FILES: IScaffoldFile[] = [
26
26
  { path: '.configs/lints/eslint.config.mjs', template: 'eslint.config.mjs' },
27
27
  ];
28
28
 
29
- export interface IScaffoldResult {
29
+ interface IScaffoldResult {
30
30
  entries: IInitEntry[];
31
31
  /** Packages to `bun add -d`, empty when everything is declared. */
32
32
  install: string[];
@@ -61,60 +61,13 @@ const readManifest = (opts: { root: string }): IPackageManifest | undefined => {
61
61
  }
62
62
  };
63
63
 
64
- /** Whether the root `package.json` declares workspaces: the array form or `{ packages: [...] }`. */
65
- export const declaresWorkspaces = (opts: { root: string }): boolean => {
66
- const workspaces = readManifest(opts)?.workspaces;
67
-
68
- return Array.isArray(workspaces) || (typeof workspaces === 'object' && workspaces !== null);
69
- };
70
-
71
- /** The root workspace globs, from either form; empty when there are none. */
72
- export const readWorkspaceGlobs = (opts: { root: string }): string[] => {
73
- const workspaces = readManifest(opts)?.workspaces;
74
-
75
- if (Array.isArray(workspaces)) {
76
- return workspaces.map(String);
77
- }
78
-
79
- const packages = readProperty({ value: workspaces, key: 'packages' });
80
-
81
- return Array.isArray(packages) ? packages.map(String) : [];
82
- };
83
-
84
- /**
85
- * Whether a workspace glob list covers the packages directly under `folder`: `folder/*` or
86
- * `folder/**`, with or without a leading `./`, or any glob that matches a package there
87
- * (`auroras/*\/*` covers `auroras/apps`).
88
- */
89
- export const coversFolder = (opts: { globs: string[]; folder: string }): boolean =>
90
- opts.globs.some((glob) => {
91
- const plain = glob.replace(/^\.\//, '');
92
-
93
- // A negation (`!umbras/legacy`) excludes packages; it never covers a folder.
94
- if (plain.startsWith('!')) {
95
- return false;
96
- }
97
-
98
- return (
99
- plain === `${opts.folder}/*` ||
100
- plain === `${opts.folder}/**` ||
101
- new Glob(plain).match(`${opts.folder}/package-probe`)
102
- );
103
- });
104
-
105
64
  /** The `package.json` name, or the directory name when there is none. */
106
- export const resolveProjectName = (opts: { root: string }): string => {
65
+ const resolveProjectName = (opts: { root: string }): string => {
107
66
  const name = readManifest(opts)?.name;
108
67
 
109
68
  return typeof name === 'string' && name !== '' ? name : basename(opts.root);
110
69
  };
111
70
 
112
- export const renderTemplate = (opts: { template: string; name: string }): string =>
113
- readFileSync(join(BASE_DIRECTORY, 'templates', opts.template), 'utf8').replaceAll(
114
- InitConstants.NAME_TOKEN,
115
- opts.name,
116
- );
117
-
118
71
  const writeIfAbsent = (opts: { root: string; path: string; content: string }): IInitEntry => {
119
72
  const target = join(opts.root, opts.path);
120
73
 
@@ -128,100 +81,150 @@ const writeIfAbsent = (opts: { root: string; path: string; content: string }): I
128
81
  return { status: InitStatuses.CREATED, subject: opts.path };
129
82
  };
130
83
 
131
- /** Scaffolds the project layer at `root`. Never overwrites: an existing file is kept and a needed edit becomes a hint; only `.gitignore` is appended to, line by line. */
132
- export const scaffoldProject = (opts: {
133
- root: string;
134
- extension: TConfigExtension;
135
- }): IScaffoldResult => {
136
- const { root } = opts;
137
- const name = resolveProjectName({ root });
138
- const isWorkspaces = declaresWorkspaces({ root });
139
- const entries: IInitEntry[] = (
140
- isWorkspaces ? SCAFFOLD_FILES : [...SCAFFOLD_FILES, ...LINT_CONFIG_FILES]
141
- ).map((file) =>
142
- writeIfAbsent({
143
- root,
144
- path: file.path,
145
- content: renderTemplate({ template: file.template, name }),
146
- }),
147
- );
148
-
149
- if (isWorkspaces) {
150
- entries.push({
151
- status: InitStatuses.SKIPPED,
152
- subject: `.configs/{lints,formatters}: a workspaces project keeps them per app (apps/<name>/.configs/lints/, apps/<name>/.configs/formatters/); the templates are in node_modules/@venizia/vulcan/base/templates/`,
153
- });
84
+ export class ProjectScaffold {
85
+ /** Whether the root `package.json` declares workspaces: the array form or `{ packages: [...] }`. */
86
+ static declaresWorkspaces(opts: { root: string }): boolean {
87
+ const workspaces = readManifest(opts)?.workspaces;
88
+
89
+ return Array.isArray(workspaces) || (typeof workspaces === 'object' && workspaces !== null);
154
90
  }
155
91
 
156
- const configs = findConfigFiles({ root });
92
+ /** The root workspace globs, from either form; empty when there are none. */
93
+ static readWorkspaceGlobs(opts: { root: string }): string[] {
94
+ const workspaces = readManifest(opts)?.workspaces;
157
95
 
158
- if (configs.length === 0) {
159
- const configFile = `${ConfigConstants.BASENAME}.${opts.extension}`;
96
+ if (Array.isArray(workspaces)) {
97
+ return workspaces.map(String);
98
+ }
160
99
 
161
- entries.push(
162
- writeIfAbsent({
163
- root,
164
- path: join(ConfigConstants.DIRECTORY, configFile),
165
- content: renderTemplate({ template: configFile, name }),
166
- }),
167
- );
168
- } else {
169
- entries.push(
170
- ...configs.map((file): IInitEntry => ({
171
- status: InitStatuses.KEPT,
172
- subject: relative(root, file),
173
- })),
174
- );
100
+ const packages = JsonValue.readProperty({ value: workspaces, key: 'packages' });
101
+
102
+ return Array.isArray(packages) ? packages.map(String) : [];
175
103
  }
176
104
 
177
- entries.push(writeIfAbsent({ root, path: '.dockerignore', content: renderDockerignore() }));
178
- entries.push(writeIfAbsent({ root, path: 'bunfig.toml', content: renderBunfig() }));
105
+ /**
106
+ * Whether a workspace glob list covers the packages directly under `folder`: `folder/*` or
107
+ * `folder/**`, with or without a leading `./`, or any glob that matches a package there
108
+ * (`auroras/*\/*` covers `auroras/apps`).
109
+ */
110
+ static coversFolder(opts: { globs: string[]; folder: string }): boolean {
111
+ return opts.globs.some((glob) => {
112
+ const plain = glob.replace(/^\.\//, '');
113
+
114
+ // A negation (`!umbras/legacy`) excludes packages; it never covers a folder.
115
+ if (plain.startsWith('!')) {
116
+ return false;
117
+ }
118
+
119
+ return (
120
+ plain === `${opts.folder}/*` ||
121
+ plain === `${opts.folder}/**` ||
122
+ new Glob(plain).match(`${opts.folder}/package-probe`)
123
+ );
124
+ });
125
+ }
179
126
 
180
- const makefile = join(root, 'Makefile');
127
+ static renderTemplate(opts: { template: string; name: string }): string {
128
+ return readFileSync(join(BASE_DIRECTORY, 'templates', opts.template), 'utf8').replaceAll(
129
+ InitConstants.NAME_TOKEN,
130
+ opts.name,
131
+ );
132
+ }
181
133
 
182
- if (!existsSync(makefile)) {
183
- entries.push(
134
+ /** Scaffolds the project layer at `root`. Never overwrites: an existing file is kept and a needed edit becomes a hint; only `.gitignore` is appended to, line by line. */
135
+ static scaffold(opts: { root: string; extension: TConfigExtension }): IScaffoldResult {
136
+ const { root } = opts;
137
+ const name = resolveProjectName({ root });
138
+ const isWorkspaces = ProjectScaffold.declaresWorkspaces({ root });
139
+ const entries: IInitEntry[] = (
140
+ isWorkspaces ? SCAFFOLD_FILES : [...SCAFFOLD_FILES, ...LINT_CONFIG_FILES]
141
+ ).map((file) =>
184
142
  writeIfAbsent({
185
143
  root,
186
- path: 'Makefile',
187
- content: renderTemplate({ template: 'Makefile', name }),
144
+ path: file.path,
145
+ content: ProjectScaffold.renderTemplate({ template: file.template, name }),
188
146
  }),
189
147
  );
190
- } else if (!readFileSync(makefile, 'utf8').includes(ProjectLayout.MAKE_INCLUDE_LINE)) {
191
- entries.push({
192
- status: InitStatuses.ADD,
193
- subject: `Makefile: ${ProjectLayout.MAKE_INCLUDE_LINE}`,
194
- });
195
- }
196
148
 
197
- const gitignore = join(root, '.gitignore');
198
- const existing = existsSync(gitignore) ? readFileSync(gitignore, 'utf8') : '';
199
- const lines = existing.split('\n');
200
- const missingIgnores = ProjectLayout.GITIGNORE_ENTRIES.filter((entry) => !lines.includes(entry));
149
+ if (isWorkspaces) {
150
+ entries.push({
151
+ status: InitStatuses.SKIPPED,
152
+ subject: `.configs/{lints,formatters}: a workspaces project keeps them per app (apps/<name>/.configs/lints/, apps/<name>/.configs/formatters/); the templates are in node_modules/@venizia/vulcan/base/templates/`,
153
+ });
154
+ }
201
155
 
202
- if (missingIgnores.length > 0) {
203
- const separator = existing === '' || existing.endsWith('\n') ? '' : '\n';
156
+ const configs = ConfigLoader.findFiles({ root });
157
+
158
+ if (configs.length === 0) {
159
+ const configFile = `${ConfigConstants.BASENAME}.${opts.extension}`;
160
+
161
+ entries.push(
162
+ writeIfAbsent({
163
+ root,
164
+ path: join(ConfigConstants.DIRECTORY, configFile),
165
+ content: ProjectScaffold.renderTemplate({ template: configFile, name }),
166
+ }),
167
+ );
168
+ } else {
169
+ entries.push(
170
+ ...configs.map((file): IInitEntry => ({
171
+ status: InitStatuses.KEPT,
172
+ subject: relative(root, file),
173
+ })),
174
+ );
175
+ }
204
176
 
205
- writeFileSync(gitignore, `${existing}${separator}${missingIgnores.join('\n')}\n`);
206
- entries.push({
207
- status: InitStatuses.UPDATED,
208
- subject: `.gitignore: + ${missingIgnores.join(' ')}`,
209
- });
210
- }
177
+ entries.push(writeIfAbsent({ root, path: '.dockerignore', content: Dockerignore.render() }));
178
+ entries.push(writeIfAbsent({ root, path: 'bunfig.toml', content: Bunfig.render() }));
179
+
180
+ const makefile = join(root, 'Makefile');
181
+
182
+ if (!existsSync(makefile)) {
183
+ entries.push(
184
+ writeIfAbsent({
185
+ root,
186
+ path: 'Makefile',
187
+ content: ProjectScaffold.renderTemplate({ template: 'Makefile', name }),
188
+ }),
189
+ );
190
+ } else if (!readFileSync(makefile, 'utf8').includes(ProjectLayout.MAKE_INCLUDE_LINE)) {
191
+ entries.push({
192
+ status: InitStatuses.ADD,
193
+ subject: `Makefile: ${ProjectLayout.MAKE_INCLUDE_LINE}`,
194
+ });
195
+ }
211
196
 
212
- const manifest = readManifest({ root });
213
- const declared = { ...manifest?.dependencies, ...manifest?.devDependencies };
214
- const needed = isWorkspaces
215
- ? [ProjectLayout.STYLE_PACKAGE]
216
- : [...ProjectLayout.LINT_TOOLS, ProjectLayout.STYLE_PACKAGE];
217
- const install = needed.filter((packageName) => !(packageName in declared));
218
- const todo = [
219
- `describe the project in ${ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE}/index.md, then delete the ${ProjectLayout.SCAFFOLD_MARKER} line`,
220
- ...entries
221
- .filter((entry) => entry.status === InitStatuses.ADD)
222
- .map((entry) => `add ${entry.subject}`),
223
- `${ProjectLayout.VULCAN_COMMAND} sync && ${ProjectLayout.VULCAN_COMMAND} doctor`,
224
- ];
225
-
226
- return { entries, install, todo };
227
- };
197
+ const gitignore = join(root, '.gitignore');
198
+ const existing = existsSync(gitignore) ? readFileSync(gitignore, 'utf8') : '';
199
+ const lines = existing.split('\n');
200
+ const missingIgnores = ProjectLayout.GITIGNORE_ENTRIES.filter(
201
+ (entry) => !lines.includes(entry),
202
+ );
203
+
204
+ if (missingIgnores.length > 0) {
205
+ const separator = existing === '' || existing.endsWith('\n') ? '' : '\n';
206
+
207
+ writeFileSync(gitignore, `${existing}${separator}${missingIgnores.join('\n')}\n`);
208
+ entries.push({
209
+ status: InitStatuses.UPDATED,
210
+ subject: `.gitignore: + ${missingIgnores.join(' ')}`,
211
+ });
212
+ }
213
+
214
+ const manifest = readManifest({ root });
215
+ const declared = { ...manifest?.dependencies, ...manifest?.devDependencies };
216
+ const needed = isWorkspaces
217
+ ? [ProjectLayout.STYLE_PACKAGE]
218
+ : [...ProjectLayout.LINT_TOOLS, ProjectLayout.STYLE_PACKAGE];
219
+ const install = needed.filter((packageName) => !(packageName in declared));
220
+ const todo = [
221
+ `describe the project in ${ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE}/index.md, then delete the ${ProjectLayout.SCAFFOLD_MARKER} line`,
222
+ ...entries
223
+ .filter((entry) => entry.status === InitStatuses.ADD)
224
+ .map((entry) => `add ${entry.subject}`),
225
+ `${ProjectLayout.VULCAN_COMMAND} sync && ${ProjectLayout.VULCAN_COMMAND} doctor`,
226
+ ];
227
+
228
+ return { entries, install, todo };
229
+ }
230
+ }