@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.
- package/LICENSE.md +1 -1
- package/README.md +13 -0
- package/base/agents.json +22 -1
- package/base/checks/wiki-anchors.ts +8 -0
- package/base/checks/wiki-source-links.ts +8 -0
- package/base/claude/remote-hosts.json +1 -1
- package/base/claude/settings.json +12 -12
- package/base/extensions/vulcan-guards.ts +301 -0
- package/base/hooks/antigravity-guards.ts +68 -0
- package/base/hooks/codex-guards.ts +66 -0
- package/base/hooks/guard-git.ts +38 -9
- package/base/hooks/guard-outside.ts +29 -9
- package/base/hooks/guard-writes.ts +29 -1
- package/base/hooks/session-start.ts +14 -4
- package/base/make/vulcan.mk +12 -1
- package/base/references/delegation-brief.md +5 -4
- package/base/rules.md +2 -2
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/docs-writing/references/agent-documents.md +1 -1
- package/base/skills/knowledge-sync/SKILL.md +1 -1
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/report-back/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +1 -1
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +33 -11
- package/base/skills/visualize-work/references/spec.md +77 -12
- package/package.json +4 -4
- package/src/agents/codex-hooks.ts +133 -0
- package/src/agents/common/constants.ts +54 -0
- package/src/agents/common/schema.ts +10 -1
- package/src/agents/common/types.ts +3 -1
- package/src/agents/exclude.ts +4 -0
- package/src/agents/hooks-json.ts +111 -0
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +5 -4
- package/src/agents/resolve.ts +24 -9
- package/src/config/common/constants.ts +12 -0
- package/src/config/common/types.ts +2 -1
- package/src/config/packages.ts +2 -1
- package/src/config/schema.ts +84 -5
- package/src/create/add-app.ts +2 -2
- package/src/create/add-lib.ts +21 -8
- package/src/create/common/constants.ts +12 -0
- package/src/create/common/types.ts +2 -1
- package/src/create/preset-diff.ts +4 -2
- package/src/create/workspace.ts +13 -9
- package/src/doctor/checks.ts +71 -1
- package/src/doctor/common/constants.ts +2 -0
- package/src/doctor/runner.ts +6 -0
- package/src/hooks/codex-patch.ts +47 -0
- package/src/hooks/command-view.ts +97 -0
- package/src/hooks/common/constants.ts +46 -0
- package/src/hooks/common/types.ts +9 -1
- package/src/hooks/decision.ts +50 -8
- package/src/hooks/guard-git.ts +64 -5
- package/src/hooks/guard-manifest.ts +22 -8
- package/src/hooks/guard-outside.ts +38 -6
- package/src/hooks/guard-package.ts +15 -12
- package/src/hooks/guard-writes.ts +72 -21
- package/src/hooks/index.ts +5 -0
- package/src/hooks/project-guards.ts +123 -0
- package/src/hooks/project-tmp.ts +36 -0
- package/src/hooks/remote-hosts.ts +38 -14
- package/src/hooks/session-digest.ts +5 -0
- package/src/hooks/shell.ts +665 -35
- package/src/hooks/trusted-scripts.ts +134 -0
- package/src/manifest/render.ts +38 -0
- package/src/sync/agent-files.ts +122 -4
- package/src/sync/agent-removal.ts +118 -4
- package/src/sync/claude-launch.ts +48 -0
- package/src/sync/index.ts +1 -0
- package/src/sync/local-choice.ts +2 -0
- package/src/visualize/assets.ts +195 -54
- package/src/visualize/charts.ts +235 -0
- package/src/visualize/constants.ts +122 -1
- package/src/visualize/diagrams.ts +224 -0
- package/src/visualize/icons.ts +28 -0
- package/src/visualize/layout.ts +58 -8
- package/src/visualize/page.ts +151 -145
- package/src/visualize/schema.ts +252 -2
- package/src/visualize/sections.ts +370 -0
- package/src/visualize/validate.ts +100 -7
- package/src/wiki/anchors.ts +118 -0
- package/src/wiki/command.ts +110 -0
- package/src/wiki/constants.ts +30 -0
- package/src/wiki/index.ts +4 -0
- package/src/wiki/source-links.ts +186 -0
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
|
|
4
|
+
/** A command the project says is a database write or a deploy: guard-writes asks on a match. */
|
|
5
|
+
export interface IProjectCommandCheck {
|
|
6
|
+
rule: 'V-W-02' | 'V-W-03';
|
|
7
|
+
what: string;
|
|
8
|
+
pattern: RegExp;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
/** What the project adds to the guards: the manifest's `guard` block, compiled. */
|
|
12
|
+
export interface IGuardPolicy {
|
|
13
|
+
commands: IProjectCommandCheck[];
|
|
14
|
+
askPush: string[];
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** Spelt out: the blocking hooks import nothing that reads the package (a test holds it equal to the manifest's name). */
|
|
18
|
+
export const GUARD_MANIFEST_FILE = '.agents/vulcan.manifest.json';
|
|
19
|
+
|
|
20
|
+
const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
|
|
21
|
+
typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
|
|
22
|
+
|
|
23
|
+
const ruleOf = (opts: { value: unknown }): 'V-W-02' | 'V-W-03' | undefined =>
|
|
24
|
+
opts.value === 'V-W-02' || opts.value === 'V-W-03' ? opts.value : undefined;
|
|
25
|
+
|
|
26
|
+
const note = (opts: { message: string }): void => {
|
|
27
|
+
console.error(`vulcan: [guard] ${opts.message}`);
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
const commandOf = (opts: { value: unknown }): IProjectCommandCheck | undefined => {
|
|
31
|
+
const holder = { value: opts.value };
|
|
32
|
+
|
|
33
|
+
if (!isRecord(holder)) {
|
|
34
|
+
return undefined;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const rule = ruleOf({ value: holder.value['rule'] });
|
|
38
|
+
const what = holder.value['what'];
|
|
39
|
+
const source = holder.value['pattern'];
|
|
40
|
+
|
|
41
|
+
if (rule === undefined || typeof what !== 'string' || what === '' || typeof source !== 'string') {
|
|
42
|
+
note({
|
|
43
|
+
message: 'ignoring a guard.writes.commands entry that has no usable rule, what or pattern',
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
return undefined;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
try {
|
|
50
|
+
return {
|
|
51
|
+
rule,
|
|
52
|
+
what,
|
|
53
|
+
pattern: new RegExp(source, holder.value['ignoreCase'] === true ? 'i' : ''),
|
|
54
|
+
};
|
|
55
|
+
} catch (error) {
|
|
56
|
+
note({
|
|
57
|
+
message: `ignoring the pattern '${source}' of guard.writes.commands (${error instanceof Error ? error.message : String(error)})`,
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
return undefined;
|
|
61
|
+
}
|
|
62
|
+
};
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* The commands and push targets a project lists, from the committed manifest (`vulcan sync` renders
|
|
66
|
+
* them from the config), so a hook reads them with no config loader and no zod. A project with no
|
|
67
|
+
* manifest, or none of the block, has none; an entry that cannot be used is skipped, said once on
|
|
68
|
+
* stderr, and the others stay.
|
|
69
|
+
*/
|
|
70
|
+
export const readGuardPolicy = (opts: { root: string }): IGuardPolicy => {
|
|
71
|
+
const path = join(opts.root, GUARD_MANIFEST_FILE);
|
|
72
|
+
const empty: IGuardPolicy = { commands: [], askPush: [] };
|
|
73
|
+
|
|
74
|
+
if (!existsSync(path)) {
|
|
75
|
+
return empty;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
let manifest: unknown;
|
|
79
|
+
|
|
80
|
+
try {
|
|
81
|
+
manifest = JSON.parse(readFileSync(path, 'utf8'));
|
|
82
|
+
} catch (error) {
|
|
83
|
+
note({
|
|
84
|
+
message: `the manifest could not be read, so the project's own patterns are off (${error instanceof Error ? error.message : String(error)})`,
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
return empty;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
const top = { value: manifest };
|
|
91
|
+
const guard = isRecord(top) ? { value: top.value['guard'] } : { value: undefined };
|
|
92
|
+
|
|
93
|
+
if (!isRecord(guard)) {
|
|
94
|
+
return empty;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
const writes = { value: guard.value['writes'] };
|
|
98
|
+
const git = { value: guard.value['git'] };
|
|
99
|
+
const listed = isRecord(writes) ? writes.value['commands'] : undefined;
|
|
100
|
+
const targets = isRecord(git) ? git.value['askPush'] : undefined;
|
|
101
|
+
|
|
102
|
+
return {
|
|
103
|
+
commands: (Array.isArray(listed) ? listed : []).flatMap((entry) => {
|
|
104
|
+
const check = commandOf({ value: entry });
|
|
105
|
+
|
|
106
|
+
return check === undefined ? [] : [check];
|
|
107
|
+
}),
|
|
108
|
+
askPush: (Array.isArray(targets) ? targets : []).filter(
|
|
109
|
+
(target): target is string => typeof target === 'string' && target !== '',
|
|
110
|
+
),
|
|
111
|
+
};
|
|
112
|
+
};
|
|
113
|
+
|
|
114
|
+
/** Whether a branch name is one of the listed names; `*` stands for any run of characters, nothing else is special. */
|
|
115
|
+
export const matchesBranch = (opts: { name: string; patterns: string[] }): boolean =>
|
|
116
|
+
opts.patterns.some((pattern) =>
|
|
117
|
+
new RegExp(
|
|
118
|
+
`^${pattern
|
|
119
|
+
.split('*')
|
|
120
|
+
.map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
|
|
121
|
+
.join('.*')}$`,
|
|
122
|
+
).test(opts.name),
|
|
123
|
+
);
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { appendFileSync, mkdirSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { HookConstants } from './common/index.ts';
|
|
4
|
+
|
|
5
|
+
/** `<root>/.agents/local/tmp`: where a session's temporary files go, absolute. `vulcan clean` reads its age. */
|
|
6
|
+
export const projectTmpOf = (opts: { root: string }): string =>
|
|
7
|
+
join(opts.root, HookConstants.PROJECT_TMP);
|
|
8
|
+
|
|
9
|
+
/** A word for `sh`, whatever it holds: in single quotes, a quote itself closed, escaped and opened again. */
|
|
10
|
+
const shellQuote = (opts: { text: string }): string => `'${opts.text.replaceAll("'", "'\\''")}'`;
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Makes every Bash command of a Claude Code session run with `TMPDIR` in the project. Claude Code hands a
|
|
14
|
+
* SessionStart hook a file (`CLAUDE_ENV_FILE`) and sources it before each Bash command, so one `export`
|
|
15
|
+
* there is enough: `mktemp`, bun, node and every script a command starts then use the project folder. It
|
|
16
|
+
* does not move Claude Code's own task-output files or an MCP server (those need the launch file), and
|
|
17
|
+
* `TMPDIR` in the project's settings `env` is not applied by Claude Code, which is why this is a hook.
|
|
18
|
+
* Returns whether it wrote; with no file (another agent, a run outside Claude Code) it does nothing. A
|
|
19
|
+
* path with a line break is refused: a line of shell must never be made from a folder name.
|
|
20
|
+
*/
|
|
21
|
+
export const exportProjectTmp = (opts: { root: string; envFile: string | undefined }): boolean => {
|
|
22
|
+
if (opts.envFile === undefined || opts.envFile === '') {
|
|
23
|
+
return false;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
const folder = projectTmpOf({ root: opts.root });
|
|
27
|
+
|
|
28
|
+
if (/[\r\n]/.test(folder)) {
|
|
29
|
+
return false;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
mkdirSync(folder, { recursive: true });
|
|
33
|
+
appendFileSync(opts.envFile, `export TMPDIR=${shellQuote({ text: folder })}\n`);
|
|
34
|
+
|
|
35
|
+
return true;
|
|
36
|
+
};
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { HookConstants } from './common/index.ts';
|
|
2
2
|
import type { IWriteHit } from './common/index.ts';
|
|
3
|
-
import {
|
|
3
|
+
import { isDataOnly } from './command-view.ts';
|
|
4
|
+
import { forHost } from './decision.ts';
|
|
5
|
+
import { optionTakesNextWord, programOf, splitHeredocs } from './shell.ts';
|
|
4
6
|
|
|
5
7
|
// -----------------------------------------------------------------------------
|
|
6
8
|
// The remote-host guard: a Bash command that reaches a host the project has not listed asks first.
|
|
@@ -752,6 +754,11 @@ const analyzeWords = (opts: {
|
|
|
752
754
|
|
|
753
755
|
const program = basenameOf({ word: words[0] ?? '' });
|
|
754
756
|
|
|
757
|
+
// `rg -n "ssh|scp" docs/`: the arguments of a search or a print are data.
|
|
758
|
+
if (isDataOnly({ command: { words, redirects: [], assignments: [] }, withMessages: false })) {
|
|
759
|
+
return [];
|
|
760
|
+
}
|
|
761
|
+
|
|
755
762
|
if (program === '' || LOOKUPS.has(program) || opts.depth > MAXIMUM_DEPTH) {
|
|
756
763
|
return opts.depth > MAXIMUM_DEPTH ? [unreadable({ why: 'the command nests too deeply' })] : [];
|
|
757
764
|
}
|
|
@@ -760,6 +767,19 @@ const analyzeWords = (opts: {
|
|
|
760
767
|
return [];
|
|
761
768
|
}
|
|
762
769
|
|
|
770
|
+
if (program === 'env') {
|
|
771
|
+
// `env -S "ssh host"` carries a whole command line in one word: the command it makes is read as one.
|
|
772
|
+
const splits = programOf({
|
|
773
|
+
command: { words, redirects: [], assignments: [] },
|
|
774
|
+
}).splitCommands;
|
|
775
|
+
|
|
776
|
+
if (splits.length > 0) {
|
|
777
|
+
return splits.flatMap((splitWords) =>
|
|
778
|
+
analyzeWords({ words: splitWords, depth: opts.depth + 1, recurse: opts.recurse }),
|
|
779
|
+
);
|
|
780
|
+
}
|
|
781
|
+
}
|
|
782
|
+
|
|
763
783
|
if (WRAPPERS.has(program) || program === 'command' || program === 'builtin') {
|
|
764
784
|
return analyzeWords({
|
|
765
785
|
words: unwrap({ program, words }),
|
|
@@ -845,7 +865,8 @@ const analyzeWords = (opts: {
|
|
|
845
865
|
};
|
|
846
866
|
|
|
847
867
|
const analyzeCommand = (opts: { command: string; depth: number }): IFinding[] =>
|
|
848
|
-
|
|
868
|
+
// A heredoc body that is data (`cat > f <<EOF`) is not a command; one a shell reads stays in the text.
|
|
869
|
+
tokenize({ command: splitHeredocs({ command: opts.command }).text }).flatMap((segment) => {
|
|
849
870
|
const findings = analyzeWords({
|
|
850
871
|
words: segment.words,
|
|
851
872
|
depth: opts.depth,
|
|
@@ -935,15 +956,18 @@ export const inspectRemoteCommand = (opts: {
|
|
|
935
956
|
return hits;
|
|
936
957
|
};
|
|
937
958
|
|
|
938
|
-
export const buildRemoteDecision = (opts: { hits: IWriteHit[] }) =>
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
|
|
959
|
+
export const buildRemoteDecision = (opts: { hits: IWriteHit[] }) =>
|
|
960
|
+
forHost({
|
|
961
|
+
output: {
|
|
962
|
+
hookSpecificOutput: {
|
|
963
|
+
hookEventName: HookConstants.PRE_TOOL_USE,
|
|
964
|
+
permissionDecision: HookConstants.GUARD_DECISION,
|
|
965
|
+
permissionDecisionReason: [
|
|
966
|
+
'This command may reach a remote host the project has not listed:',
|
|
967
|
+
...opts.hits.map((hit) => ` - ${hit.message}`),
|
|
968
|
+
'',
|
|
969
|
+
'Read on the host, never edit, restart or copy onto it. Produce the command and hand it over.',
|
|
970
|
+
].join('\n'),
|
|
971
|
+
},
|
|
972
|
+
},
|
|
973
|
+
});
|
|
@@ -11,6 +11,7 @@ import {
|
|
|
11
11
|
resolveOwnerView,
|
|
12
12
|
} from '../owner/index.ts';
|
|
13
13
|
import { extractRuleRows, parseRuleIds, readSlots, RuleConstants } from '../rules/index.ts';
|
|
14
|
+
import { projectTmpOf } from './project-tmp.ts';
|
|
14
15
|
|
|
15
16
|
/** A project row whose first cell lists IDs - `| V-W-02, V-W-03 |` - elaborates those base rules. */
|
|
16
17
|
const ID_LIST_ROW =
|
|
@@ -96,6 +97,10 @@ export const buildSessionDigest = async (opts: {
|
|
|
96
97
|
...TABLE_HEADER,
|
|
97
98
|
...baseRows.filter((row) => row.startsWith(`| ${RuleConstants.BASE_NAMESPACE}W-`)),
|
|
98
99
|
'',
|
|
100
|
+
'## Temporary files',
|
|
101
|
+
'',
|
|
102
|
+
`Scratch and temporary files go in \`${projectTmpOf({ root: opts.projectRoot })}\`, never /tmp (V-B-08). In Claude Code every Bash command already runs with \`TMPDIR\` set to it; in any other agent run \`export TMPDIR=${projectTmpOf({ root: opts.projectRoot })}\` first. Remove what you made when the task ends.`,
|
|
103
|
+
'',
|
|
99
104
|
"## This project's slot choices",
|
|
100
105
|
'',
|
|
101
106
|
...slotRows,
|