@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
@@ -1,45 +1,51 @@
1
- import { OFFICIAL_PRESETS, officialIdOf } from '@venizia/vulcan-atlas';
2
- import { promptSelect, promptText } from '../ui/index.ts';
1
+ import { OFFICIAL_PRESETS, OfficialPresets } from '@venizia/vulcan-atlas';
2
+ import { TerminalPrompt } from '../ui/index.ts';
3
3
 
4
4
  const ANOTHER_PRESET = ':another-preset';
5
5
 
6
6
  /** A preset a project recorded: what `--preset` takes back, the side it builds, what it is. */
7
- export interface IKnownPreset {
7
+ interface IKnownPreset {
8
8
  spec: string;
9
9
  side: string;
10
10
  summary: string;
11
11
  }
12
12
 
13
- /**
14
- * What a menu offers for `--preset`: the presets the project recorded, then the official ones it has
15
- * not used yet (the one list atlas answers `presets` from), then a text input for any other package
16
- * or `file:` path. null when the user cancelled.
17
- */
18
- export const askPresetSpec = async (opts: { recorded: IKnownPreset[] }): Promise<string | null> => {
19
- const used = new Set(opts.recorded.map((entry) => officialIdOf({ spec: entry.spec })));
20
- const picked = await promptSelect({
21
- message: 'Which preset?',
22
- choices: [
23
- ...opts.recorded.map((entry) => ({
24
- value: entry.spec,
25
- label: entry.spec,
26
- hint: `${entry.side}: ${entry.summary}`,
27
- })),
28
- ...OFFICIAL_PRESETS.filter((entry) => !used.has(entry.id)).map((entry) => ({
29
- value: entry.id,
30
- label: entry.id,
31
- hint: `official, ${entry.side} (app or lib)`,
32
- })),
33
- { value: ANOTHER_PRESET, label: 'Another preset...', hint: 'a package name or file:<path>' },
34
- ],
35
- });
13
+ export class PresetMenu {
14
+ /**
15
+ * What a menu offers for `--preset`: the presets the project recorded, then the official ones it has
16
+ * not used yet (the one list atlas answers `presets` from), then a text input for any other package
17
+ * or `file:` path. null when the user cancelled.
18
+ */
19
+ static async askSpec(opts: { recorded: IKnownPreset[] }): Promise<string | null> {
20
+ const used = new Set(opts.recorded.map((entry) => OfficialPresets.idOf({ spec: entry.spec })));
21
+ const picked = await TerminalPrompt.promptSelect({
22
+ message: 'Which preset?',
23
+ choices: [
24
+ ...opts.recorded.map((entry) => ({
25
+ value: entry.spec,
26
+ label: entry.spec,
27
+ hint: `${entry.side}: ${entry.summary}`,
28
+ })),
29
+ ...OFFICIAL_PRESETS.filter((entry) => !used.has(entry.id)).map((entry) => ({
30
+ value: entry.id,
31
+ label: entry.id,
32
+ hint: `official, ${entry.side} (app or lib)`,
33
+ })),
34
+ {
35
+ value: ANOTHER_PRESET,
36
+ label: 'Another preset...',
37
+ hint: 'a package name or file:<path>',
38
+ },
39
+ ],
40
+ });
36
41
 
37
- if (picked !== ANOTHER_PRESET) {
38
- return picked;
39
- }
42
+ if (picked !== ANOTHER_PRESET) {
43
+ return picked;
44
+ }
40
45
 
41
- return promptText({
42
- message: 'Preset (a package name, or file:<path>)',
43
- validate: (value) => (value.trim() === '' ? 'a package name, or file:<path>' : undefined),
44
- });
45
- };
46
+ return TerminalPrompt.promptText({
47
+ message: 'Preset (a package name, or file:<path>)',
48
+ validate: (value) => (value.trim() === '' ? 'a package name, or file:<path>' : undefined),
49
+ });
50
+ }
51
+ }
@@ -9,10 +9,10 @@ import {
9
9
  statSync,
10
10
  writeFileSync,
11
11
  } from 'node:fs';
12
- import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
12
+ import { basename, dirname, join, resolve } from 'node:path';
13
13
  import { z } from 'zod';
14
- import { readProperty } from '../common/index.ts';
15
- import { AppSides, CreateConstants } from './common/index.ts';
14
+ import { JsonValue } from '../common/index.ts';
15
+ import { AppSides, CreateConstants, PresetPath } from './common/index.ts';
16
16
  import type { ILocatedPreset, IPresetSpec, TAppSide, TPresetResult } from './common/index.ts';
17
17
 
18
18
  const PRESET_SCHEMA = z
@@ -61,23 +61,17 @@ const UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
61
61
  const EXECUTABLE_BITS = 0o111;
62
62
  const PERMISSION_BITS = 0o777;
63
63
 
64
- const escapes = (opts: { root: string; path: string }): boolean => {
65
- const relativePath = relative(opts.root, opts.path);
66
-
67
- return isAbsolute(relativePath) || relativePath === '..' || relativePath.startsWith(`..${sep}`);
68
- };
69
-
70
64
  /** A path a preset names must stay inside its own package, with symlinks resolved. */
71
65
  const resolveInside = (opts: { root: string; from: string; path: string }): string | undefined => {
72
66
  const resolved = resolve(opts.from, opts.path);
73
67
 
74
- if (escapes({ root: opts.root, path: resolved })) {
68
+ if (PresetPath.escapes({ root: opts.root, path: resolved })) {
75
69
  return undefined;
76
70
  }
77
71
 
78
72
  if (
79
73
  existsSync(resolved) &&
80
- escapes({ root: realpathSync(opts.root), path: realpathSync(resolved) })
74
+ PresetPath.escapes({ root: realpathSync(opts.root), path: realpathSync(resolved) })
81
75
  ) {
82
76
  return undefined;
83
77
  }
@@ -85,233 +79,252 @@ const resolveInside = (opts: { root: string; from: string; path: string }): stri
85
79
  return resolved;
86
80
  };
87
81
 
88
- /** A file's text when it is UTF-8 without a NUL byte; undefined for anything else, which is data and is copied as it is. */
89
- export const decodeText = (opts: { content: Buffer }): string | undefined => {
90
- if (opts.content.includes(0)) {
91
- return undefined;
82
+ export class Preset {
83
+ /** Text gets its tokens replaced; anything else is copied as it is. */
84
+ private static substituteTokens(opts: {
85
+ content: Buffer;
86
+ tokens: Record<string, string>;
87
+ }): Buffer {
88
+ const text = Preset.decodeText({ content: opts.content });
89
+
90
+ return text === undefined
91
+ ? opts.content
92
+ : Buffer.from(text.replace(TOKEN, (match, key: string) => opts.tokens[key] ?? match));
92
93
  }
93
94
 
94
- try {
95
- return UTF8.decode(opts.content);
96
- } catch {
97
- return undefined;
95
+ /** A file's text when it is UTF-8 without a NUL byte; undefined for anything else, which is data and is copied as it is. */
96
+ static decodeText(opts: { content: Buffer }): string | undefined {
97
+ if (opts.content.includes(0)) {
98
+ return undefined;
99
+ }
100
+
101
+ try {
102
+ return UTF8.decode(opts.content);
103
+ } catch {
104
+ return undefined;
105
+ }
98
106
  }
99
- };
100
107
 
101
- /** Text gets its tokens replaced; anything else is copied as it is. */
102
- const substituteTokens = (opts: { content: Buffer; tokens: Record<string, string> }): Buffer => {
103
- const text = decodeText({ content: opts.content });
108
+ static parseSpec(opts: { value: string; cwd: string }): IPresetSpec {
109
+ if (opts.value.startsWith(CreateConstants.PRESET_FILE_PREFIX)) {
110
+ const path = opts.value.slice(CreateConstants.PRESET_FILE_PREFIX.length);
104
111
 
105
- return text === undefined
106
- ? opts.content
107
- : Buffer.from(text.replace(TOKEN, (match, key: string) => opts.tokens[key] ?? match));
108
- };
112
+ return { range: `${CreateConstants.PRESET_FILE_PREFIX}${resolve(opts.cwd, path)}` };
113
+ }
109
114
 
110
- export const parsePresetSpec = (opts: { value: string; cwd: string }): IPresetSpec => {
111
- if (opts.value.startsWith(CreateConstants.PRESET_FILE_PREFIX)) {
112
- const path = opts.value.slice(CreateConstants.PRESET_FILE_PREFIX.length);
115
+ // The version separator is the last '@' that is not the scope's leading one.
116
+ const at = opts.value.lastIndexOf('@');
117
+ const [name, range] =
118
+ at > 0 ? [opts.value.slice(0, at), opts.value.slice(at + 1)] : [opts.value, 'latest'];
119
+ const packageName = name.startsWith('@') ? name : `${CreateConstants.PRESET_SCOPE}${name}`;
113
120
 
114
- return { range: `${CreateConstants.PRESET_FILE_PREFIX}${resolve(opts.cwd, path)}` };
121
+ return { packageName, range };
115
122
  }
116
123
 
117
- // The version separator is the last '@' that is not the scope's leading one.
118
- const at = opts.value.lastIndexOf('@');
119
- const [name, range] =
120
- at > 0 ? [opts.value.slice(0, at), opts.value.slice(at + 1)] : [opts.value, 'latest'];
121
- const packageName = name.startsWith('@') ? name : `${CreateConstants.PRESET_SCOPE}${name}`;
124
+ static readJson(opts: { file: string }): Record<string, unknown> | undefined {
125
+ if (!existsSync(opts.file)) {
126
+ return undefined;
127
+ }
122
128
 
123
- return { packageName, range };
124
- };
129
+ try {
130
+ return JSON.parse(readFileSync(opts.file, 'utf8'));
131
+ } catch (error) {
132
+ console.error(
133
+ `[Preset.readJson] ${opts.file} | ${error instanceof Error ? error.message : String(error)}`,
134
+ );
125
135
 
126
- export const readJson = (opts: { file: string }): Record<string, unknown> | undefined => {
127
- if (!existsSync(opts.file)) {
128
- return undefined;
136
+ return undefined;
137
+ }
129
138
  }
130
139
 
131
- try {
132
- return JSON.parse(readFileSync(opts.file, 'utf8'));
133
- } catch (error) {
134
- console.error(
135
- `[readJson] ${opts.file} | ${error instanceof Error ? error.message : String(error)}`,
136
- );
140
+ static locate(opts: { spec: IPresetSpec; root: string }): TPresetResult {
141
+ const packageRoot =
142
+ opts.spec.packageName === undefined
143
+ ? opts.spec.range.slice(CreateConstants.PRESET_FILE_PREFIX.length)
144
+ : join(opts.root, 'node_modules', opts.spec.packageName);
145
+ const manifest = Preset.readJson({ file: join(packageRoot, 'package.json') });
137
146
 
138
- return undefined;
139
- }
140
- };
147
+ if (manifest === undefined) {
148
+ return { ok: false, error: `no package at ${packageRoot} - was it installed?` };
149
+ }
141
150
 
142
- export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPresetResult => {
143
- const packageRoot =
144
- opts.spec.packageName === undefined
145
- ? opts.spec.range.slice(CreateConstants.PRESET_FILE_PREFIX.length)
146
- : join(opts.root, 'node_modules', opts.spec.packageName);
147
- const manifest = readJson({ file: join(packageRoot, 'package.json') });
151
+ const packageName = String(manifest.name);
152
+ const packageVersion = String(manifest.version);
153
+ const shown = `${packageName}@${packageVersion}`;
154
+ const vulcan = manifest[CreateConstants.PRESET_FIELD];
155
+ const oldKeys = ['preset', 'lib'].filter(
156
+ (key) => JsonValue.readProperty({ value: vulcan, key }) !== undefined,
157
+ );
148
158
 
149
- if (manifest === undefined) {
150
- return { ok: false, error: `no package at ${packageRoot} - was it installed?` };
151
- }
159
+ // No fallback to the keys before `presets`: say what the contract is now.
160
+ if (oldKeys.length > 0) {
161
+ return {
162
+ ok: false,
163
+ error: `${shown} uses the old keys "vulcan": { ${oldKeys.map((key) => `"${key}"`).join(', ')} }; the contract is now "vulcan": { "presets": { "app": "./path/preset.json", "lib": "./path/lib.json" } }`,
164
+ };
165
+ }
152
166
 
153
- const packageName = String(manifest.name);
154
- const packageVersion = String(manifest.version);
155
- const shown = `${packageName}@${packageVersion}`;
156
- const vulcan = manifest[CreateConstants.PRESET_FIELD];
157
- const oldKeys = ['preset', 'lib'].filter(
158
- (key) => readProperty({ value: vulcan, key }) !== undefined,
159
- );
160
-
161
- // No fallback to the keys before `presets`: say what the contract is now.
162
- if (oldKeys.length > 0) {
163
- return {
164
- ok: false,
165
- error: `${shown} uses the old keys "vulcan": { ${oldKeys.map((key) => `"${key}"`).join(', ')} }; the contract is now "vulcan": { "presets": { "app": "./path/preset.json", "lib": "./path/lib.json" } }`,
166
- };
167
- }
167
+ const presets = JsonValue.readProperty({ value: vulcan, key: 'presets' });
168
+ const field = JsonValue.readProperty({ value: presets, key: 'app' });
169
+ const libField = JsonValue.readProperty({ value: presets, key: 'lib' });
170
+ const sharedField = JsonValue.readProperty({ value: presets, key: 'shared' });
171
+
172
+ if (typeof field !== 'string') {
173
+ return {
174
+ ok: false,
175
+ error:
176
+ typeof libField === 'string'
177
+ ? `${shown}: vulcan.presets.lib needs vulcan.presets.app: a lib-only package is not supported`
178
+ : `${shown} ships no VULCAN preset (no "vulcan": { "presets": { "app" } } in its package.json)`,
179
+ };
180
+ }
168
181
 
169
- const presets = readProperty({ value: vulcan, key: 'presets' });
170
- const field = readProperty({ value: presets, key: 'app' });
171
- const libField = readProperty({ value: presets, key: 'lib' });
172
-
173
- if (typeof field !== 'string') {
174
- return {
175
- ok: false,
176
- error:
177
- typeof libField === 'string'
178
- ? `${shown}: vulcan.presets.lib needs vulcan.presets.app: a lib-only package is not supported`
179
- : `${shown} ships no VULCAN preset (no "vulcan": { "presets": { "app" } } in its package.json)`,
180
- };
181
- }
182
+ const presetFile = resolveInside({ root: packageRoot, from: packageRoot, path: field });
182
183
 
183
- const presetFile = resolveInside({ root: packageRoot, from: packageRoot, path: field });
184
+ if (presetFile === undefined) {
185
+ return {
186
+ ok: false,
187
+ error: `${shown}: vulcan.presets.app ${field} points outside the package`,
188
+ };
189
+ }
184
190
 
185
- if (presetFile === undefined) {
186
- return {
187
- ok: false,
188
- error: `${shown}: vulcan.presets.app ${field} points outside the package`,
189
- };
190
- }
191
+ const raw = Preset.readJson({ file: presetFile });
191
192
 
192
- const raw = readJson({ file: presetFile });
193
+ if (raw === undefined) {
194
+ return { ok: false, error: `${shown}: ${field} is missing or not JSON` };
195
+ }
193
196
 
194
- if (raw === undefined) {
195
- return { ok: false, error: `${shown}: ${field} is missing or not JSON` };
196
- }
197
+ if (raw.presetVersion !== CreateConstants.PRESET_VERSION) {
198
+ return {
199
+ ok: false,
200
+ error: `${shown} has preset version ${String(raw.presetVersion)}; this VULCAN reads version ${CreateConstants.PRESET_VERSION} - upgrade @venizia/vulcan`,
201
+ };
202
+ }
197
203
 
198
- if (raw.presetVersion !== CreateConstants.PRESET_VERSION) {
199
- return {
200
- ok: false,
201
- error: `${shown} has preset version ${String(raw.presetVersion)}; this VULCAN reads version ${CreateConstants.PRESET_VERSION} - upgrade @venizia/vulcan`,
202
- };
203
- }
204
+ const parsed = PRESET_SCHEMA.safeParse(raw);
204
205
 
205
- const parsed = PRESET_SCHEMA.safeParse(raw);
206
+ if (!parsed.success) {
207
+ const issues = parsed.error.issues
208
+ .map((issue) => `${issue.path.join('.')} ${issue.message}`)
209
+ .join('; ');
206
210
 
207
- if (!parsed.success) {
208
- const issues = parsed.error.issues
209
- .map((issue) => `${issue.path.join('.')} ${issue.message}`)
210
- .join('; ');
211
+ return { ok: false, error: `${shown}: ${field}: ${issues}` };
212
+ }
211
213
 
212
- return { ok: false, error: `${shown}: ${field}: ${issues}` };
213
- }
214
+ const filesFolder = resolveInside({
215
+ root: packageRoot,
216
+ from: dirname(presetFile),
217
+ path: parsed.data.files,
218
+ });
214
219
 
215
- const filesFolder = resolveInside({
216
- root: packageRoot,
217
- from: dirname(presetFile),
218
- path: parsed.data.files,
219
- });
220
+ if (filesFolder === undefined) {
221
+ return {
222
+ ok: false,
223
+ error: `${shown}: ${field}: files ${parsed.data.files} points outside the package`,
224
+ };
225
+ }
220
226
 
221
- if (filesFolder === undefined) {
222
- return {
223
- ok: false,
224
- error: `${shown}: ${field}: files ${parsed.data.files} points outside the package`,
225
- };
226
- }
227
+ const preset = { ...parsed.data, files: filesFolder };
228
+ const libFile =
229
+ typeof libField === 'string'
230
+ ? resolveInside({ root: packageRoot, from: packageRoot, path: libField })
231
+ : undefined;
232
+
233
+ if (typeof libField === 'string' && libFile === undefined) {
234
+ return {
235
+ ok: false,
236
+ error: `${shown}: vulcan.presets.lib ${libField} points outside the package`,
237
+ };
238
+ }
239
+
240
+ const sharedFile =
241
+ typeof sharedField === 'string'
242
+ ? resolveInside({ root: packageRoot, from: packageRoot, path: sharedField })
243
+ : undefined;
227
244
 
228
- const preset = { ...parsed.data, files: filesFolder };
229
- const libFile =
230
- typeof libField === 'string'
231
- ? resolveInside({ root: packageRoot, from: packageRoot, path: libField })
232
- : undefined;
245
+ if (typeof sharedField === 'string' && sharedFile === undefined) {
246
+ return {
247
+ ok: false,
248
+ error: `${shown}: vulcan.presets.shared ${sharedField} points outside the package`,
249
+ };
250
+ }
233
251
 
234
- if (typeof libField === 'string' && libFile === undefined) {
235
- return {
236
- ok: false,
237
- error: `${shown}: vulcan.presets.lib ${libField} points outside the package`,
252
+ const located: ILocatedPreset = {
253
+ preset,
254
+ ...(libFile === undefined ? {} : { libFile }),
255
+ ...(sharedFile === undefined ? {} : { sharedFile }),
256
+ packageRoot,
257
+ packageName,
258
+ packageVersion,
238
259
  };
239
- }
240
260
 
241
- const located: ILocatedPreset = {
242
- preset,
243
- ...(libFile === undefined ? {} : { libFile }),
244
- packageRoot,
245
- packageName,
246
- packageVersion,
247
- };
261
+ return { ok: true, located };
262
+ }
248
263
 
249
- return { ok: true, located };
250
- };
264
+ /**
265
+ * Every file the preset makes, as the app would get it: the dotfile names, the tokens replaced, symlinks
266
+ * skipped. Nothing is written: `Preset.copyFiles` writes what this returns, and `preset diff` compares it.
267
+ */
268
+ static renderFiles(opts: {
269
+ located: ILocatedPreset;
270
+ tokens: Record<string, string>;
271
+ /** The folder to render when it is not the app's: a lib preset's own. */
272
+ files?: string;
273
+ }): IRenderedPresetFile[] {
274
+ const rendered: IRenderedPresetFile[] = [];
275
+ const files = opts.files ?? opts.located.preset.files;
276
+
277
+ for (const path of new Glob('**/*').scanSync({ cwd: files, dot: true })) {
278
+ const source = join(files, path);
279
+
280
+ // A link could point at any file on the machine; only real files belong to the preset.
281
+ if (lstatSync(source).isSymbolicLink()) {
282
+ continue;
283
+ }
251
284
 
252
- /** One file a preset makes: where it lands in the app, what it holds once its tokens are replaced, its mode. */
253
- export interface IRenderedPresetFile {
254
- path: string;
255
- content: Buffer;
256
- mode: number;
257
- }
285
+ const name = basename(path);
258
286
 
259
- /**
260
- * Every file the preset makes, as the app would get it: the dotfile names, the tokens replaced, symlinks
261
- * skipped. Nothing is written: `copyPresetFiles` writes what this returns, and `preset diff` compares it.
262
- */
263
- export const renderPresetFiles = (opts: {
264
- located: ILocatedPreset;
265
- tokens: Record<string, string>;
266
- /** The folder to render when it is not the app's: a lib preset's own. */
267
- files?: string;
268
- }): IRenderedPresetFile[] => {
269
- const rendered: IRenderedPresetFile[] = [];
270
- const files = opts.files ?? opts.located.preset.files;
271
-
272
- for (const path of new Glob('**/*').scanSync({ cwd: files, dot: true })) {
273
- const source = join(files, path);
274
-
275
- // A link could point at any file on the machine; only real files belong to the preset.
276
- if (lstatSync(source).isSymbolicLink()) {
277
- continue;
287
+ rendered.push({
288
+ path: CreateConstants.PRESET_DOTFILE_NAMES.includes(name)
289
+ ? join(dirname(path), `.${name.slice(1)}`)
290
+ : path,
291
+ content: Preset.substituteTokens({ content: readFileSync(source), tokens: opts.tokens }),
292
+ mode: statSync(source).mode,
293
+ });
278
294
  }
279
295
 
280
- const name = basename(path);
281
-
282
- rendered.push({
283
- path: CreateConstants.PRESET_DOTFILE_NAMES.includes(name)
284
- ? join(dirname(path), `.${name.slice(1)}`)
285
- : path,
286
- content: substituteTokens({ content: readFileSync(source), tokens: opts.tokens }),
287
- mode: statSync(source).mode,
288
- });
296
+ return rendered;
289
297
  }
290
298
 
291
- return rendered;
292
- };
299
+ static copyFiles(opts: {
300
+ located: ILocatedPreset;
301
+ target: string;
302
+ tokens: Record<string, string>;
303
+ /** The folder to copy when it is not the app's: a lib preset's own. */
304
+ files?: string;
305
+ }): string[] {
306
+ const written: string[] = [];
293
307
 
294
- export const copyPresetFiles = (opts: {
295
- located: ILocatedPreset;
296
- target: string;
297
- tokens: Record<string, string>;
298
- /** The folder to copy when it is not the app's: a lib preset's own. */
299
- files?: string;
300
- }): string[] => {
301
- const written: string[] = [];
308
+ for (const file of Preset.renderFiles(opts)) {
309
+ const destination = join(opts.target, file.path);
302
310
 
303
- for (const file of renderPresetFiles(opts)) {
304
- const destination = join(opts.target, file.path);
311
+ mkdirSync(dirname(destination), { recursive: true });
312
+ writeFileSync(destination, file.content);
305
313
 
306
- mkdirSync(dirname(destination), { recursive: true });
307
- writeFileSync(destination, file.content);
314
+ if (file.mode & EXECUTABLE_BITS) {
315
+ chmodSync(destination, file.mode & PERMISSION_BITS);
316
+ }
308
317
 
309
- if (file.mode & EXECUTABLE_BITS) {
310
- chmodSync(destination, file.mode & PERMISSION_BITS);
318
+ written.push(file.path);
311
319
  }
312
320
 
313
- written.push(file.path);
321
+ return written;
314
322
  }
323
+ }
315
324
 
316
- return written;
317
- };
325
+ /** One file a preset makes: where it lands in the app, what it holds once its tokens are replaced, its mode. */
326
+ export interface IRenderedPresetFile {
327
+ path: string;
328
+ content: Buffer;
329
+ mode: number;
330
+ }