@venizia/vulcan 0.4.10-8 → 0.4.10-9
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/README.md +1 -3
- package/base/claude/events.json +1 -11
- package/base/claude/settings.json +3 -3
- package/base/extensions/vulcan-guards.ts +9 -2
- package/base/hooks/guard-outside.ts +34 -10
- package/base/hooks/session-start.ts +1 -1
- package/base/packs/venizia.md +16 -0
- package/base/rules.md +23 -18
- package/base/templates/AGENTS.md +2 -2
- package/package.json +3 -3
- package/src/agents/atlas-block.ts +8 -31
- package/src/agents/generated-block.ts +52 -0
- package/src/agents/index.ts +2 -0
- package/src/agents/rules-block.ts +92 -0
- package/src/commands/index.ts +0 -2
- package/src/commands/sync.command.ts +3 -3
- package/src/commands/table.ts +0 -12
- package/src/common/constants.ts +0 -1
- package/src/config/schema.ts +9 -25
- package/src/doctor/checks.ts +110 -49
- package/src/doctor/common/constants.ts +0 -2
- package/src/events/common/constants.ts +2 -12
- package/src/events/hook.ts +5 -56
- package/src/hooks/command-view.ts +1 -1
- package/src/hooks/common/types.ts +2 -0
- package/src/hooks/guard-git.ts +40 -0
- package/src/hooks/guard-outside.ts +52 -2
- package/src/hooks/session-digest.ts +24 -123
- package/src/hooks/shell-folders.ts +127 -2
- package/src/hooks/shell-writes.ts +4 -0
- package/src/hooks/shell.ts +111 -2
- package/src/manifest/render.ts +3 -15
- package/src/rules/base.ts +11 -7
- package/src/rules/index.ts +1 -0
- package/src/rules/packs.ts +44 -0
- package/src/sync/agents-block.ts +94 -0
- package/src/sync/base-rules.ts +3 -3
- package/src/sync/index.ts +1 -1
- package/src/visualize/architecture.ts +504 -0
- package/src/visualize/assets.ts +15 -14
- package/src/visualize/compare-render.ts +22 -24
- package/src/visualize/constants.ts +15 -0
- package/src/visualize/diagrams.ts +13 -121
- package/src/visualize/kinds-render.ts +2 -2
- package/src/visualize/labels-vi.ts +14 -0
- package/src/visualize/labels.ts +2 -0
- package/src/visualize/layout.ts +409 -66
- package/src/visualize/page.ts +34 -10
- package/src/visualize/schema.ts +18 -0
- package/src/visualize/sections.ts +22 -9
- package/base/hooks/guard-manifest.ts +0 -2
- package/base/hooks/guard-package.ts +0 -2
- package/base/hooks/guard-remote-hosts.ts +0 -2
- package/src/commands/graph.command.ts +0 -6
- package/src/sync/atlas-block.ts +0 -56
package/src/commands/table.ts
CHANGED
|
@@ -280,18 +280,6 @@ export class CommandTable {
|
|
|
280
280
|
exits:
|
|
281
281
|
'0 on success; 1 when --stable and --nightly are both given, the dist-tags cannot be read, or the install or sync fails.',
|
|
282
282
|
},
|
|
283
|
-
[VulcanCommands.GRAPH]: {
|
|
284
|
-
help: ` graph build [--full] Write the code graph of the project (vulcan x atlas graph build)
|
|
285
|
-
graph status [--json] Say whether the graph still matches the files it was built from`,
|
|
286
|
-
flags: {
|
|
287
|
-
'--full': 'build: read everything again, whatever changed',
|
|
288
|
-
'--json': 'status: print the answer as one line of JSON',
|
|
289
|
-
},
|
|
290
|
-
positionals: 1,
|
|
291
|
-
unknownExit: ExitCodes.USAGE,
|
|
292
|
-
exits:
|
|
293
|
-
'0 on success, and for every state of status (fresh, behind, diverged, unknown); 1 when the graph cannot be built (no git repository, a bad package.json) or atlas is not installed; 2 for an argument it does not know',
|
|
294
|
-
},
|
|
295
283
|
[VulcanCommands.X]: {
|
|
296
284
|
help: ` x <tool> [args...] Run a shipped tool at the pinned version: okf, atlas`,
|
|
297
285
|
passthrough: true,
|
package/src/common/constants.ts
CHANGED
|
@@ -16,7 +16,6 @@ export class VulcanCommands {
|
|
|
16
16
|
static readonly CI = 'ci';
|
|
17
17
|
static readonly BOARD = 'board';
|
|
18
18
|
static readonly EVENT = 'event';
|
|
19
|
-
static readonly GRAPH = 'graph';
|
|
20
19
|
static readonly X = 'x';
|
|
21
20
|
static readonly HELP = 'help';
|
|
22
21
|
static readonly VERSION = 'version';
|
package/src/config/schema.ts
CHANGED
|
@@ -3,6 +3,7 @@ import { LayoutFolder } from '../common/layout-folder.ts';
|
|
|
3
3
|
import { DOCTOR_SCHEMA } from '../doctor/schema.ts';
|
|
4
4
|
import { GuardDecisions } from '../hooks/common/constants.ts';
|
|
5
5
|
import { OWNER_SCHEMA } from '../owner/schema.ts';
|
|
6
|
+
import { RulePacks } from '../rules/packs.ts';
|
|
6
7
|
import { AgentSignaturePolicies } from '../commit/common/index.ts';
|
|
7
8
|
import type { TAgentSignaturePolicy } from '../commit/common/index.ts';
|
|
8
9
|
import { SubjectShape } from '../commit/subject.ts';
|
|
@@ -69,18 +70,6 @@ const PUSH_TARGET = z
|
|
|
69
70
|
.string()
|
|
70
71
|
.regex(/^[A-Za-z0-9._/*-]+$/, { message: 'a branch name, with * for any run of characters' });
|
|
71
72
|
|
|
72
|
-
/** An import prefix: the start of a specifier, ending in a slash (`@/`, `~/`). */
|
|
73
|
-
const GRAPH_ALIAS_PREFIX = z
|
|
74
|
-
.string()
|
|
75
|
-
.regex(/^[^\s]+\/$/, 'an alias prefix ends with a slash, for example "@/"');
|
|
76
|
-
/** The folder an alias leads to, from the importing package: relative to the package, never climbing. */
|
|
77
|
-
const GRAPH_ALIAS_FOLDER = z
|
|
78
|
-
.string()
|
|
79
|
-
.refine(
|
|
80
|
-
(value) => !value.startsWith('/') && !value.split('/').includes('..'),
|
|
81
|
-
'a folder of the package, from its root',
|
|
82
|
-
);
|
|
83
|
-
|
|
84
73
|
/** A key that was removed: optional, and refused when present with the key and what to do, instead of a bare "unrecognized key". */
|
|
85
74
|
const REMOVED_OKF_KEY = (opts: { fix: string }) =>
|
|
86
75
|
z
|
|
@@ -238,6 +227,14 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
238
227
|
agents: z.array(CODING_AGENT).optional(),
|
|
239
228
|
/** Choice of each base rule slot, keyed by rule ID (for example `V-W-01`) to the option picked; default `{}`. */
|
|
240
229
|
rules: z.record(z.string().regex(ConfigConstants.RULE_ID_PATTERN), z.string()).default({}),
|
|
230
|
+
/** The shipped rule packs this project follows, by name (`venizia`): rules for one stack, outside the base rules every project gets. */
|
|
231
|
+
packs: z
|
|
232
|
+
.array(
|
|
233
|
+
z.string().refine((name) => RulePacks.names().includes(name), {
|
|
234
|
+
error: () => `a rule pack VULCAN ships: ${RulePacks.names().join(', ')}`,
|
|
235
|
+
}),
|
|
236
|
+
)
|
|
237
|
+
.default([]),
|
|
241
238
|
/** The folders `vulcan init` and `add` put apps in, as the user named them. */
|
|
242
239
|
layout: z
|
|
243
240
|
.strictObject({
|
|
@@ -703,19 +700,6 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
703
700
|
maxAgeDays: z.number().int().min(1).optional(),
|
|
704
701
|
})
|
|
705
702
|
.default({ log: false }),
|
|
706
|
-
/**
|
|
707
|
-
* How `vulcan x atlas graph build` reads the code. `exclude` is globs of tracked files left out; `aliases` maps an import
|
|
708
|
-
* prefix to a folder of the importing package (`{ '@/': 'src/' }`), so `@/x` in `packages/a/src/y.ts` leads to
|
|
709
|
-
* `packages/a/src/x`. An alias not listed is counted as an external import.
|
|
710
|
-
*/
|
|
711
|
-
graph: z
|
|
712
|
-
.strictObject({
|
|
713
|
-
/** Globs of tracked files, from the project root, the graph leaves out. */
|
|
714
|
-
exclude: z.array(z.string().min(1)).default([]),
|
|
715
|
-
/** An import prefix ending in a slash, mapped to a folder of the importing package. */
|
|
716
|
-
aliases: z.record(GRAPH_ALIAS_PREFIX, GRAPH_ALIAS_FOLDER).default({}),
|
|
717
|
-
})
|
|
718
|
-
.default({ exclude: [], aliases: {} }),
|
|
719
703
|
/**
|
|
720
704
|
* What `vulcan` keeps tidy in `.agents/local/` by itself. `autoClean` (default true) lets the session-start hook, at
|
|
721
705
|
* most once a day, remove the safe part: stale `tmp/`, browser leftovers older than an hour, event files past their
|
package/src/doctor/checks.ts
CHANGED
|
@@ -8,21 +8,27 @@ import { MCP_SERVER_HINT, ProjectScaffold } from '../init/index.ts';
|
|
|
8
8
|
import { ProjectPackages } from '../config/index.ts';
|
|
9
9
|
import { ProjectKey } from '../events/project-key.ts';
|
|
10
10
|
import type { TResolvedConfig } from '../config/index.ts';
|
|
11
|
-
import { BaseRules, RuleParser, RuleSlots } from '../rules/index.ts';
|
|
11
|
+
import { BaseRules, RulePacks, RuleParser, RuleSlots } from '../rules/index.ts';
|
|
12
12
|
import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
|
|
13
13
|
import { AgentScopes, AgentSelection, AgentTable, LocalChoice } from '../agents/index.ts';
|
|
14
14
|
import { CommitHook, CommitHookStates } from '../commit/index.ts';
|
|
15
15
|
import { EventConstants } from '../events/common/index.ts';
|
|
16
16
|
import { EventRetention } from '../events/retention.ts';
|
|
17
17
|
import { EventSettings } from '../events/settings.ts';
|
|
18
|
-
import {
|
|
18
|
+
import {
|
|
19
|
+
AgentFiles,
|
|
20
|
+
AgentsBlockPlan,
|
|
21
|
+
LocalPlan,
|
|
22
|
+
SyncPlanner,
|
|
23
|
+
SyncStatuses,
|
|
24
|
+
} from '../sync/index.ts';
|
|
19
25
|
import { BrowserSocket, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
|
|
20
26
|
import { CLAUDE_LAUNCH_FILE } from '../sync/claude-launch.ts';
|
|
21
27
|
import { PrivateValues } from './private-values.ts';
|
|
22
28
|
import { ReplySwitch, OwnerConstants, OwnerReplySwitch, OwnerProfile } from '../owner/index.ts';
|
|
23
29
|
import { SkillCatalog } from '@venizia/vulcan-atlas';
|
|
24
30
|
import { HookConstants, ProjectTmp } from '../hooks/index.ts';
|
|
25
|
-
import { DoctorChecks, DoctorConstants } from './common/index.ts';
|
|
31
|
+
import { DoctorChecks, DoctorConstants, PrivateValueKinds } from './common/index.ts';
|
|
26
32
|
import type { IViolation, TDoctorCheck } from './common/index.ts';
|
|
27
33
|
import { Makefile } from './makefile.ts';
|
|
28
34
|
|
|
@@ -190,19 +196,24 @@ export class ProjectContract {
|
|
|
190
196
|
* rules points at a base rule - one the base does not carry dangles.
|
|
191
197
|
*/
|
|
192
198
|
static checkRuleIds(opts: ICheckContext): IViolation[] {
|
|
193
|
-
const base = BaseRules.read();
|
|
199
|
+
const base = BaseRules.read({ packs: opts.config.packs });
|
|
194
200
|
|
|
195
201
|
return RuleParser.parseBaseReferences({
|
|
196
202
|
markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
|
|
197
203
|
})
|
|
198
204
|
.filter((id) => base[id] === undefined)
|
|
199
|
-
.map((id) =>
|
|
200
|
-
|
|
205
|
+
.map((id) => {
|
|
206
|
+
const pack = RulePacks.holderOf({ id });
|
|
207
|
+
|
|
208
|
+
return createViolation({
|
|
201
209
|
check: DoctorChecks.RULE_IDS,
|
|
202
210
|
file: '.agents/rules.md',
|
|
203
|
-
message:
|
|
204
|
-
|
|
205
|
-
|
|
211
|
+
message:
|
|
212
|
+
pack === undefined
|
|
213
|
+
? `${id} is not a base rule - give the extension a bare ID`
|
|
214
|
+
: `${id} is in the ${pack} pack - add '${pack}' to packs in the config`,
|
|
215
|
+
});
|
|
216
|
+
});
|
|
206
217
|
}
|
|
207
218
|
|
|
208
219
|
static checkRuleSlots(opts: ICheckContext): IViolation[] {
|
|
@@ -896,9 +907,9 @@ export class ProjectContract {
|
|
|
896
907
|
return warnings;
|
|
897
908
|
}
|
|
898
909
|
|
|
899
|
-
/** Info only: the Atlas block of AGENTS.md is missing or no longer matches the config. */
|
|
910
|
+
/** Info only: the Atlas or rules block of AGENTS.md is missing or no longer matches the config. */
|
|
900
911
|
static checkAtlasBlock(opts: ICheckContext): IViolation[] {
|
|
901
|
-
const merged =
|
|
912
|
+
const merged = AgentsBlockPlan.merged({ root: opts.root, config: opts.config });
|
|
902
913
|
|
|
903
914
|
return merged === undefined || !merged.changed
|
|
904
915
|
? []
|
|
@@ -906,7 +917,7 @@ export class ProjectContract {
|
|
|
906
917
|
createViolation({
|
|
907
918
|
check: DoctorChecks.AGENTS,
|
|
908
919
|
file: 'AGENTS.md',
|
|
909
|
-
message: `the Atlas block is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
|
|
920
|
+
message: `the Atlas or rules block of AGENTS.md is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
|
|
910
921
|
}),
|
|
911
922
|
];
|
|
912
923
|
}
|
|
@@ -987,38 +998,66 @@ export class ProjectContract {
|
|
|
987
998
|
}
|
|
988
999
|
|
|
989
1000
|
/**
|
|
990
|
-
*
|
|
991
|
-
*
|
|
1001
|
+
* What is directly under `.agents/local/` and is not a folder of the layout, a file VULCAN writes, or a browser's
|
|
1002
|
+
* scratch folder, in one warning: how many, how big, and their names. Nothing removes them.
|
|
992
1003
|
*/
|
|
993
1004
|
static checkUnknownLocal(opts: ICheckContext): IViolation[] {
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1005
|
+
const unknown = LocalScan.unknown({ root: opts.root });
|
|
1006
|
+
|
|
1007
|
+
return unknown.length === 0
|
|
1008
|
+
? []
|
|
1009
|
+
: [
|
|
1010
|
+
createViolation({
|
|
1011
|
+
check: DoctorChecks.LOCAL,
|
|
1012
|
+
file: ProjectLayout.LOCAL_DIRECTORY,
|
|
1013
|
+
message: `${unknown.length} ${unknown.length === 1 ? 'entry is' : 'entries are'} not ${unknown.length === 1 ? 'one' : 'ones'} VULCAN knows: ${unknown
|
|
1014
|
+
.slice(0, 10)
|
|
1015
|
+
.map((entry) => `${entry.name} (${LocalFormat.formatBytes({ bytes: entry.bytes })})`)
|
|
1016
|
+
.join(
|
|
1017
|
+
', ',
|
|
1018
|
+
)}${unknown.length > 10 ? `, and ${unknown.length - 10} more` : ''}; put scratch in tmp/ and what you want to keep in reports/, what one agent keeps for itself in agents/<name>/; a script the team relies on belongs in the tracked tree (scripts/), where it gets review and history; nothing removes ${unknown.length === 1 ? 'it' : 'them'}`,
|
|
1019
|
+
}),
|
|
1020
|
+
];
|
|
1001
1021
|
}
|
|
1002
1022
|
|
|
1003
|
-
/**
|
|
1023
|
+
/**
|
|
1024
|
+
* What an agent left under `.agents/local/` that has outlived its use, in one warning: how many in each scope, how
|
|
1025
|
+
* big, and the command that clears them (which, without `--yes`, lists each one).
|
|
1026
|
+
*/
|
|
1004
1027
|
static checkStaleLocal(opts: ICheckContext): IViolation[] {
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1028
|
+
const stale = LocalScan.scan({ root: opts.root }).filter((entry) =>
|
|
1029
|
+
[
|
|
1030
|
+
LocalStates.STALE,
|
|
1031
|
+
LocalStates.MERGED,
|
|
1032
|
+
LocalStates.GONE,
|
|
1033
|
+
LocalStates.ORPHAN,
|
|
1034
|
+
LocalStates.SHIPPED,
|
|
1035
|
+
].includes(entry.state),
|
|
1036
|
+
);
|
|
1037
|
+
|
|
1038
|
+
if (stale.length === 0) {
|
|
1039
|
+
return [];
|
|
1040
|
+
}
|
|
1041
|
+
|
|
1042
|
+
const scopes = [...new Set(stale.map((entry) => entry.scope))];
|
|
1043
|
+
const counts = new Map<string, number>();
|
|
1044
|
+
|
|
1045
|
+
for (const entry of stale) {
|
|
1046
|
+
const group = `${entry.state} in ${entry.scope}`;
|
|
1047
|
+
|
|
1048
|
+
counts.set(group, (counts.get(group) ?? 0) + 1);
|
|
1049
|
+
}
|
|
1050
|
+
|
|
1051
|
+
const groups = [...counts.entries()];
|
|
1052
|
+
const bytes = stale.reduce((total, entry) => total + entry.bytes, 0);
|
|
1053
|
+
|
|
1054
|
+
return [
|
|
1055
|
+
createViolation({
|
|
1056
|
+
check: DoctorChecks.LOCAL,
|
|
1057
|
+
file: ProjectLayout.LOCAL_DIRECTORY,
|
|
1058
|
+
message: `${stale.length} ${stale.length === 1 ? 'entry has' : 'entries have'} outlived ${stale.length === 1 ? 'its' : 'their'} use (${LocalFormat.formatBytes({ bytes })}): ${groups.map(([group, count]) => `${count} ${group}`).join(', ')}; run: vulcan clean ${scopes.map((scope) => `--${scope}`).join(' ')} --yes (without --yes it lists each one)`,
|
|
1059
|
+
}),
|
|
1060
|
+
];
|
|
1022
1061
|
}
|
|
1023
1062
|
|
|
1024
1063
|
/** The owner cards are off for this shell (`VULCAN_OWNER_REPLY=off`): a session an agent starts sets it, an owner who exported it by mistake sees why the rules carry no shape card; a note, never a failure. */
|
|
@@ -1152,24 +1191,46 @@ export class ProjectContract {
|
|
|
1152
1191
|
});
|
|
1153
1192
|
}
|
|
1154
1193
|
|
|
1155
|
-
/**
|
|
1194
|
+
/**
|
|
1195
|
+
* Private values in committed files, never the text: one warning per file that holds a key, a token or a URL
|
|
1196
|
+
* credential, with the kinds and counts; the files that hold only addresses or machine paths (an example IP in a
|
|
1197
|
+
* policy file, a path in a doc) in one warning; and one per acknowledgment that covered nothing.
|
|
1198
|
+
*/
|
|
1156
1199
|
static checkPrivateValues(opts: ICheckContext): IViolation[] {
|
|
1157
1200
|
const { findings, unmatched } = PrivateValues.scan({
|
|
1158
1201
|
root: opts.root,
|
|
1159
1202
|
acknowledged: opts.config.doctor.privateValues.acknowledged,
|
|
1160
1203
|
});
|
|
1161
1204
|
const where = 'doctor.privateValues.acknowledged';
|
|
1205
|
+
const kindsOf = (counts: Record<string, number | undefined>): string =>
|
|
1206
|
+
Object.entries(counts)
|
|
1207
|
+
.map(([kind, count]) => `${count} ${kind}`)
|
|
1208
|
+
.join(', ');
|
|
1209
|
+
const isMild = (finding: { counts: Record<string, number | undefined> }): boolean =>
|
|
1210
|
+
Object.keys(finding.counts).every((kind) =>
|
|
1211
|
+
[PrivateValueKinds.IPV4, PrivateValueKinds.MACHINE_PATH].includes(kind),
|
|
1212
|
+
);
|
|
1213
|
+
const mild = findings.filter((finding) => isMild(finding));
|
|
1162
1214
|
|
|
1163
1215
|
return [
|
|
1164
|
-
...findings
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
.
|
|
1170
|
-
.
|
|
1171
|
-
|
|
1172
|
-
|
|
1216
|
+
...findings
|
|
1217
|
+
.filter((finding) => !isMild(finding))
|
|
1218
|
+
.map((finding) =>
|
|
1219
|
+
createViolation({
|
|
1220
|
+
check: DoctorChecks.PRIVATE_VALUES,
|
|
1221
|
+
file: finding.file,
|
|
1222
|
+
message: `holds private values: ${kindsOf(finding.counts)} (not shown); remove them, or record the decision in ${where}`,
|
|
1223
|
+
}),
|
|
1224
|
+
),
|
|
1225
|
+
...(mild.length === 0
|
|
1226
|
+
? []
|
|
1227
|
+
: [
|
|
1228
|
+
createViolation({
|
|
1229
|
+
check: DoctorChecks.PRIVATE_VALUES,
|
|
1230
|
+
file: mild.length === 1 ? mild[0].file : `${mild.length} files`,
|
|
1231
|
+
message: `${mild.length === 1 ? 'holds' : `${mild.length} files hold`} only addresses or machine paths: ${mild.map((finding) => `${finding.file} (${kindsOf(finding.counts)})`).join(', ')} (not shown); remove them, or record the decision in ${where}`,
|
|
1232
|
+
}),
|
|
1233
|
+
]),
|
|
1173
1234
|
...unmatched.map((entry) =>
|
|
1174
1235
|
createViolation({
|
|
1175
1236
|
check: DoctorChecks.PRIVATE_VALUES,
|
|
@@ -35,8 +35,6 @@ export class DoctorChecks {
|
|
|
35
35
|
static readonly LOCAL = 'local';
|
|
36
36
|
/** The personal profile file: unreadable, not gitignored or tracked by git; a warning. */
|
|
37
37
|
static readonly PROFILE = 'profile';
|
|
38
|
-
/** Guard config: a trusted script is a note; a stale one is a warning. */
|
|
39
|
-
static readonly GUARDS = 'guards';
|
|
40
38
|
/** The clone commit-msg hook when a commit check is on: missing, stale or not calling commit-check; a warning. */
|
|
41
39
|
static readonly COMMIT_HOOK = 'commit-hook';
|
|
42
40
|
/** The events.dir folder when outside the project: missing, not a folder or not writable; a warning. */
|
|
@@ -3,6 +3,7 @@ import { EventActorNames } from './actor-names.ts';
|
|
|
3
3
|
/** What happened. A board reads these; add one only when a reader needs to tell it apart. */
|
|
4
4
|
export class EventKinds {
|
|
5
5
|
static readonly SESSION_START = 'session-start';
|
|
6
|
+
/** No longer written (a turn that ends is not an event); read so a log written before still folds until its retention removes it. */
|
|
6
7
|
static readonly SESSION_STOP = 'session-stop';
|
|
7
8
|
static readonly MSG_SENT = 'msg-sent';
|
|
8
9
|
static readonly MSG_RECEIVED = 'msg-received';
|
|
@@ -16,7 +17,7 @@ export class EventKinds {
|
|
|
16
17
|
static readonly FLOW = 'flow';
|
|
17
18
|
/** Something was put live; a milestone of its flow, like a merge. Its summary says what. */
|
|
18
19
|
static readonly DEPLOY = 'deploy';
|
|
19
|
-
/**
|
|
20
|
+
/** No longer written (a tool that is used is not an event); read so a log written before still folds until its retention removes it. */
|
|
20
21
|
static readonly TOOL_TICK = 'tool-tick';
|
|
21
22
|
|
|
22
23
|
static readonly SCHEME_SET = new Set<string>([
|
|
@@ -112,7 +113,6 @@ export class EventFlags {
|
|
|
112
113
|
/** The names a Claude Code hook payload carries, as Claude Code 2.1.317 sends them. */
|
|
113
114
|
export class ClaudeHookEvents {
|
|
114
115
|
static readonly SESSION_START = 'SessionStart';
|
|
115
|
-
static readonly STOP = 'Stop';
|
|
116
116
|
static readonly SUBAGENT_STOP = 'SubagentStop';
|
|
117
117
|
static readonly NOTIFICATION = 'Notification';
|
|
118
118
|
static readonly POST_TOOL_USE = 'PostToolUse';
|
|
@@ -152,16 +152,6 @@ export class EventConstants {
|
|
|
152
152
|
static readonly CONTEXT_MAX = 600;
|
|
153
153
|
/** What a sent message is called when its sender gave no label: the text of a message is never used. */
|
|
154
154
|
static readonly MESSAGE_SENT_LABEL = 'message sent';
|
|
155
|
-
/** The summary of a tool tick: it says that a tool was used, and nothing of which. */
|
|
156
|
-
static readonly TOOL_TICK_LABEL = 'using a tool';
|
|
157
|
-
/** A session writes at most one tool tick in each window of this many seconds. */
|
|
158
|
-
static readonly TICK_SECONDS = 30;
|
|
159
|
-
/**
|
|
160
|
-
* The folder, from the project root, that holds one empty stamp per session and window, `<session>.<window>`; a tick
|
|
161
|
-
* removes the stamps of earlier windows. Spelt out because the hook imports no other module of the package (a test holds it
|
|
162
|
-
* inside `ProjectLayout.LOCAL_DIRECTORY/tmp`).
|
|
163
|
-
*/
|
|
164
|
-
static readonly TICK_FOLDER = '.agents/local/tmp/event-ticks';
|
|
165
155
|
static readonly REF_MAX = 120;
|
|
166
156
|
/** A flow line's lists: how many items, and how long one is. */
|
|
167
157
|
static readonly ITEM_COUNT_MAX = 30;
|
package/src/events/hook.ts
CHANGED
|
@@ -1,5 +1,3 @@
|
|
|
1
|
-
import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
|
|
2
|
-
import { join } from 'node:path';
|
|
3
1
|
import { RecordValue } from '../common/record.ts';
|
|
4
2
|
import { ClaudeHookEvents, EventConstants, EventKinds, EventSources } from './common/index.ts';
|
|
5
3
|
import type { IEvent, IHookEvent } from './common/index.ts';
|
|
@@ -16,10 +14,10 @@ const text = (opts: { value: unknown }): string =>
|
|
|
16
14
|
export class EventHook {
|
|
17
15
|
/**
|
|
18
16
|
* The event a payload stands for, or `undefined` when the payload is not one to log. Only these fields are
|
|
19
|
-
* read: `source` and `model` of a session start, `
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
* `last_assistant_message`,
|
|
17
|
+
* read: `source` and `model` of a session start, `agent_type` and `agent_id` of a subagent stop,
|
|
18
|
+
* `notification_type` and `title` of a notification, and `to` and `summary` of a SendMessage call (the label the
|
|
19
|
+
* sender gave it, or a fixed one). A turn that ends and a tool that is used are not events.
|
|
20
|
+
* `last_assistant_message`, the text of a message, `tool_response`, `tool_input` and every command stay unread.
|
|
23
21
|
*/
|
|
24
22
|
static map(opts: { input: unknown }): IHookEvent | undefined {
|
|
25
23
|
const { input } = opts;
|
|
@@ -39,12 +37,6 @@ export class EventHook {
|
|
|
39
37
|
};
|
|
40
38
|
}
|
|
41
39
|
|
|
42
|
-
case ClaudeHookEvents.STOP: {
|
|
43
|
-
return input.stop_hook_active === true
|
|
44
|
-
? undefined
|
|
45
|
-
: { kind: EventKinds.SESSION_STOP, summary: 'turn ended' };
|
|
46
|
-
}
|
|
47
|
-
|
|
48
40
|
case ClaudeHookEvents.SUBAGENT_STOP: {
|
|
49
41
|
return {
|
|
50
42
|
kind: EventKinds.SUBAGENT_STOP,
|
|
@@ -67,9 +59,7 @@ export class EventHook {
|
|
|
67
59
|
}
|
|
68
60
|
|
|
69
61
|
case ClaudeHookEvents.POST_TOOL_USE: {
|
|
70
|
-
return
|
|
71
|
-
? EventHook.mapSend({ input })
|
|
72
|
-
: { kind: EventKinds.TOOL_TICK, summary: EventConstants.TOOL_TICK_LABEL };
|
|
62
|
+
return EventHook.mapSend({ input });
|
|
73
63
|
}
|
|
74
64
|
|
|
75
65
|
default: {
|
|
@@ -125,36 +115,6 @@ export class EventHook {
|
|
|
125
115
|
};
|
|
126
116
|
}
|
|
127
117
|
|
|
128
|
-
/**
|
|
129
|
-
* Whether this session may write a tick now: the first call of each window creates the window's stamp and wins; a
|
|
130
|
-
* call that finds the stamp already there loses. `wx` makes that one step, so calls at the same instant cannot both win.
|
|
131
|
-
*/
|
|
132
|
-
private static takeTick(opts: { root: string; session: string; now: number }): boolean {
|
|
133
|
-
const folder = join(opts.root, EventConstants.TICK_FOLDER);
|
|
134
|
-
const window = Math.floor(opts.now / (EventConstants.TICK_SECONDS * 1000));
|
|
135
|
-
const stamp = join(folder, `${opts.session.replace(/[^\w-]/g, '_') || 'session'}.${window}`);
|
|
136
|
-
|
|
137
|
-
mkdirSync(folder, { recursive: true });
|
|
138
|
-
|
|
139
|
-
try {
|
|
140
|
-
writeFileSync(stamp, '', { flag: 'wx' });
|
|
141
|
-
} catch (error) {
|
|
142
|
-
if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
|
|
143
|
-
return false;
|
|
144
|
-
}
|
|
145
|
-
|
|
146
|
-
throw error;
|
|
147
|
-
}
|
|
148
|
-
|
|
149
|
-
for (const name of readdirSync(folder)) {
|
|
150
|
-
if (Number(name.slice(name.lastIndexOf('.') + 1)) < window) {
|
|
151
|
-
rmSync(join(folder, name), { force: true });
|
|
152
|
-
}
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
return true;
|
|
156
|
-
}
|
|
157
|
-
|
|
158
118
|
/**
|
|
159
119
|
* Logs what a payload stands for, when the manifest says the log is on. Returns the line it wrote.
|
|
160
120
|
* `root` is the project, where the manifest is; the flow comes from the message, else the branch at the
|
|
@@ -178,17 +138,6 @@ export class EventHook {
|
|
|
178
138
|
return undefined;
|
|
179
139
|
}
|
|
180
140
|
|
|
181
|
-
if (
|
|
182
|
-
mapped.kind === EventKinds.TOOL_TICK &&
|
|
183
|
-
!EventHook.takeTick({
|
|
184
|
-
root: opts.root,
|
|
185
|
-
session: text({ value: opts.input.session_id }),
|
|
186
|
-
now: opts.now ?? Date.now(),
|
|
187
|
-
})
|
|
188
|
-
) {
|
|
189
|
-
return undefined;
|
|
190
|
-
}
|
|
191
|
-
|
|
192
141
|
const cwd = text({ value: opts.input.cwd }) || opts.root;
|
|
193
142
|
const flowId =
|
|
194
143
|
(mapped.flowText === undefined ? undefined : EventFlow.fromText({ text: mapped.flowText })) ??
|
|
@@ -40,7 +40,7 @@ const GH_REQUESTS = new Set(['api', 'secret', 'variable']);
|
|
|
40
40
|
const GH_REPOSITORY_FLAGS = new Set(['-R', '--repo']);
|
|
41
41
|
|
|
42
42
|
/** `find` runs a command only with these; without them it only lists. */
|
|
43
|
-
const FIND_RUNS = new Set([
|
|
43
|
+
const FIND_RUNS = new Set([...ShellPrograms.FIND_RUN_OPTIONS, '-delete']);
|
|
44
44
|
|
|
45
45
|
/** Programs that read their heredoc as a query or a script: the body is part of what they run. */
|
|
46
46
|
const HEREDOC_READERS = new Set([
|
|
@@ -48,4 +48,6 @@ export interface IOutsideHit {
|
|
|
48
48
|
message: string;
|
|
49
49
|
/** Whether the path is under the scratchpad folder an agent tool offers: the hook denies it, it does not ask. */
|
|
50
50
|
isAgentToolScratchpad: boolean;
|
|
51
|
+
/** Whether the check could not read the line or the target, so it does not know that anything is outside: the hook asks, even where the project denies. */
|
|
52
|
+
isUnread: boolean;
|
|
51
53
|
}
|
package/src/hooks/guard-git.ts
CHANGED
|
@@ -289,6 +289,45 @@ const ghCall = (opts: { args: string[] }): { group: string; action: string; rest
|
|
|
289
289
|
return { group: names[0] ?? '', action: names[1] ?? '', rest: opts.args.slice(index) };
|
|
290
290
|
};
|
|
291
291
|
|
|
292
|
+
const REF_ENDPOINT = /^repos\/[^/]+\/[^/]+\/git\/refs\/heads\/(.+)$/;
|
|
293
|
+
|
|
294
|
+
/** The path `gh api` calls for a word: without the host, a `?query`, the slashes at its ends, decoded once. */
|
|
295
|
+
const endpointOf = (opts: { word: string }): string => {
|
|
296
|
+
const path = opts.word
|
|
297
|
+
.replace(/^https?:\/\/api\.github\.com/i, '')
|
|
298
|
+
.replace(/[?#].*$/s, '')
|
|
299
|
+
.replace(/^\/+|\/+$/g, '');
|
|
300
|
+
|
|
301
|
+
try {
|
|
302
|
+
return decodeURIComponent(path);
|
|
303
|
+
} catch {
|
|
304
|
+
return path;
|
|
305
|
+
}
|
|
306
|
+
};
|
|
307
|
+
|
|
308
|
+
/** `gh api -X DELETE repos/<owner>/<repo>/git/refs/heads/<branch>` deletes the branch as `git push --delete` does. */
|
|
309
|
+
const inspectGhApi = (opts: { args: string[] }): IGitHit[] => {
|
|
310
|
+
const { args } = opts;
|
|
311
|
+
const isDelete = args.some(
|
|
312
|
+
(word, index) =>
|
|
313
|
+
/^(-X|--method)=?DELETE$/i.test(word) ||
|
|
314
|
+
(/^(-X|--method)$/.test(word) && (args[index + 1] ?? '').toUpperCase() === 'DELETE'),
|
|
315
|
+
);
|
|
316
|
+
|
|
317
|
+
if (ghCall({ args }).group !== 'api' || !isDelete) {
|
|
318
|
+
return [];
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
return args
|
|
322
|
+
.map((word) => REF_ENDPOINT.exec(endpointOf({ word }))?.[1])
|
|
323
|
+
.filter((name): name is string => name !== undefined && isProtected({ name }))
|
|
324
|
+
.map((name) => ({
|
|
325
|
+
decision: GuardDecisions.DENY,
|
|
326
|
+
rule: 'V-W-06',
|
|
327
|
+
message: `deleting the remote branch '${name}'`,
|
|
328
|
+
}));
|
|
329
|
+
};
|
|
330
|
+
|
|
292
331
|
/** `gh pr merge [<pr>] --delete-branch`: the PR's head branch decides, and `gh` is asked for it. */
|
|
293
332
|
const inspectGhMerge = (opts: {
|
|
294
333
|
args: string[];
|
|
@@ -385,6 +424,7 @@ const inspectOne = (opts: {
|
|
|
385
424
|
return [
|
|
386
425
|
...inspectGhMerge({ args: program.args, cwd: opts.cwd, run: opts.run }),
|
|
387
426
|
...inspectGhCreate({ args: program.args }),
|
|
427
|
+
...inspectGhApi({ args: program.args }),
|
|
388
428
|
];
|
|
389
429
|
}
|
|
390
430
|
|
|
@@ -163,6 +163,7 @@ export class OutsideGuard {
|
|
|
163
163
|
}
|
|
164
164
|
|
|
165
165
|
let unread: string | undefined;
|
|
166
|
+
let assigned = new Set<string>();
|
|
166
167
|
|
|
167
168
|
if (opts.input.command !== undefined) {
|
|
168
169
|
const parsed = ShellParser.parseChecked({ command: opts.input.command });
|
|
@@ -175,6 +176,7 @@ export class OutsideGuard {
|
|
|
175
176
|
});
|
|
176
177
|
|
|
177
178
|
unread = ShellUnread.reasonOf(parsed);
|
|
179
|
+
assigned = ShellFolders.assignedNames({ commands: parsed.commands });
|
|
178
180
|
|
|
179
181
|
// A command's own redirects open in the folder it starts in, a `cd`'s included.
|
|
180
182
|
for (const [index, command] of parsed.commands.entries()) {
|
|
@@ -188,6 +190,8 @@ export class OutsideGuard {
|
|
|
188
190
|
...ShellWrites.targetsOf({ command, base: folder.base, tmp }).map((target) => ({
|
|
189
191
|
...target,
|
|
190
192
|
pwd: folder.pwd,
|
|
193
|
+
vars: folder.vars,
|
|
194
|
+
isKnown: folder.isKnown,
|
|
191
195
|
})),
|
|
192
196
|
);
|
|
193
197
|
}
|
|
@@ -197,18 +201,61 @@ export class OutsideGuard {
|
|
|
197
201
|
const hits: IOutsideHit[] =
|
|
198
202
|
unread === undefined
|
|
199
203
|
? []
|
|
200
|
-
: [
|
|
204
|
+
: [
|
|
205
|
+
{
|
|
206
|
+
path: '(the command line)',
|
|
207
|
+
message: unread,
|
|
208
|
+
isAgentToolScratchpad: false,
|
|
209
|
+
isUnread: true,
|
|
210
|
+
},
|
|
211
|
+
];
|
|
201
212
|
|
|
202
213
|
for (const target of targets) {
|
|
203
|
-
const expanded = ShellFolders.expandPath({
|
|
214
|
+
const expanded = ShellFolders.expandPath({
|
|
215
|
+
word: target.word,
|
|
216
|
+
home,
|
|
217
|
+
env: { ...env, ...target.vars },
|
|
218
|
+
cwd: target.pwd,
|
|
219
|
+
});
|
|
204
220
|
|
|
205
221
|
if (expanded === undefined) {
|
|
222
|
+
// Part of the word is unknown, but the folder in front of it may not be: that folder decides.
|
|
223
|
+
const lands = ShellFolders.folderOfUnknown({
|
|
224
|
+
word: target.word,
|
|
225
|
+
home,
|
|
226
|
+
env: { ...env, ...target.vars },
|
|
227
|
+
cwd: target.pwd,
|
|
228
|
+
base: target.base,
|
|
229
|
+
isKnown: target.isKnown ?? true,
|
|
230
|
+
assigned,
|
|
231
|
+
});
|
|
232
|
+
const folder = lands === undefined ? undefined : realOf({ path: lands });
|
|
233
|
+
|
|
234
|
+
if (
|
|
235
|
+
folder !== undefined &&
|
|
236
|
+
!isInside({ path: folder, root }) &&
|
|
237
|
+
!matchesAny({ path: `${folder}/x`, patterns })
|
|
238
|
+
) {
|
|
239
|
+
hits.push({
|
|
240
|
+
path: folder,
|
|
241
|
+
message: `${target.message}: it lands in ${folder}, outside the project, whatever the expansion is`,
|
|
242
|
+
isAgentToolScratchpad: matchesAny({
|
|
243
|
+
path: folder,
|
|
244
|
+
patterns: HookConstants.AGENT_TOOL_SCRATCHPAD_PATTERNS,
|
|
245
|
+
}),
|
|
246
|
+
isUnread: false,
|
|
247
|
+
});
|
|
248
|
+
|
|
249
|
+
continue;
|
|
250
|
+
}
|
|
251
|
+
|
|
206
252
|
// A redirect to a word that cannot be worked out (`> $f`, `&>$fd`, `>&$fd`) may write a file outside the project.
|
|
207
253
|
if (target.isAmbiguous === true || target.isRedirect === true) {
|
|
208
254
|
hits.push({
|
|
209
255
|
path: target.word,
|
|
210
256
|
message: `${target.message}: the target has an expansion this check cannot work out`,
|
|
211
257
|
isAgentToolScratchpad: false,
|
|
258
|
+
isUnread: true,
|
|
212
259
|
});
|
|
213
260
|
}
|
|
214
261
|
|
|
@@ -223,6 +270,7 @@ export class OutsideGuard {
|
|
|
223
270
|
path: written,
|
|
224
271
|
message: `${target.message}: a path under /proc or /dev/fd names a process, which this check cannot follow`,
|
|
225
272
|
isAgentToolScratchpad: false,
|
|
273
|
+
isUnread: true,
|
|
226
274
|
});
|
|
227
275
|
|
|
228
276
|
continue;
|
|
@@ -236,6 +284,7 @@ export class OutsideGuard {
|
|
|
236
284
|
path: written,
|
|
237
285
|
message: `${target.message}: the path goes through more links than the system follows`,
|
|
238
286
|
isAgentToolScratchpad: false,
|
|
287
|
+
isUnread: true,
|
|
239
288
|
});
|
|
240
289
|
|
|
241
290
|
continue;
|
|
@@ -249,6 +298,7 @@ export class OutsideGuard {
|
|
|
249
298
|
path,
|
|
250
299
|
patterns: HookConstants.AGENT_TOOL_SCRATCHPAD_PATTERNS,
|
|
251
300
|
}),
|
|
301
|
+
isUnread: false,
|
|
252
302
|
});
|
|
253
303
|
}
|
|
254
304
|
}
|