@venizia/vulcan 0.4.4 → 0.4.6
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/LICENSE.md +1 -1
- package/README.md +13 -0
- package/base/agents.json +22 -1
- package/base/checks/wiki-anchors.ts +8 -0
- package/base/checks/wiki-source-links.ts +8 -0
- package/base/claude/remote-hosts.json +1 -1
- package/base/claude/settings.json +12 -12
- package/base/extensions/vulcan-guards.ts +301 -0
- package/base/hooks/antigravity-guards.ts +68 -0
- package/base/hooks/codex-guards.ts +66 -0
- package/base/hooks/guard-git.ts +38 -9
- package/base/hooks/guard-outside.ts +29 -9
- package/base/hooks/guard-writes.ts +29 -1
- package/base/hooks/session-start.ts +14 -4
- package/base/make/vulcan.mk +12 -1
- package/base/references/delegation-brief.md +5 -4
- package/base/rules.md +2 -2
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/docs-writing/references/agent-documents.md +1 -1
- package/base/skills/knowledge-sync/SKILL.md +1 -1
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/report-back/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +1 -1
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +33 -11
- package/base/skills/visualize-work/references/spec.md +77 -12
- package/package.json +4 -4
- package/src/agents/codex-hooks.ts +133 -0
- package/src/agents/common/constants.ts +54 -0
- package/src/agents/common/schema.ts +10 -1
- package/src/agents/common/types.ts +3 -1
- package/src/agents/exclude.ts +4 -0
- package/src/agents/hooks-json.ts +111 -0
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +5 -4
- package/src/agents/resolve.ts +24 -9
- package/src/config/common/constants.ts +12 -0
- package/src/config/common/types.ts +2 -1
- package/src/config/packages.ts +2 -1
- package/src/config/schema.ts +84 -5
- package/src/create/add-app.ts +2 -2
- package/src/create/add-lib.ts +21 -8
- package/src/create/common/constants.ts +12 -0
- package/src/create/common/types.ts +2 -1
- package/src/create/preset-diff.ts +4 -2
- package/src/create/workspace.ts +13 -9
- package/src/doctor/checks.ts +71 -1
- package/src/doctor/common/constants.ts +2 -0
- package/src/doctor/runner.ts +6 -0
- package/src/hooks/codex-patch.ts +47 -0
- package/src/hooks/command-view.ts +97 -0
- package/src/hooks/common/constants.ts +46 -0
- package/src/hooks/common/types.ts +9 -1
- package/src/hooks/decision.ts +50 -8
- package/src/hooks/guard-git.ts +64 -5
- package/src/hooks/guard-manifest.ts +22 -8
- package/src/hooks/guard-outside.ts +38 -6
- package/src/hooks/guard-package.ts +15 -12
- package/src/hooks/guard-writes.ts +72 -21
- package/src/hooks/index.ts +5 -0
- package/src/hooks/project-guards.ts +123 -0
- package/src/hooks/project-tmp.ts +36 -0
- package/src/hooks/remote-hosts.ts +38 -14
- package/src/hooks/session-digest.ts +5 -0
- package/src/hooks/shell.ts +665 -35
- package/src/hooks/trusted-scripts.ts +134 -0
- package/src/manifest/render.ts +38 -0
- package/src/sync/agent-files.ts +122 -4
- package/src/sync/agent-removal.ts +118 -4
- package/src/sync/claude-launch.ts +48 -0
- package/src/sync/index.ts +1 -0
- package/src/sync/local-choice.ts +2 -0
- package/src/visualize/assets.ts +195 -54
- package/src/visualize/charts.ts +235 -0
- package/src/visualize/constants.ts +122 -1
- package/src/visualize/diagrams.ts +224 -0
- package/src/visualize/icons.ts +28 -0
- package/src/visualize/layout.ts +58 -8
- package/src/visualize/page.ts +151 -145
- package/src/visualize/schema.ts +252 -2
- package/src/visualize/sections.ts +370 -0
- package/src/visualize/validate.ts +100 -7
- package/src/wiki/anchors.ts +118 -0
- package/src/wiki/command.ts +110 -0
- package/src/wiki/constants.ts +30 -0
- package/src/wiki/index.ts +4 -0
- package/src/wiki/source-links.ts +186 -0
package/src/config/packages.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { TPackageKind } from './common/index.ts';
|
|
1
2
|
import type { TResolvedConfig } from './schema.ts';
|
|
2
3
|
|
|
3
4
|
const DEFAULT_PACKAGES_DIRECTORY = 'packages';
|
|
@@ -9,7 +10,7 @@ export interface IProjectPackage {
|
|
|
9
10
|
path: string;
|
|
10
11
|
aliases: string[];
|
|
11
12
|
retired: boolean;
|
|
12
|
-
kind?:
|
|
13
|
+
kind?: TPackageKind;
|
|
13
14
|
}
|
|
14
15
|
|
|
15
16
|
/** The project's packages in release order. */
|
package/src/config/schema.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
|
+
import { isAbsolute } from 'node:path';
|
|
1
2
|
import { z } from 'zod';
|
|
2
3
|
import { layoutFolderProblem, layoutOverlapProblems } from '../common/layout-folder.ts';
|
|
3
4
|
import { OWNER_SCHEMA } from '../owner/schema.ts';
|
|
4
|
-
import { CodingAgents, ConfigConstants, HookEvents } from './common/index.ts';
|
|
5
|
+
import { CodingAgents, ConfigConstants, HookEvents, PackageKinds } from './common/index.ts';
|
|
5
6
|
|
|
6
7
|
const CODING_AGENT = z.string().refine((value) => CodingAgents.isValid(value), {
|
|
7
8
|
message: `one of: ${[...CodingAgents.SCHEME_SET].join(', ')}`,
|
|
@@ -10,6 +11,41 @@ const HOOK_EVENT = z.string().refine((value) => HookEvents.isValid(value), {
|
|
|
10
11
|
message: `one of: ${[...HookEvents.SCHEME_SET].join(', ')}`,
|
|
11
12
|
});
|
|
12
13
|
|
|
14
|
+
/** An ed25519 public key as `atlas index keygen` prints it: the base64 of its 32 raw bytes, nothing else. */
|
|
15
|
+
const INDEX_PUBLIC_KEY = z.string().refine(
|
|
16
|
+
(value) => {
|
|
17
|
+
const raw = Buffer.from(value, 'base64');
|
|
18
|
+
|
|
19
|
+
return raw.length === 32 && raw.toString('base64') === value;
|
|
20
|
+
},
|
|
21
|
+
{ message: 'the public key `atlas index keygen` prints: the base64 of 32 bytes' },
|
|
22
|
+
);
|
|
23
|
+
|
|
24
|
+
const compiles = (value: string): boolean => {
|
|
25
|
+
try {
|
|
26
|
+
return new RegExp(value) instanceof RegExp;
|
|
27
|
+
} catch {
|
|
28
|
+
return false;
|
|
29
|
+
}
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
/** A command the project says is a database write (V-W-02) or a deploy (V-W-03): guard-writes asks when its pattern matches. */
|
|
33
|
+
const GUARD_COMMAND = z.strictObject({
|
|
34
|
+
rule: z.enum(['V-W-02', 'V-W-03']),
|
|
35
|
+
what: z.string().min(1).max(120),
|
|
36
|
+
pattern: z
|
|
37
|
+
.string()
|
|
38
|
+
.min(1)
|
|
39
|
+
.max(500)
|
|
40
|
+
.refine(compiles, { message: 'a regular expression (JavaScript syntax)' }),
|
|
41
|
+
ignoreCase: z.boolean().optional(),
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
/** A branch a plain `git push` asks about: a name, with `*` for any run of characters. */
|
|
45
|
+
const PUSH_TARGET = z
|
|
46
|
+
.string()
|
|
47
|
+
.regex(/^[A-Za-z0-9._/*-]+$/, { message: 'a branch name, with * for any run of characters' });
|
|
48
|
+
|
|
13
49
|
/** A layout folder: 1 to 4 plain segments, never climbing, never absolute (the validator `guard-package` shares). */
|
|
14
50
|
const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
|
|
15
51
|
const problem = layoutFolderProblem({ folder: value });
|
|
@@ -19,6 +55,23 @@ const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
|
|
|
19
55
|
}
|
|
20
56
|
});
|
|
21
57
|
|
|
58
|
+
/** A script `guard-writes` may trust: a repo-relative `.ts` path - no glob, no `~`, never climbing out of the repo. */
|
|
59
|
+
const TRUSTED_SCRIPT = z.string().superRefine((value, context) => {
|
|
60
|
+
const problem = /[*?[\]{}!]/.test(value)
|
|
61
|
+
? 'no globs: list each script by its exact path'
|
|
62
|
+
: isAbsolute(value) || value.startsWith('~')
|
|
63
|
+
? 'a path relative to the repo root'
|
|
64
|
+
: value.split(/[\\/]/).includes('..')
|
|
65
|
+
? 'a path inside the repo, without ..'
|
|
66
|
+
: /\.ts$/.test(value)
|
|
67
|
+
? undefined
|
|
68
|
+
: 'a .ts file - guard-writes reads only bun scripts ending in .ts';
|
|
69
|
+
|
|
70
|
+
if (problem !== undefined) {
|
|
71
|
+
context.addIssue({ code: 'custom', message: `${value}: ${problem}` });
|
|
72
|
+
}
|
|
73
|
+
});
|
|
74
|
+
|
|
22
75
|
/** One folder, or a list of them: a side whose apps are grouped keeps each group's folder. */
|
|
23
76
|
const LAYOUT_VALUE = z.union([LAYOUT_FOLDER, z.array(LAYOUT_FOLDER).min(1)]);
|
|
24
77
|
|
|
@@ -30,7 +83,7 @@ const PROJECT_PACKAGE = z.strictObject({
|
|
|
30
83
|
aliases: z.array(z.string()).default([]),
|
|
31
84
|
retired: z.boolean().default(false),
|
|
32
85
|
/** A shared package a preset's lib kind made lives anywhere a workspace glob covers; absent means an app or a plain package. */
|
|
33
|
-
kind: z.enum([
|
|
86
|
+
kind: z.enum([PackageKinds.APP, PackageKinds.LIB]).optional(),
|
|
34
87
|
});
|
|
35
88
|
|
|
36
89
|
/** A path as a key: no leading `./`, no trailing slash. */
|
|
@@ -235,6 +288,14 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
235
288
|
.default([]),
|
|
236
289
|
/** Tags neither read nor checked (globs) - an old layout's tags. */
|
|
237
290
|
ignoreTags: z.array(z.string()).optional(),
|
|
291
|
+
/**
|
|
292
|
+
* The prebuilt atlas index this repository publishes: the public keys (any one may have signed a
|
|
293
|
+
* pair) that a project reading this one as a source checks the signature against. Rotation is a
|
|
294
|
+
* new list; a pair signed by a key no longer listed is not used.
|
|
295
|
+
*/
|
|
296
|
+
index: z.strictObject({ keys: z.array(INDEX_PUBLIC_KEY).default([]) }).optional(),
|
|
297
|
+
/** `false`: atlas never downloads a prebuilt index for a source this project reads; the default is to. */
|
|
298
|
+
prebuilt: z.boolean().optional(),
|
|
238
299
|
})
|
|
239
300
|
.default({
|
|
240
301
|
tagPattern: '<dir>-v<version>',
|
|
@@ -275,11 +336,29 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
275
336
|
/**
|
|
276
337
|
* The hooks that guard writes. `toolOwnedPaths` extends the defaults (package manager caches, the
|
|
277
338
|
* runtime dir for locks, git config, the agent tool's memory) with stores a tool in this project
|
|
278
|
-
* manages itself: absolute globs, `~` and `$NAME` allowed.
|
|
339
|
+
* manages itself: absolute globs, `~` and `$NAME` allowed. `writes.trustedScripts` lists the project's own
|
|
340
|
+
* CLIs (repo-relative `.ts` paths, no globs) whose body guard-writes does not read for mutating calls
|
|
341
|
+
* while git tracks them and they equal HEAD; the command line is still checked. `writes.commands` adds the
|
|
342
|
+
* project's own deploy and migrate commands to what guard-writes asks about (a pattern, matched inside
|
|
343
|
+
* compound commands too), and `git.askPush` lists the branches a plain `git push` asks about; `vulcan sync`
|
|
344
|
+
* writes both to the manifest, where the hooks read them.
|
|
279
345
|
*/
|
|
280
346
|
guard: z
|
|
281
|
-
.strictObject({
|
|
282
|
-
|
|
347
|
+
.strictObject({
|
|
348
|
+
toolOwnedPaths: z.array(z.string().min(1)).default([]),
|
|
349
|
+
writes: z
|
|
350
|
+
.strictObject({
|
|
351
|
+
trustedScripts: z.array(TRUSTED_SCRIPT).default([]),
|
|
352
|
+
commands: z.array(GUARD_COMMAND).default([]),
|
|
353
|
+
})
|
|
354
|
+
.default({ trustedScripts: [], commands: [] }),
|
|
355
|
+
git: z.strictObject({ askPush: z.array(PUSH_TARGET).default([]) }).default({ askPush: [] }),
|
|
356
|
+
})
|
|
357
|
+
.default({
|
|
358
|
+
toolOwnedPaths: [],
|
|
359
|
+
writes: { trustedScripts: [], commands: [] },
|
|
360
|
+
git: { askPush: [] },
|
|
361
|
+
}),
|
|
283
362
|
});
|
|
284
363
|
|
|
285
364
|
export type VulcanConfig = z.input<typeof VULCAN_CONFIG_SCHEMA>;
|
package/src/create/add-app.ts
CHANGED
|
@@ -15,7 +15,7 @@ import type { IProjectPackage, TResolvedConfig } from '../config/index.ts';
|
|
|
15
15
|
import { readWorkspaceGlobs } from '../init/index.ts';
|
|
16
16
|
import { addLibrary } from './add-lib.ts';
|
|
17
17
|
import { runAppChecks } from './checks.ts';
|
|
18
|
-
import { AppSides, CreateFlags } from './common/index.ts';
|
|
18
|
+
import { AppSides, AppsBlockProblems, CreateFlags } from './common/index.ts';
|
|
19
19
|
import type { IAppsBlock, ILocatedPreset, IPresetSpec, TAppSide } from './common/index.ts';
|
|
20
20
|
import { writeFile } from './files.ts';
|
|
21
21
|
import { recordedPresetOf } from './lib-preset.ts';
|
|
@@ -525,7 +525,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
525
525
|
if (!parsed.ok) {
|
|
526
526
|
return fail({
|
|
527
527
|
message: [
|
|
528
|
-
parsed.reason ===
|
|
528
|
+
parsed.reason === AppsBlockProblems.MISSING
|
|
529
529
|
? `the vulcan:apps block is gone from ${configPath} - add by hand:`
|
|
530
530
|
: `the vulcan:apps block in ${configPath} is not the JSON vulcan wrote - add by hand:`,
|
|
531
531
|
...literal({ side, folders: grown, app: entry, sources: newSources }),
|
package/src/create/add-lib.ts
CHANGED
|
@@ -9,10 +9,11 @@ import {
|
|
|
9
9
|
listedFoldersNote,
|
|
10
10
|
withLayoutFolder,
|
|
11
11
|
} from '../common/layout-folder.ts';
|
|
12
|
+
import { PackageKinds } from '../config/index.ts';
|
|
12
13
|
import type { IProjectPackage, TResolvedConfig } from '../config/index.ts';
|
|
13
14
|
import { readWorkspaceGlobs } from '../init/index.ts';
|
|
14
15
|
import { runAppChecks } from './checks.ts';
|
|
15
|
-
import { CreateConstants, CreateFlags } from './common/index.ts';
|
|
16
|
+
import { AppsBlockProblems, CreateConstants, CreateFlags } from './common/index.ts';
|
|
16
17
|
import type { IAppsBlock, ILocatedPreset, IPresetSpec } from './common/index.ts';
|
|
17
18
|
import { writeFile } from './files.ts';
|
|
18
19
|
import { readLibPreset } from './lib-preset.ts';
|
|
@@ -67,7 +68,7 @@ const folderOf = async (opts: {
|
|
|
67
68
|
const libFolders = [
|
|
68
69
|
...new Set(
|
|
69
70
|
opts.packages
|
|
70
|
-
.filter((entry) => entry.kind ===
|
|
71
|
+
.filter((entry) => entry.kind === PackageKinds.LIB && !entry.retired)
|
|
71
72
|
.map((entry) => dirname(entry.path)),
|
|
72
73
|
),
|
|
73
74
|
];
|
|
@@ -219,7 +220,7 @@ export const addLibrary = async (opts: {
|
|
|
219
220
|
if (!parsed.ok) {
|
|
220
221
|
return fail({
|
|
221
222
|
message:
|
|
222
|
-
parsed.reason ===
|
|
223
|
+
parsed.reason === AppsBlockProblems.MISSING
|
|
223
224
|
? `the vulcan:apps block is gone from ${opts.configPath} - add the package by hand: { dir: '${libName}', name: '${named.name}', path: '${path}', kind: 'lib' }`
|
|
224
225
|
: `the vulcan:apps block in ${opts.configPath} is not the JSON vulcan wrote - add the package by hand: { dir: '${libName}', name: '${named.name}', path: '${path}', kind: 'lib' }`,
|
|
225
226
|
});
|
|
@@ -228,15 +229,20 @@ export const addLibrary = async (opts: {
|
|
|
228
229
|
const sharedBefore = parsed.block.layout.shared;
|
|
229
230
|
const grown = withLayoutFolder({ value: sharedBefore, folder });
|
|
230
231
|
// A valid folder the layout does not list yet is added to layout.shared, unless it would nest with another folder.
|
|
231
|
-
const
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
232
|
+
const isListed = layoutFoldersOf({ value: sharedBefore }).includes(folder);
|
|
233
|
+
const notRecorded = isListed
|
|
234
|
+
? undefined
|
|
235
|
+
: (layoutFolderProblem({ folder }) ??
|
|
236
|
+
layoutOverlapProblems({ layout: { ...parsed.block.layout, shared: grown } }).join('; '));
|
|
237
|
+
const isNewFolder = !isListed && notRecorded === '';
|
|
235
238
|
const block = opts.recorded({
|
|
236
239
|
block: {
|
|
237
240
|
...parsed.block,
|
|
238
241
|
layout: isNewFolder ? { ...parsed.block.layout, shared: grown } : parsed.block.layout,
|
|
239
|
-
packages: [
|
|
242
|
+
packages: [
|
|
243
|
+
...parsed.block.packages,
|
|
244
|
+
{ dir: libName, name: named.name, path, kind: PackageKinds.LIB },
|
|
245
|
+
],
|
|
240
246
|
},
|
|
241
247
|
});
|
|
242
248
|
const replaced = replaceAppsBlock({ source, block });
|
|
@@ -260,6 +266,13 @@ export const addLibrary = async (opts: {
|
|
|
260
266
|
process.stderr.write(`${warning}\n`);
|
|
261
267
|
}
|
|
262
268
|
|
|
269
|
+
// The folder is used all the same; the layout does not list it, so `guard-package` does not cover it.
|
|
270
|
+
if (notRecorded !== undefined && notRecorded !== '') {
|
|
271
|
+
process.stderr.write(
|
|
272
|
+
`note: '${folder}' is not added to layout.shared (${notRecorded}); guard-package does not cover it\n`,
|
|
273
|
+
);
|
|
274
|
+
}
|
|
275
|
+
|
|
263
276
|
const rows: [string, string][] = [['library', path]];
|
|
264
277
|
|
|
265
278
|
if (isNewFolder) {
|
|
@@ -7,6 +7,18 @@ export class AppSides {
|
|
|
7
7
|
}
|
|
8
8
|
}
|
|
9
9
|
|
|
10
|
+
/** Why the `vulcan:apps` block of the config could not be read: its markers are gone, or what is between them is not JSON. */
|
|
11
|
+
export class AppsBlockProblems {
|
|
12
|
+
static readonly MISSING = 'missing';
|
|
13
|
+
static readonly INVALID = 'invalid';
|
|
14
|
+
|
|
15
|
+
static readonly SCHEME_SET = new Set<string>([this.MISSING, this.INVALID]);
|
|
16
|
+
|
|
17
|
+
static isValid(value: string): boolean {
|
|
18
|
+
return this.SCHEME_SET.has(value);
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
|
|
10
22
|
export class CreateConstants {
|
|
11
23
|
static readonly NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
|
|
12
24
|
/** A plain version with an optional prerelease and build part; ranges and URLs are not one. */
|
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import type { ILayout } from '../../common/layout-folder.ts';
|
|
2
2
|
import type { TConstValue } from '../../common/index.ts';
|
|
3
|
-
import type { AppSides } from './constants.ts';
|
|
3
|
+
import type { AppSides, AppsBlockProblems } from './constants.ts';
|
|
4
4
|
|
|
5
5
|
export type TAppSide = TConstValue<typeof AppSides>;
|
|
6
|
+
export type TAppsBlockProblem = TConstValue<typeof AppsBlockProblems>;
|
|
6
7
|
|
|
7
8
|
/** One name init or add needs: the flag that carries it, the question that asks it. */
|
|
8
9
|
export interface INameField {
|
|
@@ -4,7 +4,7 @@ import type { TConstValue } from '../common/index.ts';
|
|
|
4
4
|
import { ExitCodes } from '../common/index.ts';
|
|
5
5
|
import { layoutFoldersOf } from '../common/layout-folder.ts';
|
|
6
6
|
import type { ILayout } from '../common/layout-folder.ts';
|
|
7
|
-
import { loadConfig, resolvePackages } from '../config/index.ts';
|
|
7
|
+
import { loadConfig, PackageKinds, resolvePackages } from '../config/index.ts';
|
|
8
8
|
import { locate, resolveApiUrl } from './add-app.ts';
|
|
9
9
|
import { AppSides, CreateConstants, CreateFlags, PresetDiffStatuses } from './common/index.ts';
|
|
10
10
|
import type { ILocatedPreset, IRecordedPreset, IPresetSpec, TAppSide } from './common/index.ts';
|
|
@@ -270,7 +270,9 @@ export const runPresetDiff = async (opts: { cwd: string; args: string[] }): Prom
|
|
|
270
270
|
const app = packages.find((entry) => entry.dir === appName || entry.path === appName);
|
|
271
271
|
|
|
272
272
|
if (config.layout === undefined || app === undefined) {
|
|
273
|
-
const known = packages
|
|
273
|
+
const known = packages
|
|
274
|
+
.filter((entry) => entry.kind !== PackageKinds.LIB)
|
|
275
|
+
.map((entry) => entry.dir);
|
|
274
276
|
|
|
275
277
|
return fail({
|
|
276
278
|
message: `no app '${appName}' in the config packages${known.length === 0 ? '' : ` (apps: ${known.join(', ')})`}`,
|
package/src/create/workspace.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { relative, resolve } from 'node:path';
|
|
2
2
|
import { coversFolder } from '../init/index.ts';
|
|
3
|
-
import {
|
|
3
|
+
import { PackageKinds } from '../config/index.ts';
|
|
4
|
+
import { AppsBlockProblems, CreateConstants } from './common/index.ts';
|
|
4
5
|
import { renderManifestJson } from './manifest-json.ts';
|
|
5
6
|
import type {
|
|
6
7
|
IApp,
|
|
@@ -9,6 +10,7 @@ import type {
|
|
|
9
10
|
IPresetSpec,
|
|
10
11
|
IRecordedPreset,
|
|
11
12
|
TAppSide,
|
|
13
|
+
TAppsBlockProblem,
|
|
12
14
|
} from './common/index.ts';
|
|
13
15
|
|
|
14
16
|
const ENV_PORT = /^[A-Z0-9_]*PORT=(\d+)\s*$/m;
|
|
@@ -211,7 +213,7 @@ export const renderLibManifest = (opts: {
|
|
|
211
213
|
};
|
|
212
214
|
|
|
213
215
|
/** The atlas lookups a package of one kind depends on: what a summary page cannot hold. */
|
|
214
|
-
const ATLAS_LOOKUPS: Record<TAppSide |
|
|
216
|
+
const ATLAS_LOOKUPS: Record<TAppSide | typeof PackageKinds.LIB, [string, string][]> = {
|
|
215
217
|
backend: [
|
|
216
218
|
['How a route and its controller are written', '`search` "controller routes", then `get`'],
|
|
217
219
|
[
|
|
@@ -227,7 +229,7 @@ const ATLAS_LOOKUPS: Record<TAppSide | 'lib', [string, string][]> = {
|
|
|
227
229
|
};
|
|
228
230
|
|
|
229
231
|
/** The note and the table that turn a package page into a pointer at atlas, for its kind. */
|
|
230
|
-
const renderAtlasLookups = (opts: { kind: TAppSide |
|
|
232
|
+
const renderAtlasLookups = (opts: { kind: TAppSide | typeof PackageKinds.LIB }): string[] => [
|
|
231
233
|
'> This page is a summary, not a spec: it says what the package is. How code is written here lives',
|
|
232
234
|
'> in atlas; look it up before you explain or write code.',
|
|
233
235
|
'',
|
|
@@ -260,7 +262,7 @@ export const renderLibConcept = (opts: {
|
|
|
260
262
|
'',
|
|
261
263
|
`The shared package at \`${opts.path}\`, created from the ${opts.presetPackage} preset (lib kind). ${oneLine({ text: opts.summary })}`,
|
|
262
264
|
'',
|
|
263
|
-
...renderAtlasLookups({ kind:
|
|
265
|
+
...renderAtlasLookups({ kind: PackageKinds.LIB }),
|
|
264
266
|
].join('\n');
|
|
265
267
|
|
|
266
268
|
/**
|
|
@@ -367,7 +369,7 @@ const isAppsBlock = (value: unknown): value is IAppsBlock =>
|
|
|
367
369
|
|
|
368
370
|
export type TAppsBlockResult =
|
|
369
371
|
| { ok: true; block: IAppsBlock }
|
|
370
|
-
| { ok: false; reason:
|
|
372
|
+
| { ok: false; reason: TAppsBlockProblem };
|
|
371
373
|
|
|
372
374
|
const APPS_DECLARATION = 'const apps = ';
|
|
373
375
|
|
|
@@ -377,14 +379,14 @@ export const parseAppsBlock = (opts: { source: string }): TAppsBlockResult => {
|
|
|
377
379
|
const end = opts.source.indexOf(CreateConstants.APPS_BLOCK_END);
|
|
378
380
|
|
|
379
381
|
if (start === -1 || end === -1 || end < start) {
|
|
380
|
-
return { ok: false, reason:
|
|
382
|
+
return { ok: false, reason: AppsBlockProblems.MISSING };
|
|
381
383
|
}
|
|
382
384
|
|
|
383
385
|
const body = opts.source.slice(start + CreateConstants.APPS_BLOCK_START.length, end);
|
|
384
386
|
const declaration = body.indexOf(APPS_DECLARATION);
|
|
385
387
|
|
|
386
388
|
if (declaration === -1) {
|
|
387
|
-
return { ok: false, reason:
|
|
389
|
+
return { ok: false, reason: AppsBlockProblems.INVALID };
|
|
388
390
|
}
|
|
389
391
|
|
|
390
392
|
try {
|
|
@@ -395,13 +397,15 @@ export const parseAppsBlock = (opts: { source: string }): TAppsBlockResult => {
|
|
|
395
397
|
.replace(/;$/, ''),
|
|
396
398
|
);
|
|
397
399
|
|
|
398
|
-
return isAppsBlock(parsed)
|
|
400
|
+
return isAppsBlock(parsed)
|
|
401
|
+
? { ok: true, block: parsed }
|
|
402
|
+
: { ok: false, reason: AppsBlockProblems.INVALID };
|
|
399
403
|
} catch (error) {
|
|
400
404
|
console.error(
|
|
401
405
|
`[parseAppsBlock] the vulcan:apps block is not JSON | ${error instanceof Error ? error.message : String(error)}`,
|
|
402
406
|
);
|
|
403
407
|
|
|
404
|
-
return { ok: false, reason:
|
|
408
|
+
return { ok: false, reason: AppsBlockProblems.INVALID };
|
|
405
409
|
}
|
|
406
410
|
};
|
|
407
411
|
|
package/src/doctor/checks.ts
CHANGED
|
@@ -52,6 +52,7 @@ import {
|
|
|
52
52
|
ViolationConstants,
|
|
53
53
|
} from '../owner/index.ts';
|
|
54
54
|
import { skillCatalogOf, triggerOf } from '@venizia/vulcan-atlas';
|
|
55
|
+
import { trustOf, TrustStates } from '../hooks/index.ts';
|
|
55
56
|
import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
|
|
56
57
|
import type { IViolation, TDoctorCheck } from './common/index.ts';
|
|
57
58
|
import { parseMakeIncludes, parseMakeTargets } from './makefile.ts';
|
|
@@ -839,7 +840,7 @@ export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
|
|
|
839
840
|
const FMT_SECTION_ADVICE =
|
|
840
841
|
'add a [fmt] section (printWidth = 100, singleQuote = true, arrowParens = "always", flavor = "oxfmt"): without it bun fmt formats with Bun\'s defaults, not the shared style';
|
|
841
842
|
const FMT_FLAVOR_ADVICE =
|
|
842
|
-
'without it bun fmt
|
|
843
|
+
'without it bun fmt uses its default style when oxfmt is not a dependency, and the output changes';
|
|
843
844
|
const OXFMT_LOADED_ADVICE =
|
|
844
845
|
'bun fmt loads it and it overrides the [fmt] section of bunfig.toml - delete it, or move its settings to [fmt]';
|
|
845
846
|
|
|
@@ -1163,6 +1164,75 @@ export const checkOwnerReplySettings = (opts: { root: string }): IViolation[] =>
|
|
|
1163
1164
|
});
|
|
1164
1165
|
|
|
1165
1166
|
/** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
|
|
1167
|
+
/** The states of a listed script worth a warning: a typo or a script nobody committed. A modified one is normal work, so it is only a note. */
|
|
1168
|
+
const STALE_TRUST_STATES = new Set<string>([
|
|
1169
|
+
TrustStates.MISSING,
|
|
1170
|
+
TrustStates.UNTRACKED,
|
|
1171
|
+
TrustStates.UNCOMMITTED,
|
|
1172
|
+
TrustStates.SYMLINK,
|
|
1173
|
+
TrustStates.UNKNOWN,
|
|
1174
|
+
]);
|
|
1175
|
+
|
|
1176
|
+
/** One line per script in `guard.writes.trustedScripts` with what git says about it now (a note). */
|
|
1177
|
+
export const checkTrustedScripts = (opts: ICheckContext): IViolation[] =>
|
|
1178
|
+
opts.config.guard.writes.trustedScripts.map((script) => {
|
|
1179
|
+
const trust = trustOf({ root: opts.root, script });
|
|
1180
|
+
|
|
1181
|
+
return createViolation({
|
|
1182
|
+
check: DoctorChecks.GUARDS,
|
|
1183
|
+
file: script,
|
|
1184
|
+
message:
|
|
1185
|
+
trust.state === TrustStates.TRUSTED
|
|
1186
|
+
? 'guard-writes does not read this script for mutating calls (guard.writes.trustedScripts); it is ' +
|
|
1187
|
+
trust.reason
|
|
1188
|
+
: `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
|
|
1189
|
+
});
|
|
1190
|
+
});
|
|
1191
|
+
|
|
1192
|
+
/** A listed script that does not exist or is not committed: the exemption never applies (a warning). */
|
|
1193
|
+
export const checkStaleTrustedScripts = (opts: ICheckContext): IViolation[] =>
|
|
1194
|
+
opts.config.guard.writes.trustedScripts.flatMap((script) => {
|
|
1195
|
+
const trust = trustOf({ root: opts.root, script });
|
|
1196
|
+
|
|
1197
|
+
return STALE_TRUST_STATES.has(trust.state)
|
|
1198
|
+
? [
|
|
1199
|
+
createViolation({
|
|
1200
|
+
check: DoctorChecks.GUARDS,
|
|
1201
|
+
file: script,
|
|
1202
|
+
message: `guard.writes.trustedScripts lists it, but it never takes effect: ${trust.reason}; fix the path, or commit the script`,
|
|
1203
|
+
}),
|
|
1204
|
+
]
|
|
1205
|
+
: [];
|
|
1206
|
+
});
|
|
1207
|
+
|
|
1208
|
+
/**
|
|
1209
|
+
* The commands and push targets the project adds to guard-writes and guard-git, one note each: so the
|
|
1210
|
+
* guards' reach beyond their own list is visible where a person looks, with the rule and the pattern.
|
|
1211
|
+
*/
|
|
1212
|
+
export const checkGuardPatterns = (opts: ICheckContext): IViolation[] => {
|
|
1213
|
+
const { commands } = opts.config.guard.writes;
|
|
1214
|
+
const { askPush } = opts.config.guard.git;
|
|
1215
|
+
|
|
1216
|
+
return [
|
|
1217
|
+
...commands.map((command) =>
|
|
1218
|
+
createViolation({
|
|
1219
|
+
check: DoctorChecks.GUARDS,
|
|
1220
|
+
file: opts.configFile,
|
|
1221
|
+
message: `guard.writes.commands: ${command.rule} '${command.what}' asks when a command matches /${command.pattern}/${command.ignoreCase === true ? 'i' : ''}`,
|
|
1222
|
+
}),
|
|
1223
|
+
),
|
|
1224
|
+
...(askPush.length === 0
|
|
1225
|
+
? []
|
|
1226
|
+
: [
|
|
1227
|
+
createViolation({
|
|
1228
|
+
check: DoctorChecks.GUARDS,
|
|
1229
|
+
file: opts.configFile,
|
|
1230
|
+
message: `guard.git.askPush: a plain git push asks for ${askPush.join(', ')}`,
|
|
1231
|
+
}),
|
|
1232
|
+
]),
|
|
1233
|
+
];
|
|
1234
|
+
};
|
|
1235
|
+
|
|
1166
1236
|
export const checkLocalSize = (opts: ICheckContext): IViolation[] => {
|
|
1167
1237
|
const entries = scanLocal({ root: opts.root });
|
|
1168
1238
|
const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
|
|
@@ -20,6 +20,7 @@ export class DoctorChecks {
|
|
|
20
20
|
static readonly FORMAT = 'format';
|
|
21
21
|
static readonly LOCAL = 'local';
|
|
22
22
|
static readonly PROFILE = 'profile';
|
|
23
|
+
static readonly GUARDS = 'guards';
|
|
23
24
|
static readonly SCHEME_SET = new Set<string>([
|
|
24
25
|
this.CONFIG,
|
|
25
26
|
this.LAYOUT,
|
|
@@ -42,6 +43,7 @@ export class DoctorChecks {
|
|
|
42
43
|
this.FORMAT,
|
|
43
44
|
this.LOCAL,
|
|
44
45
|
this.PROFILE,
|
|
46
|
+
this.GUARDS,
|
|
45
47
|
]);
|
|
46
48
|
static isValid(value: string): boolean {
|
|
47
49
|
return this.SCHEME_SET.has(value);
|
package/src/doctor/runner.ts
CHANGED
|
@@ -18,8 +18,11 @@ import {
|
|
|
18
18
|
checkReplyShape,
|
|
19
19
|
checkPrune,
|
|
20
20
|
checkStaleLocal,
|
|
21
|
+
checkStaleTrustedScripts,
|
|
22
|
+
checkTrustedScripts,
|
|
21
23
|
checkHooks,
|
|
22
24
|
checkLayout,
|
|
25
|
+
checkGuardPatterns,
|
|
23
26
|
checkLocalWorkspace,
|
|
24
27
|
checkMake,
|
|
25
28
|
checkOutsideWorktrees,
|
|
@@ -95,8 +98,10 @@ export const runDoctorNotes = async (opts: {
|
|
|
95
98
|
...checkAppScripts(context),
|
|
96
99
|
...checkAtlasBlock(context),
|
|
97
100
|
...checkLocalSize(context),
|
|
101
|
+
...checkGuardPatterns(context),
|
|
98
102
|
...checkReplyShape(context),
|
|
99
103
|
...checkOwnerReplySwitch({ env: opts.env ?? process.env }),
|
|
104
|
+
...checkTrustedScripts(context),
|
|
100
105
|
];
|
|
101
106
|
};
|
|
102
107
|
|
|
@@ -124,5 +129,6 @@ export const runDoctorWarnings = async (opts: { root: string }): Promise<IViolat
|
|
|
124
129
|
...checkProfile(context),
|
|
125
130
|
...checkOwnerReplySettings(context),
|
|
126
131
|
...checkStaleLocal(context),
|
|
132
|
+
...checkStaleTrustedScripts(context),
|
|
127
133
|
];
|
|
128
134
|
};
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { isAbsolute, resolve } from 'node:path';
|
|
2
|
+
import type { TConstValue } from '../common/index.ts';
|
|
3
|
+
|
|
4
|
+
/** What one file of an `apply_patch` is to the guards: a file it adds is written, one it changes, deletes or moves is edited. */
|
|
5
|
+
export class PatchedTools {
|
|
6
|
+
static readonly WRITE = 'write';
|
|
7
|
+
static readonly EDIT = 'edit';
|
|
8
|
+
|
|
9
|
+
static readonly SCHEME_SET = new Set<string>([this.WRITE, this.EDIT]);
|
|
10
|
+
|
|
11
|
+
static isValid(value: string): boolean {
|
|
12
|
+
return this.SCHEME_SET.has(value);
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export type TPatchedTool = TConstValue<typeof PatchedTools>;
|
|
17
|
+
|
|
18
|
+
export interface IPatchedFile {
|
|
19
|
+
path: string;
|
|
20
|
+
tool: TPatchedTool;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
const HEADER = /^\*\*\* (Add|Update|Delete) File: (.+)$/;
|
|
24
|
+
const MOVE = /^\*\*\* Move to: (.+)$/;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* The files an `apply_patch` touches, from the patch text Codex sends as `tool_input.command`: the
|
|
28
|
+
* `*** Add File:`, `*** Update File:`, `*** Delete File:` and `*** Move to:` lines, made absolute against `cwd`.
|
|
29
|
+
*/
|
|
30
|
+
export const patchedFilesOf = (opts: { patch: string; cwd: string }): IPatchedFile[] =>
|
|
31
|
+
opts.patch.split('\n').flatMap((line): IPatchedFile[] => {
|
|
32
|
+
const header = HEADER.exec(line);
|
|
33
|
+
const target = header?.[2] ?? MOVE.exec(line)?.[1];
|
|
34
|
+
|
|
35
|
+
if (target === undefined) {
|
|
36
|
+
return [];
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const path = target.trim();
|
|
40
|
+
|
|
41
|
+
return [
|
|
42
|
+
{
|
|
43
|
+
path: isAbsolute(path) ? path : resolve(opts.cwd, path),
|
|
44
|
+
tool: header?.[1] === 'Add' ? PatchedTools.WRITE : PatchedTools.EDIT,
|
|
45
|
+
},
|
|
46
|
+
];
|
|
47
|
+
});
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { basenameOf, parseShell, programOf, splitHeredocs } from './shell.ts';
|
|
2
|
+
import type { ISimpleCommand } from './shell.ts';
|
|
3
|
+
|
|
4
|
+
/** Programs that only read or print what they are given: their arguments are text to find or show, never a command to run. */
|
|
5
|
+
const READ_ONLY_PROGRAMS = new Set([
|
|
6
|
+
'rg',
|
|
7
|
+
'grep',
|
|
8
|
+
'egrep',
|
|
9
|
+
'fgrep',
|
|
10
|
+
'ag',
|
|
11
|
+
'ack',
|
|
12
|
+
'cat',
|
|
13
|
+
'less',
|
|
14
|
+
'more',
|
|
15
|
+
'head',
|
|
16
|
+
'tail',
|
|
17
|
+
'wc',
|
|
18
|
+
'ls',
|
|
19
|
+
'diff',
|
|
20
|
+
'sort',
|
|
21
|
+
'uniq',
|
|
22
|
+
'echo',
|
|
23
|
+
'printf',
|
|
24
|
+
'man',
|
|
25
|
+
'file',
|
|
26
|
+
'stat',
|
|
27
|
+
'which',
|
|
28
|
+
]);
|
|
29
|
+
|
|
30
|
+
/** Programs whose arguments are messages and titles for the write guards (a commit message, an issue body). */
|
|
31
|
+
const MESSAGE_PROGRAMS = new Set(['git', 'gh']);
|
|
32
|
+
|
|
33
|
+
/** `find` runs a command only with these; without them it only lists. */
|
|
34
|
+
const FIND_RUNS = new Set(['-exec', '-execdir', '-ok', '-okdir', '-delete']);
|
|
35
|
+
|
|
36
|
+
/** Programs that read their heredoc as a query or a script: the body is part of what they run. */
|
|
37
|
+
const HEREDOC_READERS = new Set([
|
|
38
|
+
'ssh',
|
|
39
|
+
'psql',
|
|
40
|
+
'mysql',
|
|
41
|
+
'mongosh',
|
|
42
|
+
'sqlite3',
|
|
43
|
+
'python',
|
|
44
|
+
'python3',
|
|
45
|
+
'node',
|
|
46
|
+
'bun',
|
|
47
|
+
'deno',
|
|
48
|
+
'ruby',
|
|
49
|
+
'perl',
|
|
50
|
+
'php',
|
|
51
|
+
]);
|
|
52
|
+
|
|
53
|
+
/** A pipe into a program that runs what it is fed: `echo "kubectl apply -f x" | sh`. */
|
|
54
|
+
const PIPED_INTO_RUNNER =
|
|
55
|
+
/\|\s*(?:sudo\s+)?(?:sh|bash|zsh|dash|psql|mysql|mongosh|sqlite3|python3?|node|bun|ssh)\b/;
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Whether the arguments of a command are data. `withMessages` adds `git` and `gh` (their arguments are
|
|
59
|
+
* messages to the write guards, but a `git` remote is a host to the remote-host guard).
|
|
60
|
+
*/
|
|
61
|
+
export const isDataOnly = (opts: { command: ISimpleCommand; withMessages: boolean }): boolean => {
|
|
62
|
+
const name = basenameOf({ word: programOf({ command: opts.command }).name });
|
|
63
|
+
|
|
64
|
+
if (name === 'find') {
|
|
65
|
+
return !opts.command.words.some((word) => FIND_RUNS.has(word));
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
return READ_ONLY_PROGRAMS.has(name) || (opts.withMessages && MESSAGE_PROGRAMS.has(name));
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
/** The texts of the simple commands: the words, a bare name for data, a reader's heredoc body appended. */
|
|
72
|
+
const textsOf = (opts: { command: string; withMessages: boolean }): string[] =>
|
|
73
|
+
parseShell({ command: opts.command }).map((command) => {
|
|
74
|
+
const name = basenameOf({ word: programOf({ command }).name });
|
|
75
|
+
|
|
76
|
+
if (isDataOnly({ command, withMessages: opts.withMessages })) {
|
|
77
|
+
return name;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
const body =
|
|
81
|
+
command.heredoc !== undefined && HEREDOC_READERS.has(name) ? `\n${command.heredoc}` : '';
|
|
82
|
+
|
|
83
|
+
return `${command.words.join(' ')}${body}`;
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* What a command line runs, one text per simple command, for a guard that matches text: the words of each
|
|
88
|
+
* command with the quotes resolved, nothing but the name for a command whose arguments are data
|
|
89
|
+
* (`rg -n "kubectl apply" docs/`), and the body of a heredoc appended only where its reader runs it
|
|
90
|
+
* (`psql <<EOF`). The body of `cat > f <<EOF` is data and is not here. A line that pipes into a program
|
|
91
|
+
* that runs its input (`echo "kubectl apply -f x" | sh`) stands as one text, because what it prints is code.
|
|
92
|
+
*/
|
|
93
|
+
export const commandTextsOf = (opts: { command: string; withMessages: boolean }): string[] => {
|
|
94
|
+
const { text } = splitHeredocs({ command: opts.command });
|
|
95
|
+
|
|
96
|
+
return PIPED_INTO_RUNNER.test(text) ? [text] : textsOf(opts);
|
|
97
|
+
};
|