@venizia/vulcan 0.4.8-0 → 0.4.9-0

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 (126) hide show
  1. package/base/hooks/antigravity-guards.ts +2 -1
  2. package/base/hooks/codex-guards.ts +2 -1
  3. package/base/hooks/guard-manifest.ts +2 -1
  4. package/base/hooks/guard-package.ts +2 -1
  5. package/base/hooks/guard-remote-hosts.ts +9 -3
  6. package/base/hooks/guard-scripting.ts +2 -1
  7. package/base/hooks/guard-writes.ts +14 -4
  8. package/base/hooks/post-tool.ts +2 -1
  9. package/base/hooks/prompt-submit.ts +2 -1
  10. package/base/hooks/session-start.ts +3 -1
  11. package/base/hooks/stop.ts +2 -1
  12. package/base/make/vulcan.mk +1 -4
  13. package/base/skills/build-a-feature/SKILL.md +1 -1
  14. package/base/skills/docs-update/SKILL.md +11 -5
  15. package/base/skills/docs-update/evals/evals.json +1 -1
  16. package/base/skills/docs-writing/SKILL.md +1 -1
  17. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  18. package/base/skills/ship/SKILL.md +1 -1
  19. package/base/skills/visualize-work/SKILL.md +20 -6
  20. package/base/skills/visualize-work/references/spec.md +16 -5
  21. package/package.json +5 -6
  22. package/src/agents/codex-hooks.ts +11 -10
  23. package/src/agents/common/types.ts +1 -1
  24. package/src/agents/exclude.ts +1 -1
  25. package/src/agents/hooks-json.ts +4 -8
  26. package/src/agents/prompt.ts +2 -2
  27. package/src/agents/render.ts +8 -12
  28. package/src/cli.ts +3 -1
  29. package/src/commands/doctor.command.ts +3 -1
  30. package/src/commands/help.command.ts +11 -9
  31. package/src/commands/init.command.ts +3 -1
  32. package/src/commands/profile.command.ts +1 -1
  33. package/src/commands/upgrade.command.ts +5 -3
  34. package/src/commands/visualize.command.ts +23 -2
  35. package/src/common/index.ts +2 -0
  36. package/src/common/layout-folder.ts +2 -20
  37. package/src/common/record.ts +7 -0
  38. package/src/common/text.ts +7 -0
  39. package/src/config/common/constants.ts +13 -1
  40. package/src/config/common/types.ts +8 -1
  41. package/src/config/loader.ts +4 -2
  42. package/src/config/packages.ts +4 -1
  43. package/src/config/schema.ts +51 -4
  44. package/src/create/add-app.ts +170 -69
  45. package/src/create/add-lib.ts +41 -31
  46. package/src/create/common/constants.ts +1 -0
  47. package/src/create/common/failure.ts +10 -0
  48. package/src/create/common/index.ts +2 -0
  49. package/src/create/common/preset-path.ts +11 -0
  50. package/src/create/common/types.ts +7 -2
  51. package/src/create/init-monorepo.ts +5 -2
  52. package/src/create/lib-preset.ts +22 -17
  53. package/src/create/names.ts +1 -1
  54. package/src/create/next.ts +1 -1
  55. package/src/create/preset-diff.ts +232 -55
  56. package/src/create/preset-menu.ts +3 -3
  57. package/src/create/preset.ts +18 -10
  58. package/src/create/process.ts +4 -2
  59. package/src/create/scratch.ts +3 -1
  60. package/src/create/workspace.ts +37 -20
  61. package/src/doctor/checks.ts +74 -16
  62. package/src/doctor/runner.ts +2 -0
  63. package/src/doctor/tags.ts +2 -4
  64. package/src/hooks/codex-patch.ts +2 -2
  65. package/src/hooks/common/constants.ts +0 -3
  66. package/src/hooks/common/types.ts +15 -1
  67. package/src/hooks/decision.ts +1 -5
  68. package/src/hooks/guard-git.ts +1 -1
  69. package/src/hooks/guard-outside.ts +28 -9
  70. package/src/hooks/guard-package.ts +13 -7
  71. package/src/hooks/guard-scripting.ts +1 -1
  72. package/src/hooks/guard-writes.ts +73 -20
  73. package/src/hooks/owner-reply.ts +1 -1
  74. package/src/hooks/project-guards.ts +39 -4
  75. package/src/hooks/remote-hosts.ts +5 -20
  76. package/src/hooks/session-digest.ts +7 -0
  77. package/src/hooks/shell.ts +13 -4
  78. package/src/hooks/trusted-scripts.ts +80 -4
  79. package/src/init/common/types.ts +1 -1
  80. package/src/init/scaffold.ts +2 -2
  81. package/src/local/clean.ts +1 -1
  82. package/src/local/scan.ts +2 -2
  83. package/src/manifest/render.ts +20 -11
  84. package/src/owner/profile.ts +1 -3
  85. package/src/owner/shape.ts +1 -1
  86. package/src/owner/survey.ts +27 -18
  87. package/src/router.ts +4 -1
  88. package/src/rules/common/types.ts +1 -1
  89. package/src/signals/state.ts +1 -4
  90. package/src/sync/agent-removal.ts +7 -10
  91. package/src/sync/claude-launch.ts +36 -1
  92. package/src/sync/common/constants.ts +4 -0
  93. package/src/sync/common/index.ts +1 -0
  94. package/src/sync/common/symlink.ts +9 -0
  95. package/src/sync/common/types.ts +2 -2
  96. package/src/sync/planner.ts +10 -12
  97. package/src/sync/settings.ts +1 -1
  98. package/src/ui/keyboard.ts +3 -1
  99. package/src/ui/prompt.ts +4 -2
  100. package/src/visualize/assets.ts +370 -195
  101. package/src/visualize/charts.ts +11 -2
  102. package/src/visualize/compare-css.ts +30 -0
  103. package/src/visualize/compare-render.ts +194 -0
  104. package/src/visualize/compare-schema.ts +81 -0
  105. package/src/visualize/compare-validate.ts +126 -0
  106. package/src/visualize/constants.ts +29 -3
  107. package/src/visualize/diagrams.ts +1 -1
  108. package/src/visualize/gate.ts +136 -0
  109. package/src/visualize/icons.ts +5 -2
  110. package/src/visualize/index.ts +2 -0
  111. package/src/visualize/kinds-css.ts +54 -0
  112. package/src/visualize/kinds-render.ts +693 -0
  113. package/src/visualize/kinds-schema.ts +148 -0
  114. package/src/visualize/kinds-validate.ts +184 -0
  115. package/src/visualize/labels-vi.ts +109 -0
  116. package/src/visualize/labels.ts +49 -0
  117. package/src/visualize/layout.ts +10 -5
  118. package/src/visualize/page.ts +99 -61
  119. package/src/visualize/render.ts +48 -7
  120. package/src/visualize/schema.ts +21 -1
  121. package/src/visualize/sections.ts +115 -34
  122. package/src/visualize/sources.ts +270 -0
  123. package/src/visualize/theme.ts +472 -0
  124. package/src/visualize/validate.ts +6 -0
  125. package/src/wiki/anchors.ts +1 -1
  126. package/src/wiki/source-links.ts +3 -5
