@venizia/vulcan 0.4.4 → 0.4.6

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 (88) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/agents.json +22 -1
  4. package/base/checks/wiki-anchors.ts +8 -0
  5. package/base/checks/wiki-source-links.ts +8 -0
  6. package/base/claude/remote-hosts.json +1 -1
  7. package/base/claude/settings.json +12 -12
  8. package/base/extensions/vulcan-guards.ts +301 -0
  9. package/base/hooks/antigravity-guards.ts +68 -0
  10. package/base/hooks/codex-guards.ts +66 -0
  11. package/base/hooks/guard-git.ts +38 -9
  12. package/base/hooks/guard-outside.ts +29 -9
  13. package/base/hooks/guard-writes.ts +29 -1
  14. package/base/hooks/session-start.ts +14 -4
  15. package/base/make/vulcan.mk +12 -1
  16. package/base/references/delegation-brief.md +5 -4
  17. package/base/rules.md +2 -2
  18. package/base/skills/docs-writing/SKILL.md +1 -1
  19. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  20. package/base/skills/knowledge-sync/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/SKILL.md +1 -1
  22. package/base/skills/report-back/SKILL.md +1 -1
  23. package/base/skills/retro/SKILL.md +1 -1
  24. package/base/skills/review-a-change/SKILL.md +1 -1
  25. package/base/skills/ship/SKILL.md +1 -1
  26. package/base/skills/visualize-work/SKILL.md +33 -11
  27. package/base/skills/visualize-work/references/spec.md +77 -12
  28. package/package.json +4 -4
  29. package/src/agents/codex-hooks.ts +133 -0
  30. package/src/agents/common/constants.ts +54 -0
  31. package/src/agents/common/schema.ts +10 -1
  32. package/src/agents/common/types.ts +3 -1
  33. package/src/agents/exclude.ts +4 -0
  34. package/src/agents/hooks-json.ts +111 -0
  35. package/src/agents/index.ts +2 -0
  36. package/src/agents/render.ts +5 -4
  37. package/src/agents/resolve.ts +24 -9
  38. package/src/config/common/constants.ts +12 -0
  39. package/src/config/common/types.ts +2 -1
  40. package/src/config/packages.ts +2 -1
  41. package/src/config/schema.ts +84 -5
  42. package/src/create/add-app.ts +2 -2
  43. package/src/create/add-lib.ts +21 -8
  44. package/src/create/common/constants.ts +12 -0
  45. package/src/create/common/types.ts +2 -1
  46. package/src/create/preset-diff.ts +4 -2
  47. package/src/create/workspace.ts +13 -9
  48. package/src/doctor/checks.ts +71 -1
  49. package/src/doctor/common/constants.ts +2 -0
  50. package/src/doctor/runner.ts +6 -0
  51. package/src/hooks/codex-patch.ts +47 -0
  52. package/src/hooks/command-view.ts +97 -0
  53. package/src/hooks/common/constants.ts +46 -0
  54. package/src/hooks/common/types.ts +9 -1
  55. package/src/hooks/decision.ts +50 -8
  56. package/src/hooks/guard-git.ts +64 -5
  57. package/src/hooks/guard-manifest.ts +22 -8
  58. package/src/hooks/guard-outside.ts +38 -6
  59. package/src/hooks/guard-package.ts +15 -12
  60. package/src/hooks/guard-writes.ts +72 -21
  61. package/src/hooks/index.ts +5 -0
  62. package/src/hooks/project-guards.ts +123 -0
  63. package/src/hooks/project-tmp.ts +36 -0
  64. package/src/hooks/remote-hosts.ts +38 -14
  65. package/src/hooks/session-digest.ts +5 -0
  66. package/src/hooks/shell.ts +665 -35
  67. package/src/hooks/trusted-scripts.ts +134 -0
  68. package/src/manifest/render.ts +38 -0
  69. package/src/sync/agent-files.ts +122 -4
  70. package/src/sync/agent-removal.ts +118 -4
  71. package/src/sync/claude-launch.ts +48 -0
  72. package/src/sync/index.ts +1 -0
  73. package/src/sync/local-choice.ts +2 -0
  74. package/src/visualize/assets.ts +195 -54
  75. package/src/visualize/charts.ts +235 -0
  76. package/src/visualize/constants.ts +122 -1
  77. package/src/visualize/diagrams.ts +224 -0
  78. package/src/visualize/icons.ts +28 -0
  79. package/src/visualize/layout.ts +58 -8
  80. package/src/visualize/page.ts +151 -145
  81. package/src/visualize/schema.ts +252 -2
  82. package/src/visualize/sections.ts +370 -0
  83. package/src/visualize/validate.ts +100 -7
  84. package/src/wiki/anchors.ts +118 -0
  85. package/src/wiki/command.ts +110 -0
  86. package/src/wiki/constants.ts +30 -0
  87. package/src/wiki/index.ts +4 -0
  88. package/src/wiki/source-links.ts +186 -0
