@venizia/vulcan 0.4.9-0 → 0.4.9-2

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 (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -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,17 +57,15 @@ 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('-')) ?? '';
74
63
 
75
64
  if (name === 'bun') {
65
+ // `check` is Bun's own type-check (Bun >= 1.4.4), two words like `test`; `tsc` stays in GATE_TOOLS for other projects.
76
66
  return (
77
67
  first === 'test' ||
68
+ first === 'check' ||
78
69
  (first === 'run' && GATE_SCRIPTS.has(args[args.indexOf('run') + 1] ?? '')) ||
79
70
  (first === 'x' && args.includes('vulcan') && args.includes('doctor'))
80
71
  );
@@ -106,27 +97,41 @@ const isGateProgram = (opts: { name: string; args: string[] }): boolean => {
106
97
  return GATE_TOOLS.has(name);
107
98
  };
108
99
 
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;
100
+ export class SignalClassifier {
101
+ /** The tool input as a short stable key: the same call twice has the same key. */
102
+ static callKeyOf(opts: { tool: string; input: unknown }): string {
103
+ return `${opts.tool}:${createHash('sha1')
104
+ .update(JSON.stringify(opts.input ?? null))
105
+ .digest('hex')
106
+ .slice(0, SignalConstants.EVENT_KEY_LENGTH)}`;
123
107
  }
124
108
 
125
- const skill = SKILL_FILE.exec(opts.path)?.[1];
109
+ /** A command that asks public state: the registry, the forge, a remote, an outside URL; not a write. */
110
+ static isPublicProbe(opts: { command: string }): boolean {
111
+ return programsOf({ command: opts.command }).some((program) => isProbeProgram(program));
112
+ }
126
113
 
127
- if (skill !== undefined) {
128
- return { kind: WatchedKinds.SKILL, name: skill };
114
+ /** The gates a command line runs (tests, lint, build, the project's own gates), each as a short name. */
115
+ static gatesOf(opts: { command: string }): string[] {
116
+ return programsOf({ command: opts.command })
117
+ .filter((program) => isGateProgram(program))
118
+ .map((program) =>
119
+ [program.name, ...program.args].join(' ').slice(0, SignalConstants.GATE_KEY_LENGTH),
120
+ );
129
121
  }
130
122
 
131
- return RULES_FILE.test(opts.path) ? { kind: WatchedKinds.RULES, name: opts.path } : undefined;
132
- };
123
+ /** What an edited file is for the nudge: a skill (with its name), a rules file, or neither. */
124
+ static watchedFileOf(opts: { path: string }): { kind: string; name: string } | undefined {
125
+ if (SCRATCH.test(opts.path)) {
126
+ return undefined;
127
+ }
128
+
129
+ const skill = SKILL_FILE.exec(opts.path)?.[1];
130
+
131
+ if (skill !== undefined) {
132
+ return { kind: WatchedKinds.SKILL, name: skill };
133
+ }
134
+
135
+ return RULES_FILE.test(opts.path) ? { kind: WatchedKinds.RULES, name: opts.path } : undefined;
136
+ }
137
+ }
@@ -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,7 +12,7 @@ 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. */
@@ -67,7 +67,7 @@ const stringOf = (opts: { value: unknown }): string =>
67
67
 
68
68
  /** The log of a trusted `.agents/local/`; neither the cache folder nor the file may be a link, or not a plain file. */
69
69
  const logFileOf = (opts: { root: string; create: boolean }): string | undefined => {
70
- const local = localRootOf({ root: opts.root });
70
+ const local = LocalScan.localRootOf({ root: opts.root });
71
71
 
72
72
  if (local === undefined) {
73
73
  return undefined;
@@ -169,105 +169,103 @@ const EMPTY_STATE = (): ISignalState => ({
169
169
  notedAt: {},
170
170
  });
171
171
 
172
- /** The current turn of `session`: its last prompt, then the calls since. `agent` narrows the events only. */
173
- export const readSignals = (opts: {
174
- root: string;
175
- session: string;
176
- agent?: string;
177
- }): ISignalState => {
178
- const file = logFileOf({ root: opts.root, create: false });
179
-
180
- if (file === undefined) {
181
- return EMPTY_STATE();
182
- }
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 });
183
176
 
184
- const entries = readEntries({ file });
185
- const state = EMPTY_STATE();
186
- const gates = new Map<string, boolean>();
187
- const mine = entries.filter(
188
- (entry) => entry.kind === EntryKinds.NOTE || entry.session === opts.session,
189
- );
190
- const turnIndex = mine.findLastIndex((entry) => entry.kind === EntryKinds.TURN);
191
-
192
- for (const entry of mine) {
193
- if (entry.kind === EntryKinds.NOTE) {
194
- state.notedAt[entry.name] = Math.max(state.notedAt[entry.name] ?? 0, entry.at);
177
+ if (file === undefined) {
178
+ return EMPTY_STATE();
195
179
  }
196
- }
197
180
 
198
- 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);
199
188
 
200
- for (const entry of mine.slice(turnIndex + 1)) {
201
- if (entry.kind !== EntryKinds.CALL) {
202
- 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
+ }
203
193
  }
204
194
 
205
- if (opts.agent === undefined || entry.agent === opts.agent) {
206
- state.events.push({ tool: entry.tool, key: entry.key, isOk: entry.isOk, at: entry.at });
207
- }
195
+ state.turnAt = turnIndex === -1 ? 0 : (mine[turnIndex]?.at ?? 0);
208
196
 
209
- if (entry.isProbe) {
210
- state.probeAt = Math.max(state.probeAt, entry.at);
211
- }
197
+ for (const entry of mine.slice(turnIndex + 1)) {
198
+ if (entry.kind !== EntryKinds.CALL) {
199
+ continue;
200
+ }
212
201
 
213
- if (entry.isEdit) {
214
- state.editAt = Math.max(state.editAt, entry.at);
215
- }
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
+ }
216
205
 
217
- for (const gate of entry.gates) {
218
- gates.set(gate, entry.isOk);
219
- }
220
- }
206
+ if (entry.isProbe) {
207
+ state.probeAt = Math.max(state.probeAt, entry.at);
208
+ }
221
209
 
222
- state.events = state.events.slice(-SignalConstants.MAX_EVENTS);
223
- state.failedGates = [...gates.entries()].filter(([, isOk]) => !isOk).map(([gate]) => gate);
210
+ if (entry.isEdit) {
211
+ state.editAt = Math.max(state.editAt, entry.at);
212
+ }
224
213
 
225
- return state;
226
- };
214
+ for (const gate of entry.gates) {
215
+ gates.set(gate, entry.isOk);
216
+ }
217
+ }
227
218
 
