@venizia/vulcan 0.4.10-0 → 0.4.10-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.
- package/base/claude/events.json +0 -1
- package/base/hooks/event.ts +4 -3
- package/base/hooks/guard-outside.ts +34 -15
- package/base/hooks/guard-remote-hosts.ts +13 -4
- package/base/rules.md +1 -1
- package/base/skills/build-a-feature/SKILL.md +11 -2
- package/base/skills/review-a-change/SKILL.md +10 -6
- package/base/skills/ship/SKILL.md +9 -4
- package/base/templates/board.html +844 -4240
- package/base/templates/pull-request.md +31 -0
- package/base/templates/trusted-hosts.local.example +11 -0
- package/base/templates/vulcan.config.mts +1 -0
- package/package.json +6 -4
- package/src/board/agent-setting.ts +43 -0
- package/src/board/command.ts +138 -17
- package/src/board/common/constants.ts +38 -1
- package/src/board/common/types.ts +40 -1
- package/src/board/fold.ts +106 -12
- package/src/board/github.ts +6 -3
- package/src/board/index.ts +2 -0
- package/src/board/schema.ts +32 -0
- package/src/board/server.ts +325 -0
- package/src/board/settings.ts +99 -17
- package/src/board/watch.ts +88 -0
- package/src/commands/help.command.ts +4 -3
- package/src/commands/init.command.ts +26 -1
- package/src/common/constants.ts +8 -0
- package/src/common/git-files.ts +11 -0
- package/src/common/index.ts +1 -0
- package/src/common/layout-folder.ts +1 -1
- package/src/config/schema.ts +33 -19
- package/src/create/common/constants.ts +1 -0
- package/src/create/dockerignore.ts +5 -3
- package/src/create/init-monorepo.ts +28 -4
- package/src/create/project-key.ts +60 -0
- package/src/create/workspace.ts +2 -1
- package/src/doctor/checks.ts +89 -2
- package/src/doctor/common/constants.ts +48 -0
- package/src/doctor/common/types.ts +2 -1
- package/src/doctor/index.ts +2 -0
- package/src/doctor/private-values.ts +108 -0
- package/src/doctor/runner.ts +4 -0
- package/src/doctor/schema.ts +29 -0
- package/src/events/actor.ts +10 -5
- package/src/events/command.ts +225 -22
- package/src/events/common/constants.ts +100 -6
- package/src/events/common/types.ts +22 -0
- package/src/events/flow-id.ts +89 -0
- package/src/events/flow.ts +4 -4
- package/src/events/hook.ts +53 -6
- package/src/events/index.ts +2 -0
- package/src/events/log.ts +115 -7
- package/src/events/project-key.ts +22 -0
- package/src/events/retention.ts +2 -4
- package/src/events/settings.ts +16 -0
- package/src/events/text.ts +23 -0
- package/src/hooks/host-pattern.ts +17 -0
- package/src/hooks/remote-hosts.ts +39 -7
- package/src/init/common/constants.ts +1 -0
- package/src/init/scaffold.ts +39 -7
- package/src/manifest/render.ts +5 -1
- package/src/router.ts +11 -2
- package/src/sync/claude-launch.ts +62 -7
- package/src/wiki/source-links.ts +5 -4
package/src/events/command.ts
CHANGED
|
@@ -10,19 +10,40 @@ import {
|
|
|
10
10
|
EventStatuses,
|
|
11
11
|
EventSubcommands,
|
|
12
12
|
} from './common/index.ts';
|
|
13
|
-
import type { IEvent, TEventKind, TEventStatus } from './common/index.ts';
|
|
13
|
+
import type { IEvent, IEventItem, TEventKind, TEventStatus } from './common/index.ts';
|
|
14
|
+
import { BoardFold } from '../board/fold.ts';
|
|
15
|
+
import { BoardStates } from '../board/common/index.ts';
|
|
14
16
|
import { EventActor } from './actor.ts';
|
|
15
17
|
import { EventFlow } from './flow.ts';
|
|
18
|
+
import { FlowId } from './flow-id.ts';
|
|
19
|
+
import { ProjectKey } from './project-key.ts';
|
|
16
20
|
import { EventLog } from './log.ts';
|
|
17
21
|
import { EventSettings } from './settings.ts';
|
|
22
|
+
import { EventText } from './text.ts';
|
|
18
23
|
|
|
19
|
-
const USAGE = `usage: vulcan event add ${EventFlags.KIND} <kind> ${EventFlags.SUMMARY} <text> [${EventFlags.FLOW}
|
|
20
|
-
vulcan event add ${EventFlags.KIND} ${EventKinds.FLOW} ${EventFlags.FLOW}
|
|
24
|
+
const USAGE = `usage: vulcan event add ${EventFlags.KIND} <kind> ${EventFlags.SUMMARY} <text> [${EventFlags.FLOW} <flow id>] [${EventFlags.REF} <ref>] [${EventFlags.STATUS} <${[...EventStatuses.SCHEME_SET].join('|')}>] [${EventFlags.ACTOR} <name>] [${EventFlags.DIR} <folder>]
|
|
25
|
+
vulcan event add ${EventFlags.KIND} ${EventKinds.FLOW} [${EventFlags.FLOW} <flow id>] ${EventFlags.TITLE} <text> [${EventFlags.WHY} <text>] [${EventFlags.CONTEXT} <text>] [${EventFlags.NEXT} <text>] [${EventFlags.DUE} <YYYY-MM-DD>] [${EventFlags.REF} <tracker id>]
|
|
26
|
+
[${EventFlags.STEP} <text> | ${EventFlags.STEP_DONE} <text>]... [${EventFlags.CHECK} <text> | ${EventFlags.CHECK_DONE} <text>]... [${EventFlags.APP} <name>]... [${EventFlags.ACTOR} <name>] [${EventFlags.DIR} <folder>]
|
|
21
27
|
vulcan event tail [${EventFlags.SINCE} <time>] [${EventFlags.JSON}] [${EventFlags.DIR} <folder>]
|
|
22
|
-
kinds: ${[...EventKinds.SCHEME_SET].join(', ')}
|
|
28
|
+
kinds: ${[...EventKinds.SCHEME_SET].join(', ')}
|
|
29
|
+
A flow line without ${EventFlags.FLOW} makes a new flow and prints its id (VULZ-<project.key>-<number>); give that id to every other line of the flow. Ids are never typed by hand.`;
|
|
23
30
|
|
|
24
31
|
type TFlagValues = Record<string, string>;
|
|
25
32
|
|
|
33
|
+
/** A flag that may be given again, and the order of the given ones matters: the lists of a flow line. */
|
|
34
|
+
interface IListFlag {
|
|
35
|
+
flag: string;
|
|
36
|
+
value: string;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const LIST_FLAGS = new Set<string>([
|
|
40
|
+
EventFlags.STEP,
|
|
41
|
+
EventFlags.STEP_DONE,
|
|
42
|
+
EventFlags.CHECK,
|
|
43
|
+
EventFlags.CHECK_DONE,
|
|
44
|
+
EventFlags.APP,
|
|
45
|
+
]);
|
|
46
|
+
|
|
26
47
|
/** `vulcan event`: write a line to the agent event log, or read the log. */
|
|
27
48
|
export class EventCommand {
|
|
28
49
|
static async run(opts: ICommandContext): Promise<number> {
|
|
@@ -39,15 +60,16 @@ export class EventCommand {
|
|
|
39
60
|
}
|
|
40
61
|
|
|
41
62
|
return subcommand === EventSubcommands.ADD
|
|
42
|
-
? EventCommand.add({ cwd: opts.cwd, values: parsed.values })
|
|
63
|
+
? EventCommand.add({ cwd: opts.cwd, values: parsed.values, lists: parsed.lists })
|
|
43
64
|
: EventCommand.tail({ cwd: opts.cwd, values: parsed.values, json: parsed.json });
|
|
44
65
|
}
|
|
45
66
|
|
|
46
67
|
/** Flags with a value, and `--json`; `undefined` for anything else (the router has already refused unknown flags). */
|
|
47
68
|
private static parse(opts: {
|
|
48
69
|
args: string[];
|
|
49
|
-
}): { values: TFlagValues; json: boolean } | undefined {
|
|
70
|
+
}): { values: TFlagValues; lists: IListFlag[]; json: boolean } | undefined {
|
|
50
71
|
const values: TFlagValues = {};
|
|
72
|
+
const lists: IListFlag[] = [];
|
|
51
73
|
let json = false;
|
|
52
74
|
|
|
53
75
|
for (let index = 0; index < opts.args.length; index++) {
|
|
@@ -60,15 +82,25 @@ export class EventCommand {
|
|
|
60
82
|
|
|
61
83
|
const value = opts.args[index + 1];
|
|
62
84
|
|
|
63
|
-
if (
|
|
85
|
+
if (
|
|
86
|
+
!arg.startsWith('--') ||
|
|
87
|
+
value === undefined ||
|
|
88
|
+
(!LIST_FLAGS.has(arg) && Object.hasOwn(values, arg)) ||
|
|
89
|
+
(LIST_FLAGS.has(arg) && EventFlags.KNOWN.has(value))
|
|
90
|
+
) {
|
|
64
91
|
return undefined;
|
|
65
92
|
}
|
|
66
93
|
|
|
67
|
-
|
|
94
|
+
if (LIST_FLAGS.has(arg)) {
|
|
95
|
+
lists.push({ flag: arg, value });
|
|
96
|
+
} else {
|
|
97
|
+
values[arg] = value;
|
|
98
|
+
}
|
|
99
|
+
|
|
68
100
|
index++;
|
|
69
101
|
}
|
|
70
102
|
|
|
71
|
-
return { values, json };
|
|
103
|
+
return { values, lists, json };
|
|
72
104
|
}
|
|
73
105
|
|
|
74
106
|
/** The folder to use: `--dir`, else the manifest's `events.dir`, else the project's own. */
|
|
@@ -81,7 +113,7 @@ export class EventCommand {
|
|
|
81
113
|
});
|
|
82
114
|
}
|
|
83
115
|
|
|
84
|
-
private static add(opts: { cwd: string; values: TFlagValues }): number {
|
|
116
|
+
private static add(opts: { cwd: string; values: TFlagValues; lists: IListFlag[] }): number {
|
|
85
117
|
const { values } = opts;
|
|
86
118
|
const kind = values[EventFlags.KIND];
|
|
87
119
|
const isFlow = kind === EventKinds.FLOW;
|
|
@@ -108,19 +140,40 @@ export class EventCommand {
|
|
|
108
140
|
if (
|
|
109
141
|
isFlow
|
|
110
142
|
? values[EventFlags.SUMMARY] !== undefined
|
|
111
|
-
: values[EventFlags.TITLE] !== undefined ||
|
|
143
|
+
: values[EventFlags.TITLE] !== undefined ||
|
|
144
|
+
values[EventFlags.WHY] !== undefined ||
|
|
145
|
+
values[EventFlags.CONTEXT] !== undefined ||
|
|
146
|
+
values[EventFlags.NEXT] !== undefined
|
|
112
147
|
) {
|
|
113
148
|
process.stderr.write(
|
|
114
149
|
isFlow
|
|
115
|
-
? `event: a flow line takes ${EventFlags.TITLE}
|
|
116
|
-
: `event: ${EventFlags.TITLE} and ${EventFlags.
|
|
150
|
+
? `event: a flow line takes ${EventFlags.TITLE}, not ${EventFlags.SUMMARY}\n`
|
|
151
|
+
: `event: ${EventFlags.TITLE}, ${EventFlags.WHY}, ${EventFlags.CONTEXT} and ${EventFlags.NEXT} belong to a flow line only\n`,
|
|
117
152
|
);
|
|
118
153
|
|
|
119
154
|
return ExitCodes.USAGE;
|
|
120
155
|
}
|
|
121
156
|
|
|
157
|
+
const items = EventCommand.itemsOf({ lists: opts.lists, due: values[EventFlags.DUE], isFlow });
|
|
158
|
+
|
|
159
|
+
if (!items.ok) {
|
|
160
|
+
process.stderr.write(`event: ${items.message}\n`);
|
|
161
|
+
|
|
162
|
+
return ExitCodes.USAGE;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
for (const flag of [EventFlags.CONTEXT, EventFlags.NEXT]) {
|
|
166
|
+
if (values[flag] !== undefined && values[flag].trim() === '') {
|
|
167
|
+
process.stderr.write(`event: ${flag} needs a short text, or leave it out\n`);
|
|
168
|
+
|
|
169
|
+
return ExitCodes.USAGE;
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
|
|
122
173
|
if (flow !== undefined && !EventFlow.isValid({ flow })) {
|
|
123
|
-
process.stderr.write(
|
|
174
|
+
process.stderr.write(
|
|
175
|
+
`event: ${EventFlags.FLOW} must look like VULZ-ACME-12 (the id the command printed), got '${flow}'\n`,
|
|
176
|
+
);
|
|
124
177
|
|
|
125
178
|
return ExitCodes.USAGE;
|
|
126
179
|
}
|
|
@@ -142,13 +195,24 @@ export class EventCommand {
|
|
|
142
195
|
return ExitCodes.USAGE;
|
|
143
196
|
}
|
|
144
197
|
|
|
145
|
-
const
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
198
|
+
const dir = EventCommand.dirOf(opts);
|
|
199
|
+
const key = EventSettings.keyOf({ root: EventSettings.rootOf({ cwd: opts.cwd }) });
|
|
200
|
+
const known = EventLog.read({ dir }).events;
|
|
201
|
+
const named = flow ?? EventFlow.fromBranch({ cwd: opts.cwd });
|
|
202
|
+
const placed = EventCommand.flowOf({
|
|
203
|
+
flow: named,
|
|
204
|
+
known,
|
|
205
|
+
key,
|
|
206
|
+
isFlow,
|
|
207
|
+
dir,
|
|
208
|
+
explicit: flow !== undefined,
|
|
209
|
+
});
|
|
149
210
|
|
|
150
|
-
|
|
211
|
+
if (!placed.ok) {
|
|
212
|
+
return placed.code;
|
|
151
213
|
}
|
|
214
|
+
|
|
215
|
+
const { flowId } = placed;
|
|
152
216
|
const actor =
|
|
153
217
|
values[EventFlags.ACTOR] === undefined
|
|
154
218
|
? EventActor.resolve({
|
|
@@ -165,23 +229,162 @@ export class EventCommand {
|
|
|
165
229
|
...(values[EventFlags.REF] === undefined ? {} : { ref: values[EventFlags.REF] }),
|
|
166
230
|
...(status === undefined ? {} : { status: status as TEventStatus }),
|
|
167
231
|
...(values[EventFlags.WHY] === undefined ? {} : { why: values[EventFlags.WHY] }),
|
|
232
|
+
...(values[EventFlags.CONTEXT] === undefined ? {} : { context: values[EventFlags.CONTEXT] }),
|
|
233
|
+
...(values[EventFlags.NEXT] === undefined ? {} : { next: values[EventFlags.NEXT] }),
|
|
234
|
+
steps: items.steps,
|
|
235
|
+
checks: items.checks,
|
|
236
|
+
apps: items.apps,
|
|
237
|
+
...(values[EventFlags.DUE] === undefined ? {} : { due: values[EventFlags.DUE] }),
|
|
168
238
|
});
|
|
169
239
|
|
|
170
240
|
try {
|
|
171
|
-
EventLog.append({ dir
|
|
241
|
+
EventLog.append({ dir, event });
|
|
172
242
|
} catch (error) {
|
|
173
243
|
process.stderr.write(
|
|
174
|
-
`event: cannot write the log in ${
|
|
244
|
+
`event: cannot write the log in ${dir}: ${error instanceof Error ? error.message : String(error)}\n`,
|
|
175
245
|
);
|
|
176
246
|
|
|
177
247
|
return ExitCodes.FAILURE;
|
|
178
248
|
}
|
|
179
249
|
|
|
180
|
-
process.stdout.write(
|
|
250
|
+
process.stdout.write(
|
|
251
|
+
`${isFlow && flow === undefined && flowId !== undefined ? flowId : event.id}\n`,
|
|
252
|
+
);
|
|
181
253
|
|
|
182
254
|
return ExitCodes.OK;
|
|
183
255
|
}
|
|
184
256
|
|
|
257
|
+
/**
|
|
258
|
+
* The lists of a flow line from the flags, in the order given, and the due date. They belong to a flow line only; a text
|
|
259
|
+
* that is empty or over its limit, too many of them, or a due date that is not a day, is refused (the other texts are
|
|
260
|
+
* cut, but a list an agent restates in full must not lose a word without a word said).
|
|
261
|
+
*/
|
|
262
|
+
private static itemsOf(opts: {
|
|
263
|
+
lists: IListFlag[];
|
|
264
|
+
due: string | undefined;
|
|
265
|
+
isFlow: boolean;
|
|
266
|
+
}):
|
|
267
|
+
| { ok: true; steps: IEventItem[]; checks: IEventItem[]; apps: string[] }
|
|
268
|
+
| { ok: false; message: string } {
|
|
269
|
+
const steps: IEventItem[] = [];
|
|
270
|
+
const checks: IEventItem[] = [];
|
|
271
|
+
const apps: string[] = [];
|
|
272
|
+
|
|
273
|
+
if (!opts.isFlow && (opts.lists.length > 0 || opts.due !== undefined)) {
|
|
274
|
+
return {
|
|
275
|
+
ok: false,
|
|
276
|
+
message: `${[...LIST_FLAGS, EventFlags.DUE].join(', ')} belong to a flow line only`,
|
|
277
|
+
};
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
for (const { flag, value } of opts.lists) {
|
|
281
|
+
const isApp = flag === EventFlags.APP;
|
|
282
|
+
const max = isApp ? EventConstants.APP_TEXT_MAX : EventConstants.ITEM_TEXT_MAX;
|
|
283
|
+
|
|
284
|
+
// The text as it will be kept: a text of control characters only is as empty as a blank one.
|
|
285
|
+
if (EventText.oneLine({ text: value, max }) === '' || Array.from(value).length > max) {
|
|
286
|
+
return { ok: false, message: `${flag} needs a text of 1 to ${max} characters` };
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
if (flag === EventFlags.STEP || flag === EventFlags.STEP_DONE) {
|
|
290
|
+
steps.push({ text: value, done: flag === EventFlags.STEP_DONE });
|
|
291
|
+
} else if (flag === EventFlags.CHECK || flag === EventFlags.CHECK_DONE) {
|
|
292
|
+
checks.push({ text: value, done: flag === EventFlags.CHECK_DONE });
|
|
293
|
+
} else {
|
|
294
|
+
apps.push(value);
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
for (const [flag, count, limit] of [
|
|
299
|
+
[`${EventFlags.STEP}/${EventFlags.STEP_DONE}`, steps.length, EventConstants.ITEM_COUNT_MAX],
|
|
300
|
+
[
|
|
301
|
+
`${EventFlags.CHECK}/${EventFlags.CHECK_DONE}`,
|
|
302
|
+
checks.length,
|
|
303
|
+
EventConstants.ITEM_COUNT_MAX,
|
|
304
|
+
],
|
|
305
|
+
[EventFlags.APP, apps.length, EventConstants.APP_COUNT_MAX],
|
|
306
|
+
] as const) {
|
|
307
|
+
if (count > limit) {
|
|
308
|
+
return { ok: false, message: `at most ${limit} of ${flag}, got ${count}` };
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
if (opts.due !== undefined && !EventText.isDay({ value: opts.due })) {
|
|
313
|
+
return {
|
|
314
|
+
ok: false,
|
|
315
|
+
message: `${EventFlags.DUE} must be a day such as 2026-11-08, got '${opts.due}'`,
|
|
316
|
+
};
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
return { ok: true, steps, checks, apps };
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/**
|
|
323
|
+
* Whether the board would show the flow as Done or Parked: the board's own fold decides, so the command and the page
|
|
324
|
+
* cannot disagree. A merge only the GitHub reader sees is not in the log, so it is not seen here.
|
|
325
|
+
*/
|
|
326
|
+
private static isOver(opts: { events: IEvent[]; id: string; key: string | undefined }): boolean {
|
|
327
|
+
const wanted = FlowId.canon({ id: opts.id, key: opts.key });
|
|
328
|
+
const lines = BoardFold.fromLog({ events: opts.events }).events.map((event) => ({
|
|
329
|
+
...event,
|
|
330
|
+
flowId: FlowId.canon({ id: event.flowId, key: opts.key }),
|
|
331
|
+
}));
|
|
332
|
+
const state = BoardFold.fold({ events: lines, owner: '' }).flows.find(
|
|
333
|
+
(flow) => flow.id === wanted,
|
|
334
|
+
)?.state;
|
|
335
|
+
|
|
336
|
+
return state === BoardStates.DONE || state === BoardStates.PARKED;
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
/**
|
|
340
|
+
* The flow a line belongs to. A flow named with `--flow` must exist (an id is never made up by hand). A flow line that
|
|
341
|
+
* names none either updates the flow of its branch, when the branch names one that exists and is not over, or starts a
|
|
342
|
+
* new flow with the next number. The exit code comes back when the line cannot be written.
|
|
343
|
+
*/
|
|
344
|
+
private static flowOf(opts: {
|
|
345
|
+
flow: string | undefined;
|
|
346
|
+
known: IEvent[];
|
|
347
|
+
key: string | undefined;
|
|
348
|
+
isFlow: boolean;
|
|
349
|
+
dir: string;
|
|
350
|
+
explicit: boolean;
|
|
351
|
+
}): { ok: true; flowId: string | undefined } | { ok: false; code: number } {
|
|
352
|
+
const { flow, known, key } = opts;
|
|
353
|
+
|
|
354
|
+
// The flow of the branch is taken only while it is open: work on a merged or parked flow's branch is a new flow.
|
|
355
|
+
if (
|
|
356
|
+
flow !== undefined &&
|
|
357
|
+
FlowId.exists({ events: known, id: flow, key }) &&
|
|
358
|
+
(opts.explicit || !opts.isFlow || !EventCommand.isOver({ events: known, id: flow, key }))
|
|
359
|
+
) {
|
|
360
|
+
return { ok: true, flowId: flow };
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
if (flow !== undefined && opts.explicit) {
|
|
364
|
+
const recent = FlowId.recent({ events: known, key, count: EventConstants.FLOW_RECENT_COUNT });
|
|
365
|
+
|
|
366
|
+
process.stderr.write(
|
|
367
|
+
`event: no flow ${flow} in the log. ${recent.length === 0 ? 'The log has no flow yet' : `Recent flows: ${recent.join(', ')}`}. Make a new flow with: vulcan event add ${EventFlags.KIND} ${EventKinds.FLOW} ${EventFlags.TITLE} <text>\n`,
|
|
368
|
+
);
|
|
369
|
+
|
|
370
|
+
return { ok: false, code: ExitCodes.USAGE };
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
if (!opts.isFlow) {
|
|
374
|
+
return { ok: true, flowId: flow };
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
if (key === undefined) {
|
|
378
|
+
process.stderr.write(
|
|
379
|
+
`event: the project has no key for its flows: set project.key in the config (${ProjectKey.MESSAGE}) and run vulcan sync\n`,
|
|
380
|
+
);
|
|
381
|
+
|
|
382
|
+
return { ok: false, code: ExitCodes.USAGE };
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
return { ok: true, flowId: FlowId.next({ dir: opts.dir, key }) };
|
|
386
|
+
}
|
|
387
|
+
|
|
185
388
|
private static tail(opts: { cwd: string; values: TFlagValues; json: boolean }): number {
|
|
186
389
|
const { values } = opts;
|
|
187
390
|
const since = EventCommand.sinceOf({ value: values[EventFlags.SINCE] });
|
|
@@ -12,6 +12,10 @@ export class EventKinds {
|
|
|
12
12
|
static readonly DECISION = 'decision';
|
|
13
13
|
/** A flow's title and the one-line reason for it, in the owner's language; the newest per flow wins. */
|
|
14
14
|
static readonly FLOW = 'flow';
|
|
15
|
+
/** Something was put live; a milestone of its flow, like a merge. Its summary says what. */
|
|
16
|
+
static readonly DEPLOY = 'deploy';
|
|
17
|
+
/** An agent used a tool, at most once in `EventConstants.TICK_SECONDS` per session: the board reads it as working. */
|
|
18
|
+
static readonly TOOL_TICK = 'tool-tick';
|
|
15
19
|
|
|
16
20
|
static readonly SCHEME_SET = new Set<string>([
|
|
17
21
|
this.SESSION_START,
|
|
@@ -24,6 +28,8 @@ export class EventKinds {
|
|
|
24
28
|
this.PR,
|
|
25
29
|
this.DECISION,
|
|
26
30
|
this.FLOW,
|
|
31
|
+
this.DEPLOY,
|
|
32
|
+
this.TOOL_TICK,
|
|
27
33
|
]);
|
|
28
34
|
|
|
29
35
|
static isValid(value: string): boolean {
|
|
@@ -56,6 +62,13 @@ export class EventSubcommands {
|
|
|
56
62
|
}
|
|
57
63
|
|
|
58
64
|
export class EventFlags {
|
|
65
|
+
/** The lists of a flow line, each given again in full on every line: the last line wins as a whole. */
|
|
66
|
+
static readonly STEP = '--step';
|
|
67
|
+
static readonly STEP_DONE = '--step-done';
|
|
68
|
+
static readonly CHECK = '--check';
|
|
69
|
+
static readonly CHECK_DONE = '--check-done';
|
|
70
|
+
static readonly APP = '--app';
|
|
71
|
+
static readonly DUE = '--due';
|
|
59
72
|
static readonly KIND = '--kind';
|
|
60
73
|
static readonly SUMMARY = '--summary';
|
|
61
74
|
static readonly FLOW = '--flow';
|
|
@@ -63,10 +76,35 @@ export class EventFlags {
|
|
|
63
76
|
static readonly STATUS = '--status';
|
|
64
77
|
static readonly TITLE = '--title';
|
|
65
78
|
static readonly WHY = '--why';
|
|
79
|
+
static readonly CONTEXT = '--context';
|
|
80
|
+
static readonly NEXT = '--next';
|
|
66
81
|
static readonly ACTOR = '--actor';
|
|
67
82
|
static readonly DIR = '--dir';
|
|
68
83
|
static readonly SINCE = '--since';
|
|
69
84
|
static readonly JSON = '--json';
|
|
85
|
+
|
|
86
|
+
/** Every flag the command knows: a list value that is one of them is a flag with its value missing. */
|
|
87
|
+
static readonly KNOWN = new Set<string>([
|
|
88
|
+
this.STEP,
|
|
89
|
+
this.STEP_DONE,
|
|
90
|
+
this.CHECK,
|
|
91
|
+
this.CHECK_DONE,
|
|
92
|
+
this.APP,
|
|
93
|
+
this.DUE,
|
|
94
|
+
this.KIND,
|
|
95
|
+
this.SUMMARY,
|
|
96
|
+
this.FLOW,
|
|
97
|
+
this.REF,
|
|
98
|
+
this.STATUS,
|
|
99
|
+
this.TITLE,
|
|
100
|
+
this.WHY,
|
|
101
|
+
this.CONTEXT,
|
|
102
|
+
this.NEXT,
|
|
103
|
+
this.ACTOR,
|
|
104
|
+
this.DIR,
|
|
105
|
+
this.SINCE,
|
|
106
|
+
this.JSON,
|
|
107
|
+
]);
|
|
70
108
|
}
|
|
71
109
|
|
|
72
110
|
/** The names a Claude Code hook payload carries, as Claude Code 2.1.317 sends them. */
|
|
@@ -104,29 +142,76 @@ export class EventConstants {
|
|
|
104
142
|
/** Relative to the project root; the default place of the log. */
|
|
105
143
|
static readonly DEFAULT_DIRECTORY = '.agents/local/events';
|
|
106
144
|
static readonly MANIFEST_FILE = '.agents/vulcan.manifest.json';
|
|
145
|
+
/** A day file of the log: `<local day>.jsonl`; the capture is the day. */
|
|
146
|
+
static readonly DAY_FILE = /^(\d{4}-\d{2}-\d{2})\.jsonl$/;
|
|
107
147
|
static readonly FILE_SUFFIX = '.jsonl';
|
|
108
148
|
static readonly SUMMARY_MAX = 200;
|
|
149
|
+
/** A flow's context is a few sentences, not a summary line. */
|
|
150
|
+
static readonly CONTEXT_MAX = 600;
|
|
109
151
|
/** What a sent message is called when its sender gave no label: the text of a message is never used. */
|
|
110
152
|
static readonly MESSAGE_SENT_LABEL = 'message sent';
|
|
153
|
+
/** The summary of a tool tick: it says that a tool was used, and nothing of which. */
|
|
154
|
+
static readonly TOOL_TICK_LABEL = 'using a tool';
|
|
155
|
+
/** A session writes at most one tool tick in each window of this many seconds. */
|
|
156
|
+
static readonly TICK_SECONDS = 30;
|
|
157
|
+
/**
|
|
158
|
+
* The folder, from the project root, that holds one empty stamp per session and window, `<session>.<window>`; a tick
|
|
159
|
+
* removes the stamps of earlier windows. Spelt out because the hook imports no other module of the package (a test holds it
|
|
160
|
+
* inside `ProjectLayout.LOCAL_DIRECTORY/tmp`).
|
|
161
|
+
*/
|
|
162
|
+
static readonly TICK_FOLDER = '.agents/local/tmp/event-ticks';
|
|
111
163
|
static readonly REF_MAX = 120;
|
|
164
|
+
/** A flow line's lists: how many items, and how long one is. */
|
|
165
|
+
static readonly ITEM_COUNT_MAX = 30;
|
|
166
|
+
static readonly ITEM_TEXT_MAX = 200;
|
|
167
|
+
static readonly APP_COUNT_MAX = 12;
|
|
168
|
+
static readonly APP_TEXT_MAX = 40;
|
|
169
|
+
/** A due date is a day: `2026-11-08`. */
|
|
170
|
+
static readonly DUE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
|
|
171
|
+
static readonly MODEL_MAX = 80;
|
|
112
172
|
static readonly ACTOR_MAX = 80;
|
|
113
173
|
static readonly REDACTED = '[redacted]';
|
|
114
|
-
|
|
115
|
-
static readonly
|
|
116
|
-
|
|
117
|
-
static readonly
|
|
174
|
+
/** A flow is named `VULZ-<key>-<number>`; the older `F-<number>` is still read and shows as the new form. */
|
|
175
|
+
static readonly FLOW_PREFIX = 'VULZ';
|
|
176
|
+
static readonly FLOW_ID = 'VULZ-[A-Z0-9]{2,8}-\\d+|F-\\d+';
|
|
177
|
+
static readonly FLOW_PATTERN = new RegExp(`\\b(?:${EventConstants.FLOW_ID})\\b`);
|
|
178
|
+
static readonly FLOW_EXACT = new RegExp(`^(?:${EventConstants.FLOW_ID})$`);
|
|
179
|
+
/** `Flow: <id>` in a message's first line. */
|
|
180
|
+
static readonly FLOW_LINE = new RegExp(`\\bFlow:\\s*(${EventConstants.FLOW_ID})\\b`);
|
|
181
|
+
/** An older flow id, `F-<number>`. */
|
|
182
|
+
static readonly FLOW_LEGACY = /^F-\d+$/;
|
|
183
|
+
/** The folder of claims beside the day files: one file per flow number given, so a number is never given twice. */
|
|
184
|
+
static readonly FLOW_CLAIM_DIR = '.flow-ids';
|
|
185
|
+
/** How many recent flows a refusal lists. */
|
|
186
|
+
static readonly FLOW_RECENT_COUNT = 5;
|
|
118
187
|
/** Where the log goes for a hook that has no better answer: the name of an actor with no session name. */
|
|
119
188
|
static readonly UNKNOWN_ACTOR = 'unknown';
|
|
189
|
+
/** What the actor of a session with no name starts with; a name that starts with it is read as no name. */
|
|
190
|
+
static readonly UNNAMED_PREFIX = 'claude:';
|
|
191
|
+
/** The `nameSource` values of a name Claude Code made up (from the folder, a counter or a clash), not a person's. */
|
|
192
|
+
static readonly MADE_UP_NAME_SOURCES = new Set(['derived', 'auto', 'collision']);
|
|
120
193
|
static readonly ACTOR_ENV = 'VULCAN_ACTOR';
|
|
121
194
|
static readonly SESSION_ENV = 'CLAUDE_CODE_SESSION_ID';
|
|
122
195
|
static readonly CONFIG_DIR_ENV = 'CLAUDE_CONFIG_DIR';
|
|
123
196
|
static readonly DAY_MS = 24 * 60 * 60 * 1000;
|
|
124
197
|
}
|
|
125
198
|
|
|
199
|
+
/** What the name of an actor says about its session. Light on purpose: the board page is built from it. */
|
|
200
|
+
export class EventActorNames {
|
|
201
|
+
/** Whether the actor is a name somebody gave, and not the fallback of a session with none (`claude:<id>`, `unknown`). */
|
|
202
|
+
static isNamed(opts: { actor: string }): boolean {
|
|
203
|
+
return (
|
|
204
|
+
opts.actor !== EventConstants.UNKNOWN_ACTOR &&
|
|
205
|
+
!opts.actor.startsWith(EventConstants.UNNAMED_PREFIX)
|
|
206
|
+
);
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
|
|
126
210
|
/** Shapes of a secret that must never reach a log line. Best effort: a summary is a label, not a document. */
|
|
127
211
|
export class EventSecrets {
|
|
128
|
-
static readonly
|
|
129
|
-
|
|
212
|
+
static readonly PRIVATE_KEY = /-----BEGIN [A-Z ]*PRIVATE KEY-----.*/g;
|
|
213
|
+
/** The known token prefixes and shapes. */
|
|
214
|
+
static readonly TOKENS: RegExp[] = [
|
|
130
215
|
/\b(?:ghp|gho|ghs|ghu|ghr)_[A-Za-z0-9]{16,}/g,
|
|
131
216
|
/\bgithub_pat_[A-Za-z0-9_]{16,}/g,
|
|
132
217
|
/\bnpm_[A-Za-z0-9]{16,}/g,
|
|
@@ -140,9 +225,18 @@ export class EventSecrets {
|
|
|
140
225
|
/\bBasic\s+(?:(?=[A-Za-z0-9+/]*(?:[0-9+/]|[a-z][A-Z]))[A-Za-z0-9+/]{8,}={0,2}|[A-Za-z0-9+/]{8,}={1,2})/g,
|
|
141
226
|
/\bxox[abprs]-[A-Za-z0-9-]{10,}/g,
|
|
142
227
|
/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi,
|
|
228
|
+
];
|
|
229
|
+
/** Long runs that are secrets in a log line but hashes in a lockfile. */
|
|
230
|
+
static readonly HIGH_ENTROPY: RegExp[] = [
|
|
143
231
|
/\b[0-9a-fA-F]{64,}\b/g,
|
|
144
232
|
/\b(?=[A-Za-z0-9+]*\d)(?=[A-Za-z0-9+]*[a-z])(?=[A-Za-z0-9+]*[A-Z])[A-Za-z0-9+]{40,}={0,2}/g,
|
|
145
233
|
];
|
|
234
|
+
/** Everything `EventText.redact` replaces, in the order it replaces it. */
|
|
235
|
+
static readonly PATTERNS: RegExp[] = [
|
|
236
|
+
EventSecrets.PRIVATE_KEY,
|
|
237
|
+
...EventSecrets.TOKENS,
|
|
238
|
+
...EventSecrets.HIGH_ENTROPY,
|
|
239
|
+
];
|
|
146
240
|
/** `user:password@host` inside a URL. */
|
|
147
241
|
static readonly URL_USERINFO = /(\/\/)[^\s/@:]+:[^\s/@]+@/g;
|
|
148
242
|
/** `name=value`, `name: value` and `"name": "value"` where the name says it is a secret. */
|
|
@@ -4,6 +4,12 @@ import type { EventKinds, EventStatuses } from './constants.ts';
|
|
|
4
4
|
export type TEventKind = TConstValue<typeof EventKinds>;
|
|
5
5
|
export type TEventStatus = TConstValue<typeof EventStatuses>;
|
|
6
6
|
|
|
7
|
+
/** One entry of a list on a flow line: a step or an acceptance check, and whether it is done. */
|
|
8
|
+
export interface IEventItem {
|
|
9
|
+
text: string;
|
|
10
|
+
done: boolean;
|
|
11
|
+
}
|
|
12
|
+
|
|
7
13
|
/** One line of the log. Field order is the order on disk. */
|
|
8
14
|
export interface IEvent {
|
|
9
15
|
id: string;
|
|
@@ -18,6 +24,20 @@ export interface IEvent {
|
|
|
18
24
|
ref?: string;
|
|
19
25
|
/** Only a `flow` has one: the one-line reason the flow exists. */
|
|
20
26
|
why?: string;
|
|
27
|
+
/** Only a `flow` has one: what the flow is, what is done and what is left, in a few sentences. */
|
|
28
|
+
context?: string;
|
|
29
|
+
/** Only a `flow` has one: the next step and who does it. */
|
|
30
|
+
next?: string;
|
|
31
|
+
/** Only a `flow` has them: what is to be done, each step as done or not, restated in full on every line. */
|
|
32
|
+
steps?: IEventItem[];
|
|
33
|
+
/** Only a `flow` has them: the acceptance checks, as `steps`. */
|
|
34
|
+
checks?: IEventItem[];
|
|
35
|
+
/** Only a `flow` has them: the apps or modules it touches. */
|
|
36
|
+
apps?: string[];
|
|
37
|
+
/** Only a `flow` has one: the day it is due, `YYYY-MM-DD`. */
|
|
38
|
+
due?: string;
|
|
39
|
+
/** Only a `session-start` the Claude Code hook wrote has one: the model of the session. */
|
|
40
|
+
model?: string;
|
|
21
41
|
/** Only a `needs-owner` the Claude Code hook wrote has one: the notification type that raised it. */
|
|
22
42
|
notification?: string;
|
|
23
43
|
source: string;
|
|
@@ -48,6 +68,8 @@ export interface IHookEvent {
|
|
|
48
68
|
ref?: string;
|
|
49
69
|
/** The notification type of a `needs-owner` line. */
|
|
50
70
|
notification?: string;
|
|
71
|
+
/** The model of a `session-start` line. */
|
|
72
|
+
model?: string;
|
|
51
73
|
/** Text a flow id may be read from: the first line of a message. */
|
|
52
74
|
flowText?: string;
|
|
53
75
|
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { closeSync, mkdirSync, openSync, readdirSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { EventConstants } from './common/index.ts';
|
|
4
|
+
import type { IEvent } from './common/index.ts';
|
|
5
|
+
import { EventLog } from './log.ts';
|
|
6
|
+
|
|
7
|
+
/** The number of a flow id of either format: `VULZ-ACME-15` or the older `F-15`. */
|
|
8
|
+
const NUMBER = /-(\d+)$/;
|
|
9
|
+
|
|
10
|
+
/** Flow ids: `VULZ-<key>-<number>`, the number given by VULCAN from a counter beside the log. */
|
|
11
|
+
export class FlowId {
|
|
12
|
+
/** The id as the board shows it: an older `F-n` becomes `VULZ-<key>-n`; with no key it stays. */
|
|
13
|
+
static canon(opts: { id: string; key?: string }): string {
|
|
14
|
+
return opts.key !== undefined && EventConstants.FLOW_LEGACY.test(opts.id)
|
|
15
|
+
? `${EventConstants.FLOW_PREFIX}-${opts.key}-${opts.id.slice(2)}`
|
|
16
|
+
: opts.id;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** The number inside an id of either format, or 0. */
|
|
20
|
+
static numberOf(opts: { id: string }): number {
|
|
21
|
+
const number = Number(NUMBER.exec(opts.id)?.[1] ?? 0);
|
|
22
|
+
|
|
23
|
+
return Number.isSafeInteger(number) ? number : 0;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** The ids the lines carry, newest first, in the form the board shows them. */
|
|
27
|
+
static recent(opts: { events: IEvent[]; key?: string; count: number }): string[] {
|
|
28
|
+
const seen = new Set<string>();
|
|
29
|
+
|
|
30
|
+
for (const event of [...opts.events].reverse()) {
|
|
31
|
+
if (event.flowId !== undefined) {
|
|
32
|
+
seen.add(FlowId.canon({ id: event.flowId, key: opts.key }));
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
if (seen.size >= opts.count) {
|
|
36
|
+
break;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
return [...seen];
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Whether any line of the log carries the flow, under either name of it. */
|
|
44
|
+
static exists(opts: { events: IEvent[]; id: string; key?: string }): boolean {
|
|
45
|
+
const wanted = FlowId.canon({ id: opts.id, key: opts.key });
|
|
46
|
+
|
|
47
|
+
return opts.events.some(
|
|
48
|
+
(event) =>
|
|
49
|
+
event.flowId !== undefined && FlowId.canon({ id: event.flowId, key: opts.key }) === wanted,
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* The next id for `key`. A number is claimed by creating the file `.flow-ids/<key>-<number>` beside the day files with
|
|
55
|
+
* `wx`, which only one process can do for a number: two processes never get the same id, and nothing is locked, so
|
|
56
|
+
* nothing can be left locked by a crash. The search starts above the highest number the log holds for the key (an older
|
|
57
|
+
* `F-n` counts) and above every claim already made, so a number is not given twice even after the retention dropped the
|
|
58
|
+
* day it was on; a claim that exists sends the search on to the next number.
|
|
59
|
+
*/
|
|
60
|
+
static next(opts: { dir: string; key: string }): string {
|
|
61
|
+
const claims = join(opts.dir, EventConstants.FLOW_CLAIM_DIR);
|
|
62
|
+
const prefix = `${EventConstants.FLOW_PREFIX}-${opts.key}-`;
|
|
63
|
+
|
|
64
|
+
mkdirSync(claims, { recursive: true });
|
|
65
|
+
|
|
66
|
+
const logged = EventLog.read({ dir: opts.dir }).events.flatMap((event) =>
|
|
67
|
+
event.flowId !== undefined &&
|
|
68
|
+
(event.flowId.startsWith(prefix) || EventConstants.FLOW_LEGACY.test(event.flowId))
|
|
69
|
+
? [FlowId.numberOf({ id: event.flowId })]
|
|
70
|
+
: [],
|
|
71
|
+
);
|
|
72
|
+
const claimed = readdirSync(claims)
|
|
73
|
+
.filter((name) => name.startsWith(`${opts.key}-`))
|
|
74
|
+
.map((name) => FlowId.numberOf({ id: name }))
|
|
75
|
+
.filter((number) => number > 0);
|
|
76
|
+
|
|
77
|
+
for (let number = Math.max(0, ...logged, ...claimed) + 1; ; number++) {
|
|
78
|
+
try {
|
|
79
|
+
closeSync(openSync(join(claims, `${opts.key}-${number}`), 'wx'));
|
|
80
|
+
|
|
81
|
+
return `${prefix}${number}`;
|
|
82
|
+
} catch (error) {
|
|
83
|
+
if (!(error instanceof Error) || !('code' in error) || error.code !== 'EEXIST') {
|
|
84
|
+
throw error;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
package/src/events/flow.ts
CHANGED
|
@@ -4,24 +4,24 @@ import { EventConstants } from './common/index.ts';
|
|
|
4
4
|
|
|
5
5
|
const GITDIR_LINE = /^gitdir:\s*(.+)$/m;
|
|
6
6
|
const HEAD_REF = /^ref:\s*refs\/heads\/(.+?)\s*$/m;
|
|
7
|
-
const BRANCH_FLOW =
|
|
7
|
+
const BRANCH_FLOW = new RegExp(`(?:^|/)(${EventConstants.FLOW_ID})(?=-|/|$)`);
|
|
8
8
|
/** Enough parents for a deep folder inside a project; the walk stops at the filesystem root anyway. */
|
|
9
9
|
const MAX_PARENTS = 40;
|
|
10
10
|
|
|
11
|
-
/** The flow a line of the log belongs to: `F
|
|
11
|
+
/** The flow a line of the log belongs to: `VULZ-<key>-<number>` (or the older `F-<number>`), from the writer, the first line of a message or the branch. */
|
|
12
12
|
export class EventFlow {
|
|
13
13
|
static isValid(opts: { flow: string }): boolean {
|
|
14
14
|
return EventConstants.FLOW_EXACT.test(opts.flow);
|
|
15
15
|
}
|
|
16
16
|
|
|
17
|
-
/** `Flow:
|
|
17
|
+
/** `Flow: <id>` in the first line of `text`. */
|
|
18
18
|
static fromText(opts: { text: string }): string | undefined {
|
|
19
19
|
const first = opts.text.split(/\r\n|\r|\n/).find((line) => line.trim() !== '') ?? '';
|
|
20
20
|
|
|
21
21
|
return EventConstants.FLOW_LINE.exec(first)?.[1];
|
|
22
22
|
}
|
|
23
23
|
|
|
24
|
-
/**
|
|
24
|
+
/** A flow id as a whole segment of a branch name: `feature/VULZ-ACME-12-events-log`. */
|
|
25
25
|
static fromBranchName(opts: { branch: string }): string | undefined {
|
|
26
26
|
return BRANCH_FLOW.exec(opts.branch)?.[1];
|
|
27
27
|
}
|