@@ -1,4 +1,5 @@
1
1
  import { join } from 'node:path';
2
+ import { RecordValue } from '../common/record.ts';
2
3
  import { RemoveOutcomes } from './common/index.ts';
3
4
 
4
5
  export const CODEX_BLOCK_START = '# vulcan:atlas:start';
@@ -6,9 +7,7 @@ export const CODEX_BLOCK_END = '# vulcan:atlas:end';
6
7
  const CODEX_TABLE = '[mcp_servers.atlas]';
7
8
  const SERVER_NAME = 'atlas';
8
9
 
9
- export type TMergeResult =
10
- | { ok: true; changed: boolean; text: string }
11
- | { ok: false; reason: string };
10
+ type TMergeResult = { ok: true; changed: boolean; text: string } | { ok: false; reason: string };
12
11
 
13
12
  /**
14
13
  * The atlas server as a per-machine file starts it: the project's own `vulcan` by absolute path with
@@ -35,9 +34,6 @@ export const canonicalAtlasEntry = (): { command: string; args: string[] } => ({
35
34
  args: ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'],
36
35
  });
37
36
 
38
- const isRecord = (value: unknown): value is Record<string, unknown> =>
39
- typeof value === 'object' && value !== null && !Array.isArray(value);
40
-
41
37
  /**
42
38
  * Whether an `atlas` entry is the one sync writes, for whatever place: `bun <root>/node_modules/.bin/vulcan
43
39
  * x atlas mcp --root <root>` (plus `type: stdio` for VS Code) with the two paths agreeing, or the relative
@@ -47,7 +43,7 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
47
43
  const isOwnEntry = (opts: { entry: unknown }): boolean => {
48
44
  const { entry } = opts;
49
45
 
50
- if (!isRecord(entry) || entry.command !== 'bun' || !Array.isArray(entry.args)) {
46
+ if (!RecordValue.isRecord(entry) || entry.command !== 'bun' || !Array.isArray(entry.args)) {
51
47
  return false;
52
48
  }
53
49
 
@@ -90,7 +86,7 @@ export const mergeMcpServers = (opts: {
90
86
  return { ok: false, reason: 'not valid JSON' };
91
87
  }
92
88
 
93
- if (!isRecord(parsed)) {
89
+ if (!RecordValue.isRecord(parsed)) {
94
90
  return { ok: false, reason: 'not a JSON object' };
95
91
  }
96
92
 
@@ -99,7 +95,7 @@ export const mergeMcpServers = (opts: {
99
95
 
100
96
  const servers = document[opts.key] ?? {};
101
97
 
102
- if (!isRecord(servers)) {
98
+ if (!RecordValue.isRecord(servers)) {
103
99
  return { ok: false, reason: `${opts.key} is not an object` };
104
100
  }
105
101
 
@@ -174,7 +170,7 @@ export const mergeCodexToml = (opts: { text: string | undefined; root: string })
174
170
  };
175
171
  };
176
172
 
177
- export type TRemoveResult =
173
+ type TRemoveResult =
178
174
  | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
179
175
  | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
180
176
  | { ok: false; reason: string };
@@ -192,13 +188,13 @@ export const removeMcpEntry = (opts: { text: string; key: string }): TRemoveResu
192
188
  return { ok: false, reason: 'not valid JSON - left untouched' };
193
189
  }
194
190
 
195
- if (!isRecord(document)) {
191
+ if (!RecordValue.isRecord(document)) {
196
192
  return { ok: false, reason: 'not a JSON object - left untouched' };
197
193
  }
198
194
 
199
195
  const servers = document[opts.key];
200
196
 
201
- if (!isRecord(servers) || !Object.hasOwn(servers, SERVER_NAME)) {
197
+ if (!RecordValue.isRecord(servers) || !Object.hasOwn(servers, SERVER_NAME)) {
202
198
  return { ok: true, outcome: RemoveOutcomes.ABSENT };
203
199
  }
204
200
 
package/src/cli.ts CHANGED
@@ -1,4 +1,6 @@
1
1
  #!/usr/bin/env bun
2
2
  import { runVulcan } from './router.ts';
3
3
 
4
- process.exit(await runVulcan({ argv: process.argv.slice(2), cwd: process.cwd() }));
4
+ const exitCode = await runVulcan({ argv: process.argv.slice(2), cwd: process.cwd() });
5
+
6
+ process.exit(exitCode);
@@ -15,7 +15,9 @@ export const runDoctorCommand = async (opts: ICommandContext): Promise<number> =
15
15
  process.stderr.write(` warning [${warning.check}] ${warning.file}: ${warning.message}\n`);
16
16
  }
17
17
 
18
- for (const note of await runDoctorNotes({ root: opts.cwd })) {
18
+ const doctorNotes = await runDoctorNotes({ root: opts.cwd });
19
+
20
+ for (const note of doctorNotes) {
19
21
  process.stderr.write(` info [${note.check}] ${note.file}: ${note.message}\n`);
20
22
  }
21
23
 
@@ -9,16 +9,18 @@ Usage: bun x vulcan <command>
9
9
  [--shared-dir <path>] [--scope <@scope>]
10
10
  Create a monorepo with its first app, from a framework preset
11
11
  (a name missing from the flags is asked in a terminal)
12
- add --preset <name|file:path> (--app <name> | --lib <name>) [--dir <folder>] [--scope <@scope>]
13
- [--backend-dir|--frontend-dir <path>] [--api <app> | --no-api]
14
- Add an app or a shared library to the monorepo (a frontend says which
15
- backend to proxy to; --dir is for a library; --scope names the package
16
- @scope/<name>, for an app or a library; a terminal asks for the kind
12
+ add --preset <name|file:path> (--app <name> | --lib <name> | --shared <name>) [--dir <folder>]
13
+ [--scope <@scope>] [--backend-dir|--frontend-dir <path>] [--api <app> | --no-api]
14
+ Add an app, a library other apps import (--lib) or a side-neutral package
15
+ other apps import (--shared) to the monorepo (a frontend says which
16
+ backend to proxy to; --dir is for a library or a shared package;
17
+ --scope names the package @scope/<name>; a terminal asks for the kind
17
18
  and every name the flags leave out)
18
- preset diff <app> [--preset <name|file:path>] [--api <app> | --no-api] [--full] [--check]
19
- Read-only: set each file the app's preset makes now against the file
20
- the app has (same, differs, missing in the app); --full prints the
21
- unified diffs, --check exits 1 when anything differs or is missing
19
+ preset diff <package> [--preset <name|file:path>] [--api <app> | --no-api] [--full] [--check]
20
+ Read-only: set each file the preset makes now (for an app, a library or
21
+ a shared package) against the file the package has (same, differs,
22
+ missing); --full prints the unified diffs, --check exits 1 when
23
+ anything differs or is missing
22
24
  sync [--agents <list>|list] [--dry-run] [--prune]
23
25
  Write the adapters of the agents you chose (--agents claude,omp or none,
24
26
  stored in .agents/vulcan.local.json; --agents list shows the table);
@@ -48,7 +48,9 @@ export const runInitCommand = async (opts: ICommandContext): Promise<number> =>
48
48
  const args = ['add', '-d', '--exact', ...result.install];
49
49
 
50
50
  process.stderr.write(`installing ${result.install.join(' ')}\n`);
51
- installCode = await runBun({ cwd: opts.cwd, args, label: `bun ${args.join(' ')}` });
51
+ const installExit = await runBun({ cwd: opts.cwd, args, label: `bun ${args.join(' ')}` });
52
+
53
+ installCode = installExit;
52
54
 
53
55
  if (installCode !== ExitCodes.OK) {
54
56
  process.stderr.write(`vulcan init: 'bun ${args.join(' ')}' failed - run it yourself\n`);
@@ -100,7 +100,7 @@ const lineIo: ISurveyIo = {
100
100
  };
101
101
 
102
102
  /** Runs the form and saves the profile; the exit code of the command. */
