@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
@@ -5,7 +5,7 @@
5
5
  */
6
6
 
7
7
  /** A folder, or a list of folders, as the layout holds it; a string stays valid. */
8
- export type TLayoutValue = string | string[];
8
+ type TLayoutValue = string | string[];
9
9
 
10
10
  export interface ILayout {
11
11
  backend?: TLayoutValue;
@@ -15,7 +15,7 @@ export interface ILayout {
15
15
  other?: TLayoutValue;
16
16
  }
17
17
 
18
- export class LayoutFolderLimits {
18
+ class LayoutFolderLimits {
19
19
  /** `auroras/apps` is two segments. */
20
20
  static readonly MAX_SEGMENTS = 4;
21
21
  /** One segment: the pattern a layout folder had before it could have several. */
@@ -38,140 +38,125 @@ export class LayoutKeys {
38
38
  }
39
39
  }
40
40
 
41
- /** Why a layout folder is not one, or undefined when it is: 1 to 4 segments, each a plain lower-case name. */
42
- export const layoutFolderProblem = (opts: { folder: unknown }): string | undefined => {
43
- const { folder } = opts;
44
-
45
- if (typeof folder !== 'string' || folder === '') {
46
- return 'a folder is a non-empty string';
47
- }
48
-
49
- if (folder.includes('\\')) {
50
- return `'${folder}' has a backslash: a folder is written with '/'`;
51
- }
41
+ /** Whether `inner` is `outer` or sits below it. */
42
+ const isWithin = (opts: { inner: string; outer: string }): boolean =>
43
+ opts.inner === opts.outer || opts.inner.startsWith(`${opts.outer}/`);
52
44
 
53
- if (folder.startsWith('/') || folder.endsWith('/')) {
54
- return `'${folder}' starts or ends with '/': a folder is a path from the project root`;
45
+ export class LayoutFolder {
46
+ private static entriesOf(opts: { layout: ILayout }): { key: string; folder: string }[] {
47
+ return LayoutKeys.ALL.flatMap((key) =>
48
+ LayoutFolder.layoutFoldersOf({ value: opts.layout[key] }).map((folder) => ({ key, folder })),
49
+ );
55
50
  }
56
51
 
57
- const segments = folder.split('/');
52
+ /** Why a layout folder is not one, or undefined when it is: 1 to 4 segments, each a plain lower-case name. */
53
+ static layoutFolderProblem(opts: { folder: unknown }): string | undefined {
54
+ const { folder } = opts;
58
55
 
59
- if (segments.length > LayoutFolderLimits.MAX_SEGMENTS) {
60
- return `'${folder}' has more than ${LayoutFolderLimits.MAX_SEGMENTS} segments`;
61
- }
62
-
63
- for (const segment of segments) {
64
- if (segment === '') {
65
- return `'${folder}' has an empty segment`;
56
+ if (typeof folder !== 'string' || folder === '') {
57
+ return 'a folder is a non-empty string';
66
58
  }
67
59
 
68
- if (segment === '..' || segment === '.') {
69
- return `'${folder}' climbs or repeats a folder ('${segment}')`;
60
+ if (folder.includes('\\')) {
61
+ return `'${folder}' has a backslash: a folder is written with '/'`;
70
62
  }
71
63
 
72
- if (LayoutFolderLimits.FORBIDDEN_SEGMENTS.has(segment)) {
73
- return `'${folder}' goes through '${segment}'`;
64
+ if (folder.startsWith('/') || folder.endsWith('/')) {
65
+ return `'${folder}' starts or ends with '/': a folder is a path from the project root`;
74
66
  }
75
67
 
76
- if (!LayoutFolderLimits.SEGMENT_PATTERN.test(segment)) {
77
- return `'${folder}' has the segment '${segment}': lowercase letters, digits and '-', starting with a letter or digit`;
68
+ const segments = folder.split('/');
69
+
70
+ if (segments.length > LayoutFolderLimits.MAX_SEGMENTS) {
71
+ return `'${folder}' has more than ${LayoutFolderLimits.MAX_SEGMENTS} segments`;
78
72
  }
79
- }
80
73
 
81
- return undefined;
82
- };
74
+ for (const segment of segments) {
75
+ if (segment === '') {
76
+ return `'${folder}' has an empty segment`;
77
+ }
78
+
79
+ if (segment === '..' || segment === '.') {
80
+ return `'${folder}' climbs or repeats a folder ('${segment}')`;
81
+ }
82
+
83
+ if (LayoutFolderLimits.FORBIDDEN_SEGMENTS.has(segment)) {
84
+ return `'${folder}' goes through '${segment}'`;
85
+ }
83
86
 
84
- /** The folders a layout value names, in order: a string is one, a list is its strings. Nothing is validated. */
85
- export const layoutFoldersOf = (opts: { value: unknown }): string[] => {
86
- const { value } = opts;
87
+ if (!LayoutFolderLimits.SEGMENT_PATTERN.test(segment)) {
88
+ return `'${folder}' has the segment '${segment}': lowercase letters, digits and '-', starting with a letter or digit`;
89
+ }
90
+ }
87
91
 
88
- if (typeof value === 'string') {
89
- return [value];
92
+ return undefined;
90
93
  }
91
94
 
92
- return Array.isArray(value)
93
- ? value.filter((entry): entry is string => typeof entry === 'string')
94
- : [];
95
- };
95
+ /** The folders a layout value names, in order: a string is one, a list is its strings. Nothing is validated. */
96
+ static layoutFoldersOf(opts: { value: unknown }): string[] {
97
+ const { value } = opts;
96
98
 
97
- /** Whether `inner` is `outer` or sits below it. */
98
- const isWithin = (opts: { inner: string; outer: string }): boolean =>
99
- opts.inner === opts.outer || opts.inner.startsWith(`${opts.outer}/`);
99
+ if (typeof value === 'string') {
100
+ return [value];
101
+ }
100
102
 
101
- const entriesOf = (opts: { layout: ILayout }): { key: string; folder: string }[] =>
102
- LayoutKeys.ALL.flatMap((key) =>
103
- layoutFoldersOf({ value: opts.layout[key] }).map((folder) => ({ key, folder })),
104
- );
105
-
106
- /** A folder listed twice or under two keys, and a folder inside another: a package path must belong to exactly one folder. */
107
- export const layoutOverlapProblems = (opts: { layout: ILayout }): string[] => {
108
- const entries = entriesOf({ layout: opts.layout }).filter(
109
- (entry) => layoutFolderProblem({ folder: entry.folder }) === undefined,
110
- );
111
- const problems: string[] = [];
112
-
113
- for (const [index, entry] of entries.entries()) {
114
- for (const other of entries.slice(index + 1)) {
115
- if (entry.folder === other.folder) {
116
- problems.push(
117
- `layout.${other.key} names '${other.folder}' again (also layout.${entry.key}): a folder belongs to one kind of code`,
118
- );
119
- } else if (
120
- isWithin({ inner: entry.folder, outer: other.folder }) ||
121
- isWithin({ inner: other.folder, outer: entry.folder })
122
- ) {
123
- problems.push(
124
- `layout.${entry.key} '${entry.folder}' and layout.${other.key} '${other.folder}' are nested: a package path must belong to exactly one folder`,
125
- );
103
+ return Array.isArray(value)
104
+ ? value.filter((entry): entry is string => typeof entry === 'string')
105
+ : [];
106
+ }
107
+
108
+ /** A folder listed twice or under two keys, and a folder inside another: a package path must belong to exactly one folder. */
109
+ static layoutOverlapProblems(opts: { layout: ILayout }): string[] {
110
+ const entries = LayoutFolder.entriesOf({ layout: opts.layout }).filter(
111
+ (entry) => LayoutFolder.layoutFolderProblem({ folder: entry.folder }) === undefined,
112
+ );
113
+ const problems: string[] = [];
114
+
115
+ for (const [index, entry] of entries.entries()) {
116
+ for (const other of entries.slice(index + 1)) {
117
+ if (entry.folder === other.folder) {
118
+ problems.push(
119
+ `layout.${other.key} names '${other.folder}' again (also layout.${entry.key}): a folder belongs to one kind of code`,
120
+ );
121
+ } else if (
122
+ isWithin({ inner: entry.folder, outer: other.folder }) ||
123
+ isWithin({ inner: other.folder, outer: entry.folder })
124
+ ) {
125
+ problems.push(
126
+ `layout.${entry.key} '${entry.folder}' and layout.${other.key} '${other.folder}' are nested: a package path must belong to exactly one folder`,
127
+ );
128
+ }
126
129
  }
127
130
  }
131
+
132
+ return problems;
128
133
  }
129
134
 
130
- return problems;
131
- };
135
+ /** The layout value with `folder` in it: unchanged when it is there already, a string that grows into a list otherwise. */
136
+ static withLayoutFolder(opts: { value: TLayoutValue | undefined; folder: string }): TLayoutValue {
137
+ const folders = LayoutFolder.layoutFoldersOf({ value: opts.value });
132
138
 
133
- /** Every problem of a layout, one line each: the folders that are not one, then the overlaps. */
134
- export const layoutProblems = (opts: { layout: ILayout }): string[] => [
135
- ...entriesOf({ layout: opts.layout }).flatMap((entry) => {
136
- const problem = layoutFolderProblem({ folder: entry.folder });
139
+ if (folders.includes(opts.folder)) {
140
+ return opts.value ?? opts.folder;
141
+ }
137
142
 
138
- return problem === undefined ? [] : [`layout.${entry.key}: ${problem}`];
139
- }),
140
- ...layoutOverlapProblems({ layout: opts.layout }),
141
- ];
143
+ return folders.length === 0 ? opts.folder : [...folders, opts.folder];
144
+ }
142
145
 
143
- /** The layout value with `folder` in it: unchanged when it is there already, a string that grows into a list otherwise. */
144
- export const withLayoutFolder = (opts: {
145
- value: TLayoutValue | undefined;
146
- folder: string;
147
- }): TLayoutValue => {
148
- const folders = layoutFoldersOf({ value: opts.value });
146
+ /** The valid folders of a layout value; a manifest is read through this, never trusted. */
147
+ static valid(opts: { value: unknown }): string[] {
148
+ return LayoutFolder.layoutFoldersOf({ value: opts.value }).filter(
149
+ (folder) => LayoutFolder.layoutFolderProblem({ folder }) === undefined,
150
+ );
151
+ }
149
152
 
150
- if (folders.includes(opts.folder)) {
151
- return opts.value ?? opts.folder;
153
+ /** The folders as a sentence part: `'a'`, or `'a', 'b'`. */
154
+ static describe(opts: { folders: string[] }): string {
155
+ return opts.folders.map((folder) => `'${folder}'`).join(', ');
152
156
  }
153
157
 
154
- return folders.length === 0 ? opts.folder : [...folders, opts.folder];
155
- };
156
-
157
- /** The layout key whose folder is exactly `folder`, or undefined. Only valid folders count. */
158
- export const layoutKeyOfFolder = (opts: { layout: ILayout; folder: string }): string | undefined =>
159
- LayoutKeys.ALL.find((key) =>
160
- layoutFoldersOf({ value: opts.layout[key] }).some(
161
- (folder) => folder === opts.folder && layoutFolderProblem({ folder }) === undefined,
162
- ),
163
- );
164
-
165
- /** The valid folders of a layout value; a manifest is read through this, never trusted. */
166
- export const validLayoutFolders = (opts: { value: unknown }): string[] =>
167
- layoutFoldersOf({ value: opts.value }).filter(
168
- (folder) => layoutFolderProblem({ folder }) === undefined,
169
- );
170
-
171
- /** The folders as a sentence part: `'a'`, or `'a', 'b'`. */
172
- export const describeFolders = (opts: { folders: string[] }): string =>
173
- opts.folders.map((folder) => `'${folder}'`).join(', ');
174
-
175
- /** What an error says when a flag must pick among several listed folders. */
176
- export const listedFoldersNote = (opts: { folders: string[] }): string =>
177
- `the layout lists ${describeFolders({ folders: opts.folders })}`;
158
+ /** What an error says when a flag must pick among several listed folders. */
159
+ static listedNote(opts: { folders: string[] }): string {
160
+ return `the layout lists ${LayoutFolder.describe({ folders: opts.folders })}`;
161
+ }
162
+ }
@@ -9,19 +9,21 @@ export const BASE_DIRECTORY = join(PACKAGE_ROOT, 'base');
9
9
 
10
10
  export const PACKAGE_NAME = '@venizia/vulcan';
11
11
 
12
- /**
13
- * The base as a project reaches it: through `node_modules/@venizia/vulcan` when that resolves to this
14
- * package. bun's isolated install keeps the files in a hashed store directory that every upgrade
15
- * replaces, so a link to the real path dies with the next upgrade; the stable path does not.
16
- * Anywhere else - no install, or another copy installed - the real directory.
17
- */
18
- export const stableBaseDirectoryOf = (opts: { root: string }): string => {
19
- const installed = join(opts.root, 'node_modules', PACKAGE_NAME, 'base');
12
+ export class BaseDirectory {
13
+ /**
14
+ * The base as a project reaches it: through `node_modules/@venizia/vulcan` when that resolves to this
15
+ * package. bun's isolated install keeps the files in a hashed store directory that every upgrade
16
+ * replaces, so a link to the real path dies with the next upgrade; the stable path does not.
17
+ * Anywhere else - no install, or another copy installed - the real directory.
18
+ */
19
+ static stableOf(opts: { root: string }): string {
20
+ const installed = join(opts.root, 'node_modules', PACKAGE_NAME, 'base');
20
21
 
21
- return existsSync(installed) && realpathSync(installed) === realpathSync(BASE_DIRECTORY)
22
- ? installed
23
- : BASE_DIRECTORY;
24
- };
22
+ return existsSync(installed) && realpathSync(installed) === realpathSync(BASE_DIRECTORY)
23
+ ? installed
24
+ : BASE_DIRECTORY;
25
+ }
26
+ }
25
27
 
26
28
  export const VULCAN_VERSION: string = JSON.parse(
27
29
  readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'),
@@ -0,0 +1,7 @@
1
+ /** The one answer to "is this parsed JSON or YAML a plain object": not an array, not null. */
2
+ export class RecordValue {
3
+ /** Takes the value itself, not an options object: a type predicate narrows only a parameter, and callers read `value.key` afterwards. */
4
+ static isRecord(value: unknown): value is Record<string, unknown> {
5
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
6
+ }
7
+ }
@@ -0,0 +1,7 @@
1
+ /** Text helpers that more than one folder of the CLI needs. */
2
+ export class TextValue {
3
+ /** `text` as a regular expression that matches exactly itself. */
4
+ static escapeLiteral(opts: { text: string }): string {
5
+ return opts.text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
6
+ }
7
+ }
@@ -1,4 +1,4 @@
1
- /** What a package of the project is: an app, or a shared package (a lib) a preset made. */
1
+ /** What a package of the project is: an app, or a library other apps import. */
2
2
  export class PackageKinds {
3
3
  static readonly APP = 'app';
4
4
  static readonly LIB = 'lib';
@@ -10,6 +10,18 @@ export class PackageKinds {
10
10
  }
11
11
  }
12
12
 
13
+ /** Which preset kind made a library: `lib` (may use the project's framework) or `shared` (depends on no framework). */
14
+ export class LibraryKinds {
15
+ static readonly LIB = 'lib';
16
+ static readonly SHARED = 'shared';
17
+
18
+ static readonly SCHEME_SET = new Set<string>([this.LIB, this.SHARED]);
19
+
20
+ static isValid(value: string): boolean {
21
+ return this.SCHEME_SET.has(value);
22
+ }
23
+ }
24
+
13
25
  /** Config file extensions, in lookup order. */
14
26
  export class ConfigExtensions {
15
27
  static readonly TS = 'ts';
@@ -1,7 +1,14 @@
1
1
  import type { TConstValue } from '../../common/index.ts';
2
- import type { CodingAgents, ConfigExtensions, HookEvents, PackageKinds } from './constants.ts';
2
+ import type {
3
+ CodingAgents,
4
+ ConfigExtensions,
5
+ HookEvents,
6
+ LibraryKinds,
7
+ PackageKinds,
8
+ } from './constants.ts';
3
9
 
4
10
  export type TConfigExtension = TConstValue<typeof ConfigExtensions>;
5
11
  export type TCodingAgent = TConstValue<typeof CodingAgents>;
6
12
  export type THookEvent = TConstValue<typeof HookEvents>;
7
13
  export type TPackageKind = TConstValue<typeof PackageKinds>;
14
+ export type TLibraryKind = TConstValue<typeof LibraryKinds>;
@@ -5,70 +5,75 @@ import { ConfigConstants, ConfigExtensions } from './common/index.ts';
5
5
  import { VULCAN_CONFIG_SCHEMA } from './schema.ts';
6
6
  import type { TResolvedConfig } from './schema.ts';
7
7
 
8
- export type TLoadResult =
8
+ type TLoadResult =
9
9
  | { ok: true; file: string; config: TResolvedConfig }
10
10
  | { ok: false; file?: string; error: string };
11
11
 
12
12
  const describeError = (opts: { error: unknown }): string =>
13
13
  opts.error instanceof Error ? opts.error.message : String(opts.error);
14
14
 
15
- /** Every `.configs/vulcan.config.<ext>` present, in lookup order. */
16
- export const findConfigFiles = (opts: { root: string }): string[] =>
17
- ConfigExtensions.LOOKUP_ORDER.map((extension) =>
18
- join(opts.root, ConfigConstants.DIRECTORY, `${ConfigConstants.BASENAME}.${extension}`),
19
- ).filter((file) => existsSync(file));
15
+ export class ConfigLoader {
16
+ /** Every `.configs/vulcan.config.<ext>` present, in lookup order. */
17
+ static findFiles(opts: { root: string }): string[] {
18
+ return ConfigExtensions.LOOKUP_ORDER.map((extension) =>
19
+ join(opts.root, ConfigConstants.DIRECTORY, `${ConfigConstants.BASENAME}.${extension}`),
20
+ ).filter((file) => existsSync(file));
21
+ }
20
22
 
21
- export const loadConfig = async (opts: { root: string }): Promise<TLoadResult> => {
22
- const files = findConfigFiles({ root: opts.root });
23
+ static async load(opts: { root: string }): Promise<TLoadResult> {
24
+ const files = ConfigLoader.findFiles({ root: opts.root });
23
25
 
24
- if (files.length === 0) {
25
- return {
26
- ok: false,
27
- error: `no ${ConfigConstants.DIRECTORY}/${ConfigConstants.BASENAME}.* found in ${opts.root}`,
28
- };
29
- }
26
+ if (files.length === 0) {
27
+ return {
28
+ ok: false,
29
+ error: `no ${ConfigConstants.DIRECTORY}/${ConfigConstants.BASENAME}.* found in ${opts.root}`,
30
+ };
31
+ }
30
32
 
31
- if (files.length > 1) {
32
- const names = files.map((file) => relative(opts.root, file)).join(', ');
33
+ if (files.length > 1) {
34
+ const names = files.map((file) => relative(opts.root, file)).join(', ');
33
35
 
34
- return { ok: false, error: `more than one config - keep exactly one of: ${names}` };
35
- }
36
+ return { ok: false, error: `more than one config - keep exactly one of: ${names}` };
37
+ }
36
38
 
37
- const [file] = files;
38
- const shown = relative(opts.root, file);
39
+ const [file] = files;
40
+ const shown = relative(opts.root, file);
39
41
 
40
- let loaded: { default?: unknown };
42
+ let loaded: { default?: unknown };
41
43
 
42
- try {
43
- loaded = await import(pathToFileURL(file).href);
44
- } catch (error) {
45
- return { ok: false, file, error: `${shown}: failed to load - ${describeError({ error })}` };
46
- }
44
+ try {
45
+ const imported = await import(pathToFileURL(file).href);
47
46
 
48
- if (loaded.default === undefined) {
49
- return {
50
- ok: false,
51
- file,
52
- error: `${shown}: no default export - write 'export default { ... }'`,
53
- };
54
- }
47
+ loaded = imported;
48
+ } catch (error) {
49
+ return { ok: false, file, error: `${shown}: failed to load - ${describeError({ error })}` };
50
+ }
55
51
 
56
- const parsed = VULCAN_CONFIG_SCHEMA.safeParse(loaded.default);
52
+ if (loaded.default === undefined) {
53
+ return {
54
+ ok: false,
55
+ file,
56
+ error: `${shown}: no default export - write 'export default { ... }'`,
57
+ };
58
+ }
57
59
 
58
- if (!parsed.success) {
59
- const issues = parsed.error.issues
60
- .map((issue) => {
61
- const path =
62
- issue.code === 'unrecognized_keys'
63
- ? issue.keys.join(', ')
64
- : issue.path.join('.') || '(root)';
60
+ const parsed = VULCAN_CONFIG_SCHEMA.safeParse(loaded.default);
65
61
 
66
- return ` ${path}: ${issue.message}`;
67
- })
68
- .join('\n');
62
+ if (!parsed.success) {
63
+ const issues = parsed.error.issues
64
+ .map((issue) => {
65
+ const path =
66
+ issue.code === 'unrecognized_keys'
67
+ ? issue.keys.join(', ')
68
+ : issue.path.join('.') || '(root)';
69
69
 
70
- return { ok: false, file, error: `${shown}: invalid config\n${issues}` };
71
- }
70
+ return ` ${path}: ${issue.message}`;
71
+ })
72
+ .join('\n');
72
73
 
73
- return { ok: true, file, config: parsed.data };
74
- };
74
+ return { ok: false, file, error: `${shown}: invalid config\n${issues}` };
75
+ }
76
+
77
+ return { ok: true, file, config: parsed.data };
78
+ }
79
+ }
@@ -1,4 +1,4 @@
1
- import type { TPackageKind } from './common/index.ts';
1
+ import type { TLibraryKind, TPackageKind } from './common/index.ts';
2
2
  import type { TResolvedConfig } from './schema.ts';
3
3
 
4
4
  const DEFAULT_PACKAGES_DIRECTORY = 'packages';
@@ -11,15 +11,21 @@ export interface IProjectPackage {
11
11
  aliases: string[];
12
12
  retired: boolean;
13
13
  kind?: TPackageKind;
14
+ /** Which preset kind made a library; absent means `lib`. */
15
+ presetKind?: TLibraryKind;
14
16
  }
15
17
 
16
- /** The project's packages in release order. */
17
- export const resolvePackages = (opts: { config: TResolvedConfig }): IProjectPackage[] =>
18
- opts.config.packages.map((entry) => ({
19
- dir: entry.dir,
20
- name: entry.name,
21
- path: entry.path ?? `${DEFAULT_PACKAGES_DIRECTORY}/${entry.dir}`,
22
- aliases: entry.aliases,
23
- retired: entry.retired,
24
- ...(entry.kind === undefined ? {} : { kind: entry.kind }),
25
- }));
18
+ export class ProjectPackages {
19
+ /** The project's packages in release order. */
20
+ static resolve(opts: { config: TResolvedConfig }): IProjectPackage[] {
21
+ return opts.config.packages.map((entry) => ({
22
+ dir: entry.dir,
23
+ name: entry.name,
24
+ path: entry.path ?? `${DEFAULT_PACKAGES_DIRECTORY}/${entry.dir}`,
25
+ aliases: entry.aliases,
26
+ retired: entry.retired,
27
+ ...(entry.kind === undefined ? {} : { kind: entry.kind }),
28
+ ...(entry.presetKind === undefined ? {} : { presetKind: entry.presetKind }),
29
+ }));
30
+ }
31
+ }
@@ -1,8 +1,14 @@
1
1
  import { isAbsolute } from 'node:path';
2
2
  import { z } from 'zod';
3
- import { layoutFolderProblem, layoutOverlapProblems } from '../common/layout-folder.ts';
3
+ import { LayoutFolder } from '../common/layout-folder.ts';
4
4
  import { OWNER_SCHEMA } from '../owner/schema.ts';
5
- import { CodingAgents, ConfigConstants, HookEvents, PackageKinds } from './common/index.ts';
5
+ import {
6
+ CodingAgents,
7
+ ConfigConstants,
8
+ HookEvents,
9
+ LibraryKinds,
10
+ PackageKinds,
11
+ } from './common/index.ts';
6
12
 
7
13
  const CODING_AGENT = z.string().refine((value) => CodingAgents.isValid(value), {
8
14
  message: `one of: ${[...CodingAgents.SCHEME_SET].join(', ')}`,
@@ -48,7 +54,7 @@ const PUSH_TARGET = z
48
54
 
49
55
  /** A layout folder: 1 to 4 plain segments, never climbing, never absolute (the validator `guard-package` shares). */
50
56
  const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
51
- const problem = layoutFolderProblem({ folder: value });
57
+ const problem = LayoutFolder.layoutFolderProblem({ folder: value });
52
58
 
53
59
  if (problem !== undefined) {
54
60
  context.addIssue({ code: 'custom', message: problem });
@@ -56,7 +62,7 @@ const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
56
62
  });
57
63
 
58
64
  /** A script `guard-writes` may trust: a repo-relative `.ts` path - no glob, no `~`, never climbing out of the repo. */
59
- const TRUSTED_SCRIPT = z.string().superRefine((value, context) => {
65
+ const TRUSTED_SCRIPT_PATH = z.string().superRefine((value, context) => {
60
66
  const problem = /[*?[\]{}!]/.test(value)
61
67
  ? 'no globs: list each script by its exact path'
62
68
  : isAbsolute(value) || value.startsWith('~')
@@ -72,6 +78,22 @@ const TRUSTED_SCRIPT = z.string().superRefine((value, context) => {
72
78
  }
73
79
  });
74
80
 
81
+ /**
82
+ * A trusted script, whole or by subcommand: a path trusts the whole file; an object trusts only the calls
83
+ * whose first argument after the script is one of `readOnly` (one word each, matched exactly).
84
+ */
85
+ const READ_ONLY_WORD = z
86
+ .string()
87
+ .regex(
88
+ /^[A-Za-z0-9_.:-]+$/,
89
+ 'one plain word: letters, digits and _ . : - only, no spaces or globs',
90
+ );
91
+
92
+ const TRUSTED_SCRIPT = z.union([
93
+ TRUSTED_SCRIPT_PATH,
94
+ z.strictObject({ script: TRUSTED_SCRIPT_PATH, readOnly: z.array(READ_ONLY_WORD).min(1) }),
95
+ ]);
96
+
75
97
  /** One folder, or a list of them: a side whose apps are grouped keeps each group's folder. */
76
98
  const LAYOUT_VALUE = z.union([LAYOUT_FOLDER, z.array(LAYOUT_FOLDER).min(1)]);
77
99
 
@@ -82,8 +104,10 @@ const PROJECT_PACKAGE = z.strictObject({
82
104
  path: z.string().optional(),
83
105
  aliases: z.array(z.string()).default([]),
84
106
  retired: z.boolean().default(false),
85
- /** A shared package a preset's lib kind made lives anywhere a workspace glob covers; absent means an app or a plain package. */
107
+ /** A library a preset made lives anywhere a workspace glob covers; absent means an app or a plain package. */
86
108
  kind: z.enum([PackageKinds.APP, PackageKinds.LIB]).optional(),
109
+ /** Which preset kind made a library; absent means the `lib` kind. */
110
+ presetKind: z.enum([LibraryKinds.LIB, LibraryKinds.SHARED]).optional(),
87
111
  });
88
112
 
89
113
  /** A path as a key: no leading `./`, no trailing slash. */
@@ -188,7 +212,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
188
212
  other: LAYOUT_VALUE.optional(),
189
213
  })
190
214
  .superRefine((layout, context) => {
191
- for (const problem of layoutOverlapProblems({ layout })) {
215
+ for (const problem of LayoutFolder.layoutOverlapProblems({ layout })) {
192
216
  context.addIssue({ code: 'custom', message: problem });
193
217
  }
194
218
  })
@@ -202,6 +226,8 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
202
226
  summary: z.string(),
203
227
  /** The summary of the preset's lib kind, when it ships one. */
204
228
  lib: z.string().optional(),
229
+ /** The summary of the preset's shared kind, when it ships one. */
230
+ shared: z.string().optional(),
205
231
  }),
206
232
  )
207
233
  .optional(),
@@ -320,6 +346,25 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
320
346
  localFile: z.string().default('.agents/hooks/trusted-hosts.local'),
321
347
  })
322
348
  .optional(),
349
+ /**
350
+ * The colour the project is known by: `vulcan visualize` takes the accent of its pages from here (the spec's own
351
+ * `accent` wins). `accent` is the colour for marks and fills; `accentDark` is the same on dark grounds (derived
352
+ * when absent); `accentText` is a darker accent for text, when `accent` is too light to be read as text.
353
+ * `vulcan sync` copies it to the manifest, where the generator reads it.
354
+ */
355
+ theme: z
356
+ .strictObject({
357
+ accent: z.string().regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #8a5a20'),
358
+ accentDark: z
359
+ .string()
360
+ .regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #dead6a')
361
+ .optional(),
362
+ accentText: z
363
+ .string()
364
+ .regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #01579b')
365
+ .optional(),
366
+ })
367
+ .optional(),
323
368
  /** Team-shared Claude settings (permissions, env, enabledPlugins...), merged by sync over personal keys. */
324
369
  claude: z
325
370
  .strictObject({ settings: z.record(z.string(), z.unknown()).default({}) })
@@ -344,7 +389,9 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
344
389
  * runtime dir for locks, git config, the agent tool's memory) with stores a tool in this project
345
390
  * manages itself: absolute globs, `~` and `$NAME` allowed. `writes.trustedScripts` lists the project's own
346
391
  * CLIs (repo-relative `.ts` paths, no globs) whose body guard-writes does not read for mutating calls
347
- * while git tracks them and they equal HEAD; the command line is still checked. `writes.commands` adds the
392
+ * while git tracks them and they equal HEAD; the command line is still checked. An entry may instead be
393
+ * `{ script, readOnly: ['plan'] }`: only a call whose first argument after the script is listed skips the
394
+ * read, and `vulcan sync` writes those entries to the manifest. `writes.commands` adds the
348
395
  * project's own deploy and migrate commands to what guard-writes asks about (a pattern, matched inside
349
396
  * compound commands too), and `git.askPush` lists the branches a plain `git push` asks about; `vulcan sync`
350
397
  * writes both to the manifest, where the hooks read them.