@venizia/vulcan 0.4.10-2 → 0.4.10-21

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 (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -1,119 +0,0 @@
1
- import { existsSync, readFileSync } from 'node:fs';
2
- import { dirname, join } from 'node:path';
3
- import { RecordValue } from '../common/record.ts';
4
- import { CiConstants } from './common/index.ts';
5
- import type { IDependency, IWorkspacePackage } from './common/index.ts';
6
-
7
- type TWorkspaceRead = { ok: true; packages: IWorkspacePackage[] } | { ok: false; error: string };
8
-
9
- /** The packages of the workspace: the folders the root `package.json` lists in `workspaces`. */
10
- export class CiWorkspace {
11
- /**
12
- * Every folder with a `package.json` that the `workspaces` globs match (an array, or an object with
13
- * `packages`; a `!` glob removes), with a name, sorted by folder. `node_modules` is never searched.
14
- */
15
- static read(opts: { root: string }): TWorkspaceRead {
16
- const file = join(opts.root, CiConstants.ROOT_MANIFEST);
17
-
18
- if (!existsSync(file)) {
19
- return { ok: false, error: `no ${CiConstants.ROOT_MANIFEST} in ${opts.root}` };
20
- }
21
-
22
- let manifest: unknown;
23
-
24
- try {
25
- manifest = JSON.parse(readFileSync(file, 'utf8'));
26
- } catch (error) {
27
- return {
28
- ok: false,
29
- error: `${CiConstants.ROOT_MANIFEST} is not JSON: ${error instanceof Error ? error.message : String(error)}`,
30
- };
31
- }
32
-
33
- const globs = RecordValue.isRecord(manifest)
34
- ? CiWorkspace.globsOf({ value: manifest.workspaces })
35
- : [];
36
-
37
- if (globs.length === 0) {
38
- return { ok: false, error: `${CiConstants.ROOT_MANIFEST} lists no workspaces` };
39
- }
40
-
41
- const include = globs.filter((glob) => !glob.startsWith('!'));
42
- // `!apps/old/**` leaves out the folder itself too, which the glob alone does not match.
43
- const exclude = globs
44
- .filter((glob) => glob.startsWith('!'))
45
- .flatMap((glob) => [glob.slice(1), glob.slice(1).replace(/\/\*\*$/, '')])
46
- .map((pattern) => new Bun.Glob(pattern));
47
- const dirs = new Set<string>();
48
-
49
- for (const glob of include) {
50
- const scan = new Bun.Glob(`${glob.replace(/\/+$/, '')}/${CiConstants.ROOT_MANIFEST}`);
51
-
52
- for (const match of scan.scanSync({ cwd: opts.root, onlyFiles: true })) {
53
- const dir = dirname(match).split('\\').join('/');
54
-
55
- if (
56
- !dir.split('/').includes('node_modules') &&
57
- !exclude.some((pattern) => pattern.match(dir))
58
- ) {
59
- dirs.add(dir);
60
- }
61
- }
62
- }
63
-
64
- const packages = [...dirs]
65
- .sort()
66
- .flatMap((dir) => CiWorkspace.packageAt({ root: opts.root, dir }) ?? []);
67
-
68
- return { ok: true, packages };
69
- }
70
-
71
- private static globsOf(opts: { value: unknown }): string[] {
72
- const list = Array.isArray(opts.value)
73
- ? opts.value
74
- : RecordValue.isRecord(opts.value) && Array.isArray(opts.value.packages)
75
- ? opts.value.packages
76
- : [];
77
-
78
- return list.filter((entry): entry is string => typeof entry === 'string' && entry !== '');
79
- }
80
-
81
- private static packageAt(opts: { root: string; dir: string }): IWorkspacePackage | undefined {
82
- let manifest: unknown;
83
-
84
- try {
85
- manifest = JSON.parse(
86
- readFileSync(join(opts.root, opts.dir, CiConstants.ROOT_MANIFEST), 'utf8'),
87
- );
88
- } catch {
89
- return undefined;
90
- }
91
-
92
- if (
93
- !RecordValue.isRecord(manifest) ||
94
- typeof manifest.name !== 'string' ||
95
- manifest.name === ''
96
- ) {
97
- return undefined;
98
- }
99
-
100
- const scripts = RecordValue.isRecord(manifest.scripts)
101
- ? Object.fromEntries(
102
- Object.entries(manifest.scripts).filter(
103
- (entry): entry is [string, string] => typeof entry[1] === 'string',
104
- ),
105
- )
106
- : {};
107
- const dependencies: IDependency[] = CiConstants.DEPENDENCY_FIELDS.flatMap((field) => {
108
- const block = manifest[field];
109
-
110
- return RecordValue.isRecord(block)
111
- ? Object.entries(block)
112
- .filter((entry): entry is [string, string] => typeof entry[1] === 'string')
113
- .map(([name, spec]) => ({ name, spec }))
114
- : [];
115
- });
116
-
117
- return { name: manifest.name, dir: opts.dir, scripts, dependencies };
118
- }
119
- }
@@ -1,4 +0,0 @@
1
- import type { ICommandContext } from '../common/index.ts';
2
- import { CiCommand } from '../ci/command.ts';
3
-
4
- export const runCiCommand = async (opts: ICommandContext): Promise<number> => CiCommand.run(opts);
@@ -1,109 +0,0 @@
1
- import { isAbsolute, join, normalize } from 'node:path';
2
- import { GuardDecisions, HookConstants } from './common/index.ts';
3
- import type { IManifestHookInput } from './common/index.ts';
4
- import { HookDecision } from './decision.ts';
5
-
6
- /** The shell tool under the names the hosts give it: Cursor's `Shell`, and a lower-case `bash`. */
7
- const SHELL_NAMES = new Set(['Shell', 'shell', 'bash']);
8
-
9
- const MANIFEST_BLOCK_MESSAGE =
10
- 'vulcan.manifest.json is generated - edit .configs/vulcan.config.* and run `vulcan sync`';
11
-
12
- const MANIFEST_SUFFIX = '/.agents/vulcan.manifest.json';
13
- const BASH_TOOL = 'Bash';
14
- /** A path word that ends in the manifest's name. */
15
- const TARGET = String.raw`[^\s;|&<>"']*vulcan\.manifest\.json`;
16
-
17
- /** The shell forms that write, replace or delete a file; reading it (cat, jq, git diff) is not among them. */
18
- const WRITE_PATTERNS: RegExp[] = [
19
- // `> file`, `>> file`, `2> file`, `&> file`, `>| file`
20
- new RegExp(String.raw`(?:^|[^<>])\d?>>?\|?\s*["']?${TARGET}`),
21
- new RegExp(String.raw`\btee\b[^;|&]*${TARGET}`),
22
- new RegExp(
23
- String.raw`\b(?:sed|perl|ruby)\b[^;|&]*\s(?:-[A-Za-z]*i\b|--in-place)[^;|&]*${TARGET}`,
24
- ),
25
- // the manifest as the destination: the last argument
26
- new RegExp(String.raw`\b(?:cp|mv|install|ln)\b[^;|&]*\s["']?${TARGET}["']?\s*(?:$|[;|&])`),
27
- new RegExp(String.raw`\bof=["']?${TARGET}`),
28
- new RegExp(String.raw`\b(?:rm|truncate|shred|unlink)\b[^;|&]*${TARGET}`),
29
- ];
30
-
31
- const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
32
- typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
33
-
34
- const toText = (opts: { value: unknown }): string | undefined =>
35
- typeof opts.value === 'string' && opts.value !== '' ? opts.value : undefined;
36
-
37
- /** The tool name, with the shell tool of another host read as Claude's `Bash`. */
38
- const toolOf = (opts: { value: unknown }): string | undefined => {
39
- const name = toText(opts);
40
-
41
- return name !== undefined && SHELL_NAMES.has(name) ? BASH_TOOL : name;
42
- };
43
-
44
- export class ManifestGuard {
45
- /** The tool call from the hook's JSON; `undefined` when it is not what Claude Code sends. */
46
- static parseHookInput(opts: { text: string }): IManifestHookInput | undefined {
47
- let payload: unknown;
48
-
49
- try {
50
- payload = JSON.parse(opts.text);
51
- } catch (error) {
52
- console.error(
53
- `[ManifestGuard.parseHookInput] unreadable hook input - letting the call through | ${error instanceof Error ? error.message : String(error)}`,
54
- );
55
-
56
- return undefined;
57
- }
58
-
59
- const holder = { value: payload };
60
-
61
- if (!isRecord(holder)) {
62
- return undefined;
63
- }
64
-
65
- // The wire names are snake_case; they stay behind string-literal access here, at the boundary (V-C-14).
66
- const toolInput = { value: holder.value['tool_input'] };
67
- const input = isRecord(toolInput) ? toolInput.value : {};
68
- const tool = toolOf({ value: holder.value['tool_name'] });
69
-
70
- return tool === undefined
71
- ? undefined
72
- : {
73
- tool,
74
- filePath:
75
- toText({ value: input['file_path'] }) ?? toText({ value: input['notebook_path'] }),
76
- command: toText({ value: input['command'] }),
77
- cwd: toText({ value: holder.value['cwd'] }),
78
- };
79
- }
80
-
81
- /** Whether this tool call writes `.agents/vulcan.manifest.json` - which only `vulcan sync` may do. */
82
- static inspectWrite(opts: { input: IManifestHookInput }): boolean {
83
- const { tool, filePath, command, cwd } = opts.input;
84
-
85
- if (tool === BASH_TOOL) {
86
- return command !== undefined && WRITE_PATTERNS.some((pattern) => pattern.test(command));
87
- }
88
-
89
- if (filePath === undefined) {
90
- return false;
91
- }
92
-
93
- const absolute = isAbsolute(filePath) ? filePath : join(cwd ?? process.cwd(), filePath);
94
-
95
- return normalize(absolute).endsWith(MANIFEST_SUFFIX);
96
- }
97
-
98
- static buildDecision() {
99
- return HookDecision.forHost({
100
- output: {
101
- hookSpecificOutput: {
102
- hookEventName: HookConstants.PRE_TOOL_USE,
103
- permissionDecision: GuardDecisions.DENY,
104
- permissionDecisionReason: MANIFEST_BLOCK_MESSAGE,
105
- },
106
- },
107
- });
108
- }
109
- }
@@ -1,226 +0,0 @@
1
- import { existsSync, readFileSync } from 'node:fs';
2
- import { basename, dirname, isAbsolute, join, normalize, relative, sep } from 'node:path';
3
- import { GuardDecisions, HookConstants, PackageVerdictKinds } from './common/index.ts';
4
- import type { IManifestHookInput, TPackageVerdictKind } from './common/index.ts';
5
- import { HookDecision } from './decision.ts';
6
- import { LayoutFolder, LayoutKeys } from '../common/layout-folder.ts';
7
-
8
- const MANIFEST_FILE = '.agents/vulcan.manifest.json';
9
- const PACKAGE_FILE = 'package.json';
10
- const NODE_MODULES = 'node_modules';
11
- const ADD = 'bun x --no-install vulcan add';
12
- const NO_HAND_WRITING = 'do not hand-write package.json, tsconfig or scripts';
13
-
14
- interface IPackageVerdict {
15
- /** `deny` only when a real `vulcan add` command exists for the folder; otherwise `warn`. */
16
- kind: TPackageVerdictKind;
17
- message: string;
18
- }
19
-
20
- interface IRecordedPreset {
21
- spec: string;
22
- side: string;
23
- lib: boolean;
24
- shared: boolean;
25
- }
26
-
27
- interface IProjectView {
28
- root: string;
29
- /** The valid folders of each managed key; `other` is not here: it is not guarded. */
30
- layout: Record<string, string[]>;
31
- presets: IRecordedPreset[];
32
- }
33
-
34
- const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
35
- typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
36
-
37
- /** The nearest project above `start`: the folder holding the generated manifest. */
38
- const findRoot = (opts: { start: string }): string | undefined => {
39
- let current = opts.start;
40
-
41
- for (;;) {
42
- if (existsSync(join(current, MANIFEST_FILE))) {
43
- return current;
44
- }
45
-
46
- const parent = dirname(current);
47
-
48
- if (parent === current) {
49
- return undefined;
50
- }
51
-
52
- current = parent;
53
- }
54
- };
55
-
56
- /** What the manifest says of layout and presets; `undefined` when it is missing or not readable. */
57
- const readProject = (opts: { start: string }): IProjectView | undefined => {
58
- const root = findRoot({ start: opts.start });
59
-
60
- if (root === undefined) {
61
- return undefined;
62
- }
63
-
64
- let manifest: unknown;
65
-
66
- try {
67
- manifest = JSON.parse(readFileSync(join(root, MANIFEST_FILE), 'utf8'));
68
- } catch (error) {
69
- console.error(
70
- `[readProject] unreadable manifest - letting the call through | ${error instanceof Error ? error.message : String(error)}`,
71
- );
72
-
73
- return undefined;
74
- }
75
-
76
- const holder = { value: manifest };
77
-
78
- if (!isRecord(holder)) {
79
- return undefined;
80
- }
81
-
82
- const layoutHolder = { value: holder.value['layout'] };
83
- const layout: Record<string, string[]> = {};
84
-
85
- // The manifest is read through the same validator as the config: a folder that is not one is dropped.
86
- if (isRecord(layoutHolder)) {
87
- for (const key of LayoutKeys.MANAGED) {
88
- const folders = LayoutFolder.valid({ value: layoutHolder.value[key] });
89
-
90
- if (folders.length > 0) {
91
- layout[key] = folders;
92
- }
93
- }
94
- }
95
-
96
- const recorded = Array.isArray(holder.value['presets']) ? holder.value['presets'] : [];
97
- const presets = recorded.flatMap((item: unknown): IRecordedPreset[] => {
98
- const entry = { value: item };
99
-
100
- if (!isRecord(entry)) {
101
- return [];
102
- }
103
-
104
- const { spec, side, lib, shared } = entry.value;
105
-
106
- return typeof spec === 'string' && typeof side === 'string'
107
- ? [{ spec, side, lib: typeof lib === 'string', shared: typeof shared === 'string' }]
108
- : [];
109
- });
110
-
111
- return { root, layout, presets };
112
- };
113
-
114
- /** `services/api3` from `services/api3/package.json`, as the folder it sits in and its name. */
115
- const newPackageOf = (opts: {
116
- root: string;
117
- path: string;
118
- }): { folder: string; name: string } | undefined => {
119
- const parts = normalize(relative(opts.root, opts.path)).split(sep);
120
-
121
- if (parts.length < 3 || parts.includes('..') || parts.includes(NODE_MODULES)) {
122
- return undefined;
123
- }
124
-
125
- const name = parts[parts.length - 2];
126
- const folder = parts.slice(0, -2).join('/');
127
-
128
- return { folder, name };
129
- };
130
-
131
- const appCommand = (opts: { preset: IRecordedPreset; name: string; folderFlag: string }): string =>
132
- `${ADD} --preset ${opts.preset.spec} --app ${opts.name}${opts.folderFlag}${opts.preset.side === 'frontend' ? ' --api <backend app> | --no-api' : ''}`;
133
-
134
- export class PackageGuard {
135
- /**
136
- * Whether this tool call creates the `package.json` of a new app or shared package in one of the
137
- * project's layout folders. A real `vulcan add` command for that folder makes it a `deny`; with no
138
- * preset behind the folder it is only a `warn`: the guard never blocks without a command to offer.
139
- */
140
- static inspectWrite(opts: { input: IManifestHookInput }): IPackageVerdict | undefined {
141
- const { tool, filePath, cwd } = opts.input;
142
-
143
- if (tool !== 'Write' || filePath === undefined || basename(filePath) !== PACKAGE_FILE) {
144
- return undefined;
145
- }
146
-
147
- const absolute = normalize(
148
- isAbsolute(filePath) ? filePath : join(cwd ?? process.cwd(), filePath),
149
- );
150
-
151
- if (absolute.split(sep).includes(NODE_MODULES) || existsSync(absolute)) {
152
- return undefined;
153
- }
154
-
155
- const project = readProject({ start: dirname(absolute) });
156
- const created =
157
- project === undefined ? undefined : newPackageOf({ root: project.root, path: absolute });
158
-
159
- if (project === undefined || created === undefined) {
160
- return undefined;
161
- }
162
-
163
- const entry = Object.entries(project.layout).find(([, folders]) =>
164
- folders.includes(created.folder),
165
- );
166
-
167
- if (entry === undefined) {
168
- return undefined;
169
- }
170
-
171
- const [key, folders] = entry;
172
- const isLib = key === 'shared';
173
- const what = isLib ? 'lib' : `${key} app`;
174
- // A side with several folders needs the one it is written in named, so the command is exact.
175
- const folderFlag =
176
- folders.length > 1 ? ` ${isLib ? '--dir' : `--${key}-dir`} ${created.folder}` : '';
177
- const commands = isLib
178
- ? [
179
- ...project.presets
180
- .filter((preset) => preset.lib)
181
- .map((preset) => `${ADD} --preset ${preset.spec} --lib ${created.name}${folderFlag}`),
182
- ...project.presets
183
- .filter((preset) => preset.shared)
184
- .map(
185
- (preset) => `${ADD} --preset ${preset.spec} --shared ${created.name}${folderFlag}`,
186
- ),
187
- ]
188
- : project.presets
189
- .filter((preset) => preset.side === key)
190
- .map((preset) => appCommand({ preset, name: created.name, folderFlag }));
191
-
192
- if (commands.length > 0) {
193
- return {
194
- kind: PackageVerdictKinds.DENY,
195
- message: `${created.folder}/${created.name} is a new ${what}: create it with a preset, not by hand - run ${commands.join(' or ')} (ask atlas \`presets\` for the choice); ${NO_HAND_WRITING}`,
196
- };
197
- }
198
-
199
- return {
200
- kind: PackageVerdictKinds.WARN,
201
- message:
202
- project.presets.length === 0
203
- ? `${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}`
204
- : `${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}`,
205
- };
206
- }
207
-
208
- static buildDecision(opts: { verdict: IPackageVerdict }) {
209
- return opts.verdict.kind === PackageVerdictKinds.DENY
210
- ? HookDecision.forHost({
211
- output: {
212
- hookSpecificOutput: {
213
- hookEventName: HookConstants.PRE_TOOL_USE,
214
- permissionDecision: GuardDecisions.DENY,
215
- permissionDecisionReason: opts.verdict.message,
216
- },
217
- },
218
- })
219
- : {
220
- hookSpecificOutput: {
221
- hookEventName: HookConstants.PRE_TOOL_USE,
222
- additionalContext: opts.verdict.message,
223
- },
224
- };
225
- }
226
- }
@@ -1,36 +0,0 @@
1
- import { HookConstants } from './common/index.ts';
2
- import { ShellParser } from './shell.ts';
3
-
4
- /** `python`, `python3`, `python3.12`, `pip`, `pip3`: the program a command runs, not a word it mentions. */
5
- const SCRIPTING_PROGRAM = /^(?:python\d*(?:\.\d+)?|pip\d*(?:\.\d+)?)$/;
6
-
7
- /** One line, worded like the rule: a preference, never a ban. */
8
- const SCRIPTING_ADVICE =
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
-
11
- /** `command -v python3` asks whether a program exists; it does not run it. */
12
- const isExistenceProbe = (opts: { words: string[] }): boolean => {
13
- const at = opts.words.indexOf('command');
14
-
15
- return at !== -1 && ['-v', '-V'].includes(opts.words[at + 1] ?? '');
16
- };
17
-
18
- export class ScriptingGuard {
19
- /** The scripting programs a command runs, in order: a mention in an argument, a message, a heredoc or an existence probe is not one. */
20
- static inspect(opts: { command: string }): string[] {
21
- return ShellParser.parse({ command: opts.command })
22
- .filter((command) => !isExistenceProbe({ words: command.words }))
23
- .map((command) => ShellParser.basenameOf({ word: ShellParser.programOf({ command }).name }))
24
- .filter((name) => SCRIPTING_PROGRAM.test(name));
25
- }
26
-
27
- /** The PreToolUse answer that adds the advice to the model's context and lets the call through. */
28
- static buildAdvice() {
29
- return {
30
- hookSpecificOutput: {
31
- hookEventName: HookConstants.PRE_TOOL_USE,
32
- additionalContext: SCRIPTING_ADVICE,
33
- },
34
- };
35
- }
36
- }
@@ -1,17 +0,0 @@
1
- /**
2
- * What a remote host entry may be, for the project config (`remoteHosts.trusted`, `readOnly`) and for the
3
- * personal list the guard reads at run time. It has no import, because the guard loads no config loader and no zod.
4
- */
5
- export class HostPatterns {
6
- /** A `$VAR` or `${VAR}`, or a host name made of letters, digits, `.`, `_`, `-` and `*`: never a user, a path or a port. */
7
- static readonly SHAPE = /^(?:\$\{?\w+\}?|[A-Za-z0-9._*-]+)$/;
8
-
9
- /** A pattern needs a letter or a digit: `*`, `-`, `*-*` or `*_*` would match every host, or every hyphenated one. */
10
- static hasLiteral(opts: { value: string }): boolean {
11
- return /[A-Za-z0-9]/.test(opts.value);
12
- }
13
-
14
- static isValid(opts: { value: string }): boolean {
15
- return HostPatterns.SHAPE.test(opts.value) && HostPatterns.hasLiteral(opts);
16
- }
17
- }
@@ -1,162 +0,0 @@
1
- import { ConfigLoader } from '../config/index.ts';
2
- import {
3
- OwnerShape,
4
- OWNER_SCHEMA,
5
- OwnerEnforcement,
6
- ReplySwitch,
7
- ViolationLog,
8
- OwnerProfile,
9
- OwnerView,
10
- ShapeClasses,
11
- } from '../owner/index.ts';
12
- import type { IOwnerView } from '../owner/index.ts';
13
- import { ReplyClaims, SignalState } from '../signals/index.ts';
14
-
15
- /** What to do about each class, in the words of the block message. */
16
- const FIXES: Record<string, string> = {
17
- [ShapeClasses.HEADLINE_NOT_SENTENCE]:
18
- 'open with a plain sentence that answers first, not a heading, list or table',
19
- [ShapeClasses.HEADLINE_TOO_LONG]: 'cut the headline to the sentence cap',
20
- [ShapeClasses.MINIMAP_MISSING]: 'add the minimap table with the configured header',
21
- [ShapeClasses.MINIMAP_STATUS]: 'use only the configured status words in the minimap',
22
- [ShapeClasses.BLOCKED_MISSING]: 'add the Blocked line, or its none string',
23
- [ShapeClasses.DECISIONS_MISSING]: 'add the decisions section, or exactly its none string',
24
- [ShapeClasses.DECISIONS_MALFORMED]: 'number the decisions',
25
- [ShapeClasses.DECISIONS_NO_RECOMMENDATION]: 'end each decision with the recommendation pattern',
26
- [ShapeClasses.SECTION_ORDER]: 'put the sections in the configured order',
27
- [ShapeClasses.EMOJI]: 'remove emoji',
28
- [ShapeClasses.SHOUTING]: 'no all-caps phrases',
29
- [ShapeClasses.RELATIVE_PATH]: 'name a file by its full absolute path',
30
- };
31
-
32
- /** The owner's view of the project in `projectRoot`; a project whose config cannot load gets the defaults. */
33
- const loadOwnerView = async (opts: { projectRoot: string }): Promise<IOwnerView> => {
34
- const loaded = await ConfigLoader.load({ root: opts.projectRoot });
35
- const profile = OwnerProfile.read({ root: opts.projectRoot });
36
-
37
- return OwnerView.resolve({
38
- owner: loaded.ok ? loaded.config.owner : OWNER_SCHEMA.parse(undefined),
39
- profile: profile.ok ? profile.profile : undefined,
40
- });
41
- };
42
-
43
- export class OwnerReply {
44
- /**
45
- * The Stop hook's answer for the last reply: it is checked and recorded (classes and date only), and
46
- * only under `block`, once per message and only for a structural fault, is it sent back to be restated.
47
- * Anything it cannot read passes: it never stops a session by failing. A session started with
48
- * `VULCAN_OWNER_REPLY=off` (a session whose reader is an agent) is not checked, logged or blocked at all.
49
- */
50
- static async buildStopOutput(opts: {
51
- projectRoot: string;
52
- input: unknown;
53
- /** The environment of the session; `VULCAN_OWNER_REPLY=off` exempts it. */
54
- env?: Record<string, string | undefined>;
55
- }): Promise<Record<string, unknown> | undefined> {
56
- const { input } = opts;
57
-
58
- if (ReplySwitch.isOwnerOff({ env: opts.env ?? process.env })) {
59
- return undefined;
60
- }
61
-
62
- if (typeof input !== 'object' || input === null || !('last_assistant_message' in input)) {
63
- return undefined;
64
- }
65
-
66
- const { last_assistant_message: text } = input;
67
- const isRetry = 'stop_hook_active' in input && input.stop_hook_active === true;
68
- const session =
69
- 'session_id' in input && typeof input.session_id === 'string' ? input.session_id : '';
70
- const view = await loadOwnerView({ projectRoot: opts.projectRoot });
71
-
72
- if (typeof text !== 'string' || view.enforce === OwnerEnforcement.OFF) {
73
- return undefined;
74
- }
75
-
76
- const result = OwnerShape.check({ text, view });
77
- // A claim is checked on every reply, a short one too: "Published." is the shortest wrong one.
78
- const claims = ReplyClaims.check({
79
- text,
80
- state: SignalState.read({ root: opts.projectRoot, session }),
81
- publicWords: view.claimWords.public,
82
- doneWords: view.claimWords.done,
83
- });
84
- const classes = [...result.classes, ...claims];
85
-
86
- // Every reply updates the note the next prompt reads, an exempt short one too; a write that fails never
87
- // costs the decision below.
88
- try {
89
- ViolationLog.recordReply({ root: opts.projectRoot, classes, session });
90
- } catch {
91
- // The log is advisory.
92
- }
93
-
94
- if (!result.isChecked) {
95
- return undefined;
96
- }
97
-
98
- const structural = result.classes.filter((name) => ShapeClasses.isStructural(name));
99
-
100
- if (
101
- view.enforce !== OwnerEnforcement.BLOCK ||
102
- isRetry ||
103
- structural.length === 0 ||
104
- ViolationLog.wasBlockedRecently({ root: opts.projectRoot, session })
105
- ) {
106
- return undefined;
107
- }
108
-
109
- try {
110
- ViolationLog.markBlocked({ root: opts.projectRoot, session });
111
- } catch {
112
- // Without the note the stop_hook_active flag is the only guard against a second block.
113
- }
114
-
115
- return {
116
- decision: 'block',
117
- reason: [
118
- 'The reply to the owner breaks the report shape (see "How to answer the owner" in the session rules). Restate it once, in full:',
119
- ...structural.map((name) => ` - ${name}: ${FIXES[name] ?? name}`),
120
- ].join('\n'),
121
- };
122
- }
123
-
124
- /**
125
- * One line added to every prompt while the shape is held: the contract, and the faults of the reply
126
- * before when it had any. Empty when the shape is not enforced.
127
- */
128
- static async buildPromptContract(opts: {
129
- projectRoot: string;
130
- /** The session the prompt belongs to; its turn begins here. */
131
- session?: string;
132
- /** The environment of the session; `VULCAN_OWNER_REPLY=off` exempts it. */
133
- env?: Record<string, string | undefined>;
134
- }): Promise<string> {
135
- // A new turn begins with this prompt: the notes of the last one are forgotten, whatever is enforced.
136
- try {
137
- SignalState.startTurn({ root: opts.projectRoot, session: opts.session ?? '' });
138
- } catch {
139
- // The notes are advisory.
140
- }
141
-
142
- if (ReplySwitch.isOwnerOff({ env: opts.env ?? process.env })) {
143
- return '';
144
- }
145
-
146
- const view = await loadOwnerView({ projectRoot: opts.projectRoot });
147
-
148
- if (view.enforce === OwnerEnforcement.OFF) {
149
- return '';
150
- }
151
-
152
- // A claim match is a hint, so it is logged but never said back to the model as a fault of the last reply.
153
- const last = ViolationLog.readLastClasses({
154
- root: opts.projectRoot,
155
- session: opts.session,
156
- }).filter((name) => ShapeClasses.isValid(name));
157
-
158
- return last.length === 0
159
- ? 'Owner reply contract: follow the report shape from the session rules.'
160
- : `Owner reply contract: follow the report shape from the session rules. Your last reply broke it - ${last.map((name) => FIXES[name] ?? name).join('; ')}.`;
161
- }
162
- }