@venizia/vulcan 0.4.5 → 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/checks/wiki-anchors.ts +8 -0
- package/base/checks/wiki-source-links.ts +8 -0
- package/base/hooks/guard-git.ts +9 -2
- package/base/hooks/guard-writes.ts +4 -0
- 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/config/schema.ts +58 -4
- package/src/doctor/checks.ts +29 -1
- package/src/doctor/runner.ts +2 -0
- package/src/hooks/common/constants.ts +5 -0
- package/src/hooks/guard-git.ts +22 -2
- package/src/hooks/guard-outside.ts +20 -3
- package/src/hooks/guard-writes.ts +17 -6
- package/src/hooks/index.ts +2 -0
- package/src/hooks/project-guards.ts +123 -0
- package/src/hooks/project-tmp.ts +36 -0
- package/src/hooks/session-digest.ts +5 -0
- package/src/manifest/render.ts +38 -0
- 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 +106 -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 +152 -146
- package/src/visualize/schema.ts +246 -0
- 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
package/src/doctor/checks.ts
CHANGED
|
@@ -840,7 +840,7 @@ export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
|
|
|
840
840
|
const FMT_SECTION_ADVICE =
|
|
841
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';
|
|
842
842
|
const FMT_FLAVOR_ADVICE =
|
|
843
|
-
'without it bun fmt
|
|
843
|
+
'without it bun fmt uses its default style when oxfmt is not a dependency, and the output changes';
|
|
844
844
|
const OXFMT_LOADED_ADVICE =
|
|
845
845
|
'bun fmt loads it and it overrides the [fmt] section of bunfig.toml - delete it, or move its settings to [fmt]';
|
|
846
846
|
|
|
@@ -1205,6 +1205,34 @@ export const checkStaleTrustedScripts = (opts: ICheckContext): IViolation[] =>
|
|
|
1205
1205
|
: [];
|
|
1206
1206
|
});
|
|
1207
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
|
+
|
|
1208
1236
|
export const checkLocalSize = (opts: ICheckContext): IViolation[] => {
|
|
1209
1237
|
const entries = scanLocal({ root: opts.root });
|
|
1210
1238
|
const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
|
package/src/doctor/runner.ts
CHANGED
|
@@ -22,6 +22,7 @@ import {
|
|
|
22
22
|
checkTrustedScripts,
|
|
23
23
|
checkHooks,
|
|
24
24
|
checkLayout,
|
|
25
|
+
checkGuardPatterns,
|
|
25
26
|
checkLocalWorkspace,
|
|
26
27
|
checkMake,
|
|
27
28
|
checkOutsideWorktrees,
|
|
@@ -97,6 +98,7 @@ export const runDoctorNotes = async (opts: {
|
|
|
97
98
|
...checkAppScripts(context),
|
|
98
99
|
...checkAtlasBlock(context),
|
|
99
100
|
...checkLocalSize(context),
|
|
101
|
+
...checkGuardPatterns(context),
|
|
100
102
|
...checkReplyShape(context),
|
|
101
103
|
...checkOwnerReplySwitch({ env: opts.env ?? process.env }),
|
|
102
104
|
...checkTrustedScripts(context),
|
|
@@ -58,6 +58,11 @@ export class HookConstants {
|
|
|
58
58
|
static readonly MAX_QUERIES = 4;
|
|
59
59
|
/** Branches no agent deletes or force-pushes (V-W-06). */
|
|
60
60
|
static readonly PROTECTED_BRANCHES = new Set(['develop', 'main']);
|
|
61
|
+
/**
|
|
62
|
+
* Where a session's temporary files go, from the project root: `ProjectLayout.LOCAL_DIRECTORY` and `tmp`.
|
|
63
|
+
* Spelt out here because the blocking hooks import nothing that reads the package (a test holds the two equal).
|
|
64
|
+
*/
|
|
65
|
+
static readonly PROJECT_TMP = '.agents/local/tmp';
|
|
61
66
|
/** Set to `off` to switch the guards off for a session; the hooks then pass every call. */
|
|
62
67
|
static readonly KILL_SWITCH_ENV = 'VULCAN_GUARDS';
|
|
63
68
|
static readonly KILL_SWITCH_OFF = 'off';
|
package/src/hooks/guard-git.ts
CHANGED
|
@@ -3,6 +3,7 @@ import { basenameOf, parseShellChecked, programOf } from './shell.ts';
|
|
|
3
3
|
import type { ISimpleCommand } from './shell.ts';
|
|
4
4
|
import { GuardDecisions, HookConstants } from './common/index.ts';
|
|
5
5
|
import type { IGitHit, IGitRunner } from './common/index.ts';
|
|
6
|
+
import { matchesBranch } from './project-guards.ts';
|
|
6
7
|
|
|
7
8
|
/** `git` and `gh` read-only queries the guard makes; `undefined` when the tool is missing, slow or fails. */
|
|
8
9
|
export const runQuery: IGitRunner = (opts) => {
|
|
@@ -57,6 +58,7 @@ const inspectPush = (opts: {
|
|
|
57
58
|
rest: string[];
|
|
58
59
|
cwd: string | undefined;
|
|
59
60
|
run: IGitRunner;
|
|
61
|
+
askPush: string[];
|
|
60
62
|
}): IGitHit[] => {
|
|
61
63
|
const flags = opts.rest.filter((word) => word.startsWith('-') && word !== '-');
|
|
62
64
|
const positional = opts.rest.filter((word) => !word.startsWith('-'));
|
|
@@ -97,6 +99,21 @@ const inspectPush = (opts: {
|
|
|
97
99
|
}
|
|
98
100
|
}
|
|
99
101
|
|
|
102
|
+
// A target the project lists asks even for a plain push; a hit already made says the push needs a human.
|
|
103
|
+
if (hits.length === 0 && !deleting) {
|
|
104
|
+
for (const name of targets) {
|
|
105
|
+
const branch = name.replace(/^\+/, '').replace(/^refs\/heads\//, '');
|
|
106
|
+
|
|
107
|
+
if (matchesBranch({ name: branch, patterns: opts.askPush })) {
|
|
108
|
+
hits.push({
|
|
109
|
+
decision: GuardDecisions.ASK,
|
|
110
|
+
rule: 'V-W-06',
|
|
111
|
+
message: `pushing to '${branch}', a target this project lists in guard.git.askPush`,
|
|
112
|
+
});
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
100
117
|
if (flags.includes('--mirror')) {
|
|
101
118
|
hits.push({
|
|
102
119
|
decision: GuardDecisions.ASK,
|
|
@@ -229,6 +246,7 @@ const inspectOne = (opts: {
|
|
|
229
246
|
command: ISimpleCommand;
|
|
230
247
|
cwd: string | undefined;
|
|
231
248
|
run: IGitRunner;
|
|
249
|
+
askPush: string[];
|
|
232
250
|
}): IGitHit[] => {
|
|
233
251
|
const program = programOf({ command: opts.command });
|
|
234
252
|
const name = basenameOf({ word: program.name });
|
|
@@ -245,7 +263,7 @@ const inspectOne = (opts: {
|
|
|
245
263
|
const cwd = call.dir ?? opts.cwd;
|
|
246
264
|
|
|
247
265
|
if (call.sub === 'push') {
|
|
248
|
-
return inspectPush({ rest: call.rest, cwd, run: opts.run });
|
|
266
|
+
return inspectPush({ rest: call.rest, cwd, run: opts.run, askPush: opts.askPush });
|
|
249
267
|
}
|
|
250
268
|
|
|
251
269
|
if (call.sub === 'branch') {
|
|
@@ -282,6 +300,8 @@ export const inspectGit = (opts: {
|
|
|
282
300
|
command: string;
|
|
283
301
|
cwd: string | undefined;
|
|
284
302
|
run?: IGitRunner;
|
|
303
|
+
/** Branches (names, `*` allowed) a plain `git push` asks about: `guard.git.askPush`. */
|
|
304
|
+
askPush?: string[];
|
|
285
305
|
}): IGitHit[] => {
|
|
286
306
|
const parsed = parseShellChecked({ command: opts.command });
|
|
287
307
|
const run = opts.run ?? runQuery;
|
|
@@ -301,7 +321,7 @@ export const inspectGit = (opts: {
|
|
|
301
321
|
return run(call);
|
|
302
322
|
};
|
|
303
323
|
const hits = parsed.commands.flatMap((command) =>
|
|
304
|
-
inspectOne({ command, cwd: opts.cwd, run: limited }),
|
|
324
|
+
inspectOne({ command, cwd: opts.cwd, run: limited, askPush: opts.askPush ?? [] }),
|
|
305
325
|
);
|
|
306
326
|
|
|
307
327
|
// Part of the line was not read: never an allow.
|
|
@@ -4,6 +4,7 @@ import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
|
|
|
4
4
|
import { basenameOf, parseShellChecked, programOf } from './shell.ts';
|
|
5
5
|
import type { ISimpleCommand } from './shell.ts';
|
|
6
6
|
import { HookConstants } from './common/index.ts';
|
|
7
|
+
import { projectTmpOf } from './project-tmp.ts';
|
|
7
8
|
import type { IManifestHookInput, IOutsideHit } from './common/index.ts';
|
|
8
9
|
|
|
9
10
|
const FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
|
|
@@ -238,7 +239,7 @@ const gitTargets = (opts: { rest: string[]; base: string; dir: string | undefine
|
|
|
238
239
|
};
|
|
239
240
|
|
|
240
241
|
/** The words a simple command would create or write, with a name for what writes them. */
|
|
241
|
-
const targetsOf = (opts: { command: ISimpleCommand; base: string }): ITarget[] => {
|
|
242
|
+
const targetsOf = (opts: { command: ISimpleCommand; base: string; tmp: string }): ITarget[] => {
|
|
242
243
|
const program = programOf({ command: opts.command });
|
|
243
244
|
const name = basenameOf({ word: program.name });
|
|
244
245
|
const { args } = program;
|
|
@@ -314,7 +315,7 @@ const targetsOf = (opts: { command: ISimpleCommand; base: string }): ITarget[] =
|
|
|
314
315
|
if (directory !== undefined) {
|
|
315
316
|
add(directory, 'mktemp creates a temporary file');
|
|
316
317
|
} else if (inTmpdir || template === undefined) {
|
|
317
|
-
add(
|
|
318
|
+
add(opts.tmp, 'mktemp creates a file in the system temp directory');
|
|
318
319
|
} else {
|
|
319
320
|
add(template, 'mktemp creates a temporary file');
|
|
320
321
|
}
|
|
@@ -327,6 +328,21 @@ const targetsOf = (opts: { command: ISimpleCommand; base: string }): ITarget[] =
|
|
|
327
328
|
return targets;
|
|
328
329
|
};
|
|
329
330
|
|
|
331
|
+
/**
|
|
332
|
+
* The folder a bare `mktemp` uses in the command: the `TMPDIR` this hook runs with (Claude Code started
|
|
333
|
+
* with the launch file or the variables), else the project's own folder when Claude Code's session-start
|
|
334
|
+
* hook exports it (`CLAUDE_PROJECT_DIR` is set only by Claude Code), else the system temp directory.
|
|
335
|
+
*/
|
|
336
|
+
const commandTmpdirOf = (opts: { env: TEnvironment; projectRoot: string }): string => {
|
|
337
|
+
if (opts.env.TMPDIR !== undefined && opts.env.TMPDIR !== '') {
|
|
338
|
+
return opts.env.TMPDIR;
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
return opts.env.CLAUDE_PROJECT_DIR === undefined
|
|
342
|
+
? tmpdir()
|
|
343
|
+
: projectTmpOf({ root: opts.projectRoot });
|
|
344
|
+
};
|
|
345
|
+
|
|
330
346
|
/**
|
|
331
347
|
* Every file, worktree, clone or temp file `input` would create outside the project. Files a package
|
|
332
348
|
* manager, a runtime or the agent tool manage themselves are allowed (`toolOwnedPaths`, extending the
|
|
@@ -350,6 +366,7 @@ export const inspectOutside = (opts: {
|
|
|
350
366
|
env,
|
|
351
367
|
});
|
|
352
368
|
const start = opts.input.cwd ?? opts.projectRoot;
|
|
369
|
+
const tmp = commandTmpdirOf({ env, projectRoot: opts.projectRoot });
|
|
353
370
|
const targets: ITarget[] = [];
|
|
354
371
|
|
|
355
372
|
if (FILE_TOOLS.has(opts.input.tool) && opts.input.filePath !== undefined) {
|
|
@@ -381,7 +398,7 @@ export const inspectOutside = (opts: {
|
|
|
381
398
|
continue;
|
|
382
399
|
}
|
|
383
400
|
|
|
384
|
-
targets.push(...targetsOf({ command, base }));
|
|
401
|
+
targets.push(...targetsOf({ command, base, tmp }));
|
|
385
402
|
}
|
|
386
403
|
}
|
|
387
404
|
|
|
@@ -5,6 +5,7 @@ import { TrustStates } from './common/index.ts';
|
|
|
5
5
|
import type { IHookCommand, IWriteCheck, IWriteHit } from './common/index.ts';
|
|
6
6
|
import { commandTextsOf } from './command-view.ts';
|
|
7
7
|
import { forHost } from './decision.ts';
|
|
8
|
+
import type { IProjectCommandCheck } from './project-guards.ts';
|
|
8
9
|
import { listedScriptOf, trustOf } from './trusted-scripts.ts';
|
|
9
10
|
|
|
10
11
|
const MUTATING_VERB = '(?:POST|PUT|PATCH|DELETE)';
|
|
@@ -87,16 +88,26 @@ export const inspectCommand = (opts: {
|
|
|
87
88
|
command: string;
|
|
88
89
|
cwd: string;
|
|
89
90
|
trust?: { root: string; scripts: string[] };
|
|
91
|
+
/** The project's own commands (`guard.writes.commands`), checked beside the fixed list. */
|
|
92
|
+
extra?: IProjectCommandCheck[];
|
|
90
93
|
}): IWriteHit[] => {
|
|
91
94
|
// The patterns run on what the command runs, not on its text: a heredoc written to a file, the pattern
|
|
92
95
|
// of an `rg` and a commit message are data.
|
|
93
96
|
const texts = commandTextsOf({ command: opts.command, withMessages: true });
|
|
94
|
-
const
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
97
|
+
const checks: IWriteCheck[] = [
|
|
98
|
+
...COMMAND_CHECKS,
|
|
99
|
+
...(opts.extra ?? []).map((check) => ({
|
|
100
|
+
rule: check.rule,
|
|
101
|
+
what: `${check.what} (this project's pattern)`,
|
|
102
|
+
pattern: check.pattern,
|
|
103
|
+
})),
|
|
104
|
+
];
|
|
105
|
+
const hits: IWriteHit[] = checks
|
|
106
|
+
.filter((check) => texts.some((text) => check.pattern.test(text)))
|
|
107
|
+
.map((check) => ({
|
|
108
|
+
rule: check.rule,
|
|
109
|
+
message: check.what,
|
|
110
|
+
}));
|
|
100
111
|
|
|
101
112
|
for (const target of extractScriptTargets({ command: texts.join('\n') })) {
|
|
102
113
|
const source = readScript({ target, cwd: opts.cwd });
|
package/src/hooks/index.ts
CHANGED
|
@@ -10,6 +10,8 @@ export * from './trusted-scripts.ts';
|
|
|
10
10
|
export * from './session-digest.ts';
|
|
11
11
|
export * from './subagent-card.ts';
|
|
12
12
|
export * from './owner-reply.ts';
|
|
13
|
+
export * from './project-tmp.ts';
|
|
14
|
+
export * from './project-guards.ts';
|
|
13
15
|
export * from './remote-hosts.ts';
|
|
14
16
|
export * from './codex-patch.ts';
|
|
15
17
|
export * from './shell.ts';
|
|
@@ -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
|
+
};
|
|
@@ -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,
|
package/src/manifest/render.ts
CHANGED
|
@@ -46,6 +46,40 @@ export const buildBaseRuleHashes = (): Record<string, string> =>
|
|
|
46
46
|
}),
|
|
47
47
|
);
|
|
48
48
|
|
|
49
|
+
/** The manifest's `guard` block: what the project adds to guard-writes and guard-git, as data a hook reads without the config. */
|
|
50
|
+
const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<string, unknown> } => {
|
|
51
|
+
const { commands } = opts.config.guard.writes;
|
|
52
|
+
const { askPush } = opts.config.guard.git;
|
|
53
|
+
const block = {
|
|
54
|
+
...(commands.length === 0
|
|
55
|
+
? {}
|
|
56
|
+
: {
|
|
57
|
+
writes: {
|
|
58
|
+
commands: commands.map((command) => ({
|
|
59
|
+
rule: command.rule,
|
|
60
|
+
what: command.what,
|
|
61
|
+
pattern: command.pattern,
|
|
62
|
+
...(command.ignoreCase === true ? { ignoreCase: true } : {}),
|
|
63
|
+
})),
|
|
64
|
+
},
|
|
65
|
+
}),
|
|
66
|
+
...(askPush.length === 0 ? {} : { git: { askPush } }),
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
return Object.keys(block).length === 0 ? {} : { guard: block };
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
/** The manifest's `atlas` block: only what the config sets (keys listed, the download turned off). */
|
|
73
|
+
const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<string, unknown> } => {
|
|
74
|
+
const keys = opts.config.atlas.index?.keys ?? [];
|
|
75
|
+
const block = {
|
|
76
|
+
...(keys.length === 0 ? {} : { index: { keys } }),
|
|
77
|
+
...(opts.config.atlas.prebuilt === false ? { prebuilt: false } : {}),
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
return Object.keys(block).length === 0 ? {} : { atlas: block };
|
|
81
|
+
};
|
|
82
|
+
|
|
49
83
|
/**
|
|
50
84
|
* The project manifest (Project Contract v1, C1): data only, rendered from the config with a fixed
|
|
51
85
|
* key order, so the committed file is byte-stable and a stale one shows as a diff.
|
|
@@ -82,6 +116,10 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
|
|
|
82
116
|
rules: { project: ManifestConstants.PROJECT_RULES, base: buildBaseRuleHashes() },
|
|
83
117
|
// The sources this project reads knowledge from (atlas, git mode); a project without any carries none.
|
|
84
118
|
...(config.atlas.sources.length === 0 ? {} : { sources: config.atlas.sources }),
|
|
119
|
+
// The prebuilt index: the keys a published pair is checked with, and the switch; neither set, nothing is written.
|
|
120
|
+
...atlasBlockOf({ config }),
|
|
121
|
+
// The commands and push targets the guards ask about beyond their own list; neither set, nothing is written.
|
|
122
|
+
...guardBlockOf({ config }),
|
|
85
123
|
// The remote-host guard reads its policy here; a project without the key has no guard.
|
|
86
124
|
...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
|
|
87
125
|
};
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import { dirname, join } from 'node:path';
|
|
3
|
+
import { ProjectLayout } from '../common/index.ts';
|
|
4
|
+
import { projectTmpOf } from '../hooks/project-tmp.ts';
|
|
5
|
+
import { SyncStatuses } from './common/index.ts';
|
|
6
|
+
import type { ISyncAction } from './common/index.ts';
|
|
7
|
+
|
|
8
|
+
/** Beside the other personal files of the developer, gitignored with them. */
|
|
9
|
+
export const CLAUDE_LAUNCH_FILE = `${ProjectLayout.LOCAL_DIRECTORY}/claude.launch.settings.json`;
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* What `claude --settings <this file>` adds to a session: `TMPDIR` and `CLAUDE_CODE_TMPDIR` in the project.
|
|
13
|
+
* Claude Code applies an `env` block given this way (and the variables in the launch environment, and the
|
|
14
|
+
* user settings file), but not the same block in the project's own settings, so this is the route that
|
|
15
|
+
* moves its own task-output files and its MCP servers into the project. Absolute paths: the file belongs
|
|
16
|
+
* to one checkout of one developer.
|
|
17
|
+
*/
|
|
18
|
+
export const renderClaudeLaunch = (opts: { root: string }): string => {
|
|
19
|
+
const folder = projectTmpOf({ root: opts.root });
|
|
20
|
+
|
|
21
|
+
return `${JSON.stringify({ env: { TMPDIR: folder, CLAUDE_CODE_TMPDIR: folder } }, null, 2)}\n`;
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
/** The launch file when it is missing or written for another folder; nothing to do when it is current. */
|
|
25
|
+
export const planClaudeLaunch = (opts: { root: string }): ISyncAction[] => {
|
|
26
|
+
const path = join(opts.root, CLAUDE_LAUNCH_FILE);
|
|
27
|
+
const text = renderClaudeLaunch({ root: opts.root });
|
|
28
|
+
const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
|
|
29
|
+
|
|
30
|
+
if (before === text) {
|
|
31
|
+
return [];
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
return [
|
|
35
|
+
{
|
|
36
|
+
path,
|
|
37
|
+
status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
|
|
38
|
+
note:
|
|
39
|
+
before === undefined
|
|
40
|
+
? 'the Claude Code launch file is missing'
|
|
41
|
+
: 'the Claude Code launch file names another folder',
|
|
42
|
+
apply: () => {
|
|
43
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
44
|
+
writeFileSync(path, text);
|
|
45
|
+
},
|
|
46
|
+
},
|
|
47
|
+
];
|
|
48
|
+
};
|
package/src/sync/index.ts
CHANGED
|
@@ -4,6 +4,7 @@ export * from './planner.ts';
|
|
|
4
4
|
export * from './prune.ts';
|
|
5
5
|
export * from './settings.ts';
|
|
6
6
|
export * from './local-choice.ts';
|
|
7
|
+
export * from './claude-launch.ts';
|
|
7
8
|
export * from './agent-files.ts';
|
|
8
9
|
export * from './atlas-block.ts';
|
|
9
10
|
export * from './exclude.ts';
|
package/src/sync/local-choice.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
|
2
2
|
import { dirname, join } from 'node:path';
|
|
3
3
|
import { LOCAL_AGENTS_FILE, renderLocalChoice } from '../agents/index.ts';
|
|
4
4
|
import { ProjectLayout } from '../common/index.ts';
|
|
5
|
+
import { planClaudeLaunch } from './claude-launch.ts';
|
|
5
6
|
import { SyncStatuses } from './common/index.ts';
|
|
6
7
|
import type { ISyncAction } from './common/index.ts';
|
|
7
8
|
|
|
@@ -71,6 +72,7 @@ export const planLocalWorkspace = (opts: { root: string }): ISyncAction[] => {
|
|
|
71
72
|
|
|
72
73
|
return [
|
|
73
74
|
...planIgnoreLine({ root: opts.root, line: `${ProjectLayout.LOCAL_DIRECTORY}/` }),
|
|
75
|
+
...planClaudeLaunch({ root: opts.root }),
|
|
74
76
|
{
|
|
75
77
|
path: directory,
|
|
76
78
|
status: missing.length === 0 ? SyncStatuses.UNCHANGED : SyncStatuses.CREATED,
|