@venizia/vulcan 0.4.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/base/claude/remote-hosts.json +1 -1
- package/base/claude/settings.json +75 -3
- package/base/hooks/guard-git.ts +55 -0
- package/base/hooks/guard-manifest.ts +1 -1
- package/base/hooks/guard-outside.ts +66 -0
- package/base/hooks/guard-package.ts +3 -2
- package/base/hooks/guard-remote-hosts.ts +3 -2
- package/base/hooks/guard-writes.ts +1 -1
- package/base/hooks/post-tool.ts +36 -0
- package/base/hooks/prompt-submit.ts +52 -0
- package/base/hooks/stop.ts +38 -0
- package/base/hooks/subagent-start.ts +18 -0
- package/base/references/delegation-brief.md +63 -0
- package/base/references/design-pass.md +39 -0
- package/base/references/evidence.md +36 -0
- package/base/references/phase-boundaries.md +20 -0
- package/base/references/testing.md +89 -0
- package/base/rules.md +11 -2
- package/base/skills/build-a-feature/SKILL.md +49 -23
- package/base/skills/docs-update/SKILL.md +12 -1
- package/base/skills/docs-writing/SKILL.md +2 -2
- package/base/skills/docs-writing/references/agent-documents.md +53 -0
- package/base/skills/fix-a-bug/SKILL.md +84 -0
- package/base/skills/fix-a-bug/evals/evals.json +17 -0
- package/base/skills/knowledge-sync/SKILL.md +4 -1
- package/base/skills/knowledge-sync/knowledge-sync.workflow.js +10 -10
- package/base/skills/plan-a-change/SKILL.md +95 -0
- package/base/skills/plan-a-change/evals/evals.json +23 -0
- package/base/skills/plan-a-change/references/spec-card.md +39 -0
- package/base/skills/report-back/SKILL.md +112 -0
- package/base/skills/report-back/evals/evals.json +23 -0
- package/base/skills/research/SKILL.md +64 -0
- package/base/skills/research/evals/evals.json +17 -0
- package/base/skills/retro/SKILL.md +69 -0
- package/base/skills/retro/evals/evals.json +17 -0
- package/base/skills/review-a-change/SKILL.md +90 -0
- package/base/skills/review-a-change/evals/evals.json +17 -0
- package/base/skills/ship/SKILL.md +82 -0
- package/base/skills/ship/evals/evals.json +23 -0
- package/base/skills/visualize-work/SKILL.md +87 -0
- package/base/skills/visualize-work/evals/evals.json +17 -0
- package/base/skills/visualize-work/references/spec.md +65 -0
- package/package.json +3 -3
- package/src/agents/common/schema.ts +2 -2
- package/src/agents/detect.ts +5 -5
- package/src/agents/exclude.ts +3 -3
- package/src/agents/local.ts +1 -1
- package/src/agents/prompt.ts +2 -2
- package/src/agents/render.ts +2 -2
- package/src/agents/resolve.ts +6 -6
- package/src/agents/table.ts +1 -1
- package/src/commands/agents.command.ts +4 -4
- package/src/commands/clean.command.ts +72 -0
- package/src/commands/help.command.ts +11 -0
- package/src/commands/index.ts +6 -0
- package/src/commands/init.command.ts +4 -1
- package/src/commands/profile.command.ts +255 -0
- package/src/commands/sync.command.ts +6 -4
- package/src/commands/upgrade.command.ts +1 -1
- package/src/commands/visualize.command.ts +107 -0
- package/src/common/constants.ts +23 -0
- package/src/config/common/constants.ts +2 -0
- package/src/config/loader.ts +4 -4
- package/src/config/packages.ts +1 -1
- package/src/config/schema.ts +16 -5
- package/src/create/add-app.ts +15 -15
- package/src/create/add-lib.ts +7 -7
- package/src/create/bunfig.ts +1 -1
- package/src/create/dockerignore.ts +4 -4
- package/src/create/init-monorepo.ts +3 -1
- package/src/create/lib-preset.ts +1 -1
- package/src/create/names.ts +7 -6
- package/src/create/next.ts +4 -4
- package/src/create/preset-menu.ts +4 -4
- package/src/create/preset.ts +3 -3
- package/src/create/scratch.ts +27 -6
- package/src/create/workspace.ts +11 -11
- package/src/doctor/checks.ts +231 -45
- package/src/doctor/common/constants.ts +4 -0
- package/src/doctor/makefile.ts +3 -3
- package/src/doctor/runner.ts +16 -1
- package/src/doctor/skills.ts +8 -8
- package/src/doctor/tags.ts +5 -5
- package/src/hooks/common/constants.ts +29 -0
- package/src/hooks/common/types.ts +20 -0
- package/src/hooks/decision.ts +15 -0
- package/src/hooks/guard-git.ts +288 -0
- package/src/hooks/guard-manifest.ts +1 -1
- package/src/hooks/guard-outside.ts +399 -0
- package/src/hooks/guard-package.ts +4 -4
- package/src/hooks/guard-writes.ts +5 -5
- package/src/hooks/index.ts +6 -0
- package/src/hooks/owner-reply.ts +148 -0
- package/src/hooks/post-tool.ts +137 -0
- package/src/hooks/remote-hosts.ts +25 -23
- package/src/hooks/session-digest.ts +24 -4
- package/src/hooks/shell.ts +325 -0
- package/src/hooks/subagent-card.ts +32 -0
- package/src/init/scaffold.ts +6 -6
- package/src/local/clean.ts +88 -0
- package/src/local/constants.ts +50 -0
- package/src/local/format.ts +25 -0
- package/src/local/index.ts +4 -0
- package/src/local/scan.ts +368 -0
- package/src/manifest/render.ts +1 -1
- package/src/owner/card.ts +85 -0
- package/src/owner/constants.ts +105 -0
- package/src/owner/index.ts +8 -0
- package/src/owner/profile.ts +123 -0
- package/src/owner/schema.ts +147 -0
- package/src/owner/shape.ts +380 -0
- package/src/owner/survey.ts +289 -0
- package/src/owner/view.ts +76 -0
- package/src/owner/violations.ts +202 -0
- package/src/router.ts +18 -1
- package/src/rules/base.ts +1 -1
- package/src/rules/parser.ts +5 -5
- package/src/signals/claims.ts +71 -0
- package/src/signals/classify.ts +132 -0
- package/src/signals/constants.ts +88 -0
- package/src/signals/index.ts +5 -0
- package/src/signals/loop.ts +46 -0
- package/src/signals/state.ts +276 -0
- package/src/sync/agent-files.ts +4 -4
- package/src/sync/agent-removal.ts +6 -6
- package/src/sync/atlas-block.ts +1 -1
- package/src/sync/base-rules.ts +1 -1
- package/src/sync/exclude.ts +9 -9
- package/src/sync/local-choice.ts +35 -5
- package/src/sync/planner.ts +16 -16
- package/src/sync/prune.ts +3 -3
- package/src/sync/settings.ts +15 -15
- package/src/ui/prompt.ts +3 -3
- package/src/visualize/assets.ts +80 -0
- package/src/visualize/constants.ts +126 -0
- package/src/visualize/index.ts +6 -0
- package/src/visualize/layout.ts +107 -0
- package/src/visualize/page.ts +211 -0
- package/src/visualize/render.ts +161 -0
- package/src/visualize/schema.ts +178 -0
- package/src/visualize/validate.ts +127 -0
|
@@ -0,0 +1,368 @@
|
|
|
1
|
+
import { spawnSync } from 'node:child_process';
|
|
2
|
+
import { existsSync, lstatSync, readdirSync, realpathSync } from 'node:fs';
|
|
3
|
+
import { join, resolve, sep } from 'node:path';
|
|
4
|
+
import { ProjectLayout } from '../common/index.ts';
|
|
5
|
+
import { CleanScopes, LocalConstants, LocalStates } from './constants.ts';
|
|
6
|
+
|
|
7
|
+
/** One thing under `.agents/local/`: a child of one of its directories, or the profile file. */
|
|
8
|
+
export interface ILocalEntry {
|
|
9
|
+
scope: string;
|
|
10
|
+
name: string;
|
|
11
|
+
path: string;
|
|
12
|
+
bytes: number;
|
|
13
|
+
ageMs: number;
|
|
14
|
+
state: string;
|
|
15
|
+
/** Whether `clean` may remove it when its scope is chosen. */
|
|
16
|
+
removable: boolean;
|
|
17
|
+
isSymlink: boolean;
|
|
18
|
+
/** A registered git worktree: removed with `git worktree remove`, then pruned. */
|
|
19
|
+
registered: boolean;
|
|
20
|
+
note: string;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
interface IRegistered {
|
|
24
|
+
/** `undefined` for a detached HEAD. */
|
|
25
|
+
branch: string | undefined;
|
|
26
|
+
/** The commit the worktree is at, as git last recorded it. */
|
|
27
|
+
head: string | undefined;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** The newest modification time under `path`, itself included: a folder's own time moves only when its direct children do. */
|
|
31
|
+
export const newestModifiedAt = (opts: { path: string }): number => {
|
|
32
|
+
let stat;
|
|
33
|
+
|
|
34
|
+
try {
|
|
35
|
+
stat = lstatSync(opts.path);
|
|
36
|
+
} catch {
|
|
37
|
+
return 0;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
if (!stat.isDirectory()) {
|
|
41
|
+
return stat.mtimeMs;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
return readdirSync(opts.path).reduce(
|
|
45
|
+
(newest, name) => Math.max(newest, newestModifiedAt({ path: join(opts.path, name) })),
|
|
46
|
+
stat.mtimeMs,
|
|
47
|
+
);
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
/** The bytes under `path`, symlinks counted as themselves and never followed. */
|
|
51
|
+
export const sizeOf = (opts: { path: string }): number => {
|
|
52
|
+
let stat;
|
|
53
|
+
|
|
54
|
+
try {
|
|
55
|
+
stat = lstatSync(opts.path);
|
|
56
|
+
} catch {
|
|
57
|
+
return 0;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
if (!stat.isDirectory()) {
|
|
61
|
+
return stat.size;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
return readdirSync(opts.path).reduce(
|
|
65
|
+
(total, name) => total + sizeOf({ path: join(opts.path, name) }),
|
|
66
|
+
0,
|
|
67
|
+
);
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* The real path of the project's `.agents/local/`, or `undefined` when there is none or it cannot be
|
|
72
|
+
* trusted: `.agents` or `.agents/local` is a symlink, or the folder resolves outside the project. Every
|
|
73
|
+
* scan and every removal starts here, so a link can never move them out of the project.
|
|
74
|
+
*/
|
|
75
|
+
export const localRootOf = (opts: { root: string }): string | undefined => {
|
|
76
|
+
const agents = join(opts.root, '.agents');
|
|
77
|
+
const local = join(opts.root, ProjectLayout.LOCAL_DIRECTORY);
|
|
78
|
+
|
|
79
|
+
try {
|
|
80
|
+
if (lstatSync(agents).isSymbolicLink() || lstatSync(local).isSymbolicLink()) {
|
|
81
|
+
return undefined;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
const real = realpathSync(local);
|
|
85
|
+
const realRoot = realpathSync(opts.root);
|
|
86
|
+
|
|
87
|
+
return real.startsWith(`${realRoot}${sep}`) && lstatSync(real).isDirectory() ? real : undefined;
|
|
88
|
+
} catch {
|
|
89
|
+
return undefined;
|
|
90
|
+
}
|
|
91
|
+
};
|
|
92
|
+
|
|
93
|
+
const git = (opts: { cwd: string; args: string[] }): string | undefined => {
|
|
94
|
+
const result = spawnSync('git', opts.args, {
|
|
95
|
+
cwd: opts.cwd,
|
|
96
|
+
encoding: 'utf8',
|
|
97
|
+
timeout: LocalConstants.GIT_TIMEOUT_MS,
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
return result.status === 0 ? result.stdout : undefined;
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* The output of `git worktree list --porcelain -z`: records end with an extra NUL and fields are NUL
|
|
105
|
+
* separated, so a path with a line break or odd characters is read whole.
|
|
106
|
+
*/
|
|
107
|
+
export const parseWorktreeList = (opts: { output: string }): Map<string, IRegistered> => {
|
|
108
|
+
const map = new Map<string, IRegistered>();
|
|
109
|
+
|
|
110
|
+
for (const record of opts.output.split('\0\0')) {
|
|
111
|
+
const fields = record.split('\0').filter((field) => field !== '');
|
|
112
|
+
const path = fields.find((field) => field.startsWith('worktree '))?.slice('worktree '.length);
|
|
113
|
+
const branch = fields
|
|
114
|
+
.find((field) => field.startsWith('branch refs/heads/'))
|
|
115
|
+
?.slice('branch refs/heads/'.length);
|
|
116
|
+
const head = fields.find((field) => /^HEAD [0-9a-f]{7,64}$/.test(field))?.slice('HEAD '.length);
|
|
117
|
+
|
|
118
|
+
if (path !== undefined) {
|
|
119
|
+
map.set(existsSync(path) ? realpathSync(path) : path, { branch, head });
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
return map;
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
/** The registered worktrees of the repository at `root`; `undefined` when git cannot list them. */
|
|
127
|
+
const registeredWorktrees = (opts: { root: string }): Map<string, IRegistered> | undefined => {
|
|
128
|
+
const listed = git({ cwd: opts.root, args: ['worktree', 'list', '--porcelain', '-z'] });
|
|
129
|
+
|
|
130
|
+
return listed === undefined ? undefined : parseWorktreeList({ output: listed });
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
interface IVerdict {
|
|
134
|
+
state: string;
|
|
135
|
+
removable: boolean;
|
|
136
|
+
registered: boolean;
|
|
137
|
+
note: string;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
const classifyBranch = (opts: {
|
|
141
|
+
root: string;
|
|
142
|
+
real: string;
|
|
143
|
+
registered: Map<string, IRegistered> | undefined;
|
|
144
|
+
}): IVerdict => {
|
|
145
|
+
if (opts.registered === undefined) {
|
|
146
|
+
return {
|
|
147
|
+
state: LocalStates.UNKNOWN,
|
|
148
|
+
removable: false,
|
|
149
|
+
registered: false,
|
|
150
|
+
note: 'git could not list worktrees',
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
const found = opts.registered.get(opts.real);
|
|
155
|
+
|
|
156
|
+
if (found === undefined) {
|
|
157
|
+
return {
|
|
158
|
+
state: LocalStates.ORPHAN,
|
|
159
|
+
removable: true,
|
|
160
|
+
registered: false,
|
|
161
|
+
note: 'not a registered worktree',
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
const { branch } = found;
|
|
166
|
+
|
|
167
|
+
if (branch === undefined) {
|
|
168
|
+
return {
|
|
169
|
+
state: LocalStates.UNMERGED,
|
|
170
|
+
removable: false,
|
|
171
|
+
registered: true,
|
|
172
|
+
note: 'detached HEAD',
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
if (
|
|
177
|
+
git({ cwd: opts.root, args: ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`] }) ===
|
|
178
|
+
undefined
|
|
179
|
+
) {
|
|
180
|
+
return {
|
|
181
|
+
state: LocalStates.GONE,
|
|
182
|
+
removable: true,
|
|
183
|
+
registered: true,
|
|
184
|
+
note: `branch ${branch} is gone`,
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
const merged = git({
|
|
189
|
+
cwd: opts.root,
|
|
190
|
+
args: ['branch', '--format=%(refname:short)', '--merged'],
|
|
191
|
+
});
|
|
192
|
+
|
|
193
|
+
if (
|
|
194
|
+
merged
|
|
195
|
+
?.split('\n')
|
|
196
|
+
.map((line) => line.trim())
|
|
197
|
+
.includes(branch)
|
|
198
|
+
) {
|
|
199
|
+
return {
|
|
200
|
+
state: LocalStates.MERGED,
|
|
201
|
+
removable: true,
|
|
202
|
+
registered: true,
|
|
203
|
+
note: `branch ${branch} is merged into the branch checked out at the project root`,
|
|
204
|
+
};
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
return {
|
|
208
|
+
state: LocalStates.UNMERGED,
|
|
209
|
+
removable: false,
|
|
210
|
+
registered: true,
|
|
211
|
+
note: `branch ${branch} is not merged`,
|
|
212
|
+
};
|
|
213
|
+
};
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* A worktree on a merged or gone branch is removable only when it holds nothing uncommitted or
|
|
217
|
+
* untracked: `git worktree remove --force` would otherwise lose that work without a word. Dirtiness is
|
|
218
|
+
* judged against the commit git recorded for the worktree, not HEAD: a gone branch leaves HEAD
|
|
219
|
+
* unresolvable and `status` would then list every file as new. (Work staged but not committed on a gone
|
|
220
|
+
* branch cannot be told from the checkout's own index.)
|
|
221
|
+
*/
|
|
222
|
+
const classifyWorktree = (opts: {
|
|
223
|
+
root: string;
|
|
224
|
+
real: string;
|
|
225
|
+
registered: Map<string, IRegistered> | undefined;
|
|
226
|
+
}): IVerdict => {
|
|
227
|
+
const verdict = classifyBranch(opts);
|
|
228
|
+
|
|
229
|
+
if (!verdict.registered || !verdict.removable) {
|
|
230
|
+
return verdict;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
const head = opts.registered?.get(opts.real)?.head;
|
|
234
|
+
// A gone branch has no commit (git records all zeros): the working tree is then compared with the
|
|
235
|
+
// index, which still catches an edited file and, with the untracked check, a new one.
|
|
236
|
+
const baseline = head === undefined || /^0+$/.test(head) ? [] : [head];
|
|
237
|
+
const tracked = spawnSync('git', ['diff', '--quiet', ...baseline], {
|
|
238
|
+
cwd: opts.real,
|
|
239
|
+
timeout: LocalConstants.GIT_TIMEOUT_MS,
|
|
240
|
+
}).status;
|
|
241
|
+
const untracked = git({ cwd: opts.real, args: ['ls-files', '--others', '--exclude-standard'] });
|
|
242
|
+
const clean = tracked === 0 && untracked !== undefined && untracked.trim() === '';
|
|
243
|
+
|
|
244
|
+
return clean
|
|
245
|
+
? verdict
|
|
246
|
+
: {
|
|
247
|
+
state: LocalStates.DIRTY,
|
|
248
|
+
removable: false,
|
|
249
|
+
registered: true,
|
|
250
|
+
note: `${verdict.note}, but it has uncommitted or untracked files`,
|
|
251
|
+
};
|
|
252
|
+
};
|
|
253
|
+
|
|
254
|
+
/** A directory that is really one: not a link, not a file. */
|
|
255
|
+
const isRealDirectory = (opts: { path: string }): boolean => {
|
|
256
|
+
try {
|
|
257
|
+
const stat = lstatSync(opts.path);
|
|
258
|
+
|
|
259
|
+
return stat.isDirectory() && !stat.isSymbolicLink();
|
|
260
|
+
} catch {
|
|
261
|
+
return false;
|
|
262
|
+
}
|
|
263
|
+
};
|
|
264
|
+
|
|
265
|
+
/** Every entry of `.agents/local/`, with size, age and what may be removed. Nothing is followed outside it. */
|
|
266
|
+
export const scanLocal = (opts: { root: string; now?: number }): ILocalEntry[] => {
|
|
267
|
+
const local = localRootOf({ root: opts.root });
|
|
268
|
+
const now = opts.now ?? Date.now();
|
|
269
|
+
|
|
270
|
+
if (local === undefined) {
|
|
271
|
+
return [];
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
const registered = registeredWorktrees({ root: opts.root });
|
|
275
|
+
const entries: ILocalEntry[] = [];
|
|
276
|
+
|
|
277
|
+
for (const layout of ProjectLayout.LOCAL_LAYOUT) {
|
|
278
|
+
const directory = join(local, layout.name);
|
|
279
|
+
|
|
280
|
+
if (!isRealDirectory({ path: directory })) {
|
|
281
|
+
continue;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
for (const name of readdirSync(directory)) {
|
|
285
|
+
if (name === '.gitkeep') {
|
|
286
|
+
continue;
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
const path = join(directory, name);
|
|
290
|
+
const stat = lstatSync(path);
|
|
291
|
+
const ageMs = now - newestModifiedAt({ path });
|
|
292
|
+
const staleAfter =
|
|
293
|
+
'staleAfterDays' in layout ? layout.staleAfterDays * LocalConstants.DAY_MS : undefined;
|
|
294
|
+
let state: string = LocalStates.OK;
|
|
295
|
+
let removable = true;
|
|
296
|
+
let isRegistered = false;
|
|
297
|
+
let note = '';
|
|
298
|
+
|
|
299
|
+
if (layout.name === CleanScopes.WORKTREES) {
|
|
300
|
+
const verdict = classifyWorktree({
|
|
301
|
+
root: opts.root,
|
|
302
|
+
real: stat.isSymbolicLink() ? resolve(path) : realpathSync(path),
|
|
303
|
+
registered,
|
|
304
|
+
});
|
|
305
|
+
|
|
306
|
+
({ state, removable, registered: isRegistered, note } = verdict);
|
|
307
|
+
} else if (staleAfter !== undefined && ageMs > staleAfter) {
|
|
308
|
+
state = LocalStates.STALE;
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
entries.push({
|
|
312
|
+
scope: layout.name,
|
|
313
|
+
name,
|
|
314
|
+
path,
|
|
315
|
+
bytes: sizeOf({ path }),
|
|
316
|
+
ageMs,
|
|
317
|
+
state,
|
|
318
|
+
removable,
|
|
319
|
+
isSymlink: stat.isSymbolicLink(),
|
|
320
|
+
registered: isRegistered,
|
|
321
|
+
note,
|
|
322
|
+
});
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
const profile = join(local, 'profile.json');
|
|
327
|
+
|
|
328
|
+
if (existsSync(profile)) {
|
|
329
|
+
const stat = lstatSync(profile);
|
|
330
|
+
|
|
331
|
+
entries.push({
|
|
332
|
+
scope: CleanScopes.PROFILE,
|
|
333
|
+
name: 'profile.json',
|
|
334
|
+
path: profile,
|
|
335
|
+
bytes: stat.size,
|
|
336
|
+
ageMs: now - stat.mtimeMs,
|
|
337
|
+
state: LocalStates.OK,
|
|
338
|
+
removable: true,
|
|
339
|
+
isSymlink: stat.isSymbolicLink(),
|
|
340
|
+
registered: false,
|
|
341
|
+
note: '',
|
|
342
|
+
});
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
return entries;
|
|
346
|
+
};
|
|
347
|
+
|
|
348
|
+
/**
|
|
349
|
+
* Whether `path` sits under the project's trusted `.agents/local/` once its parent is resolved; a final
|
|
350
|
+
* symlink is not followed. A symlinked `.agents` or `.agents/local` makes it false for everything.
|
|
351
|
+
*/
|
|
352
|
+
export const isInsideLocal = (opts: { root: string; path: string }): boolean => {
|
|
353
|
+
const local = localRootOf({ root: opts.root });
|
|
354
|
+
|
|
355
|
+
if (local === undefined) {
|
|
356
|
+
return false;
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
const parent = resolve(opts.path, '..');
|
|
360
|
+
|
|
361
|
+
if (!existsSync(parent)) {
|
|
362
|
+
return false;
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
const target = join(realpathSync(parent), resolve(opts.path).split(sep).at(-1) ?? '');
|
|
366
|
+
|
|
367
|
+
return target.startsWith(`${local}${sep}`);
|
|
368
|
+
};
|
package/src/manifest/render.ts
CHANGED
|
@@ -58,7 +58,7 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
|
|
|
58
58
|
[ManifestConstants.GENERATED_KEY]: ManifestConstants.GENERATED_NOTE,
|
|
59
59
|
schemaVersion: ManifestConstants.SCHEMA_VERSION,
|
|
60
60
|
name: projectNameOf(opts),
|
|
61
|
-
packages: resolvePackages({ config }).map(entry => ({
|
|
61
|
+
packages: resolvePackages({ config }).map((entry) => ({
|
|
62
62
|
name: entry.name,
|
|
63
63
|
dir: entry.dir,
|
|
64
64
|
path: entry.path,
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { OwnerConstants, OwnerEnforcement, OwnerSections } from './constants.ts';
|
|
2
|
+
import type { IOwnerView } from './view.ts';
|
|
3
|
+
|
|
4
|
+
/** Free text as one quotable line: whitespace collapsed, quotes softened, cut to the card's limit. */
|
|
5
|
+
const plain = (opts: { text: string }): string =>
|
|
6
|
+
opts.text
|
|
7
|
+
.replace(/\s+/g, ' ')
|
|
8
|
+
.replace(/"/g, "'")
|
|
9
|
+
.trim()
|
|
10
|
+
.slice(0, OwnerConstants.CARD_ABOUT_MAX_CHARACTERS);
|
|
11
|
+
|
|
12
|
+
const SECTION_TEXT = (opts: { section: string; view: IOwnerView }): string => {
|
|
13
|
+
const { labels, headlineMaxSentences } = opts.view;
|
|
14
|
+
const [number, task, status] = labels.minimapColumns;
|
|
15
|
+
const statuses = Object.values(labels.status).join(', ');
|
|
16
|
+
|
|
17
|
+
switch (opts.section) {
|
|
18
|
+
case OwnerSections.HEADLINE: {
|
|
19
|
+
return `a headline: the answer first, at most ${headlineMaxSentences} sentence${headlineMaxSentences === 1 ? '' : 's'}, no preamble`;
|
|
20
|
+
}
|
|
21
|
+
case OwnerSections.MINIMAP: {
|
|
22
|
+
return `a table \`| ${number} | ${task} | ${status} |\` whose status is one of: ${statuses}`;
|
|
23
|
+
}
|
|
24
|
+
case OwnerSections.BLOCKED: {
|
|
25
|
+
return `one line \`${labels.labels.blocked}\` naming the blocker, or \`${labels.labels.noBlocker}\``;
|
|
26
|
+
}
|
|
27
|
+
case OwnerSections.DETAIL: {
|
|
28
|
+
return 'detail: tables over prose, every technical point with its plain meaning';
|
|
29
|
+
}
|
|
30
|
+
case OwnerSections.DECISIONS: {
|
|
31
|
+
return `\`${labels.labels.decisions}\`: a numbered list, each ending \`${labels.labels.recommend}\`, or exactly \`${labels.labels.noDecision}\``;
|
|
32
|
+
}
|
|
33
|
+
default: {
|
|
34
|
+
return opts.section;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
};
|
|
38
|
+
|
|
39
|
+
/** The shape every answer to the owner follows, from the resolved view; empty when enforcement is off. */
|
|
40
|
+
export const renderOwnerShapeCard = (opts: { view: IOwnerView }): string[] => {
|
|
41
|
+
if (opts.view.enforce === OwnerEnforcement.OFF) {
|
|
42
|
+
return [];
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const { view } = opts;
|
|
46
|
+
|
|
47
|
+
return [
|
|
48
|
+
'## How to answer the owner',
|
|
49
|
+
'',
|
|
50
|
+
`Every reply, in this order: ${view.shape.map((section) => SECTION_TEXT({ section, view })).join('; ')}.`,
|
|
51
|
+
...(view.absolutePaths ? ['Name a file the owner should open by its full absolute path.'] : []),
|
|
52
|
+
`Language: ${view.language}. Identifiers stay in backticks. Say what is unverified and what you got wrong, plainly.`,
|
|
53
|
+
];
|
|
54
|
+
};
|
|
55
|
+
|
|
56
|
+
/** What the person told VULCAN about working with them; empty when there is no profile. */
|
|
57
|
+
export const renderProfileCard = (opts: { view: IOwnerView }): string[] => {
|
|
58
|
+
const { view } = opts;
|
|
59
|
+
|
|
60
|
+
if (view.address === undefined) {
|
|
61
|
+
return [];
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const about = view.about === undefined ? '' : ` In their words: "${plain({ text: view.about })}"`;
|
|
65
|
+
|
|
66
|
+
return [
|
|
67
|
+
'## Working with this person',
|
|
68
|
+
'',
|
|
69
|
+
[
|
|
70
|
+
`Reply in ${view.language}.`,
|
|
71
|
+
view.address.you === undefined ? '' : `Address them as "${view.address.you}".`,
|
|
72
|
+
view.address.self === undefined ? '' : `Refer to yourself as "${view.address.self}".`,
|
|
73
|
+
`Formality: ${view.address.formality}. Tone: ${view.tone}. Reports: ${view.reportDetail === 'headline' ? 'headline only' : 'headline plus tables'}.`,
|
|
74
|
+
view.habits?.askBeforeReversible === true
|
|
75
|
+
? 'Ask before a reversible choice.'
|
|
76
|
+
: 'For a reversible choice state a default and continue.',
|
|
77
|
+
view.habits?.proposeCommits === true ? 'Propose commits.' : '',
|
|
78
|
+
view.codeTaste === undefined
|
|
79
|
+
? ''
|
|
80
|
+
: `Their code taste, in their words: "${plain({ text: view.codeTaste })}".`,
|
|
81
|
+
]
|
|
82
|
+
.filter((part) => part !== '')
|
|
83
|
+
.join(' ') + about,
|
|
84
|
+
];
|
|
85
|
+
};
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/** The sections of a reply to the owner; a project picks which appear and in what order. */
|
|
2
|
+
export class OwnerSections {
|
|
3
|
+
static readonly HEADLINE = 'headline';
|
|
4
|
+
static readonly MINIMAP = 'minimap';
|
|
5
|
+
static readonly BLOCKED = 'blocked';
|
|
6
|
+
static readonly DETAIL = 'detail';
|
|
7
|
+
static readonly DECISIONS = 'decisions';
|
|
8
|
+
static readonly SCHEME_SET = new Set<string>([
|
|
9
|
+
this.HEADLINE,
|
|
10
|
+
this.MINIMAP,
|
|
11
|
+
this.BLOCKED,
|
|
12
|
+
this.DETAIL,
|
|
13
|
+
this.DECISIONS,
|
|
14
|
+
]);
|
|
15
|
+
static isValid(value: string): boolean {
|
|
16
|
+
return this.SCHEME_SET.has(value);
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** How hard the shape of an owner reply is held: not at all, by a reminder, or by blocking a wrong one once. */
|
|
21
|
+
export class OwnerEnforcement {
|
|
22
|
+
static readonly OFF = 'off';
|
|
23
|
+
static readonly ADVISE = 'advise';
|
|
24
|
+
static readonly BLOCK = 'block';
|
|
25
|
+
/** From the loosest to the strictest: the stricter of two values wins. */
|
|
26
|
+
static readonly STRICTNESS = [this.OFF, this.ADVISE, this.BLOCK] as const;
|
|
27
|
+
static readonly SCHEME_SET = new Set<string>(this.STRICTNESS);
|
|
28
|
+
static isValid(value: string): boolean {
|
|
29
|
+
return this.SCHEME_SET.has(value);
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export class OwnerTones {
|
|
34
|
+
static readonly TERSE = 'terse';
|
|
35
|
+
static readonly NEUTRAL = 'neutral';
|
|
36
|
+
static readonly FRIENDLY = 'friendly';
|
|
37
|
+
static readonly SCHEME_SET = new Set<string>([this.TERSE, this.NEUTRAL, this.FRIENDLY]);
|
|
38
|
+
static isValid(value: string): boolean {
|
|
39
|
+
return this.SCHEME_SET.has(value);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export class OwnerFormalities {
|
|
44
|
+
static readonly INFORMAL = 'informal';
|
|
45
|
+
static readonly NEUTRAL = 'neutral';
|
|
46
|
+
static readonly FORMAL = 'formal';
|
|
47
|
+
static readonly SCHEME_SET = new Set<string>([this.INFORMAL, this.NEUTRAL, this.FORMAL]);
|
|
48
|
+
static isValid(value: string): boolean {
|
|
49
|
+
return this.SCHEME_SET.has(value);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export class OwnerDetails {
|
|
54
|
+
static readonly HEADLINE = 'headline';
|
|
55
|
+
static readonly TABLES = 'tables';
|
|
56
|
+
static readonly SCHEME_SET = new Set<string>([this.HEADLINE, this.TABLES]);
|
|
57
|
+
static isValid(value: string): boolean {
|
|
58
|
+
return this.SCHEME_SET.has(value);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const DEFAULT_MINIMAP_COLUMNS: [string, string, string] = ['#', 'Task', 'Status'];
|
|
63
|
+
|
|
64
|
+
export class OwnerConstants {
|
|
65
|
+
/** The personal profile: one file per developer per project, gitignored, inside the project. */
|
|
66
|
+
static readonly PROFILE_FILE = '.agents/local/profile.json';
|
|
67
|
+
static readonly PROFILE_SCHEMA_VERSION = 1;
|
|
68
|
+
static readonly DEFAULT_LANGUAGE = 'en';
|
|
69
|
+
static readonly DEFAULT_SHAPE = [
|
|
70
|
+
OwnerSections.HEADLINE,
|
|
71
|
+
OwnerSections.MINIMAP,
|
|
72
|
+
OwnerSections.BLOCKED,
|
|
73
|
+
OwnerSections.DETAIL,
|
|
74
|
+
OwnerSections.DECISIONS,
|
|
75
|
+
];
|
|
76
|
+
/** The English label set, the only one that ships: any other language is the owner's own. */
|
|
77
|
+
static readonly DEFAULT_LABELS = {
|
|
78
|
+
minimapColumns: DEFAULT_MINIMAP_COLUMNS,
|
|
79
|
+
status: {
|
|
80
|
+
done: 'done',
|
|
81
|
+
doing: 'in progress',
|
|
82
|
+
waiting: 'waiting',
|
|
83
|
+
todo: 'not started',
|
|
84
|
+
blocked: 'blocked',
|
|
85
|
+
dropped: 'dropped',
|
|
86
|
+
},
|
|
87
|
+
labels: {
|
|
88
|
+
blocked: 'Blocked:',
|
|
89
|
+
decisions: 'Decisions needed',
|
|
90
|
+
noBlocker: 'none',
|
|
91
|
+
noDecision: 'Nothing needed yet.',
|
|
92
|
+
recommend: 'I recommend **{x}**.',
|
|
93
|
+
},
|
|
94
|
+
};
|
|
95
|
+
static readonly DEFAULT_HEADLINE_MAX_SENTENCES = 2;
|
|
96
|
+
/** A reply shorter than this many words (an acknowledgement) is exempt from the shape; 0 checks every reply. */
|
|
97
|
+
static readonly DEFAULT_SHORT_REPLY_WORDS = 20;
|
|
98
|
+
static readonly MAX_SHORT_REPLY_WORDS = 200;
|
|
99
|
+
/** A language code: a 2-3 letter primary tag and optional subtags (`en`, `pt-BR`); never a word like `constructor`. */
|
|
100
|
+
static readonly LANGUAGE_PATTERN = /^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i;
|
|
101
|
+
/** A label or a form of address sits inside one line of a digest card: no line breaks, backticks, pipes or quotes. */
|
|
102
|
+
static readonly LABEL_PATTERN = /^[^\n\r`|"]{1,80}$/;
|
|
103
|
+
/** The profile's free text, as the card shows it. */
|
|
104
|
+
static readonly CARD_ABOUT_MAX_CHARACTERS = 200;
|
|
105
|
+
}
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import { spawnSync } from 'node:child_process';
|
|
2
|
+
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
3
|
+
import { dirname, join } from 'node:path';
|
|
4
|
+
import { OwnerConstants } from './constants.ts';
|
|
5
|
+
import { PROFILE_SCHEMA } from './schema.ts';
|
|
6
|
+
import type { TProfile } from './schema.ts';
|
|
7
|
+
|
|
8
|
+
export type TProfileRead =
|
|
9
|
+
| { ok: true; profile: TProfile | undefined }
|
|
10
|
+
| { ok: false; error: string };
|
|
11
|
+
|
|
12
|
+
/** A symlink at the profile's place, or at `.agents/local`, would read or write a file outside the project. */
|
|
13
|
+
export const linkedAt = (opts: { root: string }): string | undefined =>
|
|
14
|
+
[join(opts.root, OwnerConstants.PROFILE_FILE), join(opts.root, '.agents', 'local')].find(
|
|
15
|
+
(path) => {
|
|
16
|
+
try {
|
|
17
|
+
return lstatSync(path).isSymbolicLink();
|
|
18
|
+
} catch {
|
|
19
|
+
return false;
|
|
20
|
+
}
|
|
21
|
+
},
|
|
22
|
+
);
|
|
23
|
+
|
|
24
|
+
const SYMLINK_ERROR = `${OwnerConstants.PROFILE_FILE} (or .agents/local) is a symlink - it must be a regular file inside the project`;
|
|
25
|
+
|
|
26
|
+
/** The personal profile of the developer at `root`: absent reads as none, a broken file says what is wrong. */
|
|
27
|
+
export const readProfile = (opts: { root: string }): TProfileRead => {
|
|
28
|
+
const file = join(opts.root, OwnerConstants.PROFILE_FILE);
|
|
29
|
+
|
|
30
|
+
if (linkedAt({ root: opts.root }) !== undefined) {
|
|
31
|
+
return { ok: false, error: SYMLINK_ERROR };
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
if (!existsSync(file)) {
|
|
35
|
+
return { ok: true, profile: undefined };
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
let payload: unknown;
|
|
39
|
+
|
|
40
|
+
try {
|
|
41
|
+
payload = JSON.parse(readFileSync(file, 'utf8'));
|
|
42
|
+
} catch {
|
|
43
|
+
return { ok: false, error: `${OwnerConstants.PROFILE_FILE} is not valid JSON` };
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const parsed = PROFILE_SCHEMA.safeParse(payload);
|
|
47
|
+
|
|
48
|
+
if (parsed.success) {
|
|
49
|
+
return { ok: true, profile: parsed.data };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const issue = parsed.error.issues[0];
|
|
53
|
+
const where = issue?.path.join('.') ?? '';
|
|
54
|
+
|
|
55
|
+
return {
|
|
56
|
+
ok: false,
|
|
57
|
+
error: `${OwnerConstants.PROFILE_FILE}: ${where === '' ? '' : `${where}: `}${issue?.message ?? 'not a profile'}`,
|
|
58
|
+
};
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Whether git ignores the profile's place: `git check-ignore` decides when the project is a git repository
|
|
63
|
+
* (so a later `!` line or a nested ignore file counts); otherwise the `.gitignore` is read for the line.
|
|
64
|
+
*/
|
|
65
|
+
export const profileIsIgnored = (opts: { root: string }): boolean => {
|
|
66
|
+
const checked = spawnSync(
|
|
67
|
+
'git',
|
|
68
|
+
['check-ignore', '-q', '--no-index', OwnerConstants.PROFILE_FILE],
|
|
69
|
+
{ cwd: opts.root, timeout: 5000 },
|
|
70
|
+
);
|
|
71
|
+
|
|
72
|
+
if (checked.status === 0 || checked.status === 1) {
|
|
73
|
+
return checked.status === 0;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const file = join(opts.root, '.gitignore');
|
|
77
|
+
|
|
78
|
+
return (
|
|
79
|
+
existsSync(file) &&
|
|
80
|
+
readFileSync(file, 'utf8')
|
|
81
|
+
.split('\n')
|
|
82
|
+
.some((line) => ['.agents/local/', '.agents/local', '/.agents/local/'].includes(line.trim()))
|
|
83
|
+
);
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
/** The profile as the file holds it. */
|
|
87
|
+
export const renderProfile = (opts: { profile: TProfile }): string =>
|
|
88
|
+
`${JSON.stringify(opts.profile, null, 2)}\n`;
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Saves the profile. It refuses while `.gitignore` is missing or does not list `.agents/local/`, so a
|
|
92
|
+
* personal file cannot be written where a commit could pick it up.
|
|
93
|
+
*/
|
|
94
|
+
export const writeProfile = (opts: {
|
|
95
|
+
root: string;
|
|
96
|
+
profile: unknown;
|
|
97
|
+
}): { ok: true } | { ok: false; error: string } => {
|
|
98
|
+
const parsed = PROFILE_SCHEMA.safeParse(opts.profile);
|
|
99
|
+
|
|
100
|
+
if (!parsed.success) {
|
|
101
|
+
return { ok: false, error: parsed.error.issues[0]?.message ?? 'not a profile' };
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
if (!profileIsIgnored({ root: opts.root })) {
|
|
105
|
+
return {
|
|
106
|
+
ok: false,
|
|
107
|
+
error: `.gitignore does not list .agents/local/ - run vulcan sync (or add the line) before saving a personal profile`,
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
if (linkedAt({ root: opts.root }) !== undefined) {
|
|
112
|
+
return { ok: false, error: SYMLINK_ERROR };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
const file = join(opts.root, OwnerConstants.PROFILE_FILE);
|
|
116
|
+
|
|
117
|
+
mkdirSync(dirname(file), { recursive: true });
|
|
118
|
+
writeFileSync(file, renderProfile({ profile: parsed.data }), { mode: 0o600 });
|
|
119
|
+
// `mode` applies to a new file only; an existing one keeps its old mode until this.
|
|
120
|
+
chmodSync(file, 0o600);
|
|
121
|
+
|
|
122
|
+
return { ok: true };
|
|
123
|
+
};
|