@venizia/vulcan 0.4.9-0 → 0.4.9-2

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 (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -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
+ }
@@ -3,7 +3,7 @@ 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
5
  import type { IReadOnlyScript, IScriptInvocation, IScriptTrust } from './common/index.ts';
6
- import { basenameOf, parseShell, programOf } from './shell.ts';
6
+ import { ShellParser } from './shell.ts';
7
7
 
8
8
  /** Variables that point git at another repository or index than the one in `cwd`. */
9
9
  const REDIRECTING_VARIABLES = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE'];
@@ -34,128 +34,130 @@ const gitQuery = (opts: { cwd: string; args: string[] }): string | undefined =>
34
34
 
35
35
  const untrusted = (opts: { state: IScriptTrust['state']; reason: string }): IScriptTrust => opts;
36
36
 
37
- /**
38
- * Whether the listed script `script` (repo-relative) may skip the script checks of guard-writes: only
39
- * while git tracks it and its worktree file, its index entry and HEAD hold the same bytes. A script an
40
- * agent edited and then runs is therefore checked like any other; so is one that was never committed.
41
- * The blobs are compared, not `git status`, so `--assume-unchanged` and `--skip-worktree` hide nothing.
42
- */
43
- export const trustOf = (opts: { root: string; script: string }): IScriptTrust => {
44
- const path = resolve(opts.root, opts.script);
45
-
46
- if (!existsSync(path)) {
47
- 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}`;
48
44
  }
49
45
 
50
- const root = realpathSync(opts.root);
51
- const real = realpathSync(path);
52
-
53
- // A link could point at an untracked file that git never looks at.
54
- if (real !== join(root, relative(resolve(opts.root), path))) {
55
- return untrusted({
56
- state: TrustStates.SYMLINK,
57
- reason: 'its path goes through a symlink, which git does not follow',
58
- });
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
+ }
59
53
  }
54
+ }
60
55
 
61
- const repoPath = relative(root, real).split(sep).join('/');
62
- const entry = gitQuery({
63
- cwd: root,
64
- args: ['ls-files', '--stage', '--', `:(literal)${repoPath}`],
65
- });
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);
66
65
 
67
- if (entry === undefined) {
68
- return untrusted({
69
- state: TrustStates.UNKNOWN,
70
- reason: 'git could not say whether it is tracked',
71
- });
72
- }
66
+ if (!existsSync(path)) {
67
+ return untrusted({ state: TrustStates.MISSING, reason: 'the file does not exist' });
68
+ }
73
69
 
74
- if (entry === '') {
75
- return untrusted({ state: TrustStates.UNTRACKED, reason: 'it is not tracked by git' });
76
- }
70
+ const root = realpathSync(opts.root);
71
+ const real = realpathSync(path);
77
72
 
78
- const [mode, indexBlob, stage] = entry.split('\n')[0].split(/\s+/);
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
+ }
79
80
 
80
- if (mode === SYMLINK_MODE) {
81
- return untrusted({
82
- state: TrustStates.SYMLINK,
83
- reason: 'it is a symlink, which git does not follow',
81
+ const repoPath = relative(root, real).split(sep).join('/');
82
+ const entry = gitQuery({
83
+ cwd: root,
84
+ args: ['ls-files', '--stage', '--', `:(literal)${repoPath}`],
84
85
  });
85
- }
86
86
 
87
- if (stage !== '0') {
88
- return untrusted({
89
- state: TrustStates.MODIFIED,
90
- reason: 'modified trusted script (it has an unresolved merge)',
91
- });
92
- }
87
+ if (entry === undefined) {
88
+ return untrusted({
89
+ state: TrustStates.UNKNOWN,
90
+ reason: 'git could not say whether it is tracked',
91
+ });
92
+ }
93
93
 
94
- const headBlob = gitQuery({
95
- cwd: root,
96
- args: ['rev-parse', '--verify', '--quiet', `HEAD:./${repoPath}`],
97
- });
94
+ if (entry === '') {
95
+ return untrusted({ state: TrustStates.UNTRACKED, reason: 'it is not tracked by git' });
96
+ }
98
97
 
99
- if (headBlob === undefined) {
100
- return untrusted({
101
- state: TrustStates.UNCOMMITTED,
102
- reason: 'it is not in the last commit yet',
103
- });
104
- }
98
+ const [mode, indexBlob, stage] = entry.split('\n')[0].split(/\s+/);
105
99
 
106
- const workBlob = gitQuery({ cwd: root, args: ['hash-object', '--', real] });
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
+ }
107
106
 
108
- if (workBlob === undefined) {
109
- return untrusted({
110
- state: TrustStates.UNKNOWN,
111
- reason: 'git could not read the file',
112
- });
113
- }
107
+ if (stage !== '0') {
108
+ return untrusted({
109
+ state: TrustStates.MODIFIED,
110
+ reason: 'modified trusted script (it has an unresolved merge)',
111
+ });
112
+ }
114
113
 
115
- if (workBlob !== headBlob || indexBlob !== headBlob) {
116
- return untrusted({
117
- state: TrustStates.MODIFIED,
118
- reason: `modified trusted script (${workBlob === headBlob ? 'the index' : 'the working tree'} differs from the last commit)`,
114
+ const headBlob = gitQuery({
115
+ cwd: root,
116
+ args: ['rev-parse', '--verify', '--quiet', `HEAD:./${repoPath}`],
119
117
  });
120
- }
121
118
 
122
- return { state: TrustStates.TRUSTED, reason: 'tracked, and identical to the last commit' };
123
- };
119
+ if (headBlob === undefined) {
120
+ return untrusted({
121
+ state: TrustStates.UNCOMMITTED,
122
+ reason: 'it is not in the last commit yet',
123
+ });
124
+ }
124
125
 
125
- export class ScriptPaths {
126
- /**
127
- * The script word as the shell opens it: joined to the working folder without folding `..`, so a link
128
- * before a `..` is followed the way the shell follows it.
129
- */
130
- static targetPath(opts: { target: string; cwd: string }): string {
131
- return isAbsolute(opts.target) ? opts.target : `${opts.cwd}${sep}${opts.target}`;
132
- }
126
+ const workBlob = gitQuery({ cwd: root, args: ['hash-object', '--', real] });
133
127
 
134
- /** The file `path` is on disk, links followed by the OS; the path folded as written when nothing is there. */
135
- static physicalOf(opts: { path: string }): string {
136
- try {
137
- return realpathSync.native(opts.path);
138
- } catch {
139
- return resolve(opts.path);
128
+ if (workBlob === undefined) {
129
+ return untrusted({
130
+ state: TrustStates.UNKNOWN,
131
+ reason: 'git could not read the file',
132
+ });
140
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' };
141
143
  }
142
- }
143
144
 
144
- /** The listed script `target` names, if any: both resolved to the file on disk, an exact match. */
145
- export const listedScriptOf = (opts: {
146
- target: string;
147
- cwd: string;
148
- root: string;
149
- scripts: string[];
150
- }): string | undefined => {
151
- const path = ScriptPaths.physicalOf({
152
- path: ScriptPaths.targetPath({ target: opts.target, cwd: opts.cwd }),
153
- });
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 }),
154
+ });
154
155
 
155
- return opts.scripts.find(
156
- (script) => ScriptPaths.physicalOf({ path: resolve(opts.root, script) }) === path,
157
- );
158
- };
156
+ return opts.scripts.find(
157
+ (script) => ScriptPaths.physicalOf({ path: resolve(opts.root, script) }) === path,
158
+ );
159
+ }
160
+ }
159
161
 
160
162
  export class ReadOnlyScripts {
161
163
  /**
@@ -166,9 +168,9 @@ export class ReadOnlyScripts {
166
168
  static extractInvocations(opts: { command: string }): IScriptInvocation[] {
167
169
  let moved = false;
168
170
 
169
- return parseShell({ command: opts.command }).flatMap((command) => {
170
- const { name, args } = programOf({ command });
171
- const program = basenameOf({ word: name });
171
+ return ShellParser.parse({ command: opts.command }).flatMap((command) => {
172
+ const { name, args } = ShellParser.programOf({ command });
173
+ const program = ShellParser.basenameOf({ word: name });
172
174
 
173
175
  if (ReadOnlyScripts.MOVING_COMMANDS.has(program)) {
174
176
  moved = true;
@@ -198,7 +200,7 @@ export class ReadOnlyScripts {
198
200
  root: string;
199
201
  entries: IReadOnlyScript[];
200
202
  }): string | undefined {
201
- return listedScriptOf({
203
+ return ScriptTrust.listedOf({
202
204
  target: opts.target,
203
205
  cwd: opts.cwd,
204
206
  root: opts.root,
@@ -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. */
@@ -61,47 +61,6 @@ 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
65
  const resolveProjectName = (opts: { root: string }): string => {
107
66
  const name = readManifest(opts)?.name;
@@ -109,12 +68,6 @@ const resolveProjectName = (opts: { root: string }): string => {
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
+ }