@@ -1,3 +1,4 @@
1
+ import type { TPackageKind } from './common/index.ts';
1
2
  import type { TResolvedConfig } from './schema.ts';
2
3
 
3
4
  const DEFAULT_PACKAGES_DIRECTORY = 'packages';
@@ -9,7 +10,7 @@ export interface IProjectPackage {
9
10
  path: string;
10
11
  aliases: string[];
11
12
  retired: boolean;
12
- kind?: 'app' | 'lib';
13
+ kind?: TPackageKind;
13
14
  }
14
15
 
15
16
  /** The project's packages in release order. */
@@ -1,7 +1,8 @@
1
+ import { isAbsolute } from 'node:path';
1
2
  import { z } from 'zod';
2
3
  import { layoutFolderProblem, layoutOverlapProblems } from '../common/layout-folder.ts';
3
4
  import { OWNER_SCHEMA } from '../owner/schema.ts';
4
- import { CodingAgents, ConfigConstants, HookEvents } from './common/index.ts';
5
+ import { CodingAgents, ConfigConstants, HookEvents, PackageKinds } from './common/index.ts';
5
6
 
6
7
  const CODING_AGENT = z.string().refine((value) => CodingAgents.isValid(value), {
7
8
  message: `one of: ${[...CodingAgents.SCHEME_SET].join(', ')}`,
@@ -10,6 +11,41 @@ const HOOK_EVENT = z.string().refine((value) => HookEvents.isValid(value), {
10
11
  message: `one of: ${[...HookEvents.SCHEME_SET].join(', ')}`,
11
12
  });
12
13
 
14
+ /** An ed25519 public key as `atlas index keygen` prints it: the base64 of its 32 raw bytes, nothing else. */
15
+ const INDEX_PUBLIC_KEY = z.string().refine(
16
+ (value) => {
17
+ const raw = Buffer.from(value, 'base64');
18
+
19
+ return raw.length === 32 && raw.toString('base64') === value;
20
+ },
21
+ { message: 'the public key `atlas index keygen` prints: the base64 of 32 bytes' },
22
+ );
23
+
24
+ const compiles = (value: string): boolean => {
25
+ try {
26
+ return new RegExp(value) instanceof RegExp;
27
+ } catch {
28
+ return false;
29
+ }
30
+ };
31
+
32
+ /** A command the project says is a database write (V-W-02) or a deploy (V-W-03): guard-writes asks when its pattern matches. */
33
+ const GUARD_COMMAND = z.strictObject({
34
+ rule: z.enum(['V-W-02', 'V-W-03']),
35
+ what: z.string().min(1).max(120),
36
+ pattern: z
37
+ .string()
38
+ .min(1)
39
+ .max(500)
40
+ .refine(compiles, { message: 'a regular expression (JavaScript syntax)' }),
41
+ ignoreCase: z.boolean().optional(),
42
+ });
43
+
44
+ /** A branch a plain `git push` asks about: a name, with `*` for any run of characters. */
45
+ const PUSH_TARGET = z
46
+ .string()
47
+ .regex(/^[A-Za-z0-9._/*-]+$/, { message: 'a branch name, with * for any run of characters' });
48
+
13
49
  /** A layout folder: 1 to 4 plain segments, never climbing, never absolute (the validator `guard-package` shares). */
14
50
  const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
15
51
  const problem = layoutFolderProblem({ folder: value });
@@ -19,6 +55,23 @@ const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
19
55
  }
20
56
  });
21
57
 
58
+ /** 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) => {
60
+ const problem = /[*?[\]{}!]/.test(value)
61
+ ? 'no globs: list each script by its exact path'
62
+ : isAbsolute(value) || value.startsWith('~')
63
+ ? 'a path relative to the repo root'
64
+ : value.split(/[\\/]/).includes('..')
65
+ ? 'a path inside the repo, without ..'
66
+ : /\.ts$/.test(value)
67
+ ? undefined
68
+ : 'a .ts file - guard-writes reads only bun scripts ending in .ts';
69
+
70
+ if (problem !== undefined) {
71
+ context.addIssue({ code: 'custom', message: `${value}: ${problem}` });
72
+ }
73
+ });
74
+
22
75
  /** One folder, or a list of them: a side whose apps are grouped keeps each group's folder. */
23
76
  const LAYOUT_VALUE = z.union([LAYOUT_FOLDER, z.array(LAYOUT_FOLDER).min(1)]);
24
77
 
@@ -30,7 +83,7 @@ const PROJECT_PACKAGE = z.strictObject({
30
83
  aliases: z.array(z.string()).default([]),
31
84
  retired: z.boolean().default(false),
32
85
  /** A shared package a preset's lib kind made lives anywhere a workspace glob covers; absent means an app or a plain package. */
33
- kind: z.enum(['app', 'lib']).optional(),
86
+ kind: z.enum([PackageKinds.APP, PackageKinds.LIB]).optional(),
34
87
  });
35
88
 
36
89
  /** A path as a key: no leading `./`, no trailing slash. */
@@ -235,6 +288,14 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
235
288
  .default([]),
236
289
  /** Tags neither read nor checked (globs) - an old layout's tags. */
237
290
  ignoreTags: z.array(z.string()).optional(),
291
+ /**
292
+ * The prebuilt atlas index this repository publishes: the public keys (any one may have signed a
293
+ * pair) that a project reading this one as a source checks the signature against. Rotation is a
294
+ * new list; a pair signed by a key no longer listed is not used.
295
+ */
296
+ index: z.strictObject({ keys: z.array(INDEX_PUBLIC_KEY).default([]) }).optional(),
297
+ /** `false`: atlas never downloads a prebuilt index for a source this project reads; the default is to. */
298
+ prebuilt: z.boolean().optional(),
238
299
  })
