@venizia/vulcan 0.4.9-4 → 0.4.9-5
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/ci-global.json +13 -0
- package/base/claude/events.json +60 -0
- package/base/hooks/event.ts +37 -0
- package/base/rules.md +1 -1
- package/base/templates/ci/github-actions.yml +75 -0
- package/base/templates/ci/gitlab-ci.yml +52 -0
- package/package.json +3 -3
- package/src/ci/affected.ts +176 -0
- package/src/ci/command.ts +166 -0
- package/src/ci/common/constants.ts +76 -0
- package/src/ci/common/index.ts +2 -0
- package/src/ci/common/types.ts +37 -0
- package/src/ci/git.ts +72 -0
- package/src/ci/global.ts +48 -0
- package/src/ci/graph.ts +43 -0
- package/src/ci/index.ts +7 -0
- package/src/ci/workspace.ts +119 -0
- package/src/commands/ci.command.ts +4 -0
- package/src/commands/clean.command.ts +3 -5
- package/src/commands/event.command.ts +5 -0
- package/src/commands/help.command.ts +10 -2
- package/src/commands/index.ts +3 -0
- package/src/common/constants.ts +10 -0
- package/src/config/common/constants.ts +1 -0
- package/src/config/schema.ts +49 -0
- package/src/doctor/checks.ts +81 -7
- package/src/doctor/common/constants.ts +1 -0
- package/src/doctor/runner.ts +2 -0
- package/src/events/actor.ts +116 -0
- package/src/events/command.ts +191 -0
- package/src/events/common/constants.ts +118 -0
- package/src/events/common/index.ts +2 -0
- package/src/events/common/types.ts +39 -0
- package/src/events/flow.ts +92 -0
- package/src/events/hook.ts +163 -0
- package/src/events/index.ts +8 -0
- package/src/events/log.ts +162 -0
- package/src/events/settings.ts +80 -0
- package/src/events/text.ts +49 -0
- package/src/local/constants.ts +36 -1
- package/src/local/scan.ts +256 -27
- package/src/manifest/render.ts +18 -0
- package/src/router.ts +24 -0
- package/src/sync/common/constants.ts +2 -0
- package/src/sync/local-choice.ts +3 -3
- package/src/sync/planner.ts +10 -1
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { TConstValue } from '../../common/index.ts';
|
|
2
|
+
import type { AffectedReasons, CiChecks } from './constants.ts';
|
|
3
|
+
|
|
4
|
+
export type TCiCheck = TConstValue<typeof CiChecks>;
|
|
5
|
+
export type TAffectedReason = TConstValue<typeof AffectedReasons>;
|
|
6
|
+
|
|
7
|
+
/** A package of the workspace, as its `package.json` says. */
|
|
8
|
+
export interface IWorkspacePackage {
|
|
9
|
+
name: string;
|
|
10
|
+
/** Relative to the root, with `/`. */
|
|
11
|
+
dir: string;
|
|
12
|
+
scripts: Record<string, string>;
|
|
13
|
+
/** Every dependency of every field: the name and the spec it is declared with. */
|
|
14
|
+
dependencies: IDependency[];
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export interface IDependency {
|
|
18
|
+
name: string;
|
|
19
|
+
spec: string;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export interface IAffectedPackage {
|
|
23
|
+
name: string;
|
|
24
|
+
dir: string;
|
|
25
|
+
reason: TAffectedReason;
|
|
26
|
+
/** The checks the package has: the check name to the script that runs it. */
|
|
27
|
+
checks: Partial<Record<TCiCheck, string>>;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface IAffectedResult {
|
|
31
|
+
base: string;
|
|
32
|
+
head: string;
|
|
33
|
+
/** Whether every package is on the list, and the file or the fact that made it so. */
|
|
34
|
+
all: boolean;
|
|
35
|
+
allBecause?: string;
|
|
36
|
+
packages: IAffectedPackage[];
|
|
37
|
+
}
|
package/src/ci/git.ts
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { spawnSync } from 'node:child_process';
|
|
2
|
+
import { CiConstants } from './common/index.ts';
|
|
3
|
+
|
|
4
|
+
type TGitResult = { ok: true; stdout: string } | { ok: false; error: string };
|
|
5
|
+
|
|
6
|
+
/** The few read-only git questions the command asks. */
|
|
7
|
+
export class CiGit {
|
|
8
|
+
static run(opts: { root: string; args: string[] }): TGitResult {
|
|
9
|
+
const result = spawnSync('git', opts.args, {
|
|
10
|
+
cwd: opts.root,
|
|
11
|
+
encoding: 'utf8',
|
|
12
|
+
timeout: CiConstants.GIT_TIMEOUT_MS,
|
|
13
|
+
maxBuffer: CiConstants.GIT_MAX_BUFFER,
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
if (result.error !== undefined) {
|
|
17
|
+
return { ok: false, error: `git could not run: ${result.error.message}` };
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
return result.status === 0
|
|
21
|
+
? { ok: true, stdout: result.stdout }
|
|
22
|
+
: { ok: false, error: result.stderr.trim() || `git ${opts.args[0]} exited ${result.status}` };
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** The commit a revision names, or the reason it names none. */
|
|
26
|
+
static resolve(opts: { root: string; ref: string }): TGitResult {
|
|
27
|
+
const result = CiGit.run({
|
|
28
|
+
root: opts.root,
|
|
29
|
+
args: ['rev-parse', '--verify', '--quiet', '--end-of-options', `${opts.ref}^{commit}`],
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
return result.ok
|
|
33
|
+
? { ok: true, stdout: result.stdout.trim() }
|
|
34
|
+
: {
|
|
35
|
+
ok: false,
|
|
36
|
+
error: `${opts.ref} is not a commit here (a shallow clone has only the recent ones: fetch-depth 0 in GitHub Actions, GIT_DEPTH 0 in GitLab CI)`,
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** The files that differ between the merge base of two commits and the second one, deletions and both sides of a rename included. */
|
|
41
|
+
static changedFiles(opts: {
|
|
42
|
+
root: string;
|
|
43
|
+
base: string;
|
|
44
|
+
head: string;
|
|
45
|
+
}): { ok: true; files: string[]; mergeBase: string } | { ok: false; error: string } {
|
|
46
|
+
const mergeBase = CiGit.run({ root: opts.root, args: ['merge-base', opts.base, opts.head] });
|
|
47
|
+
|
|
48
|
+
if (!mergeBase.ok) {
|
|
49
|
+
return {
|
|
50
|
+
ok: false,
|
|
51
|
+
error: `${opts.base} and ${opts.head} share no history here (a shallow clone cuts it: fetch-depth 0 in GitHub Actions, GIT_DEPTH 0 in GitLab CI)`,
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
const point = mergeBase.stdout.trim();
|
|
56
|
+
const diff = CiGit.run({
|
|
57
|
+
root: opts.root,
|
|
58
|
+
args: ['diff', '--name-only', '--no-renames', '-z', point, opts.head],
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
return diff.ok
|
|
62
|
+
? { ok: true, files: diff.stdout.split('\0').filter((file) => file !== ''), mergeBase: point }
|
|
63
|
+
: { ok: false, error: diff.error };
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** The text of a file at a commit, or `undefined` when the commit has no such file. */
|
|
67
|
+
static show(opts: { root: string; commit: string; path: string }): string | undefined {
|
|
68
|
+
const result = CiGit.run({ root: opts.root, args: ['show', `${opts.commit}:${opts.path}`] });
|
|
69
|
+
|
|
70
|
+
return result.ok ? result.stdout : undefined;
|
|
71
|
+
}
|
|
72
|
+
}
|
package/src/ci/global.ts
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { BASE_DIRECTORY } from '../common/paths.ts';
|
|
4
|
+
import { RecordValue } from '../common/record.ts';
|
|
5
|
+
import { CiConstants } from './common/index.ts';
|
|
6
|
+
|
|
7
|
+
/** The files every package depends on: when one changes, all of them are affected. */
|
|
8
|
+
export class CiGlobal {
|
|
9
|
+
/** The shipped list (data, `base/ci-global.json`) and the project's own from the manifest. */
|
|
10
|
+
static read(opts: { root: string }): string[] {
|
|
11
|
+
return [...CiGlobal.shipped(), ...CiGlobal.project({ root: opts.root })];
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/** The first file of `files` that matches one of `globs` (root-relative, dotfiles included). */
|
|
15
|
+
static firstHit(opts: { files: string[]; globs: string[] }): string | undefined {
|
|
16
|
+
const matchers = opts.globs.map((glob) => new Bun.Glob(glob));
|
|
17
|
+
|
|
18
|
+
return opts.files.find((file) => matchers.some((matcher) => matcher.match(file)));
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
private static shipped(): string[] {
|
|
22
|
+
const list: unknown = JSON.parse(
|
|
23
|
+
readFileSync(join(BASE_DIRECTORY, CiConstants.GLOBAL_FILE), 'utf8'),
|
|
24
|
+
);
|
|
25
|
+
|
|
26
|
+
return RecordValue.isRecord(list) ? CiGlobal.stringsOf({ value: list.files }) : [];
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
private static project(opts: { root: string }): string[] {
|
|
30
|
+
try {
|
|
31
|
+
const manifest: unknown = JSON.parse(
|
|
32
|
+
readFileSync(join(opts.root, CiConstants.MANIFEST_FILE), 'utf8'),
|
|
33
|
+
);
|
|
34
|
+
const ci = RecordValue.isRecord(manifest) ? manifest.ci : undefined;
|
|
35
|
+
const affected = RecordValue.isRecord(ci) ? ci.affected : undefined;
|
|
36
|
+
|
|
37
|
+
return RecordValue.isRecord(affected) ? CiGlobal.stringsOf({ value: affected.global }) : [];
|
|
38
|
+
} catch {
|
|
39
|
+
return [];
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
private static stringsOf(opts: { value: unknown }): string[] {
|
|
44
|
+
return Array.isArray(opts.value)
|
|
45
|
+
? opts.value.filter((entry): entry is string => typeof entry === 'string' && entry !== '')
|
|
46
|
+
: [];
|
|
47
|
+
}
|
|
48
|
+
}
|
package/src/ci/graph.ts
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { AffectedReasons } from './common/index.ts';
|
|
2
|
+
import type { IWorkspacePackage, TAffectedReason } from './common/index.ts';
|
|
3
|
+
|
|
4
|
+
/** Who depends on whom, inside the workspace. */
|
|
5
|
+
export class CiGraph {
|
|
6
|
+
/**
|
|
7
|
+
* `seeds` and every package that depends on one, directly or through others, each with the reason it is
|
|
8
|
+
* on the list: a seed keeps its own, the others are `dependent`. A dependency on a workspace package
|
|
9
|
+
* counts whatever its spec is (`workspace:*`, a range, `catalog:`), which can only add a package, never
|
|
10
|
+
* lose one. Cycles end.
|
|
11
|
+
*/
|
|
12
|
+
static closure(opts: {
|
|
13
|
+
packages: IWorkspacePackage[];
|
|
14
|
+
seeds: Map<string, TAffectedReason>;
|
|
15
|
+
}): Map<string, TAffectedReason> {
|
|
16
|
+
const names = new Set(opts.packages.map((entry) => entry.name));
|
|
17
|
+
const dependents = new Map<string, string[]>();
|
|
18
|
+
|
|
19
|
+
for (const entry of opts.packages) {
|
|
20
|
+
for (const dependency of entry.dependencies) {
|
|
21
|
+
if (names.has(dependency.name) && dependency.name !== entry.name) {
|
|
22
|
+
dependents.set(dependency.name, [...(dependents.get(dependency.name) ?? []), entry.name]);
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
const reached = new Map<string, TAffectedReason>(opts.seeds);
|
|
28
|
+
const queue = [...opts.seeds.keys()];
|
|
29
|
+
|
|
30
|
+
while (queue.length > 0) {
|
|
31
|
+
const name = queue.shift() ?? '';
|
|
32
|
+
|
|
33
|
+
for (const dependent of dependents.get(name) ?? []) {
|
|
34
|
+
if (!reached.has(dependent)) {
|
|
35
|
+
reached.set(dependent, AffectedReasons.DEPENDENT);
|
|
36
|
+
queue.push(dependent);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
return reached;
|
|
42
|
+
}
|
|
43
|
+
}
|
package/src/ci/index.ts
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
2
|
+
import { dirname, join } from 'node:path';
|
|
3
|
+
import { RecordValue } from '../common/record.ts';
|
|
4
|
+
import { CiConstants } from './common/index.ts';
|
|
5
|
+
import type { IDependency, IWorkspacePackage } from './common/index.ts';
|
|
6
|
+
|
|
7
|
+
type TWorkspaceRead = { ok: true; packages: IWorkspacePackage[] } | { ok: false; error: string };
|
|
8
|
+
|
|
9
|
+
/** The packages of the workspace: the folders the root `package.json` lists in `workspaces`. */
|
|
10
|
+
export class CiWorkspace {
|
|
11
|
+
/**
|
|
12
|
+
* Every folder with a `package.json` that the `workspaces` globs match (an array, or an object with
|
|
13
|
+
* `packages`; a `!` glob removes), with a name, sorted by folder. `node_modules` is never searched.
|
|
14
|
+
*/
|
|
15
|
+
static read(opts: { root: string }): TWorkspaceRead {
|
|
16
|
+
const file = join(opts.root, CiConstants.ROOT_MANIFEST);
|
|
17
|
+
|
|
18
|
+
if (!existsSync(file)) {
|
|
19
|
+
return { ok: false, error: `no ${CiConstants.ROOT_MANIFEST} in ${opts.root}` };
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
let manifest: unknown;
|
|
23
|
+
|
|
24
|
+
try {
|
|
25
|
+
manifest = JSON.parse(readFileSync(file, 'utf8'));
|
|
26
|
+
} catch (error) {
|
|
27
|
+
return {
|
|
28
|
+
ok: false,
|
|
29
|
+
error: `${CiConstants.ROOT_MANIFEST} is not JSON: ${error instanceof Error ? error.message : String(error)}`,
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const globs = RecordValue.isRecord(manifest)
|
|
34
|
+
? CiWorkspace.globsOf({ value: manifest.workspaces })
|
|
35
|
+
: [];
|
|
36
|
+
|
|
37
|
+
if (globs.length === 0) {
|
|
38
|
+
return { ok: false, error: `${CiConstants.ROOT_MANIFEST} lists no workspaces` };
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const include = globs.filter((glob) => !glob.startsWith('!'));
|
|
42
|
+
// `!apps/old/**` leaves out the folder itself too, which the glob alone does not match.
|
|
43
|
+
const exclude = globs
|
|
44
|
+
.filter((glob) => glob.startsWith('!'))
|
|
45
|
+
.flatMap((glob) => [glob.slice(1), glob.slice(1).replace(/\/\*\*$/, '')])
|
|
46
|
+
.map((pattern) => new Bun.Glob(pattern));
|
|
47
|
+
const dirs = new Set<string>();
|
|
48
|
+
|
|
49
|
+
for (const glob of include) {
|
|
50
|
+
const scan = new Bun.Glob(`${glob.replace(/\/+$/, '')}/${CiConstants.ROOT_MANIFEST}`);
|
|
51
|
+
|
|
52
|
+
for (const match of scan.scanSync({ cwd: opts.root, onlyFiles: true })) {
|
|
53
|
+
const dir = dirname(match).split('\\').join('/');
|
|
54
|
+
|
|
55
|
+
if (
|
|
56
|
+
!dir.split('/').includes('node_modules') &&
|
|
57
|
+
!exclude.some((pattern) => pattern.match(dir))
|
|
58
|
+
) {
|
|
59
|
+
dirs.add(dir);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const packages = [...dirs]
|
|
65
|
+
.sort()
|
|
66
|
+
.flatMap((dir) => CiWorkspace.packageAt({ root: opts.root, dir }) ?? []);
|
|
67
|
+
|
|
68
|
+
return { ok: true, packages };
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
private static globsOf(opts: { value: unknown }): string[] {
|
|
72
|
+
const list = Array.isArray(opts.value)
|
|
73
|
+
? opts.value
|
|
74
|
+
: RecordValue.isRecord(opts.value) && Array.isArray(opts.value.packages)
|
|
75
|
+
? opts.value.packages
|
|
76
|
+
: [];
|
|
77
|
+
|
|
78
|
+
return list.filter((entry): entry is string => typeof entry === 'string' && entry !== '');
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
private static packageAt(opts: { root: string; dir: string }): IWorkspacePackage | undefined {
|
|
82
|
+
let manifest: unknown;
|
|
83
|
+
|
|
84
|
+
try {
|
|
85
|
+
manifest = JSON.parse(
|
|
86
|
+
readFileSync(join(opts.root, opts.dir, CiConstants.ROOT_MANIFEST), 'utf8'),
|
|
87
|
+
);
|
|
88
|
+
} catch {
|
|
89
|
+
return undefined;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
if (
|
|
93
|
+
!RecordValue.isRecord(manifest) ||
|
|
94
|
+
typeof manifest.name !== 'string' ||
|
|
95
|
+
manifest.name === ''
|
|
96
|
+
) {
|
|
97
|
+
return undefined;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
const scripts = RecordValue.isRecord(manifest.scripts)
|
|
101
|
+
? Object.fromEntries(
|
|
102
|
+
Object.entries(manifest.scripts).filter(
|
|
103
|
+
(entry): entry is [string, string] => typeof entry[1] === 'string',
|
|
104
|
+
),
|
|
105
|
+
)
|
|
106
|
+
: {};
|
|
107
|
+
const dependencies: IDependency[] = CiConstants.DEPENDENCY_FIELDS.flatMap((field) => {
|
|
108
|
+
const block = manifest[field];
|
|
109
|
+
|
|
110
|
+
return RecordValue.isRecord(block)
|
|
111
|
+
? Object.entries(block)
|
|
112
|
+
.filter((entry): entry is [string, string] => typeof entry[1] === 'string')
|
|
113
|
+
.map(([name, spec]) => ({ name, spec }))
|
|
114
|
+
: [];
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
return { name: manifest.name, dir: opts.dir, scripts, dependencies };
|
|
118
|
+
}
|
|
119
|
+
}
|
|
@@ -10,7 +10,7 @@ const lineOf = (opts: { entry: ILocalEntry }): string => {
|
|
|
10
10
|
const { entry } = opts;
|
|
11
11
|
const note = entry.note === '' ? (entry.state === 'stale' ? 'stale' : '') : entry.note;
|
|
12
12
|
|
|
13
|
-
return ` ${entry.
|
|
13
|
+
return ` ${entry.where} ${LocalFormat.formatBytes({ bytes: entry.bytes })} ${LocalFormat.formatAge({ ageMs: entry.ageMs })}${note === '' ? '' : ` ${note}`}`;
|
|
14
14
|
};
|
|
15
15
|
|
|
16
16
|
/**
|
|
@@ -45,7 +45,7 @@ export const runCleanCommand = async (opts: ICommandContext): Promise<number> =>
|
|
|
45
45
|
}
|
|
46
46
|
|
|
47
47
|
for (const entry of plan.keep) {
|
|
48
|
-
process.stderr.write(` kept ${entry.
|
|
48
|
+
process.stderr.write(` kept ${entry.where} ${entry.note}\n`);
|
|
49
49
|
}
|
|
50
50
|
|
|
51
51
|
if (!yes) {
|
|
@@ -59,9 +59,7 @@ export const runCleanCommand = async (opts: ICommandContext): Promise<number> =>
|
|
|
59
59
|
const result = LocalClean.run({ root: opts.cwd, plan });
|
|
60
60
|
|
|
61
61
|
for (const failure of result.failed) {
|
|
62
|
-
process.stderr.write(
|
|
63
|
-
` failed ${failure.entry.scope}/${failure.entry.name}: ${failure.error}\n`,
|
|
64
|
-
);
|
|
62
|
+
process.stderr.write(` failed ${failure.entry.where}: ${failure.error}\n`);
|
|
65
63
|
}
|
|
66
64
|
|
|
67
65
|
process.stderr.write(
|
|
@@ -31,6 +31,14 @@ Usage: bun x vulcan <command>
|
|
|
31
31
|
Check a commit message against the commit.message checks of the config (an
|
|
32
32
|
agent in a trailer or a "generated with" line, the project's subject shape);
|
|
33
33
|
sync installs it as the commit-msg hook; exit 1 on a problem, 2 on bad input
|
|
34
|
+
ci affected --base <ref> [--head <ref>] [--check <check>] [--json | --names] | template <github|gitlab>
|
|
35
|
+
List the workspace packages a change touches (changed ones and what
|
|
36
|
+
depends on them) with the checks each has; template prints a CI file that
|
|
37
|
+
runs exactly those; exit 2 on bad input
|
|
38
|
+
event add --kind <k> --summary <text> [--flow F-n] [--ref <r>] | tail [--since <time>] [--json] [--dir <folder>]
|
|
39
|
+
Write a line to the agent event log (.agents/local/events/<day>.jsonl) or
|
|
40
|
+
read it; with events.log on, sync installs the Claude Code hooks that
|
|
41
|
+
write it; exit 2 on bad input
|
|
34
42
|
visualize <spec.json> [--out <name>] | --schema
|
|
35
43
|
Make one small static HTML page (a flow, a status, a before and after) from
|
|
36
44
|
a JSON spec, in .agents/local/prototypes/; --schema prints the spec's schema
|
|
@@ -38,10 +46,10 @@ Usage: bun x vulcan <command>
|
|
|
38
46
|
Tell VULCAN how you like to work (reply language, how to address you,
|
|
39
47
|
tone, habits) in .agents/local/profile.json; no argument runs the form,
|
|
40
48
|
show prints it, reset deletes it
|
|
41
|
-
clean [--tmp|--worktrees|--clones|--cache|--all] [--reports|--prototypes|--profile] [--yes]
|
|
49
|
+
clean [--tmp|--worktrees|--clones|--cache|--all] [--reports|--prototypes|--events|--release-candidates|--profile] [--yes]
|
|
42
50
|
List what an agent left under .agents/local/ (a dry run) and, with
|
|
43
51
|
--yes, remove it; --tmp is the default, --worktrees takes merged or
|
|
44
|
-
gone branches only, --all never touches reports, prototypes or the profile
|
|
52
|
+
gone branches only, --all never touches reports, prototypes, events, release candidates or the profile
|
|
45
53
|
upgrade [--stable | --nightly] [<version|tag>]
|
|
46
54
|
Bump the pinned @venizia/vulcan, then sync; --stable (default)
|
|
47
55
|
takes the latest tag, --nightly the newest of latest and next
|
package/src/commands/index.ts
CHANGED
|
@@ -6,12 +6,15 @@ export const COMMAND_LOADERS: Record<string, () => Promise<TCommandHandler>> = {
|
|
|
6
6
|
[VulcanCommands.ADD]: () => import('./add.command.ts').then((module) => module.runAddCommand),
|
|
7
7
|
[VulcanCommands.AGENTS]: () =>
|
|
8
8
|
import('./agents.command.ts').then((module) => module.runAgentsCommand),
|
|
9
|
+
[VulcanCommands.CI]: () => import('./ci.command.ts').then((module) => module.runCiCommand),
|
|
9
10
|
[VulcanCommands.CLEAN]: () =>
|
|
10
11
|
import('./clean.command.ts').then((module) => module.runCleanCommand),
|
|
11
12
|
[VulcanCommands.COMMIT_CHECK]: () =>
|
|
12
13
|
import('./commit-check.command.ts').then((module) => module.runCommitCheckCommand),
|
|
13
14
|
[VulcanCommands.DOCTOR]: () =>
|
|
14
15
|
import('./doctor.command.ts').then((module) => module.runDoctorCommand),
|
|
16
|
+
[VulcanCommands.EVENT]: () =>
|
|
17
|
+
import('./event.command.ts').then((module) => module.runEventCommand),
|
|
15
18
|
[VulcanCommands.HELP]: () => import('./help.command.ts').then((module) => module.runHelpCommand),
|
|
16
19
|
[VulcanCommands.INIT]: () => import('./init.command.ts').then((module) => module.runInitCommand),
|
|
17
20
|
[VulcanCommands.PRESET]: () =>
|
package/src/common/constants.ts
CHANGED
|
@@ -10,6 +10,8 @@ export class VulcanCommands {
|
|
|
10
10
|
static readonly PRESET = 'preset';
|
|
11
11
|
static readonly VISUALIZE = 'visualize';
|
|
12
12
|
static readonly COMMIT_CHECK = 'commit-check';
|
|
13
|
+
static readonly CI = 'ci';
|
|
14
|
+
static readonly EVENT = 'event';
|
|
13
15
|
static readonly X = 'x';
|
|
14
16
|
static readonly HELP = 'help';
|
|
15
17
|
static readonly VERSION = 'version';
|
|
@@ -74,6 +76,14 @@ export class ProjectLayout {
|
|
|
74
76
|
{ name: 'cache', lifetime: 'kept', removedWhen: 'the user asks; it rebuilds' },
|
|
75
77
|
{ name: 'reports', lifetime: 'kept', removedWhen: 'the user deletes it' },
|
|
76
78
|
{ name: 'prototypes', lifetime: 'kept', removedWhen: 'the user deletes it' },
|
|
79
|
+
// On demand: sync does not create these; the folder appears when something writes there.
|
|
80
|
+
{ name: 'events', lifetime: 'kept', removedWhen: 'the user deletes it', onDemand: true },
|
|
81
|
+
{
|
|
82
|
+
name: 'release-candidates',
|
|
83
|
+
lifetime: 'release',
|
|
84
|
+
removedWhen: 'the release ships',
|
|
85
|
+
onDemand: true,
|
|
86
|
+
},
|
|
77
87
|
] as const;
|
|
78
88
|
/** What the scaffolded lint configs run; optional peers of dev-configs, so bun never installs them alone. */
|
|
79
89
|
static readonly LINT_TOOLS = ['oxlint', 'oxlint-tsgolint', 'eslint'];
|
package/src/config/schema.ts
CHANGED
|
@@ -5,6 +5,7 @@ import { OWNER_SCHEMA } from '../owner/schema.ts';
|
|
|
5
5
|
import { AgentSignaturePolicies } from '../commit/common/index.ts';
|
|
6
6
|
import type { TAgentSignaturePolicy } from '../commit/common/index.ts';
|
|
7
7
|
import { SubjectShape } from '../commit/subject.ts';
|
|
8
|
+
import { EventSettings } from '../events/settings.ts';
|
|
8
9
|
import {
|
|
9
10
|
CodingAgents,
|
|
10
11
|
ConfigConstants,
|
|
@@ -460,6 +461,54 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
460
461
|
.default({
|
|
461
462
|
message: { agent: { signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] } },
|
|
462
463
|
}),
|
|
464
|
+
/**
|
|
465
|
+
* What `vulcan ci affected` treats as touching every package. `affected.global` adds root-relative globs
|
|
466
|
+
* to the shipped list (lockfiles, `bunfig.toml`, root `tsconfig*.json`, `.configs/`, the workflow files);
|
|
467
|
+
* a project cannot remove a shipped one. Written to the manifest only when it is not empty.
|
|
468
|
+
*/
|
|
469
|
+
ci: z
|
|
470
|
+
.strictObject({
|
|
471
|
+
affected: z
|
|
472
|
+
.strictObject({
|
|
473
|
+
global: z
|
|
474
|
+
.array(
|
|
475
|
+
z
|
|
476
|
+
.string()
|
|
477
|
+
.min(1)
|
|
478
|
+
.refine((glob) => !glob.startsWith('/') && !glob.split('/').includes('..'), {
|
|
479
|
+
message:
|
|
480
|
+
'a glob relative to the project root, with no leading / and no .. segment',
|
|
481
|
+
}),
|
|
482
|
+
)
|
|
483
|
+
.default([]),
|
|
484
|
+
})
|
|
485
|
+
.default({ global: [] }),
|
|
486
|
+
})
|
|
487
|
+
.default({ affected: { global: [] } }),
|
|
488
|
+
/**
|
|
489
|
+
* The agent event log: one JSON line per thing an agent did (a session started, a message sent, an
|
|
490
|
+
* owner is needed), summaries only, in `.agents/local/events/<day>.jsonl`. `log: true` makes
|
|
491
|
+
* `vulcan sync` install the Claude Code hooks that write it; `vulcan event add` writes it for any
|
|
492
|
+
* other agent whatever this says. `dir` is an absolute folder that takes the log instead of the
|
|
493
|
+
* project's own, so one coordinator can read the events of sessions in different repositories.
|
|
494
|
+
* Off by default; written to the manifest only when `log` is true or `dir` is set.
|
|
495
|
+
*/
|
|
496
|
+
events: z
|
|
497
|
+
.strictObject({
|
|
498
|
+
log: z.boolean().default(false),
|
|
499
|
+
dir: z
|
|
500
|
+
.string()
|
|
501
|
+
.min(1)
|
|
502
|
+
.superRefine((value, context) => {
|
|
503
|
+
const error = EventSettings.dirError({ dir: value });
|
|
504
|
+
|
|
505
|
+
if (error !== undefined) {
|
|
506
|
+
context.addIssue({ code: 'custom', message: `dir must be ${error}` });
|
|
507
|
+
}
|
|
508
|
+
})
|
|
509
|
+
.optional(),
|
|
510
|
+
})
|
|
511
|
+
.default({ log: false }),
|
|
463
512
|
});
|
|
464
513
|
|
|
465
514
|
export type VulcanConfig = z.input<typeof VULCAN_CONFIG_SCHEMA>;
|
package/src/doctor/checks.ts
CHANGED
|
@@ -1,7 +1,16 @@
|
|
|
1
1
|
import { Glob } from 'bun';
|
|
2
2
|
import { spawnSync } from 'node:child_process';
|
|
3
|
-
import {
|
|
4
|
-
|
|
3
|
+
import {
|
|
4
|
+
accessSync,
|
|
5
|
+
constants,
|
|
6
|
+
existsSync,
|
|
7
|
+
lstatSync,
|
|
8
|
+
readdirSync,
|
|
9
|
+
readFileSync,
|
|
10
|
+
realpathSync,
|
|
11
|
+
statSync,
|
|
12
|
+
} from 'node:fs';
|
|
13
|
+
import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
|
|
5
14
|
import { BASE_DIRECTORY, ProjectLayout, RecordValue } from '../common/index.ts';
|
|
6
15
|
import { LayoutKeys, LayoutFolder } from '../common/layout-folder.ts';
|
|
7
16
|
import { MCP_SERVER_HINT, ProjectScaffold } from '../init/index.ts';
|
|
@@ -718,6 +727,53 @@ export class ProjectContract {
|
|
|
718
727
|
}
|
|
719
728
|
}
|
|
720
729
|
|
|
730
|
+
/**
|
|
731
|
+
* `events.dir` names a folder outside the project: it must exist and be writable by this user, or the
|
|
732
|
+
* event hooks lose every line without a word (they fail open). A folder inside the project is made
|
|
733
|
+
* on the first write and is not checked. A warning: the folder belongs to the machine, not to the repository.
|
|
734
|
+
*/
|
|
735
|
+
static checkEventsDir(opts: ICheckContext): IViolation[] {
|
|
736
|
+
const { dir } = opts.config.events;
|
|
737
|
+
|
|
738
|
+
if (dir === undefined) {
|
|
739
|
+
return [];
|
|
740
|
+
}
|
|
741
|
+
|
|
742
|
+
const away = relative(opts.root, dir);
|
|
743
|
+
|
|
744
|
+
if (away !== '' && !away.startsWith('..') && !isAbsolute(away)) {
|
|
745
|
+
return [];
|
|
746
|
+
}
|
|
747
|
+
|
|
748
|
+
const problem = ((): string | undefined => {
|
|
749
|
+
if (!existsSync(dir)) {
|
|
750
|
+
return `does not exist - create it (mkdir -p ${dir})`;
|
|
751
|
+
}
|
|
752
|
+
|
|
753
|
+
if (!statSync(dir).isDirectory()) {
|
|
754
|
+
return 'is not a folder';
|
|
755
|
+
}
|
|
756
|
+
|
|
757
|
+
try {
|
|
758
|
+
accessSync(dir, constants.W_OK);
|
|
759
|
+
|
|
760
|
+
return undefined;
|
|
761
|
+
} catch {
|
|
762
|
+
return 'is not writable by this user';
|
|
763
|
+
}
|
|
764
|
+
})();
|
|
765
|
+
|
|
766
|
+
return problem === undefined
|
|
767
|
+
? []
|
|
768
|
+
: [
|
|
769
|
+
createViolation({
|
|
770
|
+
check: DoctorChecks.EVENTS_DIR,
|
|
771
|
+
file: opts.configFile,
|
|
772
|
+
message: `events.dir ${dir} ${problem}, so the event log hooks cannot write there`,
|
|
773
|
+
}),
|
|
774
|
+
];
|
|
775
|
+
}
|
|
776
|
+
|
|
721
777
|
/**
|
|
722
778
|
* The atlas server is registered the one way every project does: the root `.mcp.json` (a per-machine
|
|
723
779
|
* file `sync` writes for the agents that read it) holds an `atlas` entry that runs the project's own
|
|
@@ -1088,19 +1144,37 @@ export class ProjectContract {
|
|
|
1088
1144
|
return violations;
|
|
1089
1145
|
}
|
|
1090
1146
|
|
|
1147
|
+
/**
|
|
1148
|
+
* Something directly under `.agents/local/` that is not a folder of the layout, a file VULCAN writes, or a
|
|
1149
|
+
* browser's scratch folder. Nothing removes it; the message says where scratch belongs. A warning.
|
|
1150
|
+
*/
|
|
1151
|
+
static checkUnknownLocal(opts: ICheckContext): IViolation[] {
|
|
1152
|
+
return LocalScan.unknown({ root: opts.root }).map((entry) =>
|
|
1153
|
+
createViolation({
|
|
1154
|
+
check: DoctorChecks.LOCAL,
|
|
1155
|
+
file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.name}`,
|
|
1156
|
+
message: `not an entry VULCAN knows (${LocalFormat.formatBytes({ bytes: entry.bytes })}): put scratch in tmp/ and what you want to keep in reports/; nothing removes it`,
|
|
1157
|
+
}),
|
|
1158
|
+
);
|
|
1159
|
+
}
|
|
1160
|
+
|
|
1091
1161
|
/** What an agent left under `.agents/local/` that has outlived its use, one line each with the command that clears it. */
|
|
1092
1162
|
static checkStaleLocal(opts: ICheckContext): IViolation[] {
|
|
1093
1163
|
return LocalScan.scan({ root: opts.root })
|
|
1094
1164
|
.filter((entry) =>
|
|
1095
|
-
[
|
|
1096
|
-
|
|
1097
|
-
|
|
1165
|
+
[
|
|
1166
|
+
LocalStates.STALE,
|
|
1167
|
+
LocalStates.MERGED,
|
|
1168
|
+
LocalStates.GONE,
|
|
1169
|
+
LocalStates.ORPHAN,
|
|
1170
|
+
LocalStates.SHIPPED,
|
|
1171
|
+
].includes(entry.state),
|
|
1098
1172
|
)
|
|
1099
1173
|
.map((entry) =>
|
|
1100
1174
|
createViolation({
|
|
1101
1175
|
check: DoctorChecks.LOCAL,
|
|
1102
|
-
file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.
|
|
1103
|
-
message: `${entry.state === LocalStates.STALE ? `left ${LocalFormat.formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${LocalFormat.formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
|
|
1176
|
+
file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.where}`,
|
|
1177
|
+
message: `${entry.state === LocalStates.STALE && entry.note === '' ? `left ${LocalFormat.formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${LocalFormat.formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
|
|
1104
1178
|
}),
|
|
1105
1179
|
);
|
|
1106
1180
|
}
|
|
@@ -21,6 +21,7 @@ export class DoctorChecks {
|
|
|
21
21
|
static readonly PROFILE = 'profile';
|
|
22
22
|
static readonly GUARDS = 'guards';
|
|
23
23
|
static readonly COMMIT_HOOK = 'commit-hook';
|
|
24
|
+
static readonly EVENTS_DIR = 'events-dir';
|
|
24
25
|
}
|
|
25
26
|
|
|
26
27
|
/** The `package.json` scripts every app carries, and the names the standard retired. */
|
package/src/doctor/runner.ts
CHANGED
|
@@ -92,6 +92,7 @@ export class DoctorRunner {
|
|
|
92
92
|
return [
|
|
93
93
|
...ProjectContract.checkMcpAtlas(context),
|
|
94
94
|
...ProjectContract.checkCommitHook(context),
|
|
95
|
+
...ProjectContract.checkEventsDir(context),
|
|
95
96
|
...ProjectContract.checkDockerignore(context),
|
|
96
97
|
...ProjectContract.checkSkillTriggers(context),
|
|
97
98
|
...ProjectContract.checkFormat(context),
|
|
@@ -100,6 +101,7 @@ export class DoctorRunner {
|
|
|
100
101
|
...ProjectContract.checkProfile(context),
|
|
101
102
|
...ProjectContract.checkOwnerReplySettings(context),
|
|
102
103
|
...ProjectContract.checkStaleLocal(context),
|
|
104
|
+
...ProjectContract.checkUnknownLocal(context),
|
|
103
105
|
...ProjectContract.checkStaleTrustedScripts(context),
|
|
104
106
|
];
|
|
105
107
|
}
|