@venizia/vulcan 0.4.9-5 → 0.4.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/base/hooks/auto-clean.ts +22 -0
- package/base/hooks/session-start.ts +12 -0
- package/base/skills/retro/SKILL.md +2 -2
- package/base/templates/board.html +4697 -0
- package/package.json +3 -3
- package/src/board/command.ts +200 -0
- package/src/board/common/constants.ts +122 -0
- package/src/board/common/index.ts +2 -0
- package/src/board/common/types.ts +86 -0
- package/src/board/fold.ts +428 -0
- package/src/board/github.ts +255 -0
- package/src/board/index.ts +6 -0
- package/src/board/page.ts +26 -0
- package/src/board/settings.ts +106 -0
- package/src/commands/board.command.ts +5 -0
- package/src/commands/help.command.ts +5 -1
- package/src/commands/index.ts +2 -0
- package/src/common/constants.ts +1 -0
- package/src/config/schema.ts +59 -0
- package/src/doctor/checks.ts +29 -0
- package/src/doctor/common/constants.ts +1 -0
- package/src/doctor/runner.ts +1 -0
- package/src/events/command.ts +21 -2
- package/src/events/common/constants.ts +31 -0
- package/src/events/common/types.ts +15 -1
- package/src/events/index.ts +1 -0
- package/src/events/log.ts +7 -3
- package/src/events/retention.ts +172 -0
- package/src/events/settings.ts +12 -0
- package/src/local/auto-clean-run.ts +99 -0
- package/src/local/auto-clean.ts +147 -0
- package/src/local/clean.ts +33 -1
- package/src/local/constants.ts +1 -0
- package/src/local/index.ts +1 -0
- package/src/local/scan.ts +43 -6
- package/src/manifest/render.ts +36 -2
- package/src/router.ts +8 -0
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
import { existsSync, readdirSync, rmSync, statSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { EventConstants, EventSizeUnits } from './common/index.ts';
|
|
4
|
+
import type { IEventLimits, IEventSettings } from './common/index.ts';
|
|
5
|
+
import { EventLog } from './log.ts';
|
|
6
|
+
|
|
7
|
+
const DAY_FILE = /^(\d{4}-\d{2}-\d{2})\.jsonl$/;
|
|
8
|
+
|
|
9
|
+
export interface IRetentionFile {
|
|
10
|
+
name: string;
|
|
11
|
+
bytes: number;
|
|
12
|
+
/** Why it goes: `older than 30 days`, `more than 30 files`, `over the size limit`. */
|
|
13
|
+
reason: string;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export interface IRetentionPlan {
|
|
17
|
+
remove: IRetentionFile[];
|
|
18
|
+
/** Today's file is bigger than `maxSize` alone: nothing is truncated, `doctor` says so. */
|
|
19
|
+
todayOver: boolean;
|
|
20
|
+
todayBytes: number;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** How much of the event log is kept: whole day files go, oldest first, and today's file never does. */
|
|
24
|
+
export class EventRetention {
|
|
25
|
+
/** `50MB`, `1.5 GB`, `200mb` as bytes; `undefined` when the text is not a number with KB, MB or GB. */
|
|
26
|
+
static parseSize(opts: { text: string }): number | undefined {
|
|
27
|
+
const found = EventSizeUnits.PATTERN.exec(opts.text.trim());
|
|
28
|
+
|
|
29
|
+
return found === null
|
|
30
|
+
? undefined
|
|
31
|
+
: Math.floor(Number(found[1]) * (EventSizeUnits.BYTES[found[2].toUpperCase()] ?? 0));
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** The limits of a project: what the manifest sets, and the defaults for what it does not. */
|
|
35
|
+
static limitsOf(opts: { settings: IEventSettings }): IEventLimits {
|
|
36
|
+
const { settings } = opts;
|
|
37
|
+
|
|
38
|
+
return {
|
|
39
|
+
maxBytes:
|
|
40
|
+
EventRetention.parseSize({ text: settings.maxSize ?? EventConstants.DEFAULT_MAX_SIZE }) ??
|
|
41
|
+
0,
|
|
42
|
+
maxFiles: settings.maxFiles ?? EventConstants.DEFAULT_MAX_FILES,
|
|
43
|
+
maxAgeDays: settings.maxAgeDays ?? EventConstants.DEFAULT_MAX_AGE_DAYS,
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Whether the project keeps its log within limits: the log is on, or it set a limit itself. */
|
|
48
|
+
static isActive(opts: { settings: IEventSettings }): boolean {
|
|
49
|
+
const { settings } = opts;
|
|
50
|
+
|
|
51
|
+
return (
|
|
52
|
+
settings.log ||
|
|
53
|
+
settings.maxSize !== undefined ||
|
|
54
|
+
settings.maxFiles !== undefined ||
|
|
55
|
+
settings.maxAgeDays !== undefined
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* What goes from the folder `dir`. First every day file older than `maxAgeDays` days; then the oldest files, one by
|
|
61
|
+
* one, until the count is within `maxFiles` and the total within `maxBytes`. Today's file (of the local day of `now`)
|
|
62
|
+
* and a file of a later day are never in the list, even when today's alone is over the size, which `todayOver` then says.
|
|
63
|
+
*/
|
|
64
|
+
static plan(opts: { dir: string; limits: IEventLimits; now: number }): IRetentionPlan {
|
|
65
|
+
const empty: IRetentionPlan = { remove: [], todayOver: false, todayBytes: 0 };
|
|
66
|
+
|
|
67
|
+
if (!existsSync(opts.dir)) {
|
|
68
|
+
return empty;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
const today = EventLog.dayOf({ time: opts.now });
|
|
72
|
+
let names: string[];
|
|
73
|
+
|
|
74
|
+
try {
|
|
75
|
+
names = readdirSync(opts.dir);
|
|
76
|
+
} catch {
|
|
77
|
+
// Not a folder, or one that cannot be read: nothing to prune, and `doctor` says what is wrong with it.
|
|
78
|
+
return empty;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
const files = names
|
|
82
|
+
.flatMap((name) => {
|
|
83
|
+
const day = DAY_FILE.exec(name)?.[1];
|
|
84
|
+
|
|
85
|
+
return day === undefined
|
|
86
|
+
? []
|
|
87
|
+
: [{ name, day, bytes: EventRetention.sizeOf({ path: join(opts.dir, name) }) }];
|
|
88
|
+
})
|
|
89
|
+
.sort((left, right) => left.day.localeCompare(right.day));
|
|
90
|
+
const todayFile = files.find((file) => file.day === today);
|
|
91
|
+
const remove: IRetentionFile[] = [];
|
|
92
|
+
const todayStart = new Date(`${today}T00:00:00`).getTime();
|
|
93
|
+
const keep = files.filter((file) => {
|
|
94
|
+
const ageDays = Math.round(
|
|
95
|
+
(todayStart - new Date(`${file.day}T00:00:00`).getTime()) / EventConstants.DAY_MS,
|
|
96
|
+
);
|
|
97
|
+
|
|
98
|
+
if (file.day < today && ageDays > opts.limits.maxAgeDays) {
|
|
99
|
+
remove.push({
|
|
100
|
+
name: file.name,
|
|
101
|
+
bytes: file.bytes,
|
|
102
|
+
reason: `older than ${opts.limits.maxAgeDays} days`,
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
return false;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
return true;
|
|
109
|
+
});
|
|
110
|
+
let total = keep.reduce((sum, file) => sum + file.bytes, 0);
|
|
111
|
+
let count = keep.length;
|
|
112
|
+
|
|
113
|
+
for (const file of keep) {
|
|
114
|
+
// Today's file and any later one (a clock that is ahead, a writer past midnight) are never removed.
|
|
115
|
+
if (file.day >= today) {
|
|
116
|
+
continue;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
if (count <= opts.limits.maxFiles && total <= opts.limits.maxBytes) {
|
|
120
|
+
break;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
remove.push({
|
|
124
|
+
name: file.name,
|
|
125
|
+
bytes: file.bytes,
|
|
126
|
+
reason:
|
|
127
|
+
count > opts.limits.maxFiles
|
|
128
|
+
? `more than ${opts.limits.maxFiles} files`
|
|
129
|
+
: 'over the size limit',
|
|
130
|
+
});
|
|
131
|
+
total -= file.bytes;
|
|
132
|
+
count -= 1;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
return {
|
|
136
|
+
remove,
|
|
137
|
+
todayOver: todayFile !== undefined && todayFile.bytes > opts.limits.maxBytes,
|
|
138
|
+
todayBytes: todayFile?.bytes ?? 0,
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** Whether `name` is a day file of the log: `yyyy-mm-dd.jsonl`. */
|
|
143
|
+
static isDayFile(opts: { name: string }): boolean {
|
|
144
|
+
return DAY_FILE.test(opts.name);
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/** Removes the files of a plan; returns what went. A file that cannot be removed is left and not counted. */
|
|
148
|
+
static apply(opts: { dir: string; plan: IRetentionPlan }): { files: number; bytes: number } {
|
|
149
|
+
let files = 0;
|
|
150
|
+
let bytes = 0;
|
|
151
|
+
|
|
152
|
+
for (const file of opts.plan.remove) {
|
|
153
|
+
try {
|
|
154
|
+
rmSync(join(opts.dir, file.name), { force: true });
|
|
155
|
+
files += 1;
|
|
156
|
+
bytes += file.bytes;
|
|
157
|
+
} catch {
|
|
158
|
+
// Left in place; the next run tries again.
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
return { files, bytes };
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
private static sizeOf(opts: { path: string }): number {
|
|
166
|
+
try {
|
|
167
|
+
return statSync(opts.path).size;
|
|
168
|
+
} catch {
|
|
169
|
+
return 0;
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
}
|
package/src/events/settings.ts
CHANGED
|
@@ -3,6 +3,7 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
|
|
|
3
3
|
import { RecordValue } from '../common/record.ts';
|
|
4
4
|
import { EventConstants } from './common/index.ts';
|
|
5
5
|
import type { IEventSettings } from './common/index.ts';
|
|
6
|
+
import { EventRetention } from './retention.ts';
|
|
6
7
|
|
|
7
8
|
/** Where the log is and whether the Claude Code hooks write it: the `events` block of the manifest `vulcan sync` wrote. */
|
|
8
9
|
export class EventSettings {
|
|
@@ -38,11 +39,22 @@ export class EventSettings {
|
|
|
38
39
|
|
|
39
40
|
const { dir } = block;
|
|
40
41
|
|
|
42
|
+
const { maxSize, maxFiles, maxAgeDays } = block;
|
|
43
|
+
|
|
41
44
|
return {
|
|
42
45
|
log: block.log === true,
|
|
43
46
|
...(typeof dir === 'string' && EventSettings.dirError({ dir }) === undefined
|
|
44
47
|
? { dir }
|
|
45
48
|
: {}),
|
|
49
|
+
...(typeof maxSize === 'string' && EventRetention.parseSize({ text: maxSize }) !== undefined
|
|
50
|
+
? { maxSize }
|
|
51
|
+
: {}),
|
|
52
|
+
...(typeof maxFiles === 'number' && Number.isInteger(maxFiles) && maxFiles >= 1
|
|
53
|
+
? { maxFiles }
|
|
54
|
+
: {}),
|
|
55
|
+
...(typeof maxAgeDays === 'number' && Number.isInteger(maxAgeDays) && maxAgeDays >= 1
|
|
56
|
+
? { maxAgeDays }
|
|
57
|
+
: {}),
|
|
46
58
|
};
|
|
47
59
|
} catch {
|
|
48
60
|
return { log: false };
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import { lstatSync, readdirSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { EventRetention } from '../events/retention.ts';
|
|
4
|
+
import { EventSettings } from '../events/settings.ts';
|
|
5
|
+
import { LocalAutoClean } from './auto-clean.ts';
|
|
6
|
+
import { LocalClean } from './clean.ts';
|
|
7
|
+
import { CleanScopes, LocalStates } from './constants.ts';
|
|
8
|
+
import { LocalScan } from './scan.ts';
|
|
9
|
+
import { EventLog } from '../events/log.ts';
|
|
10
|
+
|
|
11
|
+
/** The safe part of `.agents/local/`, removed by itself. A wrong guess here would cost nothing a build or a day cannot give back. */
|
|
12
|
+
export class AutoCleanRun {
|
|
13
|
+
/**
|
|
14
|
+
* Removes: `tmp/` entries past their days and browser leftovers an hour old (scope `tmp`, state stale), release
|
|
15
|
+
* candidates whose version is tagged (state shipped), and event day files past the limits of `events`. A worktree
|
|
16
|
+
* or a clone is never scanned, let alone removed: those stay with `vulcan clean --yes` and the warnings of `vulcan doctor`.
|
|
17
|
+
* Writes the stamp with what went, for the next session to say once.
|
|
18
|
+
*/
|
|
19
|
+
static run(opts: { root: string; now?: number }): { files: number; bytes: number } {
|
|
20
|
+
const now = opts.now ?? Date.now();
|
|
21
|
+
const scanned = LocalScan.scan({
|
|
22
|
+
root: opts.root,
|
|
23
|
+
now,
|
|
24
|
+
only: [CleanScopes.TMP, CleanScopes.RELEASE_CANDIDATES],
|
|
25
|
+
});
|
|
26
|
+
// A folder that holds a repository (a clone, a worktree) is somebody's work: only `vulcan clean --yes` takes it, with its checks.
|
|
27
|
+
const remove = scanned.filter(
|
|
28
|
+
(entry) =>
|
|
29
|
+
entry.removable &&
|
|
30
|
+
(entry.state === LocalStates.STALE || entry.state === LocalStates.SHIPPED) &&
|
|
31
|
+
!AutoCleanRun.holdsRepository({ path: entry.path }),
|
|
32
|
+
);
|
|
33
|
+
const ran = LocalClean.run({ root: opts.root, plan: { remove, keep: [] } });
|
|
34
|
+
let files = ran.removed.length;
|
|
35
|
+
let bytes = ran.removed.reduce((sum, entry) => sum + entry.bytes, 0);
|
|
36
|
+
const settings = EventSettings.read({ root: opts.root });
|
|
37
|
+
|
|
38
|
+
if (EventRetention.isActive({ settings })) {
|
|
39
|
+
const dir = EventSettings.dirOf({ root: opts.root, settings });
|
|
40
|
+
const plan = EventRetention.plan({ dir, limits: EventRetention.limitsOf({ settings }), now });
|
|
41
|
+
const events = EventRetention.apply({ dir, plan });
|
|
42
|
+
|
|
43
|
+
files += events.files;
|
|
44
|
+
bytes += events.bytes;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const previous = LocalAutoClean.readStamp({ root: opts.root });
|
|
48
|
+
|
|
49
|
+
LocalAutoClean.writeStamp({
|
|
50
|
+
root: opts.root,
|
|
51
|
+
stamp: {
|
|
52
|
+
day: previous?.day ?? EventLog.dayOf({ time: now }),
|
|
53
|
+
startedAt: previous?.startedAt ?? new Date(now).toISOString(),
|
|
54
|
+
removedFiles: files,
|
|
55
|
+
removedBytes: bytes,
|
|
56
|
+
reported: false,
|
|
57
|
+
},
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
return { files, bytes };
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Whether `path`, or anything under it, is a `.git` file or folder (a clone has the folder, a worktree the file). A
|
|
65
|
+
* link is not followed and `node_modules` is not entered. A tree too big to look through counts as holding one.
|
|
66
|
+
*/
|
|
67
|
+
static holdsRepository(opts: { path: string; budget?: { left: number } }): boolean {
|
|
68
|
+
const budget = opts.budget ?? { left: AutoCleanRun.LOOK_LIMIT };
|
|
69
|
+
|
|
70
|
+
try {
|
|
71
|
+
if (!lstatSync(opts.path).isDirectory()) {
|
|
72
|
+
return false;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
for (const name of readdirSync(opts.path)) {
|
|
76
|
+
budget.left -= 1;
|
|
77
|
+
|
|
78
|
+
if (budget.left < 0 || name === '.git') {
|
|
79
|
+
return true;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
if (
|
|
83
|
+
name !== 'node_modules' &&
|
|
84
|
+
AutoCleanRun.holdsRepository({ path: join(opts.path, name), budget })
|
|
85
|
+
) {
|
|
86
|
+
return true;
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
return false;
|
|
91
|
+
} catch {
|
|
92
|
+
// What cannot be read cannot be judged: it stays.
|
|
93
|
+
return true;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** How many entries are looked at before a tree counts as holding a repository. */
|
|
98
|
+
static readonly LOOK_LIMIT = 20_000;
|
|
99
|
+
}
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
import { spawn } from 'node:child_process';
|
|
2
|
+
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
import { BASE_DIRECTORY } from '../common/paths.ts';
|
|
5
|
+
import { RecordValue } from '../common/record.ts';
|
|
6
|
+
import { EventLog } from '../events/log.ts';
|
|
7
|
+
import { LocalFormat } from './format.ts';
|
|
8
|
+
|
|
9
|
+
export interface IAutoCleanStamp {
|
|
10
|
+
/** The local day of the last run, `2026-11-03`. */
|
|
11
|
+
day: string;
|
|
12
|
+
startedAt: string;
|
|
13
|
+
removedFiles: number;
|
|
14
|
+
removedBytes: number;
|
|
15
|
+
/** Whether a session has already printed what that run removed. */
|
|
16
|
+
reported: boolean;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* The automatic clean of `.agents/local/`, as the session-start hook sees it: at most once a day it starts a detached
|
|
21
|
+
* process that removes the safe part (see `AutoCleanRun`) and leaves a stamp. Everything here is a stat and a read of two
|
|
22
|
+
* small files, so a session that finds nothing due does not wait.
|
|
23
|
+
*/
|
|
24
|
+
export class LocalAutoClean {
|
|
25
|
+
static readonly STAMP = '.agents/local/auto-clean.json';
|
|
26
|
+
static readonly OFF_ENV = 'VULCAN_AUTO_CLEAN';
|
|
27
|
+
static readonly SCRIPT = join('hooks', 'auto-clean.ts');
|
|
28
|
+
|
|
29
|
+
/** On unless the project's manifest says `local.autoClean: false`, or the environment says `VULCAN_AUTO_CLEAN=off`. */
|
|
30
|
+
static isEnabled(opts: { root: string; env: Record<string, string | undefined> }): boolean {
|
|
31
|
+
if (opts.env[LocalAutoClean.OFF_ENV] === 'off') {
|
|
32
|
+
return false;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
try {
|
|
36
|
+
const manifest: unknown = JSON.parse(
|
|
37
|
+
readFileSync(join(opts.root, '.agents/vulcan.manifest.json'), 'utf8'),
|
|
38
|
+
);
|
|
39
|
+
const local = RecordValue.isRecord(manifest) ? manifest.local : undefined;
|
|
40
|
+
|
|
41
|
+
return !(RecordValue.isRecord(local) && local.autoClean === false);
|
|
42
|
+
} catch {
|
|
43
|
+
return true;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
static readStamp(opts: { root: string }): IAutoCleanStamp | undefined {
|
|
48
|
+
try {
|
|
49
|
+
const value: unknown = JSON.parse(
|
|
50
|
+
readFileSync(join(opts.root, LocalAutoClean.STAMP), 'utf8'),
|
|
51
|
+
);
|
|
52
|
+
|
|
53
|
+
if (
|
|
54
|
+
RecordValue.isRecord(value) &&
|
|
55
|
+
typeof value.day === 'string' &&
|
|
56
|
+
typeof value.startedAt === 'string' &&
|
|
57
|
+
typeof value.removedFiles === 'number' &&
|
|
58
|
+
typeof value.removedBytes === 'number' &&
|
|
59
|
+
typeof value.reported === 'boolean'
|
|
60
|
+
) {
|
|
61
|
+
return {
|
|
62
|
+
day: value.day,
|
|
63
|
+
startedAt: value.startedAt,
|
|
64
|
+
removedFiles: value.removedFiles,
|
|
65
|
+
removedBytes: value.removedBytes,
|
|
66
|
+
reported: value.reported,
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
} catch {
|
|
70
|
+
// No stamp, or one that is not ours: the clean is due.
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
return undefined;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
static writeStamp(opts: { root: string; stamp: IAutoCleanStamp }): void {
|
|
77
|
+
writeFileSync(join(opts.root, LocalAutoClean.STAMP), `${JSON.stringify(opts.stamp)}\n`);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Called at session start. Does nothing when the project has no `.agents/local/`, turned the clean off, or already ran
|
|
82
|
+
* today. Otherwise it writes today's stamp first (a second session that starts a moment later finds it) and starts the
|
|
83
|
+
* clean in a process of its own that outlives the hook. Returns the one line to print, or `undefined`: the line says what the
|
|
84
|
+
* last finished run removed, once, because the run itself ends after the hook did.
|
|
85
|
+
*/
|
|
86
|
+
static tick(opts: {
|
|
87
|
+
root: string;
|
|
88
|
+
now?: number;
|
|
89
|
+
env?: Record<string, string | undefined>;
|
|
90
|
+
start?: (opts: { root: string }) => void;
|
|
91
|
+
}): string | undefined {
|
|
92
|
+
const now = opts.now ?? Date.now();
|
|
93
|
+
|
|
94
|
+
if (
|
|
95
|
+
!existsSync(join(opts.root, '.agents/local')) ||
|
|
96
|
+
!LocalAutoClean.isEnabled({ root: opts.root, env: opts.env ?? process.env })
|
|
97
|
+
) {
|
|
98
|
+
return undefined;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
const today = EventLog.dayOf({ time: now });
|
|
102
|
+
const stamp = LocalAutoClean.readStamp({ root: opts.root });
|
|
103
|
+
const pending =
|
|
104
|
+
stamp !== undefined && !stamp.reported && stamp.removedBytes > 0 ? stamp : undefined;
|
|
105
|
+
const line =
|
|
106
|
+
pending === undefined
|
|
107
|
+
? undefined
|
|
108
|
+
: `vulcan: cleaned ${LocalFormat.formatBytes({ bytes: pending.removedBytes })} from .agents/local`;
|
|
109
|
+
|
|
110
|
+
if (stamp?.day === today) {
|
|
111
|
+
if (pending !== undefined) {
|
|
112
|
+
LocalAutoClean.writeStamp({ root: opts.root, stamp: { ...pending, reported: true } });
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
return line;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
LocalAutoClean.writeStamp({
|
|
119
|
+
root: opts.root,
|
|
120
|
+
stamp: {
|
|
121
|
+
day: today,
|
|
122
|
+
startedAt: new Date(now).toISOString(),
|
|
123
|
+
removedFiles: 0,
|
|
124
|
+
removedBytes: 0,
|
|
125
|
+
reported: true,
|
|
126
|
+
},
|
|
127
|
+
});
|
|
128
|
+
(opts.start ?? LocalAutoClean.startDetached)({ root: opts.root });
|
|
129
|
+
|
|
130
|
+
return line;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** Starts `base/hooks/auto-clean.ts` for `root` as a detached process: the hook does not wait for it and its end does not matter to the session. */
|
|
134
|
+
static startDetached(opts: { root: string }): void {
|
|
135
|
+
const child = spawn(
|
|
136
|
+
process.execPath,
|
|
137
|
+
[join(BASE_DIRECTORY, LocalAutoClean.SCRIPT), opts.root],
|
|
138
|
+
{
|
|
139
|
+
detached: true,
|
|
140
|
+
stdio: 'ignore',
|
|
141
|
+
},
|
|
142
|
+
);
|
|
143
|
+
|
|
144
|
+
child.on('error', () => {});
|
|
145
|
+
child.unref();
|
|
146
|
+
}
|
|
147
|
+
}
|
package/src/local/clean.ts
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
import { spawnSync } from 'node:child_process';
|
|
2
2
|
import { existsSync, lstatSync, rmSync, unlinkSync } from 'node:fs';
|
|
3
|
-
import {
|
|
3
|
+
import { basename, dirname } from 'node:path';
|
|
4
|
+
import { EventRetention } from '../events/retention.ts';
|
|
5
|
+
import { EventSettings } from '../events/settings.ts';
|
|
6
|
+
import { CleanScopes, LocalConstants } from './constants.ts';
|
|
4
7
|
import { LocalScan } from './scan.ts';
|
|
5
8
|
import type { ILocalEntry } from './scan.ts';
|
|
6
9
|
|
|
@@ -17,10 +20,39 @@ const git = (opts: { cwd: string; args: string[] }): boolean =>
|
|
|
17
20
|
timeout: LocalConstants.GIT_TIMEOUT_MS,
|
|
18
21
|
}).status === 0;
|
|
19
22
|
|
|
23
|
+
/**
|
|
24
|
+
* Removes one day file of an event log kept outside the project. Only a plain file named `yyyy-mm-dd.jsonl`, directly
|
|
25
|
+
* in the folder the project's settings name, is ever removed; anything else is refused.
|
|
26
|
+
*/
|
|
27
|
+
const removeSharedEvent = (opts: { root: string; entry: ILocalEntry }): string | undefined => {
|
|
28
|
+
const { entry } = opts;
|
|
29
|
+
|
|
30
|
+
try {
|
|
31
|
+
if (
|
|
32
|
+
entry.scope !== CleanScopes.EVENTS ||
|
|
33
|
+
!EventRetention.isDayFile({ name: basename(entry.path) }) ||
|
|
34
|
+
dirname(entry.path) !== EventSettings.dirOf({ root: opts.root }) ||
|
|
35
|
+
!lstatSync(entry.path).isFile()
|
|
36
|
+
) {
|
|
37
|
+
return 'refused: not a day file in the folder events.dir names';
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
unlinkSync(entry.path);
|
|
41
|
+
|
|
42
|
+
return undefined;
|
|
43
|
+
} catch (error) {
|
|
44
|
+
return error instanceof Error ? error.message : String(error);
|
|
45
|
+
}
|
|
46
|
+
};
|
|
47
|
+
|
|
20
48
|
/** Removes one entry. Only a path inside `.agents/local/` is touched, and a symlink is unlinked, never followed. */
|
|
21
49
|
const removeEntry = (opts: { root: string; entry: ILocalEntry }): string | undefined => {
|
|
22
50
|
const { entry } = opts;
|
|
23
51
|
|
|
52
|
+
if (entry.outside === true) {
|
|
53
|
+
return removeSharedEvent({ root: opts.root, entry });
|
|
54
|
+
}
|
|
55
|
+
|
|
24
56
|
if (!LocalScan.isInside({ root: opts.root, path: entry.path })) {
|
|
25
57
|
return 'refused: the path is not inside .agents/local/';
|
|
26
58
|
}
|
package/src/local/constants.ts
CHANGED
package/src/local/index.ts
CHANGED
package/src/local/scan.ts
CHANGED
|
@@ -2,6 +2,8 @@ import { spawnSync } from 'node:child_process';
|
|
|
2
2
|
import { existsSync, lstatSync, readdirSync, realpathSync } from 'node:fs';
|
|
3
3
|
import { join, resolve, sep } from 'node:path';
|
|
4
4
|
import { ProjectLayout } from '../common/index.ts';
|
|
5
|
+
import { EventRetention } from '../events/retention.ts';
|
|
6
|
+
import { EventSettings } from '../events/settings.ts';
|
|
5
7
|
import { CleanScopes, LocalConstants, LocalStates } from './constants.ts';
|
|
6
8
|
|
|
7
9
|
/** One thing under `.agents/local/`: a child of one of its directories, or the profile file. */
|
|
@@ -19,6 +21,8 @@ export interface ILocalEntry {
|
|
|
19
21
|
isSymlink: boolean;
|
|
20
22
|
/** A registered git worktree: removed with `git worktree remove`, then pruned. */
|
|
21
23
|
registered: boolean;
|
|
24
|
+
/** A day file of an event log kept outside the project (`events.dir`): removed only after its folder is checked against the settings. */
|
|
25
|
+
outside?: boolean;
|
|
22
26
|
note: string;
|
|
23
27
|
}
|
|
24
28
|
|
|
@@ -416,7 +420,7 @@ export class LocalScan {
|
|
|
416
420
|
}
|
|
417
421
|
|
|
418
422
|
/** Every entry of `.agents/local/`, with size, age and what may be removed. Nothing is followed outside it. */
|
|
419
|
-
static scan(opts: { root: string; now?: number }): ILocalEntry[] {
|
|
423
|
+
static scan(opts: { root: string; now?: number; only?: string[] }): ILocalEntry[] {
|
|
420
424
|
const local = LocalScan.localRootOf({ root: opts.root });
|
|
421
425
|
const now = opts.now ?? Date.now();
|
|
422
426
|
|
|
@@ -424,11 +428,31 @@ export class LocalScan {
|
|
|
424
428
|
return [];
|
|
425
429
|
}
|
|
426
430
|
|
|
427
|
-
|
|
431
|
+
// `only` names the folders to look at: the automatic clean asks for two and never starts git for the worktrees.
|
|
432
|
+
const wants = (name: string): boolean => opts.only === undefined || opts.only.includes(name);
|
|
433
|
+
const registered = wants(CleanScopes.WORKTREES)
|
|
434
|
+
? LocalScan.registeredWorktrees({ root: opts.root })
|
|
435
|
+
: undefined;
|
|
428
436
|
const entries: ILocalEntry[] = [];
|
|
437
|
+
// The event log is where the project's settings put it (`events.dir`, else `.agents/local/events`), with its limits.
|
|
438
|
+
const eventSettings = EventSettings.read({ root: opts.root });
|
|
439
|
+
const eventsDir = EventSettings.dirOf({ root: opts.root, settings: eventSettings });
|
|
440
|
+
const eventPlan = wants(CleanScopes.EVENTS)
|
|
441
|
+
? EventRetention.plan({
|
|
442
|
+
dir: eventsDir,
|
|
443
|
+
limits: EventRetention.limitsOf({ settings: eventSettings }),
|
|
444
|
+
now,
|
|
445
|
+
})
|
|
446
|
+
: undefined;
|
|
447
|
+
const isEventsOutside = !`${eventsDir}${sep}`.startsWith(`${local}${sep}`);
|
|
429
448
|
|
|
430
449
|
for (const layout of ProjectLayout.LOCAL_LAYOUT) {
|
|
431
|
-
|
|
450
|
+
if (!wants(layout.name)) {
|
|
451
|
+
continue;
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
const isEvents = layout.name === CleanScopes.EVENTS;
|
|
455
|
+
const directory = isEvents ? eventsDir : join(local, layout.name);
|
|
432
456
|
|
|
433
457
|
if (!isRealDirectory({ path: directory })) {
|
|
434
458
|
continue;
|
|
@@ -457,6 +481,17 @@ export class LocalScan {
|
|
|
457
481
|
});
|
|
458
482
|
|
|
459
483
|
({ state, removable, registered: isRegistered, note } = verdict);
|
|
484
|
+
} else if (layout.name === CleanScopes.EVENTS) {
|
|
485
|
+
// Day files are removed by the limits of `events` (age, count, size), never all at once and never today's.
|
|
486
|
+
const goes = eventPlan?.remove.find((file) => file.name === name);
|
|
487
|
+
|
|
488
|
+
({ removable, note } =
|
|
489
|
+
goes === undefined
|
|
490
|
+
? {
|
|
491
|
+
removable: false,
|
|
492
|
+
note: 'within the limits of events (maxSize, maxFiles, maxAgeDays)',
|
|
493
|
+
}
|
|
494
|
+
: { removable: true, note: goes.reason });
|
|
460
495
|
} else if (layout.name === CleanScopes.RELEASE_CANDIDATES) {
|
|
461
496
|
// A candidate is named by its version: once that version is tagged the release has shipped.
|
|
462
497
|
const isShipped =
|
|
@@ -483,7 +518,8 @@ export class LocalScan {
|
|
|
483
518
|
entries.push({
|
|
484
519
|
scope: layout.name,
|
|
485
520
|
name,
|
|
486
|
-
|
|
521
|
+
// An event log kept outside the project is named by its whole path.
|
|
522
|
+
where: isEvents && isEventsOutside ? path : `${layout.name}/${name}`,
|
|
487
523
|
path,
|
|
488
524
|
bytes: sizeOf({ path }),
|
|
489
525
|
ageMs,
|
|
@@ -492,13 +528,14 @@ export class LocalScan {
|
|
|
492
528
|
isSymlink: stat.isSymbolicLink(),
|
|
493
529
|
registered: isRegistered,
|
|
494
530
|
note,
|
|
531
|
+
...(isEvents && isEventsOutside ? { outside: true } : {}),
|
|
495
532
|
});
|
|
496
533
|
}
|
|
497
534
|
}
|
|
498
535
|
|
|
499
536
|
const profile = join(local, 'profile.json');
|
|
500
537
|
|
|
501
|
-
if (existsSync(profile)) {
|
|
538
|
+
if (wants(CleanScopes.PROFILE) && existsSync(profile)) {
|
|
502
539
|
const stat = lstatSync(profile);
|
|
503
540
|
|
|
504
541
|
entries.push({
|
|
@@ -516,7 +553,7 @@ export class LocalScan {
|
|
|
516
553
|
});
|
|
517
554
|
}
|
|
518
555
|
|
|
519
|
-
return [...entries, ...LocalScan.strays({ local, now })];
|
|
556
|
+
return [...entries, ...(wants(CleanScopes.TMP) ? LocalScan.strays({ local, now }) : [])];
|
|
520
557
|
}
|
|
521
558
|
|
|
522
559
|
/**
|
package/src/manifest/render.ts
CHANGED
|
@@ -79,9 +79,39 @@ const ciBlockOf = (opts: { config: TResolvedConfig }): { ci?: Record<string, unk
|
|
|
79
79
|
|
|
80
80
|
/** The manifest's `events` block, which the hooks and `vulcan event` read: only when the log is on or has a folder. */
|
|
81
81
|
const eventsBlockOf = (opts: { config: TResolvedConfig }): { events?: Record<string, unknown> } => {
|
|
82
|
-
const { log, dir } = opts.config.events;
|
|
82
|
+
const { log, dir, maxSize, maxFiles, maxAgeDays } = opts.config.events;
|
|
83
|
+
const limits = {
|
|
84
|
+
...(maxSize === undefined ? {} : { maxSize }),
|
|
85
|
+
...(maxFiles === undefined ? {} : { maxFiles }),
|
|
86
|
+
...(maxAgeDays === undefined ? {} : { maxAgeDays }),
|
|
87
|
+
};
|
|
88
|
+
|
|
89
|
+
return log || dir !== undefined || Object.keys(limits).length > 0
|
|
90
|
+
? { events: { log, ...(dir === undefined ? {} : { dir }), ...limits } }
|
|
91
|
+
: {};
|
|
92
|
+
};
|
|
83
93
|
|
|
84
|
-
|
|
94
|
+
/** The manifest's `local` block: only when the project turns the automatic clean off, which the hook reads. */
|
|
95
|
+
const localBlockOf = (opts: { config: TResolvedConfig }): { local?: Record<string, unknown> } =>
|
|
96
|
+
opts.config.local.autoClean ? {} : { local: { autoClean: false } };
|
|
97
|
+
|
|
98
|
+
/** The manifest's `board` block, which `vulcan board` reads: only what the project sets. */
|
|
99
|
+
const boardBlockOf = (opts: { config: TResolvedConfig }): { board?: Record<string, unknown> } => {
|
|
100
|
+
const { owner, title, logo, agents } = opts.config.board;
|
|
101
|
+
|
|
102
|
+
return owner === undefined &&
|
|
103
|
+
title === undefined &&
|
|
104
|
+
logo === undefined &&
|
|
105
|
+
Object.keys(agents).length === 0
|
|
106
|
+
? {}
|
|
107
|
+
: {
|
|
108
|
+
board: {
|
|
109
|
+
...(owner === undefined ? {} : { owner }),
|
|
110
|
+
...(title === undefined ? {} : { title }),
|
|
111
|
+
...(logo === undefined ? {} : { logo }),
|
|
112
|
+
...(Object.keys(agents).length === 0 ? {} : { agents }),
|
|
113
|
+
},
|
|
114
|
+
};
|
|
85
115
|
};
|
|
86
116
|
|
|
87
117
|
/** The manifest's `atlas` block: only what the config sets (keys listed, the download turned off). */
|
|
@@ -180,6 +210,10 @@ export class ProjectManifest {
|
|
|
180
210
|
...commitBlockOf({ config }),
|
|
181
211
|
// The files the project adds to the ones that make every package affected; none added, nothing is written.
|
|
182
212
|
...ciBlockOf({ config }),
|
|
213
|
+
// The names and the logo `vulcan board` puts on its page; nothing set, nothing is written.
|
|
214
|
+
...boardBlockOf({ config }),
|
|
215
|
+
// The automatic clean of .agents/local is on unless the project turns it off here.
|
|
216
|
+
...localBlockOf({ config }),
|
|
183
217
|
// Whether the Claude Code hooks write the agent event log, and the folder it goes to.
|
|
184
218
|
...eventsBlockOf({ config }),
|
|
185
219
|
};
|