239
300
  .default({
240
301
  tagPattern: '<dir>-v<version>',
@@ -275,11 +336,29 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
275
336
  /**
276
337
  * The hooks that guard writes. `toolOwnedPaths` extends the defaults (package manager caches, the
277
338
  * runtime dir for locks, git config, the agent tool's memory) with stores a tool in this project
278
- * manages itself: absolute globs, `~` and `$NAME` allowed.
339
+ * manages itself: absolute globs, `~` and `$NAME` allowed. `writes.trustedScripts` lists the project's own
340
+ * CLIs (repo-relative `.ts` paths, no globs) whose body guard-writes does not read for mutating calls
341
+ * while git tracks them and they equal HEAD; the command line is still checked. `writes.commands` adds the
342
+ * project's own deploy and migrate commands to what guard-writes asks about (a pattern, matched inside
343
+ * compound commands too), and `git.askPush` lists the branches a plain `git push` asks about; `vulcan sync`
344
+ * writes both to the manifest, where the hooks read them.
279
345
  */
280
346
  guard: z
281
- .strictObject({ toolOwnedPaths: z.array(z.string().min(1)).default([]) })
282
- .default({ toolOwnedPaths: [] }),
347
+ .strictObject({
348
+ toolOwnedPaths: z.array(z.string().min(1)).default([]),
349
+ writes: z
350
+ .strictObject({
351
+ trustedScripts: z.array(TRUSTED_SCRIPT).default([]),
352
+ commands: z.array(GUARD_COMMAND).default([]),
353
+ })
354
+ .default({ trustedScripts: [], commands: [] }),
355
+ git: z.strictObject({ askPush: z.array(PUSH_TARGET).default([]) }).default({ askPush: [] }),
356
+ })
357
+ .default({
358
+ toolOwnedPaths: [],
359
+ writes: { trustedScripts: [], commands: [] },
360
+ git: { askPush: [] },
361
+ }),
283
362
  });
284
363
 
285
364
  export type VulcanConfig = z.input<typeof VULCAN_CONFIG_SCHEMA>;
@@ -15,7 +15,7 @@ import type { IProjectPackage, TResolvedConfig } from '../config/index.ts';
15
15
  import { readWorkspaceGlobs } from '../init/index.ts';
16
16
  import { addLibrary } from './add-lib.ts';
17
17
  import { runAppChecks } from './checks.ts';
18
- import { AppSides, CreateFlags } from './common/index.ts';
18
+ import { AppSides, AppsBlockProblems, CreateFlags } from './common/index.ts';
19
19
  import type { IAppsBlock, ILocatedPreset, IPresetSpec, TAppSide } from './common/index.ts';
20
20
  import { writeFile } from './files.ts';
21
21
  import { recordedPresetOf } from './lib-preset.ts';