103
- export const fillInProfile = async (opts: { root: string }): Promise<number> => {
103
+ const fillInProfile = async (opts: { root: string }): Promise<number> => {
104
104
  const current = readProfile({ root: opts.root });
105
105
 
106
106
  if (!current.ok) {
@@ -32,7 +32,7 @@ const parseTag = (opts: { tags: unknown; key: keyof IDistTags }): string | undef
32
32
  };
33
33
 
34
34
  /** The `latest` and `next` tags of a registry answer, or undefined when it is not an object of versions. */
35
- export const parseDistTags = (opts: { text: string }): IDistTags | undefined => {
35
+ const parseDistTags = (opts: { text: string }): IDistTags | undefined => {
36
36
  let parsed: unknown;
37
37
 
38
38
  try {
@@ -56,7 +56,7 @@ export const parseDistTags = (opts: { text: string }): IDistTags | undefined =>
56
56
  * auth settings. `VULCAN_DIST_TAGS` replaces it so tests run offline. Undefined when the read fails,
57
57
  * after printing why bun failed.
58
58
  */
59
- export const readDistTags = async (opts: { cwd: string }): Promise<IDistTags | undefined> => {
59
+ const readDistTags = async (opts: { cwd: string }): Promise<IDistTags | undefined> => {
60
60
  const injected = process.env[UpgradeFlags.DIST_TAGS_ENV];
61
61
 
62
62
  if (injected !== undefined) {
@@ -73,7 +73,9 @@ export const readDistTags = async (opts: { cwd: string }): Promise<IDistTags | u
73
73
  new Response(child.stderr).text(),
74
74
  ]);
75
75
 
76
- if ((await child.exited) !== ExitCodes.OK) {
76
+ const exitCode = await child.exited;
77
+
78
+ if (exitCode !== ExitCodes.OK) {
77
79
  process.stderr.write(errorText.endsWith('\n') ? errorText : `${errorText}\n`);
78
80
 
79
81
  return undefined;
@@ -2,7 +2,14 @@ import { readFileSync, statSync } from 'node:fs';
2
2
  import { basename, resolve } from 'node:path';
3
3
  import { ExitCodes } from '../common/index.ts';
4
4
  import type { ICommandContext } from '../common/index.ts';
5
- import { pageNameOf, renderSpecText, specSchemaText, writePage } from '../visualize/index.ts';
5
+ import { readProfile } from '../owner/profile.ts';
6
+ import {
7
+ pageNameOf,
8
+ ProjectTheme,
9
+ renderSpecText,
10
+ specSchemaText,
11
+ writePage,
12
+ } from '../visualize/index.ts';
6
13
 
7
14
  const SCHEMA_FLAG = '--schema';
8
15
  const OUT_FLAG = '--out';
@@ -75,7 +82,17 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
75
82
  return ExitCodes.FAILURE;
76
83
  }
77
84
 
78
- const rendered = renderSpecText({ text });
85
+ // The page takes the project's colour from the manifest of the folder it runs in (no config is loaded, nothing
86
+ // is requested) and its words from the owner's profile; a spec's own `accent` and `language` win.
87
+ const manifest = ProjectTheme.readManifestTheme({ root: opts.cwd });
88
+ const profile = readProfile({ root: opts.cwd });
89
+ const rendered = renderSpecText({
90
+ text,
91
+ context: {
92
+ language: profile.ok ? profile.profile?.language : undefined,
93
+ project: manifest.theme,
94
+ },
95
+ });
79
96
 
80
97
  if (!rendered.ok) {
81
98
  process.stderr.write(
@@ -95,6 +112,10 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
95
112
 
96
113
  process.stdout.write(`${written.path}\n`);
97
114
 
115
+ if (manifest.warning !== undefined) {
116
+ process.stderr.write(`warning: ${manifest.warning}\n`);
117
+ }
118
+
98
119
  for (const warning of rendered.page.warnings) {
99
120
  process.stderr.write(`warning: ${warning}\n`);
100
121
  }
@@ -3,3 +3,5 @@ export * from './paths.ts';
3
3
  export * from './types.ts';
4
4
  export * from './json.ts';
5
5
  export * from './format.ts';
6
+ export * from './record.ts';
7
+ export * from './text.ts';
@@ -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. */
@@ -130,16 +130,6 @@ export const layoutOverlapProblems = (opts: { layout: ILayout }): string[] => {
130
130
  return problems;
131
131
  };
132
132
 
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 });
137
-
138
- return problem === undefined ? [] : [`layout.${entry.key}: ${problem}`];
139
- }),
140
- ...layoutOverlapProblems({ layout: opts.layout }),
141
- ];
142
-
143
133
  /** The layout value with `folder` in it: unchanged when it is there already, a string that grows into a list otherwise. */
144
134
  export const withLayoutFolder = (opts: {
145
135
  value: TLayoutValue | undefined;
@@ -154,14 +144,6 @@ export const withLayoutFolder = (opts: {
154
144
  return folders.length === 0 ? opts.folder : [...folders, opts.folder];
155
145
  };
156
146
 
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
147
  /** The valid folders of a layout value; a manifest is read through this, never trusted. */
166
148
  export const validLayoutFolders = (opts: { value: unknown }): string[] =>
167
149
  layoutFoldersOf({ value: opts.value }).filter(
@@ -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,7 +5,7 @@ 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
 
@@ -40,7 +40,9 @@ export const loadConfig = async (opts: { root: string }): Promise<TLoadResult> =
40
40
  let loaded: { default?: unknown };
41
41
 
42
42
  try {
43
- loaded = await import(pathToFileURL(file).href);
43
+ const imported = await import(pathToFileURL(file).href);
44
+
45
+ loaded = imported;
44
46
  } catch (error) {
45
47
  return { ok: false, file, error: `${shown}: failed to load - ${describeError({ error })}` };
46
48
  }
@@ -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,6 +11,8 @@ 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
18
  /** The project's packages in release order. */
@@ -22,4 +24,5 @@ export const resolvePackages = (opts: { config: TResolvedConfig }): IProjectPack
22
24
  aliases: entry.aliases,
23
25
  retired: entry.retired,
24
26
  ...(entry.kind === undefined ? {} : { kind: entry.kind }),
27
+ ...(entry.presetKind === undefined ? {} : { presetKind: entry.presetKind }),
25
28
  }));
@@ -2,7 +2,13 @@ import { isAbsolute } from 'node:path';
2
2
  import { z } from 'zod';
3
3
  import { layoutFolderProblem, layoutOverlapProblems } 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(', ')}`,
@@ -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. */
@@ -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.