@venizia/vulcan 0.4.8 → 0.4.9-1

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 (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -38,34 +38,36 @@ const asserts = (opts: { text: string; words: string[] }): boolean =>
38
38
  (sentence) => !isDenied({ sentence }) && opts.words.some((word) => hasWord({ sentence, word })),
39
39
  );
40
40
 
41
- /**
42
- * What the reply claims against what the turn's calls show. A claim that something is published, released
43
- * or live needs a public-state probe in the turn; a claim that the checks pass is contradicted while a gate
44
- * of the turn still failed on its latest run. Phrases match whole words in a sentence that does not deny,
45
- * ask or quote; English plus any the project adds. Logged, never blocked: a match is a hint, not proof.
46
- */
47
- export const checkClaims = (opts: {
48
- text: string;
49
- state: ISignalState;
50
- publicWords?: string[];
51
- doneWords?: string[];
52
- }): string[] => {
53
- const classes: string[] = [];
54
- const { state } = opts;
41
+ export class ReplyClaims {
42
+ /**
43
+ * What the reply claims against what the turn's calls show. A claim that something is published, released
44
+ * or live needs a public-state probe in the turn; a claim that the checks pass is contradicted while a gate
45
+ * of the turn still failed on its latest run. Phrases match whole words in a sentence that does not deny,
46
+ * ask or quote; English plus any the project adds. Logged, never blocked: a match is a hint, not proof.
47
+ */
48
+ static check(opts: {
49
+ text: string;
50
+ state: ISignalState;
51
+ publicWords?: string[];
52
+ doneWords?: string[];
53
+ }): string[] {
54
+ const classes: string[] = [];
55
+ const { state } = opts;
55
56
 
56
- if (
57
- asserts({ text: opts.text, words: [...ClaimWords.PUBLIC, ...(opts.publicWords ?? [])] }) &&
58
- state.probeAt < state.turnAt
59
- ) {
60
- classes.push(ClaimClasses.PUBLIC_CLAIM_NO_PROBE);
61
- }
57
+ if (
58
+ asserts({ text: opts.text, words: [...ClaimWords.PUBLIC, ...(opts.publicWords ?? [])] }) &&
59
+ state.probeAt < state.turnAt
60
+ ) {
61
+ classes.push(ClaimClasses.PUBLIC_CLAIM_NO_PROBE);
62
+ }
62
63
 
63
- if (
64
- asserts({ text: opts.text, words: [...ClaimWords.DONE, ...(opts.doneWords ?? [])] }) &&
65
- state.failedGates.length > 0
66
- ) {
67
- classes.push(ClaimClasses.CONTRADICTED_COMPLETION);
68
- }
64
+ if (
65
+ asserts({ text: opts.text, words: [...ClaimWords.DONE, ...(opts.doneWords ?? [])] }) &&
66
+ state.failedGates.length > 0
67
+ ) {
68
+ classes.push(ClaimClasses.CONTRADICTED_COMPLETION);
69
+ }
69
70
 
70
- return classes;
71
- };
71
+ return classes;
72
+ }
73
+ }
@@ -1,5 +1,5 @@
1
1
  import { createHash } from 'node:crypto';
2
- import { parseShell, programOf } from '../hooks/shell.ts';
2
+ import { ShellParser } from '../hooks/shell.ts';
3
3
  import { SignalConstants, WatchedKinds } from './constants.ts';
4
4
 
5
5
  const LOCAL_URL = /^https?:\/\/(?:localhost|127\.|0\.0\.0\.0|\[::1\])/;
@@ -15,8 +15,8 @@ const SCRATCH = /(?:^|\/)\.agents\/local\//;
15
15
  /** The simple commands of a line as program and arguments; a line that cannot be parsed has none. */