228
- /** Adds one line; appending a short line is atomic, so parallel hook processes lose nothing. */
229
- export const appendSignal = (opts: {
230
- root: string;
231
- entry: Partial<ISignalEntry> & { kind: string; at: number };
232
- }): void => {
233
- 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);
234
221
 
235
- if (file === undefined) {
236
- return;
222
+ return state;
237
223
  }
238
224
 
239
- appendFileSync(file, `${JSON.stringify(opts.entry)}\n`, { mode: 0o600 });
240
- };
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 });
241
231
 
242
- /** A new turn for `session`: a marker line; a log grown past its size is first cut to what still matters. */
243
- export const startTurn = (opts: { root: string; session: string; now?: number }): void => {
244
- const file = logFileOf({ root: opts.root, create: true });
232
+ if (file === undefined) {
233
+ return;
234
+ }
245
235
 
246
- if (file === undefined) {
247
- return;
236
+ appendFileSync(file, `${JSON.stringify(opts.entry)}\n`, { mode: 0o600 });
248
237
  }
249
238
 
250
- 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 });
251
242
 
252
- if ((lstatSync(file, { throwIfNoEntry: false })?.size ?? 0) > SignalConstants.COMPACT_BYTES) {
253
- const kept = readEntries({ file }).filter(
254
- (entry) => entry.kind === EntryKinds.NOTE || now - entry.at < SignalConstants.DEBOUNCE_MS,
255
- );
256
- const partial = `${file}.${randomBytes(6).toString('hex')}.partial`;
243
+ if (file === undefined) {
244
+ return;
245
+ }
257
246
 
258
- try {
259
- writeFileSync(partial, kept.map((entry) => `${JSON.stringify(entry)}\n`).join(''), {
260
- mode: 0o600,
261
- flag: 'wx',
262
- });
263
- renameSync(partial, file);
264
- } finally {
265
- 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
+ }
266
264
  }
267
- }
268
265
 
269
- appendSignal({
270
- root: opts.root,
271
- entry: { kind: EntryKinds.TURN, session: opts.session, at: now },
272
- });
273
- };
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
+ }