@venizia/vulcan 0.4.8 → 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
@@ -56,7 +56,9 @@ export const withScratch = async <TResult>(opts: {
56
56
  const scratch = mkdtempSync(join(parent, 'preset-'));
57
57
 
58
58
  try {
59
- return await opts.run(scratch);
59
+ const outcome = await opts.run(scratch);
60
+
61
+ return outcome;
60
62
  } finally {
61
63
  rmSync(scratch, { recursive: true, force: true });
62
64
  removeIfEmpty({ directory: parent });
@@ -1,6 +1,8 @@
1
1
  import { relative, resolve } from 'node:path';
2
+ import { RecordValue } from '../common/record.ts';
2
3
  import { coversFolder } from '../init/index.ts';
3
- import { PackageKinds } from '../config/index.ts';
4
+ import { LibraryKinds, PackageKinds } from '../config/index.ts';
5
+ import type { TLibraryKind } from '../config/index.ts';
4
6
  import { AppsBlockProblems, CreateConstants } from './common/index.ts';
5
7
  import { renderManifestJson } from './manifest-json.ts';
6
8
  import type {
@@ -40,11 +42,8 @@ export const mergeCatalog = (opts: {
40
42
  additions: Record<string, string>;
41
43
  }): Record<string, string> => ({ ...opts.additions, ...opts.catalog });
42
44
 
43
- const isRecord = (value: unknown): value is Record<string, unknown> =>
44
- typeof value === 'object' && value !== null && !Array.isArray(value);
45
-
46
45
  const toStringRecord = (opts: { value: unknown }): Record<string, string> =>
47
- isRecord(opts.value)
46
+ RecordValue.isRecord(opts.value)
48
47
  ? Object.fromEntries(
49
48
  Object.entries(opts.value).filter(
50
49
  (entry): entry is [string, string] => typeof entry[1] === 'string',
@@ -56,7 +55,7 @@ const toStringRecord = (opts: { value: unknown }): Record<string, string> =>
56
55
  export const readCatalog = (opts: {
57
56
  manifest: Record<string, unknown>;
58
57
  }): Record<string, string> => ({
59
- ...(isRecord(opts.manifest.workspaces)
58
+ ...(RecordValue.isRecord(opts.manifest.workspaces)
60
59
  ? toStringRecord({ value: opts.manifest.workspaces.catalog })
61
60
  : {}),
62
61
  ...toStringRecord({ value: opts.manifest.catalog }),
@@ -82,14 +81,14 @@ export const planRootManifest = (opts: {
82
81
  const fresh = Object.fromEntries(
83
82
  Object.entries(opts.additions).filter(([name]) => existing[name] === undefined),
84
83
  );
85
- const isTopLevel = isRecord(manifest.catalog) || Array.isArray(workspaces);
84
+ const isTopLevel = RecordValue.isRecord(manifest.catalog) || Array.isArray(workspaces);
86
85
 
87
86
  if (isTopLevel) {
88
87
  return {
89
88
  ...manifest,
90
89
  workspaces: Array.isArray(workspaces)
91
90
  ? globs
92
- : { ...(isRecord(workspaces) ? workspaces : {}), packages: globs },
91
+ : { ...(RecordValue.isRecord(workspaces) ? workspaces : {}), packages: globs },
93
92
  catalog: mergeCatalog({
94
93
  catalog: toStringRecord({ value: manifest.catalog }),
95
94
  additions: fresh,
@@ -97,7 +96,7 @@ export const planRootManifest = (opts: {
97
96
  };
98
97
  }
99
98
 
100
- const inside = isRecord(workspaces) ? workspaces : {};
99
+ const inside = RecordValue.isRecord(workspaces) ? workspaces : {};
101
100
 
102
101
  return {
103
102
  ...manifest,
@@ -121,6 +120,8 @@ export const planRootManifest = (opts: {
121
120
  export const checkPeers = (opts: {
122
121
  catalog: Record<string, string>;
123
122
  peers: Record<string, string>;
123
+ /** What the preset itself lists, so the catalog `init` wrote from it is not held to its own range. */
124
+ presetVersions?: Pick<IPreset, 'dependencies' | 'devDependencies'>;
124
125
  }): string | undefined => {
125
126
  for (const [name, range] of Object.entries(opts.peers)) {
126
127
  const pinned = opts.catalog[name];
@@ -129,6 +130,15 @@ export const checkPeers = (opts: {
129
130
  continue;
130
131
  }
131
132
 
133
+ // A pin equal to the version this preset lists is satisfied by construction (`init` wrote it
134
+ // from the preset); only a pin set by something else is compared with the range.
135
+ if (
136
+ pinned === opts.presetVersions?.dependencies[name] ||
137
+ pinned === opts.presetVersions?.devDependencies[name]
138
+ ) {
139
+ continue;
140
+ }
141
+
132
142
  const version = pinned.replace(/^[\^~]/, '');
133
143
 
134
144
  if (!CreateConstants.VERSION_PATTERN.test(version)) {
@@ -225,7 +235,7 @@ const ATLAS_LOOKUPS: Record<TAppSide | typeof PackageKinds.LIB, [string, string]
225
235
  ['How a page or a resource is added', '`search` "page resource", then `get`'],
226
236
  ['How the app reads data from its backend', '`search` "data provider"'],
227
237
  ],
228
- lib: [['How a shared package exposes its API', '`search` "shared package exports", then `get`']],
238
+ lib: [['How a library exposes its API', '`search` "library exports", then `get`']],
229
239
  };
230
240
 
231
241
  /** The note and the table that turn a package page into a pointer at atlas, for its kind. */
@@ -248,6 +258,8 @@ export const renderLibConcept = (opts: {
248
258
  path: string;
249
259
  summary: string;
250
260
  presetPackage: string;
261
+ /** Which preset kind made the package; `lib` when absent. */
262
+ kind?: TLibraryKind;
251
263
  }): string =>
252
264
  [
253
265
  '---',
@@ -260,7 +272,7 @@ export const renderLibConcept = (opts: {
260
272
  '',
261
273
  `# ${opts.name}`,
262
274
  '',
263
- `The shared package at \`${opts.path}\`, created from the ${opts.presetPackage} preset (lib kind). ${oneLine({ text: opts.summary })}`,
275
+ `The ${opts.kind === LibraryKinds.SHARED ? 'side-neutral package' : 'library'} at \`${opts.path}\`, created from the ${opts.presetPackage} preset (${opts.kind ?? LibraryKinds.LIB} kind). ${oneLine({ text: opts.summary })}`,
264
276
  '',
265
277
  ...renderAtlasLookups({ kind: PackageKinds.LIB }),
266
278
  ].join('\n');
@@ -343,33 +355,38 @@ export const replaceAppsBlock = (opts: {
343
355
  const hasStrings = (opts: { value: unknown; keys: string[] }): boolean => {
344
356
  const { value } = opts;
345
357
 
346
- return isRecord(value) && opts.keys.every((key) => typeof value[key] === 'string');
358
+ return RecordValue.isRecord(value) && opts.keys.every((key) => typeof value[key] === 'string');
347
359
  };
348
360
 
349
361
  const isRecordedPreset = (value: unknown): boolean =>
350
362
  hasStrings({ value, keys: ['spec', 'side', 'summary'] }) &&
351
- isRecord(value) &&
363
+ RecordValue.isRecord(value) &&
352
364
  (value.side === 'backend' || value.side === 'frontend') &&
353
- (value.lib === undefined || typeof value.lib === 'string');
365
+ (value.lib === undefined || typeof value.lib === 'string') &&
366
+ (value.shared === undefined || typeof value.shared === 'string');
354
367
 
355
368
  const isAppsBlock = (value: unknown): value is IAppsBlock =>
356
- isRecord(value) &&
369
+ RecordValue.isRecord(value) &&
357
370
  (value.presets === undefined ||
358
371
  (Array.isArray(value.presets) && value.presets.every((entry) => isRecordedPreset(entry)))) &&
359
- isRecord(value.layout) &&
372
+ RecordValue.isRecord(value.layout) &&
360
373
  Object.values(value.layout).every(
361
374
  (folders) =>
362
375
  typeof folders === 'string' ||
363
376
  (Array.isArray(folders) && folders.every((folder) => typeof folder === 'string')),
364
377
  ) &&
365
378
  Array.isArray(value.packages) &&
366
- value.packages.every((entry) => hasStrings({ value: entry, keys: ['dir', 'name', 'path'] })) &&
379
+ value.packages.every(
380
+ (entry) =>
381
+ hasStrings({ value: entry, keys: ['dir', 'name', 'path'] }) &&
382
+ RecordValue.isRecord(entry) &&
383
+ (entry.presetKind === undefined ||
384
+ (typeof entry.presetKind === 'string' && LibraryKinds.isValid(entry.presetKind))),
385
+ ) &&
367
386
  Array.isArray(value.sources) &&
368
387
  value.sources.every((entry) => hasStrings({ value: entry, keys: ['name', 'repo', 'ref'] }));
369
388
 
370
- export type TAppsBlockResult =
371
- | { ok: true; block: IAppsBlock }
372
- | { ok: false; reason: TAppsBlockProblem };
389
+ type TAppsBlockResult = { ok: true; block: IAppsBlock } | { ok: false; reason: TAppsBlockProblem };
373
390
 
374
391
  const APPS_DECLARATION = 'const apps = ';
375
392
 
@@ -1,8 +1,8 @@
1
1
  import { Glob } from 'bun';
2
2
  import { spawnSync } from 'node:child_process';
3
- import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
3
+ import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
4
4
  import { basename, dirname, join, relative, sep } from 'node:path';
5
- import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
5
+ import { BASE_DIRECTORY, ProjectLayout, RecordValue } from '../common/index.ts';
6
6
  import { LayoutKeys, layoutFoldersOf } from '../common/layout-folder.ts';
7
7
  import {
8
8
  coversFolder,
@@ -51,7 +51,7 @@ import {
51
51
  violationLogBytes,
52
52
  ViolationConstants,
53
53
  } from '../owner/index.ts';
54
- import { skillCatalogOf, triggerOf } from '@venizia/vulcan-atlas';
54
+ import { SkillCatalog } from '@venizia/vulcan-atlas';
55
55
  import { trustOf, TrustStates } from '../hooks/index.ts';
56
56
  import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
57
57
  import type { IViolation, TDoctorCheck } from './common/index.ts';
@@ -273,7 +273,7 @@ export const checkAdapters = (opts: ICheckContext): IViolation[] => {
273
273
  createViolation({
274
274
  check: DoctorChecks.ADAPTERS,
275
275
  file: relative(opts.root, absent[0].path),
276
- message: `not synced yet - run '${ProjectLayout.VULCAN_COMMAND} sync' (make agent-setup) first`,
276
+ message: `not synced yet - run '${ProjectLayout.VULCAN_COMMAND} sync' (make vulcan-sync) first`,
277
277
  }),
278
278
  ];
279
279
 
@@ -644,9 +644,6 @@ const readJsonObject = (opts: { file: string }): Record<string, unknown> | undef
644
644
  }
645
645
  };
646
646
 
647
- const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
648
- typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
649
-
650
647
  /** Whether git lists the file as untracked and not ignored: what a clean-tree check, such as a release, refuses on. */
651
648
  const isUntrackedAndVisible = (opts: { root: string; path: string }): boolean => {
652
649
  const listed = spawnSync('git', ['status', '--porcelain', '--', opts.path], {
@@ -708,17 +705,17 @@ export const checkMcpAtlas = (opts: ICheckContext): IViolation[] => {
708
705
  );
709
706
  } else {
710
707
  const holder = { value: parsed['mcpServers'] };
711
- const servers = isRecord(holder) ? holder.value : {};
708
+ const servers = RecordValue.isRecord(holder.value) ? holder.value : {};
712
709
  const entry = { value: servers[ATLAS_SERVER] };
713
- const args = isRecord(entry) ? entry.value['args'] : undefined;
710
+ const args = RecordValue.isRecord(entry.value) ? entry.value['args'] : undefined;
714
711
  const isCanonical =
715
- isRecord(entry) &&
712
+ RecordValue.isRecord(entry.value) &&
716
713
  entry.value['command'] === 'bun' &&
717
714
  Array.isArray(args) &&
718
715
  args.length === CANONICAL_ATLAS_ARGS.length &&
719
716
  args.every((arg, index) => arg === CANONICAL_ATLAS_ARGS[index]);
720
717
 
721
- if (!isRecord(entry)) {
718
+ if (!RecordValue.isRecord(entry.value)) {
722
719
  warnings.push(
723
720
  mcpWarning({
724
721
  file: MCP_FILE,
@@ -974,8 +971,8 @@ export const checkAtlasBlock = (opts: ICheckContext): IViolation[] => {
974
971
 
975
972
  /** A skill with no "Use when" part gives the atlas server's instructions nothing to say when to load it: a warning, never a failure. */
976
973
  export const checkSkillTriggers = (opts: ICheckContext): IViolation[] =>
977
- skillCatalogOf({ root: opts.root })
978
- .filter((entry) => !triggerOf({ description: entry.description }).hasUseWhen)
974
+ SkillCatalog.catalogOf({ root: opts.root })
975
+ .filter((entry) => !SkillCatalog.triggerOf({ description: entry.description }).hasUseWhen)
979
976
  .map((entry) =>
980
977
  createViolation({
981
978
  check: DoctorChecks.SKILLS,
@@ -1173,25 +1170,86 @@ const STALE_TRUST_STATES = new Set<string>([
1173
1170
  TrustStates.UNKNOWN,
1174
1171
  ]);
1175
1172
 
1173
+ const QUOTES = ["'", '"', '`'];
1174
+
1175
+ /** The path of a `guard.writes.trustedScripts` entry, and the subcommands when it is the object form. */
1176
+ const trustedScriptOf = (opts: {
1177
+ entry: TResolvedConfig['guard']['writes']['trustedScripts'][number];
1178
+ }): { script: string; readOnly: string[] | undefined } =>
1179
+ typeof opts.entry === 'string'
1180
+ ? { script: opts.entry, readOnly: undefined }
1181
+ : { script: opts.entry.script, readOnly: opts.entry.readOnly };
1182
+
1176
1183
  /** One line per script in `guard.writes.trustedScripts` with what git says about it now (a note). */
1177
1184
  export const checkTrustedScripts = (opts: ICheckContext): IViolation[] =>
1178
- opts.config.guard.writes.trustedScripts.map((script) => {
1185
+ opts.config.guard.writes.trustedScripts.map((entry) => {
1186
+ const { script, readOnly } = trustedScriptOf({ entry });
1179
1187
  const trust = trustOf({ root: opts.root, script });
1188
+ const scope = readOnly === undefined ? 'mutating calls' : `the calls ${readOnly.join(', ')}`;
1180
1189
 
1181
1190
  return createViolation({
1182
1191
  check: DoctorChecks.GUARDS,
1183
1192
  file: script,
1184
1193
  message:
1185
1194
  trust.state === TrustStates.TRUSTED
1186
- ? 'guard-writes does not read this script for mutating calls (guard.writes.trustedScripts); it is ' +
1195
+ ? `guard-writes does not read this script for ${scope} (guard.writes.trustedScripts); it is ` +
1187
1196
  trust.reason
1188
1197
  : `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
1189
1198
  });
1190
1199
  });
1191
1200
 
1201
+ /**
1202
+ * A subcommand an object entry lists that its script never holds as a quoted string (a note). It reads the
1203
+ * text of the file, so it cannot tell a subcommand the script handles another way from a typo.
1204
+ */
1205
+ export class ReadOnlySubcommandChecks {
1206
+ static readonly MAX_SOURCE_BYTES = 1_000_000;
1207
+
1208
+ static sourceOf(opts: { path: string }): string | undefined {
1209
+ try {
1210
+ const stat = lstatSync(opts.path);
1211
+
1212
+ return stat.isFile() && stat.size <= ReadOnlySubcommandChecks.MAX_SOURCE_BYTES
1213
+ ? readFileSync(opts.path, 'utf8')
1214
+ : undefined;
1215
+ } catch {
1216
+ return undefined;
1217
+ }
1218
+ }
1219
+
1220
+ static check(opts: ICheckContext): IViolation[] {
1221
+ return opts.config.guard.writes.trustedScripts.flatMap((entry) => {
1222
+ const { script, readOnly } = trustedScriptOf({ entry });
1223
+ const path = join(opts.root, script);
1224
+
1225
+ if (readOnly === undefined) {
1226
+ return [];
1227
+ }
1228
+
1229
+ // Only a plain, small file inside the repo is read: a link, a folder or a device is skipped, never followed.
1230
+ const source = ReadOnlySubcommandChecks.sourceOf({ path });
1231
+
1232
+ if (source === undefined) {
1233
+ return [];
1234
+ }
1235
+
1236
+ return readOnly
1237
+ .filter((word) => !QUOTES.some((quote) => source.includes(`${quote}${word}${quote}`)))
1238
+ .map((word) =>
1239
+ createViolation({
1240
+ check: DoctorChecks.GUARDS,
1241
+ file: script,
1242
+ message: `guard.writes.trustedScripts lists the subcommand '${word}' for this script, but the script does not hold it as a quoted string; this is a check of the text of the file, not what the script does`,
1243
+ }),
1244
+ );
1245
+ });
1246
+ }
1247
+ }
1248
+
1192
1249
  /** A listed script that does not exist or is not committed: the exemption never applies (a warning). */
1193
1250
  export const checkStaleTrustedScripts = (opts: ICheckContext): IViolation[] =>
1194
- opts.config.guard.writes.trustedScripts.flatMap((script) => {
1251
+ opts.config.guard.writes.trustedScripts.flatMap((entry) => {
1252
+ const { script } = trustedScriptOf({ entry });
1195
1253
  const trust = trustOf({ root: opts.root, script });
1196
1254
 
1197
1255
  return STALE_TRUST_STATES.has(trust.state)
@@ -18,6 +18,7 @@ import {
18
18
  checkReplyShape,
19
19
  checkPrune,
20
20
  checkStaleLocal,
21
+ ReadOnlySubcommandChecks,
21
22
  checkStaleTrustedScripts,
22
23
  checkTrustedScripts,
23
24
  checkHooks,
@@ -102,6 +103,7 @@ export const runDoctorNotes = async (opts: {
102
103
  ...checkReplyShape(context),
103
104
  ...checkOwnerReplySwitch({ env: opts.env ?? process.env }),
104
105
  ...checkTrustedScripts(context),
106
+ ...ReadOnlySubcommandChecks.check(context),
105
107
  ];
106
108
  };
107
109
 
@@ -1,12 +1,10 @@
1
1
  import { spawnSync } from 'node:child_process';
2
+ import { TextValue } from '../common/text.ts';
2
3
  import { resolvePackages } from '../config/index.ts';
3
4
  import type { ICheckContext } from './checks.ts';
4
5
  import { DoctorChecks } from './common/index.ts';
5
6
  import type { IViolation } from './common/index.ts';
6
7
 
7
- const escapeLiteral = (opts: { text: string }): string =>
8
- opts.text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
9
-
10
8
  /** The tag pattern as a regular expression that captures `<dir>` (or `<package>`). */
11
9
  const tagPatternOf = (opts: { template: string }): RegExp =>
12
10
  new RegExp(
@@ -28,7 +26,7 @@ const tagPatternOf = (opts: { template: string }): RegExp =>
28
26
  }
29
27
 
30
28
  default: {
31
- return escapeLiteral({ text: part });
29
+ return TextValue.escapeLiteral({ text: part });
32
30
  }
33
31
  }
34
32
  })
@@ -13,9 +13,9 @@ export class PatchedTools {
13
13
  }
14
14
  }
15
15
 
16
- export type TPatchedTool = TConstValue<typeof PatchedTools>;
16
+ type TPatchedTool = TConstValue<typeof PatchedTools>;
17
17
 
18
- export interface IPatchedFile {
18
+ interface IPatchedFile {
19
19
  path: string;
20
20
  tool: TPatchedTool;
21
21
  }
@@ -78,9 +78,6 @@ export class HookConstants {
78
78
  '/tmp/claude-[0-9]*/*/*/scratchpad',
79
79
  '/tmp/claude-[0-9]*/*/*/scratchpad/**',
80
80
  ];
81
- /** Set to `off` to switch the guards off for a session; the hooks then pass every call. */
82
- static readonly KILL_SWITCH_ENV = 'VULCAN_GUARDS';
83
- static readonly KILL_SWITCH_OFF = 'off';
84
81
  /**
85
82
  * Tool-owned stores an agent may write into: package manager caches, the runtime dir for locks, the
86
83
  * agent tool's memory. Never a directory on PATH (`~/.bun/bin`) or a file git or a shell runs (`~/.gitconfig`).
@@ -3,7 +3,7 @@ import type { GuardDecisions, PackageVerdictKinds, TrustStates } from './constan
3
3
 
4
4
  export type TGuardDecision = TConstValue<typeof GuardDecisions>;
5
5
  export type TPackageVerdictKind = TConstValue<typeof PackageVerdictKinds>;
6
- export type TTrustState = TConstValue<typeof TrustStates>;
6
+ type TTrustState = TConstValue<typeof TrustStates>;
7
7
 
8
8
  /** Whether a listed trusted script may skip the script checks, and if not, why - in words an ask can show. */
9
9
  export interface IScriptTrust {
@@ -11,6 +11,20 @@ export interface IScriptTrust {
11
11
  reason: string;
12
12
  }
13
13
 
14
+ /** A script the project vouches for on some subcommands only: the first argument after the script is one of `readOnly`. */
15
+ export interface IReadOnlyScript {
16
+ script: string;
17
+ readOnly: string[];
18
+ }
19
+
20
+ /** One `bun x.ts` call as the shell sees it: the script word and the word right after it, if any. */
21
+ export interface IScriptInvocation {
22
+ script: string;
23
+ subcommand: string | undefined;
24
+ /** A `cd`, `pushd` or `popd` came before it in the line, so a relative script word is not from the hook's folder. */
25
+ moved: boolean;
26
+ }
27
+
14
28
  export interface IWriteCheck {
15
29
  rule: string;
16
30
  what: string;
@@ -1,7 +1,7 @@
1
1
  import { GuardDecisions, HookConstants } from './common/index.ts';
2
2
  import type { TGuardDecision } from './common/index.ts';
3
3
 
4
- export interface IDecisionOutput {
4
+ interface IDecisionOutput {
5
5
  hookSpecificOutput: {
6
6
  hookEventName: string;
7
7
  permissionDecision: string;
@@ -51,7 +51,3 @@ export const buildToolDecision = (opts: { decision: TGuardDecision; reason: stri
51
51
  },
52
52
  },
53
53
  });
54
-
55
- /** Whether the session switched the guards off (`VULCAN_GUARDS=off`): every call then passes. */
56
- export const guardsAreOff = (opts: { env?: Record<string, string | undefined> } = {}): boolean =>
57
- (opts.env ?? process.env)[HookConstants.KILL_SWITCH_ENV] === HookConstants.KILL_SWITCH_OFF;
@@ -6,7 +6,7 @@ import type { IGitHit, IGitRunner } from './common/index.ts';
6
6
  import { matchesBranch } from './project-guards.ts';
7
7
 
8
8
  /** `git` and `gh` read-only queries the guard makes; `undefined` when the tool is missing, slow or fails. */
9
- export const runQuery: IGitRunner = (opts) => {
9
+ const runQuery: IGitRunner = (opts) => {
10
10
  const result = spawnSync(opts.program, opts.args, {
11
11
  cwd: opts.cwd,
12
12
  encoding: 'utf8',
@@ -11,11 +11,15 @@ const FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
11
11
 
12
12
  type TEnvironment = Record<string, string | undefined>;
13
13
 
14
- /** `~` and `$NAME` / `${NAME}` expanded; `undefined` when a variable is unset or the word is not a plain path. */
14
+ /**
15
+ * `~` and `$NAME` / `${NAME}` expanded; `undefined` when a variable is unset or the word is not a plain path.
16
+ * `$PWD` is the folder the command runs in (`cwd`), not the `PWD` of this hook's own process.
17
+ */
15
18
  const expandPath = (opts: {
16
19
  word: string;
17
20
  home: string;
18
21
  env: TEnvironment;
22
+ cwd?: string;
19
23
  }): string | undefined => {
20
24
  if (opts.word === '' || /[`*?[]/.test(opts.word) || opts.word.includes('$(')) {
21
25
  return undefined;
@@ -25,7 +29,7 @@ const expandPath = (opts: {
25
29
  const home = opts.word === '~' || opts.word.startsWith('~/') ? opts.home : undefined;
26
30
  const withHome = home === undefined ? opts.word : `${home}${opts.word.slice(1)}`;
27
31
  const expanded = withHome.replace(/\$\{?(\w+)\}?/g, (_, name: string) => {
28
- const value = opts.env[name];
32
+ const value = name === 'PWD' && opts.cwd !== undefined ? opts.cwd : opts.env[name];
29
33
 
30
34
  if (value === undefined || value === '') {
31
35
  unresolved = true;
@@ -61,10 +65,15 @@ const realOf = (opts: { path: string; depth?: number }): string => {
61
65
  try {
62
66
  base = realpathSync(existing);
63
67
  } catch {
64
- // A dangling link: its target is where a write through it lands.
65
- const target = depth < 8 ? readlinkSync(existing) : existing;
68
+ // A dangling link: its target is where a write through it lands; a chain this long is a loop.
69
+ if (depth >= 8) {
70
+ return join(existing, ...rest);
71
+ }
66
72
 
67
- base = realOf({ path: resolve(dirname(existing), target), depth: depth + 1 });
73
+ base = realOf({
74
+ path: resolve(dirname(existing), readlinkSync(existing)),
75
+ depth: depth + 1,
76
+ });
68
77
  }
69
78
 
70
79
  return join(base, ...rest);
@@ -111,6 +120,8 @@ interface ITarget {
111
120
  message: string;
112
121
  /** The directory a relative `word` is taken from: the hook's, moved by `cd` and `git -C`. */
113
122
  base: string;
123
+ /** What `$PWD` is in `word`: the shell's folder, moved by `cd` but not by `git -C`; undefined when it is not known. */
124
+ pwd?: string;
114
125
  }
115
126
 
116
127
  const positional = (opts: { args: string[] }): string[] =>
@@ -365,7 +376,9 @@ export const inspectOutside = (opts: {
365
376
  home,
366
377
  env,
367
378
  });
368
- const start = opts.input.cwd ?? opts.projectRoot;
379
+ const start = resolve(opts.input.cwd ?? opts.projectRoot);
380
+ // `$PWD` is the call's folder only when the host said which one it is; otherwise the hook's own `PWD` stays the fallback.
381
+ const startPwd = opts.input.cwd === undefined ? undefined : start;
369
382
  const tmp = commandTmpdirOf({ env, projectRoot: opts.projectRoot });
370
383
  const targets: ITarget[] = [];
371
384
 
@@ -373,6 +386,7 @@ export const inspectOutside = (opts: {
373
386
  targets.push({
374
387
  word: opts.input.filePath,
375
388
  base: start,
389
+ pwd: startPwd,
376
390
  message: `${opts.input.tool} writes ${opts.input.filePath}`,
377
391
  });
378
392
  }
@@ -381,6 +395,7 @@ export const inspectOutside = (opts: {
381
395
 
382
396
  if (opts.input.command !== undefined) {
383
397
  let base = start;
398
+ let pwd = startPwd;
384
399
 
385
400
  const parsed = parseShellChecked({ command: opts.input.command });
386
401
 
@@ -392,13 +407,17 @@ export const inspectOutside = (opts: {
392
407
  if (basenameOf({ word: program.name }) === 'cd') {
393
408
  const [destination] = positional({ args: program.args });
394
409
  const expanded =
395
- destination === undefined ? undefined : expandPath({ word: destination, home, env });
410
+ destination === undefined
411
+ ? undefined
412
+ : expandPath({ word: destination, home, env, cwd: pwd });
396
413
 
397
414
  base = expanded === undefined ? base : resolve(base, expanded);
415
+ // A `cd` the guard cannot work out leaves the shell's folder unknown.
416
+ pwd = expanded === undefined ? undefined : base;
398
417
  continue;
399
418
  }
400
419
 
401
- targets.push(...targetsOf({ command, base, tmp }));
420
+ targets.push(...targetsOf({ command, base, tmp }).map((target) => ({ ...target, pwd })));
402
421
  }
403
422
  }
404
423
 
@@ -415,7 +434,7 @@ export const inspectOutside = (opts: {
415
434
  : [];
416
435
 
417
436
  for (const target of targets) {
418
- const expanded = expandPath({ word: target.word, home, env });
437
+ const expanded = expandPath({ word: target.word, home, env, cwd: target.pwd });
419
438
 
420
439
  if (expanded === undefined) {
421
440
  continue;
@@ -11,7 +11,7 @@ const NODE_MODULES = 'node_modules';
11
11
  const ADD = 'bun x --no-install vulcan add';
12
12
  const NO_HAND_WRITING = 'do not hand-write package.json, tsconfig or scripts';
13
13
 
14
- export interface IPackageVerdict {
14
+ interface IPackageVerdict {
15
15
  /** `deny` only when a real `vulcan add` command exists for the folder; otherwise `warn`. */
16
16
  kind: TPackageVerdictKind;
17
17
  message: string;
@@ -21,6 +21,7 @@ interface IRecordedPreset {
21
21
  spec: string;
22
22
  side: string;
23
23
  lib: boolean;
24
+ shared: boolean;
24
25
  }
25
26
 
26
27
  interface IProjectView {
@@ -100,10 +101,10 @@ const readProject = (opts: { start: string }): IProjectView | undefined => {
100
101
  return [];
101
102
  }
102
103
 
103
- const { spec, side, lib } = entry.value;
104
+ const { spec, side, lib, shared } = entry.value;
104
105
 
105
106
  return typeof spec === 'string' && typeof side === 'string'
106
- ? [{ spec, side, lib: typeof lib === 'string' }]
107
+ ? [{ spec, side, lib: typeof lib === 'string', shared: typeof shared === 'string' }]
107
108
  : [];
108
109
  });
109
110
 
@@ -175,9 +176,14 @@ export const inspectPackageWrite = (opts: {
175
176
  const folderFlag =
176
177
  folders.length > 1 ? ` ${isLib ? '--dir' : `--${key}-dir`} ${created.folder}` : '';
177
178
  const commands = isLib
178
- ? project.presets
179
- .filter((preset) => preset.lib)
180
- .map((preset) => `${ADD} --preset ${preset.spec} --lib ${created.name}${folderFlag}`)
179
+ ? [
180
+ ...project.presets
181
+ .filter((preset) => preset.lib)
182
+ .map((preset) => `${ADD} --preset ${preset.spec} --lib ${created.name}${folderFlag}`),
183
+ ...project.presets
184
+ .filter((preset) => preset.shared)
185
+ .map((preset) => `${ADD} --preset ${preset.spec} --shared ${created.name}${folderFlag}`),
186
+ ]
181
187
  : project.presets
182
188
  .filter((preset) => preset.side === key)
183
189
  .map((preset) => appCommand({ preset, name: created.name, folderFlag }));
@@ -193,7 +199,7 @@ export const inspectPackageWrite = (opts: {
193
199
  kind: PackageVerdictKinds.WARN,
194
200
  message:
195
201
  project.presets.length === 0
196
- ? `${created.folder}/${created.name} looks like a new ${what} and this project recorded no preset: ask the user which preset to use (\`vulcan add --preset <name|file:path> --app <name>\`, --lib <name> for a shared package); ${NO_HAND_WRITING}`
202
+ ? `${created.folder}/${created.name} looks like a new ${what} and this project recorded no preset: ask the user which preset to use (\`vulcan add --preset <name|file:path> --app <name>\`, --lib <name> for a library other apps import, --shared <name> for a side-neutral package); ${NO_HAND_WRITING}`
197
203
  : `${created.folder}/${created.name} looks like a new ${what} but no recorded preset makes a ${what}: ask the user how it should be made; ${NO_HAND_WRITING}`,
198
204
  };
199
205
  };
@@ -5,7 +5,7 @@ import { basenameOf, parseShell, programOf } from './shell.ts';
5
5
  const SCRIPTING_PROGRAM = /^(?:python\d*(?:\.\d+)?|pip\d*(?:\.\d+)?)$/;
6
6
 
7
7
  /** One line, worded like the rule: a preference, never a ban. */
8
- export const SCRIPTING_ADVICE =
8
+ const SCRIPTING_ADVICE =
9
9
  'V-B-09: agent scripting uses bun by default (bun -e, bun file.ts, Bun.file()). Python or another language is fine when the task needs it (an existing project script, a tool only that language has); say so in one line when you use it.';
10
10
 
11
11
  /** `command -v python3` asks whether a program exists; it does not run it. */