@@ -525,7 +525,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
525
525
  if (!parsed.ok) {
526
526
  return fail({
527
527
  message: [
528
- parsed.reason === 'missing'
528
+ parsed.reason === AppsBlockProblems.MISSING
529
529
  ? `the vulcan:apps block is gone from ${configPath} - add by hand:`
530
530
  : `the vulcan:apps block in ${configPath} is not the JSON vulcan wrote - add by hand:`,
531
531
  ...literal({ side, folders: grown, app: entry, sources: newSources }),
@@ -9,10 +9,11 @@ import {
9
9
  listedFoldersNote,
10
10
  withLayoutFolder,
11
11
  } from '../common/layout-folder.ts';
12
+ import { PackageKinds } from '../config/index.ts';
12
13
  import type { IProjectPackage, TResolvedConfig } from '../config/index.ts';
13
14
  import { readWorkspaceGlobs } from '../init/index.ts';
14
15
  import { runAppChecks } from './checks.ts';
15
- import { CreateConstants, CreateFlags } from './common/index.ts';
16
+ import { AppsBlockProblems, CreateConstants, CreateFlags } from './common/index.ts';
16
17
  import type { IAppsBlock, ILocatedPreset, IPresetSpec } from './common/index.ts';
17
18
  import { writeFile } from './files.ts';
18
19
  import { readLibPreset } from './lib-preset.ts';
@@ -67,7 +68,7 @@ const folderOf = async (opts: {
67
68
  const libFolders = [
68
69
  ...new Set(
69
70
  opts.packages
70
- .filter((entry) => entry.kind === 'lib' && !entry.retired)
71
+ .filter((entry) => entry.kind === PackageKinds.LIB && !entry.retired)
71
72
  .map((entry) => dirname(entry.path)),
72
73
  ),
73
74
  ];
@@ -219,7 +220,7 @@ export const addLibrary = async (opts: {
219
220
  if (!parsed.ok) {
220
221
  return fail({
221
222
  message:
222
- parsed.reason === 'missing'
223
+ parsed.reason === AppsBlockProblems.MISSING
223
224
  ? `the vulcan:apps block is gone from ${opts.configPath} - add the package by hand: { dir: '${libName}', name: '${named.name}', path: '${path}', kind: 'lib' }`
224
225
  : `the vulcan:apps block in ${opts.configPath} is not the JSON vulcan wrote - add the package by hand: { dir: '${libName}', name: '${named.name}', path: '${path}', kind: 'lib' }`,
225
226
  });
@@ -228,15 +229,20 @@ export const addLibrary = async (opts: {
228
229
  const sharedBefore = parsed.block.layout.shared;
229
230
  const grown = withLayoutFolder({ value: sharedBefore, folder });
230
231
  // A valid folder the layout does not list yet is added to layout.shared, unless it would nest with another folder.
231
- const isNewFolder =
232
- !layoutFoldersOf({ value: sharedBefore }).includes(folder) &&
233
- layoutFolderProblem({ folder }) === undefined &&
234
- layoutOverlapProblems({ layout: { ...parsed.block.layout, shared: grown } }).length === 0;
232
+ const isListed = layoutFoldersOf({ value: sharedBefore }).includes(folder);
233
+ const notRecorded = isListed
234
+ ? undefined
235
+ : (layoutFolderProblem({ folder }) ??
236
+ layoutOverlapProblems({ layout: { ...parsed.block.layout, shared: grown } }).join('; '));
237
+ const isNewFolder = !isListed && notRecorded === '';
235
238
  const block = opts.recorded({
236
239
  block: {
237
240
  ...parsed.block,
238
241
  layout: isNewFolder ? { ...parsed.block.layout, shared: grown } : parsed.block.layout,
239
- packages: [...parsed.block.packages, { dir: libName, name: named.name, path, kind: 'lib' }],
242
+ packages: [
243
+ ...parsed.block.packages,
244
+ { dir: libName, name: named.name, path, kind: PackageKinds.LIB },
245
+ ],
240
246
  },
241
247
  });
242
248
  const replaced = replaceAppsBlock({ source, block });
@@ -260,6 +266,13 @@ export const addLibrary = async (opts: {
260
266
  process.stderr.write(`${warning}\n`);
261
267
  }
262
268
 
269
+ // The folder is used all the same; the layout does not list it, so `guard-package` does not cover it.
270
+ if (notRecorded !== undefined && notRecorded !== '') {
271
+ process.stderr.write(
272
+ `note: '${folder}' is not added to layout.shared (${notRecorded}); guard-package does not cover it\n`,
273
+ );
274
+ }
275
+
263
276
  const rows: [string, string][] = [['library', path]];
264
277
 
265
278
  if (isNewFolder) {
@@ -7,6 +7,18 @@ export class AppSides {
7
7
  }
8
8
  }
9
9
 
10
+ /** Why the `vulcan:apps` block of the config could not be read: its markers are gone, or what is between them is not JSON. */
11
+ export class AppsBlockProblems {
12
+ static readonly MISSING = 'missing';
13
+ static readonly INVALID = 'invalid';
14
+
15
+ static readonly SCHEME_SET = new Set<string>([this.MISSING, this.INVALID]);
16
+
17
+ static isValid(value: string): boolean {
18
+ return this.SCHEME_SET.has(value);
19
+ }
20
+ }
21
+
10
22
  export class CreateConstants {
11
23
  static readonly NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
12
24
  /** A plain version with an optional prerelease and build part; ranges and URLs are not one. */
@@ -1,8 +1,9 @@
1
1
  import type { ILayout } from '../../common/layout-folder.ts';
2
2
  import type { TConstValue } from '../../common/index.ts';
3
- import type { AppSides } from './constants.ts';
3
+ import type { AppSides, AppsBlockProblems } from './constants.ts';
4
4
 
5
5
  export type TAppSide = TConstValue<typeof AppSides>;
6
+ export type TAppsBlockProblem = TConstValue<typeof AppsBlockProblems>;
6
7
 
7
8
  /** One name init or add needs: the flag that carries it, the question that asks it. */
8
9
  export interface INameField {
@@ -4,7 +4,7 @@ import type { TConstValue } from '../common/index.ts';
4
4
  import { ExitCodes } from '../common/index.ts';
5
5
  import { layoutFoldersOf } from '../common/layout-folder.ts';
6
6
  import type { ILayout } from '../common/layout-folder.ts';
7
- import { loadConfig, resolvePackages } from '../config/index.ts';
7
+ import { loadConfig, PackageKinds, resolvePackages } from '../config/index.ts';
8
8
  import { locate, resolveApiUrl } from './add-app.ts';
9
9
  import { AppSides, CreateConstants, CreateFlags, PresetDiffStatuses } from './common/index.ts';
10
10
  import type { ILocatedPreset, IRecordedPreset, IPresetSpec, TAppSide } from './common/index.ts';
@@ -270,7 +270,9 @@ export const runPresetDiff = async (opts: { cwd: string; args: string[] }): Prom
270
270
  const app = packages.find((entry) => entry.dir === appName || entry.path === appName);
271
271
 
272
272
  if (config.layout === undefined || app === undefined) {
273
- const known = packages.filter((entry) => entry.kind !== 'lib').map((entry) => entry.dir);
273
+ const known = packages
274
+ .filter((entry) => entry.kind !== PackageKinds.LIB)
275
+ .map((entry) => entry.dir);
274
276
 
275
277
  return fail({
276
278
  message: `no app '${appName}' in the config packages${known.length === 0 ? '' : ` (apps: ${known.join(', ')})`}`,
@@ -1,6 +1,7 @@
1
1
  import { relative, resolve } from 'node:path';
2
2
  import { coversFolder } from '../init/index.ts';
3
- import { CreateConstants } from './common/index.ts';
3
+ import { PackageKinds } from '../config/index.ts';
4
+ import { AppsBlockProblems, CreateConstants } from './common/index.ts';
4
5
  import { renderManifestJson } from './manifest-json.ts';
5
6
  import type {
6
7
  IApp,
@@ -9,6 +10,7 @@ import type {
9
10
  IPresetSpec,
10
11
  IRecordedPreset,
11
12
  TAppSide,
13
+ TAppsBlockProblem,
12
14
  } from './common/index.ts';
13
15
 
14
16
  const ENV_PORT = /^[A-Z0-9_]*PORT=(\d+)\s*$/m;
@@ -211,7 +213,7 @@ export const renderLibManifest = (opts: {
211
213
  };
212
214
 
213
215
  /** The atlas lookups a package of one kind depends on: what a summary page cannot hold. */
214
- const ATLAS_LOOKUPS: Record<TAppSide | 'lib', [string, string][]> = {
216
+ const ATLAS_LOOKUPS: Record<TAppSide | typeof PackageKinds.LIB, [string, string][]> = {
215
217
  backend: [
216
218
  ['How a route and its controller are written', '`search` "controller routes", then `get`'],
217
219
  [
@@ -227,7 +229,7 @@ const ATLAS_LOOKUPS: Record<TAppSide | 'lib', [string, string][]> = {
227
229
  };
228
230
 
229
231
  /** The note and the table that turn a package page into a pointer at atlas, for its kind. */
230
- const renderAtlasLookups = (opts: { kind: TAppSide | 'lib' }): string[] => [
232
+ const renderAtlasLookups = (opts: { kind: TAppSide | typeof PackageKinds.LIB }): string[] => [
231
233
  '> This page is a summary, not a spec: it says what the package is. How code is written here lives',
232
234
  '> in atlas; look it up before you explain or write code.',
233
235
  '',
@@ -260,7 +262,7 @@ export const renderLibConcept = (opts: {
260
262
  '',
261
263
  `The shared package at \`${opts.path}\`, created from the ${opts.presetPackage} preset (lib kind). ${oneLine({ text: opts.summary })}`,
262
264
  '',
263
- ...renderAtlasLookups({ kind: 'lib' }),
265
+ ...renderAtlasLookups({ kind: PackageKinds.LIB }),
264
266
  ].join('\n');
265
267
 
266
268
  /**
@@ -367,7 +369,7 @@ const isAppsBlock = (value: unknown): value is IAppsBlock =>
367
369
 
368
370
  export type TAppsBlockResult =
369
371
  | { ok: true; block: IAppsBlock }
370
- | { ok: false; reason: 'missing' | 'invalid' };
372
+ | { ok: false; reason: TAppsBlockProblem };
371
373
 
372
374
  const APPS_DECLARATION = 'const apps = ';
373
375
 
@@ -377,14 +379,14 @@ export const parseAppsBlock = (opts: { source: string }): TAppsBlockResult => {
377
379
  const end = opts.source.indexOf(CreateConstants.APPS_BLOCK_END);
378
380
 
379
381
  if (start === -1 || end === -1 || end < start) {
380
- return { ok: false, reason: 'missing' };
382
+ return { ok: false, reason: AppsBlockProblems.MISSING };
381
383
  }
382
384
 
383
385
  const body = opts.source.slice(start + CreateConstants.APPS_BLOCK_START.length, end);
384
386
  const declaration = body.indexOf(APPS_DECLARATION);
385
387
 
386
388
  if (declaration === -1) {
387
- return { ok: false, reason: 'invalid' };
389
+ return { ok: false, reason: AppsBlockProblems.INVALID };
388
390
  }
389
391
 
390
392
  try {
@@ -395,13 +397,15 @@ export const parseAppsBlock = (opts: { source: string }): TAppsBlockResult => {
395
397
  .replace(/;$/, ''),
396
398
  );
397
399
 
398
- return isAppsBlock(parsed) ? { ok: true, block: parsed } : { ok: false, reason: 'invalid' };
400
+ return isAppsBlock(parsed)
401
+ ? { ok: true, block: parsed }
402
+ : { ok: false, reason: AppsBlockProblems.INVALID };
399
403
  } catch (error) {
400
404
  console.error(
401
405
  `[parseAppsBlock] the vulcan:apps block is not JSON | ${error instanceof Error ? error.message : String(error)}`,
402
406
  );
403
407
 
404
- return { ok: false, reason: 'invalid' };
408
+ return { ok: false, reason: AppsBlockProblems.INVALID };
405
409
  }
406
410
  };
407
411
 
@@ -52,6 +52,7 @@ import {
52
52
  ViolationConstants,
53
53
  } from '../owner/index.ts';
54
54
  import { skillCatalogOf, triggerOf } from '@venizia/vulcan-atlas';
55
+ import { trustOf, TrustStates } from '../hooks/index.ts';
55
56
  import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
56
57
  import type { IViolation, TDoctorCheck } from './common/index.ts';
57
58
  import { parseMakeIncludes, parseMakeTargets } from './makefile.ts';
@@ -839,7 +840,7 @@ export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
839
840
  const FMT_SECTION_ADVICE =
840
841
  'add a [fmt] section (printWidth = 100, singleQuote = true, arrowParens = "always", flavor = "oxfmt"): without it bun fmt formats with Bun\'s defaults, not the shared style';
841
842
  const FMT_FLAVOR_ADVICE =
842
- 'without it bun fmt formats like Prettier when oxfmt is not a dependency, and the output changes';
843
+ 'without it bun fmt uses its default style when oxfmt is not a dependency, and the output changes';
843
844
  const OXFMT_LOADED_ADVICE =
844
845
  'bun fmt loads it and it overrides the [fmt] section of bunfig.toml - delete it, or move its settings to [fmt]';
845
846
 
@@ -1163,6 +1164,75 @@ export const checkOwnerReplySettings = (opts: { root: string }): IViolation[] =>
1163
1164
  });
1164
1165
 
1165
1166
  /** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
1167
+ /** The states of a listed script worth a warning: a typo or a script nobody committed. A modified one is normal work, so it is only a note. */
1168
+ const STALE_TRUST_STATES = new Set<string>([
1169
+ TrustStates.MISSING,
1170
+ TrustStates.UNTRACKED,
1171
+ TrustStates.UNCOMMITTED,
1172
+ TrustStates.SYMLINK,
1173
+ TrustStates.UNKNOWN,
1174
+ ]);
1175
+
1176
+ /** One line per script in `guard.writes.trustedScripts` with what git says about it now (a note). */
1177
+ export const checkTrustedScripts = (opts: ICheckContext): IViolation[] =>
1178
+ opts.config.guard.writes.trustedScripts.map((script) => {
1179
+ const trust = trustOf({ root: opts.root, script });
1180
+
1181
+ return createViolation({
1182
+ check: DoctorChecks.GUARDS,
1183
+ file: script,
1184
+ message:
1185
+ trust.state === TrustStates.TRUSTED
1186
+ ? 'guard-writes does not read this script for mutating calls (guard.writes.trustedScripts); it is ' +
1187
+ trust.reason
1188
+ : `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
1189
+ });
1190
+ });
1191
+
1192
+ /** A listed script that does not exist or is not committed: the exemption never applies (a warning). */
1193
+ export const checkStaleTrustedScripts = (opts: ICheckContext): IViolation[] =>
1194
+ opts.config.guard.writes.trustedScripts.flatMap((script) => {
1195
+ const trust = trustOf({ root: opts.root, script });
1196
+
1197
+ return STALE_TRUST_STATES.has(trust.state)
1198
+ ? [
1199
+ createViolation({
1200
+ check: DoctorChecks.GUARDS,
1201
+ file: script,
1202
+ message: `guard.writes.trustedScripts lists it, but it never takes effect: ${trust.reason}; fix the path, or commit the script`,
1203
+ }),
1204
+ ]
1205
+ : [];
1206
+ });
1207
+
1208
+ /**
1209
+ * The commands and push targets the project adds to guard-writes and guard-git, one note each: so the
1210
+ * guards' reach beyond their own list is visible where a person looks, with the rule and the pattern.
1211
+ */
1212
+ export const checkGuardPatterns = (opts: ICheckContext): IViolation[] => {
1213
+ const { commands } = opts.config.guard.writes;
1214
+ const { askPush } = opts.config.guard.git;
1215
+
1216
+ return [
1217
+ ...commands.map((command) =>
1218
+ createViolation({
1219
+ check: DoctorChecks.GUARDS,
1220
+ file: opts.configFile,
1221
+ message: `guard.writes.commands: ${command.rule} '${command.what}' asks when a command matches /${command.pattern}/${command.ignoreCase === true ? 'i' : ''}`,
1222
+ }),
1223
+ ),
1224
+ ...(askPush.length === 0
1225
+ ? []
1226
+ : [
1227
+ createViolation({
1228
+ check: DoctorChecks.GUARDS,
1229
+ file: opts.configFile,
1230
+ message: `guard.git.askPush: a plain git push asks for ${askPush.join(', ')}`,
1231
+ }),
1232
+ ]),
1233
+ ];
1234
+ };
1235
+
1166
1236
  export const checkLocalSize = (opts: ICheckContext): IViolation[] => {
1167
1237
  const entries = scanLocal({ root: opts.root });
1168
1238
  const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
@@ -20,6 +20,7 @@ export class DoctorChecks {
20
20
  static readonly FORMAT = 'format';
21
21
  static readonly LOCAL = 'local';
22
22
  static readonly PROFILE = 'profile';
23
+ static readonly GUARDS = 'guards';
23
24
  static readonly SCHEME_SET = new Set<string>([
24
25
  this.CONFIG,
25
26
  this.LAYOUT,
@@ -42,6 +43,7 @@ export class DoctorChecks {
42
43
  this.FORMAT,
43
44
  this.LOCAL,
44
45
  this.PROFILE,
46
+ this.GUARDS,
45
47
  ]);
46
48
  static isValid(value: string): boolean {
47
49
  return this.SCHEME_SET.has(value);
@@ -18,8 +18,11 @@ import {
18
18
  checkReplyShape,
19
19
  checkPrune,
20
20
  checkStaleLocal,
21
+ checkStaleTrustedScripts,
22
+ checkTrustedScripts,
21
23
  checkHooks,
22
24
  checkLayout,
25
+ checkGuardPatterns,
23
26
  checkLocalWorkspace,
24
27
  checkMake,
25
28
  checkOutsideWorktrees,
@@ -95,8 +98,10 @@ export const runDoctorNotes = async (opts: {
95
98
  ...checkAppScripts(context),
96
99
  ...checkAtlasBlock(context),
97
100
  ...checkLocalSize(context),
101
+ ...checkGuardPatterns(context),
98
102
  ...checkReplyShape(context),
99
103
  ...checkOwnerReplySwitch({ env: opts.env ?? process.env }),
104
+ ...checkTrustedScripts(context),
100
105
  ];
101
106
  };
102
107
 
@@ -124,5 +129,6 @@ export const runDoctorWarnings = async (opts: { root: string }): Promise<IViolat
124
129
  ...checkProfile(context),
125
130
  ...checkOwnerReplySettings(context),
126
131
  ...checkStaleLocal(context),
132
+ ...checkStaleTrustedScripts(context),
127
133
  ];
128
134
  };
@@ -0,0 +1,47 @@
1
+ import { isAbsolute, resolve } from 'node:path';
2
+ import type { TConstValue } from '../common/index.ts';
3
+
4
+ /** What one file of an `apply_patch` is to the guards: a file it adds is written, one it changes, deletes or moves is edited. */
5
+ export class PatchedTools {
6
+ static readonly WRITE = 'write';
7
+ static readonly EDIT = 'edit';
8
+
9
+ static readonly SCHEME_SET = new Set<string>([this.WRITE, this.EDIT]);
10
+
11
+ static isValid(value: string): boolean {
12
+ return this.SCHEME_SET.has(value);
13
+ }
14
+ }
15
+
16
+ export type TPatchedTool = TConstValue<typeof PatchedTools>;
17
+
18
+ export interface IPatchedFile {
19
+ path: string;
20
+ tool: TPatchedTool;
21
+ }
22
+
23
+ const HEADER = /^\*\*\* (Add|Update|Delete) File: (.+)$/;
24
+ const MOVE = /^\*\*\* Move to: (.+)$/;
25
+
26
+ /**
27
+ * The files an `apply_patch` touches, from the patch text Codex sends as `tool_input.command`: the
28
+ * `*** Add File:`, `*** Update File:`, `*** Delete File:` and `*** Move to:` lines, made absolute against `cwd`.
29
+ */
30
+ export const patchedFilesOf = (opts: { patch: string; cwd: string }): IPatchedFile[] =>
31
+ opts.patch.split('\n').flatMap((line): IPatchedFile[] => {
32
+ const header = HEADER.exec(line);
33
+ const target = header?.[2] ?? MOVE.exec(line)?.[1];
34
+
35
+ if (target === undefined) {
36
+ return [];
37
+ }
38
+
39
+ const path = target.trim();
40
+
41
+ return [
42
+ {
43
+ path: isAbsolute(path) ? path : resolve(opts.cwd, path),
44
+ tool: header?.[1] === 'Add' ? PatchedTools.WRITE : PatchedTools.EDIT,
45
+ },
46
+ ];
47
+ });
@@ -0,0 +1,97 @@
1
+ import { basenameOf, parseShell, programOf, splitHeredocs } from './shell.ts';
2
+ import type { ISimpleCommand } from './shell.ts';
3
+
4
+ /** Programs that only read or print what they are given: their arguments are text to find or show, never a command to run. */
5
+ const READ_ONLY_PROGRAMS = new Set([
6
+ 'rg',
7
+ 'grep',
8
+ 'egrep',
9
+ 'fgrep',
10
+ 'ag',
11
+ 'ack',
12
+ 'cat',
13
+ 'less',
14
+ 'more',
15
+ 'head',
16
+ 'tail',
17
+ 'wc',
18
+ 'ls',
19
+ 'diff',
20
+ 'sort',
21
+ 'uniq',
22
+ 'echo',
23
+ 'printf',
24
+ 'man',
25
+ 'file',
26
+ 'stat',
27
+ 'which',
28
+ ]);
29
+
30
+ /** Programs whose arguments are messages and titles for the write guards (a commit message, an issue body). */
31
+ const MESSAGE_PROGRAMS = new Set(['git', 'gh']);
32
+
33
+ /** `find` runs a command only with these; without them it only lists. */
34
+ const FIND_RUNS = new Set(['-exec', '-execdir', '-ok', '-okdir', '-delete']);
35
+
36
+ /** Programs that read their heredoc as a query or a script: the body is part of what they run. */
37
+ const HEREDOC_READERS = new Set([
38
+ 'ssh',
39
+ 'psql',
40
+ 'mysql',
41
+ 'mongosh',
42
+ 'sqlite3',
43
+ 'python',
44
+ 'python3',
45
+ 'node',
46
+ 'bun',
47
+ 'deno',
48
+ 'ruby',
49
+ 'perl',
50
+ 'php',
51
+ ]);
52
+
53
+ /** A pipe into a program that runs what it is fed: `echo "kubectl apply -f x" | sh`. */
54
+ const PIPED_INTO_RUNNER =
55
+ /\|\s*(?:sudo\s+)?(?:sh|bash|zsh|dash|psql|mysql|mongosh|sqlite3|python3?|node|bun|ssh)\b/;
56
+
57
+ /**
58
+ * Whether the arguments of a command are data. `withMessages` adds `git` and `gh` (their arguments are
59
+ * messages to the write guards, but a `git` remote is a host to the remote-host guard).
60
+ */
61
+ export const isDataOnly = (opts: { command: ISimpleCommand; withMessages: boolean }): boolean => {
62
+ const name = basenameOf({ word: programOf({ command: opts.command }).name });
63
+
64
+ if (name === 'find') {
65
+ return !opts.command.words.some((word) => FIND_RUNS.has(word));
66
+ }
67
+
68
+ return READ_ONLY_PROGRAMS.has(name) || (opts.withMessages && MESSAGE_PROGRAMS.has(name));
69
+ };
70
+
71
+ /** The texts of the simple commands: the words, a bare name for data, a reader's heredoc body appended. */
72
+ const textsOf = (opts: { command: string; withMessages: boolean }): string[] =>
73
+ parseShell({ command: opts.command }).map((command) => {
74
+ const name = basenameOf({ word: programOf({ command }).name });
75
+
76
+ if (isDataOnly({ command, withMessages: opts.withMessages })) {
77
+ return name;
78
+ }
79
+
80
+ const body =
81
+ command.heredoc !== undefined && HEREDOC_READERS.has(name) ? `\n${command.heredoc}` : '';
82
+
83
+ return `${command.words.join(' ')}${body}`;
84
+ });
85
+
86
+ /**
87
+ * What a command line runs, one text per simple command, for a guard that matches text: the words of each
88
+ * command with the quotes resolved, nothing but the name for a command whose arguments are data
89
+ * (`rg -n "kubectl apply" docs/`), and the body of a heredoc appended only where its reader runs it
90
+ * (`psql <<EOF`). The body of `cat > f <<EOF` is data and is not here. A line that pipes into a program
91
+ * that runs its input (`echo "kubectl apply -f x" | sh`) stands as one text, because what it prints is code.
92
+ */
93
+ export const commandTextsOf = (opts: { command: string; withMessages: boolean }): string[] => {
94
+ const { text } = splitHeredocs({ command: opts.command });
95
+
96
+ return PIPED_INTO_RUNNER.test(text) ? [text] : textsOf(opts);
97
+ };