16
16
  const programsOf = (opts: { command: string }): { name: string; args: string[] }[] => {
17
17
  try {
18
- return parseShell({ command: opts.command }).map((simple) => {
19
- const { name, args } = programOf({ command: simple });
18
+ return ShellParser.parse({ command: opts.command }).map((simple) => {
19
+ const { name, args } = ShellParser.programOf({ command: simple });
20
20
 
21
21
  return { name, args };
22
22
  });
@@ -25,13 +25,6 @@ const programsOf = (opts: { command: string }): { name: string; args: string[] }
25
25
  }
26
26
  };
27
27
 
28
- /** The tool input as a short stable key: the same call twice has the same key. */
29
- export const callKeyOf = (opts: { tool: string; input: unknown }): string =>
30
- `${opts.tool}:${createHash('sha1')
31
- .update(JSON.stringify(opts.input ?? null))
32
- .digest('hex')
33
- .slice(0, SignalConstants.EVENT_KEY_LENGTH)}`;
34
-
35
28
  const isProbeProgram = (opts: { name: string; args: string[] }): boolean => {
36
29
  const { name, args } = opts;
37
30
 
@@ -64,10 +57,6 @@ const isProbeProgram = (opts: { name: string; args: string[] }): boolean => {
64
57
  return false;
65
58
  };
66
59
 
67
- /** A command that asks public state: the registry, the forge, a remote, an outside URL; not a write. */
68
- export const isPublicProbe = (opts: { command: string }): boolean =>
69
- programsOf({ command: opts.command }).some((program) => isProbeProgram(program));
70
-
71
60
  const isGateProgram = (opts: { name: string; args: string[] }): boolean => {
72
61
  const { name, args } = opts;
73
62
  const first = args.find((arg) => !arg.startsWith('-')) ?? '';
@@ -106,27 +95,41 @@ const isGateProgram = (opts: { name: string; args: string[] }): boolean => {
106
95
  return GATE_TOOLS.has(name);
107
96
  };
108
97
 
109
- /** The gates a command line runs (tests, lint, build, the project's own gates), each as a short name. */
110
- export const gatesOf = (opts: { command: string }): string[] =>
111
- programsOf({ command: opts.command })
112
- .filter((program) => isGateProgram(program))
113
- .map((program) =>
114
- [program.name, ...program.args].join(' ').slice(0, SignalConstants.GATE_KEY_LENGTH),
115
- );
116
-
117
- /** What an edited file is for the nudge: a skill (with its name), a rules file, or neither. */
118
- export const watchedFileOf = (opts: {
119
- path: string;
120
- }): { kind: string; name: string } | undefined => {
121
- if (SCRATCH.test(opts.path)) {
122
- return undefined;
98
+ export class SignalClassifier {
99
+ /** The tool input as a short stable key: the same call twice has the same key. */
100
+ static callKeyOf(opts: { tool: string; input: unknown }): string {
101
+ return `${opts.tool}:${createHash('sha1')
102
+ .update(JSON.stringify(opts.input ?? null))
103
+ .digest('hex')
104
+ .slice(0, SignalConstants.EVENT_KEY_LENGTH)}`;
123
105
  }
124
106
 
125
- const skill = SKILL_FILE.exec(opts.path)?.[1];
107
+ /** A command that asks public state: the registry, the forge, a remote, an outside URL; not a write. */
108
+ static isPublicProbe(opts: { command: string }): boolean {
109
+ return programsOf({ command: opts.command }).some((program) => isProbeProgram(program));
110
+ }
126
111
 
127
- if (skill !== undefined) {
128
- return { kind: WatchedKinds.SKILL, name: skill };
112
+ /** The gates a command line runs (tests, lint, build, the project's own gates), each as a short name. */
113
+ static gatesOf(opts: { command: string }): string[] {
114
+ return programsOf({ command: opts.command })
115
+ .filter((program) => isGateProgram(program))
116
+ .map((program) =>
117
+ [program.name, ...program.args].join(' ').slice(0, SignalConstants.GATE_KEY_LENGTH),
118
+ );
129
119
  }
130
120
 
131
- return RULES_FILE.test(opts.path) ? { kind: WatchedKinds.RULES, name: opts.path } : undefined;
132
- };
121
+ /** What an edited file is for the nudge: a skill (with its name), a rules file, or neither. */
122
+ static watchedFileOf(opts: { path: string }): { kind: string; name: string } | undefined {
123
+ if (SCRATCH.test(opts.path)) {
124
+ return undefined;
125
+ }
126
+
127
+ const skill = SKILL_FILE.exec(opts.path)?.[1];
128
+
129
+ if (skill !== undefined) {
130
+ return { kind: WatchedKinds.SKILL, name: skill };
131
+ }
132
+
133
+ return RULES_FILE.test(opts.path) ? { kind: WatchedKinds.RULES, name: opts.path } : undefined;
134
+ }
135
+ }
@@ -1,46 +1,48 @@
1
1
  import { SignalConstants } from './constants.ts';
2
2
  import type { ISignalEvent } from './state.ts';
3
3
 
4
- /**
5
- * What the last calls look like when an agent is going round in circles: the same call three times within
6
- * a minute, two calls alternating for three rounds, or one call failing again and again. `undefined` when nothing looks stuck.
7
- */
8
- export const loopOf = (opts: { events: ISignalEvent[] }): string | undefined => {
9
- const { events } = opts;
10
- const last = events.slice(-SignalConstants.SAME_CALL_LIMIT);
11
- const first = last[0];
12
-
13
- if (
14
- first !== undefined &&
15
- last.length === SignalConstants.SAME_CALL_LIMIT &&
16
- last.every((event) => event.key === first.key) &&
17
- (last.at(-1)?.at ?? 0) - first.at < SignalConstants.POLL_WINDOW_MS
18
- ) {
19
- return `the same ${first.tool} call ${SignalConstants.SAME_CALL_LIMIT} times in a row`;
20
- }
4
+ export class SignalLoop {
5
+ /**
6
+ * What the last calls look like when an agent is going round in circles: the same call three times within
7
+ * a minute, two calls alternating for three rounds, or one call failing again and again. `undefined` when nothing looks stuck.
8
+ */
9
+ static loopOf(opts: { events: ISignalEvent[] }): string | undefined {
10
+ const { events } = opts;
11
+ const last = events.slice(-SignalConstants.SAME_CALL_LIMIT);
12
+ const first = last[0];
13
+
14
+ if (
15
+ first !== undefined &&
16
+ last.length === SignalConstants.SAME_CALL_LIMIT &&
17
+ last.every((event) => event.key === first.key) &&
18
+ (last.at(-1)?.at ?? 0) - first.at < SignalConstants.POLL_WINDOW_MS
19
+ ) {
20
+ return `the same ${first.tool} call ${SignalConstants.SAME_CALL_LIMIT} times in a row`;
21
+ }
21
22
 
22
- const cycle = events.slice(-SignalConstants.ALTERNATION_LENGTH);
23
- const [one, two] = cycle;
24
-
25
- if (
26
- cycle.length === SignalConstants.ALTERNATION_LENGTH &&
27
- one !== undefined &&
28
- two !== undefined &&
29
- one.key !== two.key &&
30
- cycle.every((event, index) => event.key === (index % 2 === 0 ? one.key : two.key))
31
- ) {
32
- return `${one.tool} and ${two.tool} calls alternating without progress`;
33
- }
23
+ const cycle = events.slice(-SignalConstants.ALTERNATION_LENGTH);
24
+ const [one, two] = cycle;
25
+
26
+ if (
27
+ cycle.length === SignalConstants.ALTERNATION_LENGTH &&
28
+ one !== undefined &&
29
+ two !== undefined &&
30
+ one.key !== two.key &&
31
+ cycle.every((event, index) => event.key === (index % 2 === 0 ? one.key : two.key))
32
+ ) {
33
+ return `${one.tool} and ${two.tool} calls alternating without progress`;
34
+ }
34
35
 
35
- const recent = events.slice(-SignalConstants.FAILURE_WINDOW);
36
+ const recent = events.slice(-SignalConstants.FAILURE_WINDOW);
36
37
 
37
- for (const key of new Set(recent.map((event) => event.key))) {
38
- const failures = recent.filter((event) => event.key === key && !event.isOk);
38
+ for (const key of new Set(recent.map((event) => event.key))) {
39
+ const failures = recent.filter((event) => event.key === key && !event.isOk);
39
40
 
40
- if (failures.length >= SignalConstants.FAILURE_LIMIT) {
41
- return `${failures[0]?.tool ?? 'a tool'} failing ${SignalConstants.FAILURE_LIMIT} times with the same input in the last ${SignalConstants.FAILURE_WINDOW} calls`;
41
+ if (failures.length >= SignalConstants.FAILURE_LIMIT) {
42
+ return `${failures[0]?.tool ?? 'a tool'} failing ${SignalConstants.FAILURE_LIMIT} times with the same input in the last ${SignalConstants.FAILURE_WINDOW} calls`;
43
+ }
42
44
  }
43
- }
44
45
 
45
- return undefined;
46
- };
46
+ return undefined;
47
+ }
48
+ }
@@ -12,11 +12,11 @@ import {
12
12
  } from 'node:fs';
13
13
  import { randomBytes } from 'node:crypto';
14
14
  import { dirname, join } from 'node:path';
15
- import { localRootOf } from '../local/scan.ts';
15
+ import { LocalScan } from '../local/scan.ts';
16
16
  import { EntryKinds, SignalConstants } from './constants.ts';
17
17
 
18
18
  /** One line of the log. Only the fields of its kind are set. */
19
- export interface ISignalEntry {
19
+ interface ISignalEntry {
20
20
  kind: string;
21
21
  /** The session and the agent inside it ('' for the main agent) the line belongs to. */
22
22
  session: string;
@@ -54,9 +54,6 @@ export interface ISignalState {
54
54
  notedAt: Record<string, number>;
55
55
  }
56
56
 
57
- export const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
58
- typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
59
-
60
57
  const recordOf = (opts: { value: unknown }): Record<string, unknown> =>
61
58
  typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value)
62
59
  ? Object.fromEntries(Object.entries(opts.value))
@@ -70,7 +67,7 @@ const stringOf = (opts: { value: unknown }): string =>
70
67
 
71
68
  /** The log of a trusted `.agents/local/`; neither the cache folder nor the file may be a link, or not a plain file. */
72
69
  const logFileOf = (opts: { root: string; create: boolean }): string | undefined => {
73
- const local = localRootOf({ root: opts.root });
70
+ const local = LocalScan.localRootOf({ root: opts.root });
74
71
 
75
72
  if (local === undefined) {
76
73
  return undefined;
@@ -172,105 +169,103 @@ const EMPTY_STATE = (): ISignalState => ({
172
169
  notedAt: {},
173
170
  });
174
171
 
175
- /** The current turn of `session`: its last prompt, then the calls since. `agent` narrows the events only. */
176
- export const readSignals = (opts: {
177
- root: string;
178
- session: string;
179
- agent?: string;
180
- }): ISignalState => {
181
- const file = logFileOf({ root: opts.root, create: false });
182
-
183
- if (file === undefined) {
184
- return EMPTY_STATE();
185
- }
172
+ export class SignalState {
173
+ /** The current turn of `session`: its last prompt, then the calls since. `agent` narrows the events only. */
174
+ static read(opts: { root: string; session: string; agent?: string }): ISignalState {
175
+ const file = logFileOf({ root: opts.root, create: false });
186
176
 
187
- const entries = readEntries({ file });
188
- const state = EMPTY_STATE();
189
- const gates = new Map<string, boolean>();
190
- const mine = entries.filter(
191
- (entry) => entry.kind === EntryKinds.NOTE || entry.session === opts.session,
192
- );
193
- const turnIndex = mine.findLastIndex((entry) => entry.kind === EntryKinds.TURN);
194
-
195
- for (const entry of mine) {
196
- if (entry.kind === EntryKinds.NOTE) {
197
- state.notedAt[entry.name] = Math.max(state.notedAt[entry.name] ?? 0, entry.at);
177
+ if (file === undefined) {
178
+ return EMPTY_STATE();
198
179
  }
199
- }
200
180
 
201
- state.turnAt = turnIndex === -1 ? 0 : (mine[turnIndex]?.at ?? 0);
181
+ const entries = readEntries({ file });
182
+ const state = EMPTY_STATE();
183
+ const gates = new Map<string, boolean>();
184
+ const mine = entries.filter(
185
+ (entry) => entry.kind === EntryKinds.NOTE || entry.session === opts.session,
186
+ );
187
+ const turnIndex = mine.findLastIndex((entry) => entry.kind === EntryKinds.TURN);
202
188
 
203
- for (const entry of mine.slice(turnIndex + 1)) {
204
- if (entry.kind !== EntryKinds.CALL) {
205
- continue;
189
+ for (const entry of mine) {
190
+ if (entry.kind === EntryKinds.NOTE) {
191
+ state.notedAt[entry.name] = Math.max(state.notedAt[entry.name] ?? 0, entry.at);
192
+ }
206
193
  }
207
194
 
208
- if (opts.agent === undefined || entry.agent === opts.agent) {
209
- state.events.push({ tool: entry.tool, key: entry.key, isOk: entry.isOk, at: entry.at });
210
- }
195
+ state.turnAt = turnIndex === -1 ? 0 : (mine[turnIndex]?.at ?? 0);
211
196
 
212
- if (entry.isProbe) {
213
- state.probeAt = Math.max(state.probeAt, entry.at);
214
- }
197
+ for (const entry of mine.slice(turnIndex + 1)) {
198
+ if (entry.kind !== EntryKinds.CALL) {
199
+ continue;
200
+ }
215
201
 
216
- if (entry.isEdit) {
217
- state.editAt = Math.max(state.editAt, entry.at);
218
- }
202
+ if (opts.agent === undefined || entry.agent === opts.agent) {
203
+ state.events.push({ tool: entry.tool, key: entry.key, isOk: entry.isOk, at: entry.at });
204
+ }
219
205
 
220
- for (const gate of entry.gates) {
221
- gates.set(gate, entry.isOk);
222
- }
223
- }
206
+ if (entry.isProbe) {
207
+ state.probeAt = Math.max(state.probeAt, entry.at);
208
+ }
224
209
 
225
- state.events = state.events.slice(-SignalConstants.MAX_EVENTS);
226
- state.failedGates = [...gates.entries()].filter(([, isOk]) => !isOk).map(([gate]) => gate);
210
+ if (entry.isEdit) {
211
+ state.editAt = Math.max(state.editAt, entry.at);
212
+ }
227
213
 
228
- return state;
229
- };
214
+ for (const gate of entry.gates) {
215
+ gates.set(gate, entry.isOk);
216
+ }
217
+ }
230
218
 
231
- /** Adds one line; appending a short line is atomic, so parallel hook processes lose nothing. */
232
- export const appendSignal = (opts: {
233
- root: string;
234
- entry: Partial<ISignalEntry> & { kind: string; at: number };
235
- }): void => {
236
- const file = logFileOf({ root: opts.root, create: true });
219
+ state.events = state.events.slice(-SignalConstants.MAX_EVENTS);
220
+ state.failedGates = [...gates.entries()].filter(([, isOk]) => !isOk).map(([gate]) => gate);
237
221
 
238
- if (file === undefined) {
239
- return;
222
+ return state;
240
223
  }
241
224
 
242
- appendFileSync(file, `${JSON.stringify(opts.entry)}\n`, { mode: 0o600 });
243
- };
225
+ /** Adds one line; appending a short line is atomic, so parallel hook processes lose nothing. */
226
+ static append(opts: {
227
+ root: string;
228
+ entry: Partial<ISignalEntry> & { kind: string; at: number };
229
+ }): void {
230
+ const file = logFileOf({ root: opts.root, create: true });
244
231
 
245
- /** A new turn for `session`: a marker line; a log grown past its size is first cut to what still matters. */
246
- export const startTurn = (opts: { root: string; session: string; now?: number }): void => {
247
- const file = logFileOf({ root: opts.root, create: true });
232
+ if (file === undefined) {
233
+ return;
234
+ }
248
235
 
249
- if (file === undefined) {
250
- return;
236
+ appendFileSync(file, `${JSON.stringify(opts.entry)}\n`, { mode: 0o600 });
251
237
  }
252
238
 
253
- const now = opts.now ?? Date.now();
239
+ /** A new turn for `session`: a marker line; a log grown past its size is first cut to what still matters. */
240
+ static startTurn(opts: { root: string; session: string; now?: number }): void {
241
+ const file = logFileOf({ root: opts.root, create: true });
254
242
 
255
- if ((lstatSync(file, { throwIfNoEntry: false })?.size ?? 0) > SignalConstants.COMPACT_BYTES) {
256
- const kept = readEntries({ file }).filter(
257
- (entry) => entry.kind === EntryKinds.NOTE || now - entry.at < SignalConstants.DEBOUNCE_MS,
258
- );
259
- const partial = `${file}.${randomBytes(6).toString('hex')}.partial`;
243
+ if (file === undefined) {
244
+ return;
245
+ }
260
246
 
261
- try {
262
- writeFileSync(partial, kept.map((entry) => `${JSON.stringify(entry)}\n`).join(''), {
263
- mode: 0o600,
264
- flag: 'wx',
265
- });
266
- renameSync(partial, file);
267
- } finally {
268
- rmSync(partial, { force: true });
247
+ const now = opts.now ?? Date.now();
248
+
249
+ if ((lstatSync(file, { throwIfNoEntry: false })?.size ?? 0) > SignalConstants.COMPACT_BYTES) {
250
+ const kept = readEntries({ file }).filter(
251
+ (entry) => entry.kind === EntryKinds.NOTE || now - entry.at < SignalConstants.DEBOUNCE_MS,
252
+ );
253
+ const partial = `${file}.${randomBytes(6).toString('hex')}.partial`;
254
+
255
+ try {
256
+ writeFileSync(partial, kept.map((entry) => `${JSON.stringify(entry)}\n`).join(''), {
257
+ mode: 0o600,
258
+ flag: 'wx',
259
+ });
260
+ renameSync(partial, file);
261
+ } finally {
262
+ rmSync(partial, { force: true });
263
+ }
269
264
  }
270
- }
271
265
 
272
- appendSignal({
273
- root: opts.root,
274
- entry: { kind: EntryKinds.TURN, session: opts.session, at: now },
275
- });
276
- };
266
+ SignalState.append({
267
+ root: opts.root,
268
+ entry: { kind: EntryKinds.TURN, session: opts.session, at: now },
269
+ });
270
+ }
271
+ }
@@ -8,36 +8,36 @@ const parseYaml = (opts: { text: string }): { value?: unknown; error?: string }
8
8
  }
9
9
  };
10
10
 
11
- /**
12
- * The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
13
- * is the first one at which the block stops parsing - counted in the file, the opening `---` is 1.
14
- */
15
- export const frontmatterOf = (opts: {
16
- text: string;
17
- }): { data: Record<string, unknown>; error?: string } => {
18
- const block = FRONTMATTER.exec(opts.text)?.[1];
11
+ export class SkillFrontmatter {
12
+ /**
13
+ * The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
14
+ * is the first one at which the block stops parsing - counted in the file, the opening `---` is 1.
15
+ */
16
+ static frontmatterOf(opts: { text: string }): { data: Record<string, unknown>; error?: string } {
17
+ const block = FRONTMATTER.exec(opts.text)?.[1];
19
18
 
20
- if (block === undefined) {
21
- return { data: {} };
22
- }
19
+ if (block === undefined) {
20
+ return { data: {} };
21
+ }
23
22
 
24
- const parsed = parseYaml({ text: block });
23
+ const parsed = parseYaml({ text: block });
25
24
 
26
- if (parsed.error !== undefined) {
27
- const blockLines = block.split('\n');
28
- const failsAt = blockLines.findIndex(
29
- (_line, index) =>
30
- parseYaml({ text: blockLines.slice(0, index + 1).join('\n') }).error !== undefined,
31
- );
32
- const where = failsAt === -1 ? '' : ` at line ${failsAt + 2}`;
25
+ if (parsed.error !== undefined) {
26
+ const blockLines = block.split('\n');
27
+ const failsAt = blockLines.findIndex(
28
+ (_line, index) =>
29
+ parseYaml({ text: blockLines.slice(0, index + 1).join('\n') }).error !== undefined,
30
+ );
31
+ const where = failsAt === -1 ? '' : ` at line ${failsAt + 2}`;
33
32
 
34
- return { data: {}, error: `the frontmatter is not valid YAML${where} (${parsed.error})` };
35
- }
33
+ return { data: {}, error: `the frontmatter is not valid YAML${where} (${parsed.error})` };
34
+ }
36
35
 
37
- return {
38
- data:
39
- typeof parsed.value === 'object' && parsed.value !== null
40
- ? Object.fromEntries(Object.entries(parsed.value))
41
- : {},
42
- };
43
- };
36
+ return {
37
+ data:
38
+ typeof parsed.value === 'object' && parsed.value !== null
39
+ ? Object.fromEntries(Object.entries(parsed.value))
40
+ : {},
41
+ };
42
+ }
43
+ }