@venizia/vulcan 0.4.8 → 0.4.9-0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/base/hooks/antigravity-guards.ts +2 -1
- package/base/hooks/codex-guards.ts +2 -1
- package/base/hooks/guard-manifest.ts +2 -1
- package/base/hooks/guard-package.ts +2 -1
- package/base/hooks/guard-remote-hosts.ts +9 -3
- package/base/hooks/guard-scripting.ts +2 -1
- package/base/hooks/guard-writes.ts +14 -4
- package/base/hooks/post-tool.ts +2 -1
- package/base/hooks/prompt-submit.ts +2 -1
- package/base/hooks/session-start.ts +3 -1
- package/base/hooks/stop.ts +2 -1
- package/base/make/vulcan.mk +1 -4
- package/base/skills/build-a-feature/SKILL.md +1 -1
- package/base/skills/docs-update/SKILL.md +11 -5
- package/base/skills/docs-update/evals/evals.json +1 -1
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/plan-a-change/references/spec-card.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +20 -6
- package/base/skills/visualize-work/references/spec.md +16 -5
- package/package.json +5 -6
- package/src/agents/codex-hooks.ts +11 -10
- package/src/agents/common/types.ts +1 -1
- package/src/agents/exclude.ts +1 -1
- package/src/agents/hooks-json.ts +4 -8
- package/src/agents/prompt.ts +2 -2
- package/src/agents/render.ts +8 -12
- package/src/cli.ts +3 -1
- package/src/commands/doctor.command.ts +3 -1
- package/src/commands/help.command.ts +11 -9
- package/src/commands/init.command.ts +3 -1
- package/src/commands/profile.command.ts +1 -1
- package/src/commands/upgrade.command.ts +5 -3
- package/src/commands/visualize.command.ts +23 -2
- package/src/common/index.ts +2 -0
- package/src/common/layout-folder.ts +2 -20
- package/src/common/record.ts +7 -0
- package/src/common/text.ts +7 -0
- package/src/config/common/constants.ts +13 -1
- package/src/config/common/types.ts +8 -1
- package/src/config/loader.ts +4 -2
- package/src/config/packages.ts +4 -1
- package/src/config/schema.ts +51 -4
- package/src/create/add-app.ts +170 -69
- package/src/create/add-lib.ts +41 -31
- package/src/create/common/constants.ts +1 -0
- package/src/create/common/failure.ts +10 -0
- package/src/create/common/index.ts +2 -0
- package/src/create/common/preset-path.ts +11 -0
- package/src/create/common/types.ts +7 -2
- package/src/create/init-monorepo.ts +5 -2
- package/src/create/lib-preset.ts +22 -17
- package/src/create/names.ts +1 -1
- package/src/create/next.ts +1 -1
- package/src/create/preset-diff.ts +232 -55
- package/src/create/preset-menu.ts +3 -3
- package/src/create/preset.ts +18 -10
- package/src/create/process.ts +4 -2
- package/src/create/scratch.ts +3 -1
- package/src/create/workspace.ts +37 -20
- package/src/doctor/checks.ts +74 -16
- package/src/doctor/runner.ts +2 -0
- package/src/doctor/tags.ts +2 -4
- package/src/hooks/codex-patch.ts +2 -2
- package/src/hooks/common/constants.ts +0 -3
- package/src/hooks/common/types.ts +15 -1
- package/src/hooks/decision.ts +1 -5
- package/src/hooks/guard-git.ts +1 -1
- package/src/hooks/guard-outside.ts +28 -9
- package/src/hooks/guard-package.ts +13 -7
- package/src/hooks/guard-scripting.ts +1 -1
- package/src/hooks/guard-writes.ts +73 -20
- package/src/hooks/owner-reply.ts +1 -1
- package/src/hooks/project-guards.ts +39 -4
- package/src/hooks/remote-hosts.ts +5 -20
- package/src/hooks/session-digest.ts +7 -0
- package/src/hooks/shell.ts +13 -4
- package/src/hooks/trusted-scripts.ts +80 -4
- package/src/init/common/types.ts +1 -1
- package/src/init/scaffold.ts +2 -2
- package/src/local/clean.ts +1 -1
- package/src/local/scan.ts +2 -2
- package/src/manifest/render.ts +20 -11
- package/src/owner/profile.ts +1 -3
- package/src/owner/shape.ts +1 -1
- package/src/owner/survey.ts +27 -18
- package/src/router.ts +4 -1
- package/src/rules/common/types.ts +1 -1
- package/src/signals/state.ts +1 -4
- package/src/sync/agent-removal.ts +7 -10
- package/src/sync/claude-launch.ts +36 -1
- package/src/sync/common/constants.ts +4 -0
- package/src/sync/common/index.ts +1 -0
- package/src/sync/common/symlink.ts +9 -0
- package/src/sync/common/types.ts +2 -2
- package/src/sync/planner.ts +10 -12
- package/src/sync/settings.ts +1 -1
- package/src/ui/keyboard.ts +3 -1
- package/src/ui/prompt.ts +4 -2
- package/src/visualize/assets.ts +370 -195
- package/src/visualize/charts.ts +11 -2
- package/src/visualize/compare-css.ts +30 -0
- package/src/visualize/compare-render.ts +194 -0
- package/src/visualize/compare-schema.ts +81 -0
- package/src/visualize/compare-validate.ts +126 -0
- package/src/visualize/constants.ts +29 -3
- package/src/visualize/diagrams.ts +1 -1
- package/src/visualize/gate.ts +136 -0
- package/src/visualize/icons.ts +5 -2
- package/src/visualize/index.ts +2 -0
- package/src/visualize/kinds-css.ts +54 -0
- package/src/visualize/kinds-render.ts +693 -0
- package/src/visualize/kinds-schema.ts +148 -0
- package/src/visualize/kinds-validate.ts +184 -0
- package/src/visualize/labels-vi.ts +109 -0
- package/src/visualize/labels.ts +49 -0
- package/src/visualize/layout.ts +10 -5
- package/src/visualize/page.ts +99 -61
- package/src/visualize/render.ts +48 -7
- package/src/visualize/schema.ts +21 -1
- package/src/visualize/sections.ts +115 -34
- package/src/visualize/sources.ts +270 -0
- package/src/visualize/theme.ts +472 -0
- package/src/visualize/validate.ts +6 -0
- package/src/wiki/anchors.ts +1 -1
- package/src/wiki/source-links.ts +3 -5
package/src/create/scratch.ts
CHANGED
|
@@ -56,7 +56,9 @@ export const withScratch = async <TResult>(opts: {
|
|
|
56
56
|
const scratch = mkdtempSync(join(parent, 'preset-'));
|
|
57
57
|
|
|
58
58
|
try {
|
|
59
|
-
|
|
59
|
+
const outcome = await opts.run(scratch);
|
|
60
|
+
|
|
61
|
+
return outcome;
|
|
60
62
|
} finally {
|
|
61
63
|
rmSync(scratch, { recursive: true, force: true });
|
|
62
64
|
removeIfEmpty({ directory: parent });
|
package/src/create/workspace.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { relative, resolve } from 'node:path';
|
|
2
|
+
import { RecordValue } from '../common/record.ts';
|
|
2
3
|
import { coversFolder } from '../init/index.ts';
|
|
3
|
-
import { PackageKinds } from '../config/index.ts';
|
|
4
|
+
import { LibraryKinds, PackageKinds } from '../config/index.ts';
|
|
5
|
+
import type { TLibraryKind } from '../config/index.ts';
|
|
4
6
|
import { AppsBlockProblems, CreateConstants } from './common/index.ts';
|
|
5
7
|
import { renderManifestJson } from './manifest-json.ts';
|
|
6
8
|
import type {
|
|
@@ -40,11 +42,8 @@ export const mergeCatalog = (opts: {
|
|
|
40
42
|
additions: Record<string, string>;
|
|
41
43
|
}): Record<string, string> => ({ ...opts.additions, ...opts.catalog });
|
|
42
44
|
|
|
43
|
-
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
44
|
-
typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
45
|
-
|
|
46
45
|
const toStringRecord = (opts: { value: unknown }): Record<string, string> =>
|
|
47
|
-
isRecord(opts.value)
|
|
46
|
+
RecordValue.isRecord(opts.value)
|
|
48
47
|
? Object.fromEntries(
|
|
49
48
|
Object.entries(opts.value).filter(
|
|
50
49
|
(entry): entry is [string, string] => typeof entry[1] === 'string',
|
|
@@ -56,7 +55,7 @@ const toStringRecord = (opts: { value: unknown }): Record<string, string> =>
|
|
|
56
55
|
export const readCatalog = (opts: {
|
|
57
56
|
manifest: Record<string, unknown>;
|
|
58
57
|
}): Record<string, string> => ({
|
|
59
|
-
...(isRecord(opts.manifest.workspaces)
|
|
58
|
+
...(RecordValue.isRecord(opts.manifest.workspaces)
|
|
60
59
|
? toStringRecord({ value: opts.manifest.workspaces.catalog })
|
|
61
60
|
: {}),
|
|
62
61
|
...toStringRecord({ value: opts.manifest.catalog }),
|
|
@@ -82,14 +81,14 @@ export const planRootManifest = (opts: {
|
|
|
82
81
|
const fresh = Object.fromEntries(
|
|
83
82
|
Object.entries(opts.additions).filter(([name]) => existing[name] === undefined),
|
|
84
83
|
);
|
|
85
|
-
const isTopLevel = isRecord(manifest.catalog) || Array.isArray(workspaces);
|
|
84
|
+
const isTopLevel = RecordValue.isRecord(manifest.catalog) || Array.isArray(workspaces);
|
|
86
85
|
|
|
87
86
|
if (isTopLevel) {
|
|
88
87
|
return {
|
|
89
88
|
...manifest,
|
|
90
89
|
workspaces: Array.isArray(workspaces)
|
|
91
90
|
? globs
|
|
92
|
-
: { ...(isRecord(workspaces) ? workspaces : {}), packages: globs },
|
|
91
|
+
: { ...(RecordValue.isRecord(workspaces) ? workspaces : {}), packages: globs },
|
|
93
92
|
catalog: mergeCatalog({
|
|
94
93
|
catalog: toStringRecord({ value: manifest.catalog }),
|
|
95
94
|
additions: fresh,
|
|
@@ -97,7 +96,7 @@ export const planRootManifest = (opts: {
|
|
|
97
96
|
};
|
|
98
97
|
}
|
|
99
98
|
|
|
100
|
-
const inside = isRecord(workspaces) ? workspaces : {};
|
|
99
|
+
const inside = RecordValue.isRecord(workspaces) ? workspaces : {};
|
|
101
100
|
|
|
102
101
|
return {
|
|
103
102
|
...manifest,
|
|
@@ -121,6 +120,8 @@ export const planRootManifest = (opts: {
|
|
|
121
120
|
export const checkPeers = (opts: {
|
|
122
121
|
catalog: Record<string, string>;
|
|
123
122
|
peers: Record<string, string>;
|
|
123
|
+
/** What the preset itself lists, so the catalog `init` wrote from it is not held to its own range. */
|
|
124
|
+
presetVersions?: Pick<IPreset, 'dependencies' | 'devDependencies'>;
|
|
124
125
|
}): string | undefined => {
|
|
125
126
|
for (const [name, range] of Object.entries(opts.peers)) {
|
|
126
127
|
const pinned = opts.catalog[name];
|
|
@@ -129,6 +130,15 @@ export const checkPeers = (opts: {
|
|
|
129
130
|
continue;
|
|
130
131
|
}
|
|
131
132
|
|
|
133
|
+
// A pin equal to the version this preset lists is satisfied by construction (`init` wrote it
|
|
134
|
+
// from the preset); only a pin set by something else is compared with the range.
|
|
135
|
+
if (
|
|
136
|
+
pinned === opts.presetVersions?.dependencies[name] ||
|
|
137
|
+
pinned === opts.presetVersions?.devDependencies[name]
|
|
138
|
+
) {
|
|
139
|
+
continue;
|
|
140
|
+
}
|
|
141
|
+
|
|
132
142
|
const version = pinned.replace(/^[\^~]/, '');
|
|
133
143
|
|
|
134
144
|
if (!CreateConstants.VERSION_PATTERN.test(version)) {
|
|
@@ -225,7 +235,7 @@ const ATLAS_LOOKUPS: Record<TAppSide | typeof PackageKinds.LIB, [string, string]
|
|
|
225
235
|
['How a page or a resource is added', '`search` "page resource", then `get`'],
|
|
226
236
|
['How the app reads data from its backend', '`search` "data provider"'],
|
|
227
237
|
],
|
|
228
|
-
lib: [['How a
|
|
238
|
+
lib: [['How a library exposes its API', '`search` "library exports", then `get`']],
|
|
229
239
|
};
|
|
230
240
|
|
|
231
241
|
/** The note and the table that turn a package page into a pointer at atlas, for its kind. */
|
|
@@ -248,6 +258,8 @@ export const renderLibConcept = (opts: {
|
|
|
248
258
|
path: string;
|
|
249
259
|
summary: string;
|
|
250
260
|
presetPackage: string;
|
|
261
|
+
/** Which preset kind made the package; `lib` when absent. */
|
|
262
|
+
kind?: TLibraryKind;
|
|
251
263
|
}): string =>
|
|
252
264
|
[
|
|
253
265
|
'---',
|
|
@@ -260,7 +272,7 @@ export const renderLibConcept = (opts: {
|
|
|
260
272
|
'',
|
|
261
273
|
`# ${opts.name}`,
|
|
262
274
|
'',
|
|
263
|
-
`The
|
|
275
|
+
`The ${opts.kind === LibraryKinds.SHARED ? 'side-neutral package' : 'library'} at \`${opts.path}\`, created from the ${opts.presetPackage} preset (${opts.kind ?? LibraryKinds.LIB} kind). ${oneLine({ text: opts.summary })}`,
|
|
264
276
|
'',
|
|
265
277
|
...renderAtlasLookups({ kind: PackageKinds.LIB }),
|
|
266
278
|
].join('\n');
|
|
@@ -343,33 +355,38 @@ export const replaceAppsBlock = (opts: {
|
|
|
343
355
|
const hasStrings = (opts: { value: unknown; keys: string[] }): boolean => {
|
|
344
356
|
const { value } = opts;
|
|
345
357
|
|
|
346
|
-
return isRecord(value) && opts.keys.every((key) => typeof value[key] === 'string');
|
|
358
|
+
return RecordValue.isRecord(value) && opts.keys.every((key) => typeof value[key] === 'string');
|
|
347
359
|
};
|
|
348
360
|
|
|
349
361
|
const isRecordedPreset = (value: unknown): boolean =>
|
|
350
362
|
hasStrings({ value, keys: ['spec', 'side', 'summary'] }) &&
|
|
351
|
-
isRecord(value) &&
|
|
363
|
+
RecordValue.isRecord(value) &&
|
|
352
364
|
(value.side === 'backend' || value.side === 'frontend') &&
|
|
353
|
-
(value.lib === undefined || typeof value.lib === 'string')
|
|
365
|
+
(value.lib === undefined || typeof value.lib === 'string') &&
|
|
366
|
+
(value.shared === undefined || typeof value.shared === 'string');
|
|
354
367
|
|
|
355
368
|
const isAppsBlock = (value: unknown): value is IAppsBlock =>
|
|
356
|
-
isRecord(value) &&
|
|
369
|
+
RecordValue.isRecord(value) &&
|
|
357
370
|
(value.presets === undefined ||
|
|
358
371
|
(Array.isArray(value.presets) && value.presets.every((entry) => isRecordedPreset(entry)))) &&
|
|
359
|
-
isRecord(value.layout) &&
|
|
372
|
+
RecordValue.isRecord(value.layout) &&
|
|
360
373
|
Object.values(value.layout).every(
|
|
361
374
|
(folders) =>
|
|
362
375
|
typeof folders === 'string' ||
|
|
363
376
|
(Array.isArray(folders) && folders.every((folder) => typeof folder === 'string')),
|
|
364
377
|
) &&
|
|
365
378
|
Array.isArray(value.packages) &&
|
|
366
|
-
value.packages.every(
|
|
379
|
+
value.packages.every(
|
|
380
|
+
(entry) =>
|
|
381
|
+
hasStrings({ value: entry, keys: ['dir', 'name', 'path'] }) &&
|
|
382
|
+
RecordValue.isRecord(entry) &&
|
|
383
|
+
(entry.presetKind === undefined ||
|
|
384
|
+
(typeof entry.presetKind === 'string' && LibraryKinds.isValid(entry.presetKind))),
|
|
385
|
+
) &&
|
|
367
386
|
Array.isArray(value.sources) &&
|
|
368
387
|
value.sources.every((entry) => hasStrings({ value: entry, keys: ['name', 'repo', 'ref'] }));
|
|
369
388
|
|
|
370
|
-
|
|
371
|
-
| { ok: true; block: IAppsBlock }
|
|
372
|
-
| { ok: false; reason: TAppsBlockProblem };
|
|
389
|
+
type TAppsBlockResult = { ok: true; block: IAppsBlock } | { ok: false; reason: TAppsBlockProblem };
|
|
373
390
|
|
|
374
391
|
const APPS_DECLARATION = 'const apps = ';
|
|
375
392
|
|
package/src/doctor/checks.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { Glob } from 'bun';
|
|
2
2
|
import { spawnSync } from 'node:child_process';
|
|
3
|
-
import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
|
|
3
|
+
import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
|
|
4
4
|
import { basename, dirname, join, relative, sep } from 'node:path';
|
|
5
|
-
import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
|
|
5
|
+
import { BASE_DIRECTORY, ProjectLayout, RecordValue } from '../common/index.ts';
|
|
6
6
|
import { LayoutKeys, layoutFoldersOf } from '../common/layout-folder.ts';
|
|
7
7
|
import {
|
|
8
8
|
coversFolder,
|
|
@@ -51,7 +51,7 @@ import {
|
|
|
51
51
|
violationLogBytes,
|
|
52
52
|
ViolationConstants,
|
|
53
53
|
} from '../owner/index.ts';
|
|
54
|
-
import {
|
|
54
|
+
import { SkillCatalog } from '@venizia/vulcan-atlas';
|
|
55
55
|
import { trustOf, TrustStates } from '../hooks/index.ts';
|
|
56
56
|
import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
|
|
57
57
|
import type { IViolation, TDoctorCheck } from './common/index.ts';
|
|
@@ -273,7 +273,7 @@ export const checkAdapters = (opts: ICheckContext): IViolation[] => {
|
|
|
273
273
|
createViolation({
|
|
274
274
|
check: DoctorChecks.ADAPTERS,
|
|
275
275
|
file: relative(opts.root, absent[0].path),
|
|
276
|
-
message: `not synced yet - run '${ProjectLayout.VULCAN_COMMAND} sync' (make
|
|
276
|
+
message: `not synced yet - run '${ProjectLayout.VULCAN_COMMAND} sync' (make vulcan-sync) first`,
|
|
277
277
|
}),
|
|
278
278
|
];
|
|
279
279
|
|
|
@@ -644,9 +644,6 @@ const readJsonObject = (opts: { file: string }): Record<string, unknown> | undef
|
|
|
644
644
|
}
|
|
645
645
|
};
|
|
646
646
|
|
|
647
|
-
const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
|
|
648
|
-
typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
|
|
649
|
-
|
|
650
647
|
/** Whether git lists the file as untracked and not ignored: what a clean-tree check, such as a release, refuses on. */
|
|
651
648
|
const isUntrackedAndVisible = (opts: { root: string; path: string }): boolean => {
|
|
652
649
|
const listed = spawnSync('git', ['status', '--porcelain', '--', opts.path], {
|
|
@@ -708,17 +705,17 @@ export const checkMcpAtlas = (opts: ICheckContext): IViolation[] => {
|
|
|
708
705
|
);
|
|
709
706
|
} else {
|
|
710
707
|
const holder = { value: parsed['mcpServers'] };
|
|
711
|
-
const servers = isRecord(holder) ? holder.value : {};
|
|
708
|
+
const servers = RecordValue.isRecord(holder.value) ? holder.value : {};
|
|
712
709
|
const entry = { value: servers[ATLAS_SERVER] };
|
|
713
|
-
const args = isRecord(entry) ? entry.value['args'] : undefined;
|
|
710
|
+
const args = RecordValue.isRecord(entry.value) ? entry.value['args'] : undefined;
|
|
714
711
|
const isCanonical =
|
|
715
|
-
isRecord(entry) &&
|
|
712
|
+
RecordValue.isRecord(entry.value) &&
|
|
716
713
|
entry.value['command'] === 'bun' &&
|
|
717
714
|
Array.isArray(args) &&
|
|
718
715
|
args.length === CANONICAL_ATLAS_ARGS.length &&
|
|
719
716
|
args.every((arg, index) => arg === CANONICAL_ATLAS_ARGS[index]);
|
|
720
717
|
|
|
721
|
-
if (!isRecord(entry)) {
|
|
718
|
+
if (!RecordValue.isRecord(entry.value)) {
|
|
722
719
|
warnings.push(
|
|
723
720
|
mcpWarning({
|
|
724
721
|
file: MCP_FILE,
|
|
@@ -974,8 +971,8 @@ export const checkAtlasBlock = (opts: ICheckContext): IViolation[] => {
|
|
|
974
971
|
|
|
975
972
|
/** A skill with no "Use when" part gives the atlas server's instructions nothing to say when to load it: a warning, never a failure. */
|
|
976
973
|
export const checkSkillTriggers = (opts: ICheckContext): IViolation[] =>
|
|
977
|
-
|
|
978
|
-
.filter((entry) => !triggerOf({ description: entry.description }).hasUseWhen)
|
|
974
|
+
SkillCatalog.catalogOf({ root: opts.root })
|
|
975
|
+
.filter((entry) => !SkillCatalog.triggerOf({ description: entry.description }).hasUseWhen)
|
|
979
976
|
.map((entry) =>
|
|
980
977
|
createViolation({
|
|
981
978
|
check: DoctorChecks.SKILLS,
|
|
@@ -1173,25 +1170,86 @@ const STALE_TRUST_STATES = new Set<string>([
|
|
|
1173
1170
|
TrustStates.UNKNOWN,
|
|
1174
1171
|
]);
|
|
1175
1172
|
|
|
1173
|
+
const QUOTES = ["'", '"', '`'];
|
|
1174
|
+
|
|
1175
|
+
/** The path of a `guard.writes.trustedScripts` entry, and the subcommands when it is the object form. */
|
|
1176
|
+
const trustedScriptOf = (opts: {
|
|
1177
|
+
entry: TResolvedConfig['guard']['writes']['trustedScripts'][number];
|
|
1178
|
+
}): { script: string; readOnly: string[] | undefined } =>
|
|
1179
|
+
typeof opts.entry === 'string'
|
|
1180
|
+
? { script: opts.entry, readOnly: undefined }
|
|
1181
|
+
: { script: opts.entry.script, readOnly: opts.entry.readOnly };
|
|
1182
|
+
|
|
1176
1183
|
/** One line per script in `guard.writes.trustedScripts` with what git says about it now (a note). */
|
|
1177
1184
|
export const checkTrustedScripts = (opts: ICheckContext): IViolation[] =>
|
|
1178
|
-
opts.config.guard.writes.trustedScripts.map((
|
|
1185
|
+
opts.config.guard.writes.trustedScripts.map((entry) => {
|
|
1186
|
+
const { script, readOnly } = trustedScriptOf({ entry });
|
|
1179
1187
|
const trust = trustOf({ root: opts.root, script });
|
|
1188
|
+
const scope = readOnly === undefined ? 'mutating calls' : `the calls ${readOnly.join(', ')}`;
|
|
1180
1189
|
|
|
1181
1190
|
return createViolation({
|
|
1182
1191
|
check: DoctorChecks.GUARDS,
|
|
1183
1192
|
file: script,
|
|
1184
1193
|
message:
|
|
1185
1194
|
trust.state === TrustStates.TRUSTED
|
|
1186
|
-
?
|
|
1195
|
+
? `guard-writes does not read this script for ${scope} (guard.writes.trustedScripts); it is ` +
|
|
1187
1196
|
trust.reason
|
|
1188
1197
|
: `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
|
|
1189
1198
|
});
|
|
1190
1199
|
});
|
|
1191
1200
|
|
|
1201
|
+
/**
|
|
1202
|
+
* A subcommand an object entry lists that its script never holds as a quoted string (a note). It reads the
|
|
1203
|
+
* text of the file, so it cannot tell a subcommand the script handles another way from a typo.
|
|
1204
|
+
*/
|
|
1205
|
+
export class ReadOnlySubcommandChecks {
|
|
1206
|
+
static readonly MAX_SOURCE_BYTES = 1_000_000;
|
|
1207
|
+
|
|
1208
|
+
static sourceOf(opts: { path: string }): string | undefined {
|
|
1209
|
+
try {
|
|
1210
|
+
const stat = lstatSync(opts.path);
|
|
1211
|
+
|
|
1212
|
+
return stat.isFile() && stat.size <= ReadOnlySubcommandChecks.MAX_SOURCE_BYTES
|
|
1213
|
+
? readFileSync(opts.path, 'utf8')
|
|
1214
|
+
: undefined;
|
|
1215
|
+
} catch {
|
|
1216
|
+
return undefined;
|
|
1217
|
+
}
|
|
1218
|
+
}
|
|
1219
|
+
|
|
1220
|
+
static check(opts: ICheckContext): IViolation[] {
|
|
1221
|
+
return opts.config.guard.writes.trustedScripts.flatMap((entry) => {
|
|
1222
|
+
const { script, readOnly } = trustedScriptOf({ entry });
|
|
1223
|
+
const path = join(opts.root, script);
|
|
1224
|
+
|
|
1225
|
+
if (readOnly === undefined) {
|
|
1226
|
+
return [];
|
|
1227
|
+
}
|
|
1228
|
+
|
|
1229
|
+
// Only a plain, small file inside the repo is read: a link, a folder or a device is skipped, never followed.
|
|
1230
|
+
const source = ReadOnlySubcommandChecks.sourceOf({ path });
|
|
1231
|
+
|
|
1232
|
+
if (source === undefined) {
|
|
1233
|
+
return [];
|
|
1234
|
+
}
|
|
1235
|
+
|
|
1236
|
+
return readOnly
|
|
1237
|
+
.filter((word) => !QUOTES.some((quote) => source.includes(`${quote}${word}${quote}`)))
|
|
1238
|
+
.map((word) =>
|
|
1239
|
+
createViolation({
|
|
1240
|
+
check: DoctorChecks.GUARDS,
|
|
1241
|
+
file: script,
|
|
1242
|
+
message: `guard.writes.trustedScripts lists the subcommand '${word}' for this script, but the script does not hold it as a quoted string; this is a check of the text of the file, not what the script does`,
|
|
1243
|
+
}),
|
|
1244
|
+
);
|
|
1245
|
+
});
|
|
1246
|
+
}
|
|
1247
|
+
}
|
|
1248
|
+
|
|
1192
1249
|
/** A listed script that does not exist or is not committed: the exemption never applies (a warning). */
|
|
1193
1250
|
export const checkStaleTrustedScripts = (opts: ICheckContext): IViolation[] =>
|
|
1194
|
-
opts.config.guard.writes.trustedScripts.flatMap((
|
|
1251
|
+
opts.config.guard.writes.trustedScripts.flatMap((entry) => {
|
|
1252
|
+
const { script } = trustedScriptOf({ entry });
|
|
1195
1253
|
const trust = trustOf({ root: opts.root, script });
|
|
1196
1254
|
|
|
1197
1255
|
return STALE_TRUST_STATES.has(trust.state)
|
package/src/doctor/runner.ts
CHANGED
|
@@ -18,6 +18,7 @@ import {
|
|
|
18
18
|
checkReplyShape,
|
|
19
19
|
checkPrune,
|
|
20
20
|
checkStaleLocal,
|
|
21
|
+
ReadOnlySubcommandChecks,
|
|
21
22
|
checkStaleTrustedScripts,
|
|
22
23
|
checkTrustedScripts,
|
|
23
24
|
checkHooks,
|
|
@@ -102,6 +103,7 @@ export const runDoctorNotes = async (opts: {
|
|
|
102
103
|
...checkReplyShape(context),
|
|
103
104
|
...checkOwnerReplySwitch({ env: opts.env ?? process.env }),
|
|
104
105
|
...checkTrustedScripts(context),
|
|
106
|
+
...ReadOnlySubcommandChecks.check(context),
|
|
105
107
|
];
|
|
106
108
|
};
|
|
107
109
|
|
package/src/doctor/tags.ts
CHANGED
|
@@ -1,12 +1,10 @@
|
|
|
1
1
|
import { spawnSync } from 'node:child_process';
|
|
2
|
+
import { TextValue } from '../common/text.ts';
|
|
2
3
|
import { resolvePackages } from '../config/index.ts';
|
|
3
4
|
import type { ICheckContext } from './checks.ts';
|
|
4
5
|
import { DoctorChecks } from './common/index.ts';
|
|
5
6
|
import type { IViolation } from './common/index.ts';
|
|
6
7
|
|
|
7
|
-
const escapeLiteral = (opts: { text: string }): string =>
|
|
8
|
-
opts.text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
9
|
-
|
|
10
8
|
/** The tag pattern as a regular expression that captures `<dir>` (or `<package>`). */
|
|
11
9
|
const tagPatternOf = (opts: { template: string }): RegExp =>
|
|
12
10
|
new RegExp(
|
|
@@ -28,7 +26,7 @@ const tagPatternOf = (opts: { template: string }): RegExp =>
|
|
|
28
26
|
}
|
|
29
27
|
|
|
30
28
|
default: {
|
|
31
|
-
return escapeLiteral({ text: part });
|
|
29
|
+
return TextValue.escapeLiteral({ text: part });
|
|
32
30
|
}
|
|
33
31
|
}
|
|
34
32
|
})
|
package/src/hooks/codex-patch.ts
CHANGED
|
@@ -13,9 +13,9 @@ export class PatchedTools {
|
|
|
13
13
|
}
|
|
14
14
|
}
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
type TPatchedTool = TConstValue<typeof PatchedTools>;
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
interface IPatchedFile {
|
|
19
19
|
path: string;
|
|
20
20
|
tool: TPatchedTool;
|
|
21
21
|
}
|
|
@@ -78,9 +78,6 @@ export class HookConstants {
|
|
|
78
78
|
'/tmp/claude-[0-9]*/*/*/scratchpad',
|
|
79
79
|
'/tmp/claude-[0-9]*/*/*/scratchpad/**',
|
|
80
80
|
];
|
|
81
|
-
/** Set to `off` to switch the guards off for a session; the hooks then pass every call. */
|
|
82
|
-
static readonly KILL_SWITCH_ENV = 'VULCAN_GUARDS';
|
|
83
|
-
static readonly KILL_SWITCH_OFF = 'off';
|
|
84
81
|
/**
|
|
85
82
|
* Tool-owned stores an agent may write into: package manager caches, the runtime dir for locks, the
|
|
86
83
|
* agent tool's memory. Never a directory on PATH (`~/.bun/bin`) or a file git or a shell runs (`~/.gitconfig`).
|
|
@@ -3,7 +3,7 @@ import type { GuardDecisions, PackageVerdictKinds, TrustStates } from './constan
|
|
|
3
3
|
|
|
4
4
|
export type TGuardDecision = TConstValue<typeof GuardDecisions>;
|
|
5
5
|
export type TPackageVerdictKind = TConstValue<typeof PackageVerdictKinds>;
|
|
6
|
-
|
|
6
|
+
type TTrustState = TConstValue<typeof TrustStates>;
|
|
7
7
|
|
|
8
8
|
/** Whether a listed trusted script may skip the script checks, and if not, why - in words an ask can show. */
|
|
9
9
|
export interface IScriptTrust {
|
|
@@ -11,6 +11,20 @@ export interface IScriptTrust {
|
|
|
11
11
|
reason: string;
|
|
12
12
|
}
|
|
13
13
|
|
|
14
|
+
/** A script the project vouches for on some subcommands only: the first argument after the script is one of `readOnly`. */
|
|
15
|
+
export interface IReadOnlyScript {
|
|
16
|
+
script: string;
|
|
17
|
+
readOnly: string[];
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** One `bun x.ts` call as the shell sees it: the script word and the word right after it, if any. */
|
|
21
|
+
export interface IScriptInvocation {
|
|
22
|
+
script: string;
|
|
23
|
+
subcommand: string | undefined;
|
|
24
|
+
/** A `cd`, `pushd` or `popd` came before it in the line, so a relative script word is not from the hook's folder. */
|
|
25
|
+
moved: boolean;
|
|
26
|
+
}
|
|
27
|
+
|
|
14
28
|
export interface IWriteCheck {
|
|
15
29
|
rule: string;
|
|
16
30
|
what: string;
|
package/src/hooks/decision.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { GuardDecisions, HookConstants } from './common/index.ts';
|
|
2
2
|
import type { TGuardDecision } from './common/index.ts';
|
|
3
3
|
|
|
4
|
-
|
|
4
|
+
interface IDecisionOutput {
|
|
5
5
|
hookSpecificOutput: {
|
|
6
6
|
hookEventName: string;
|
|
7
7
|
permissionDecision: string;
|
|
@@ -51,7 +51,3 @@ export const buildToolDecision = (opts: { decision: TGuardDecision; reason: stri
|
|
|
51
51
|
},
|
|
52
52
|
},
|
|
53
53
|
});
|
|
54
|
-
|
|
55
|
-
/** Whether the session switched the guards off (`VULCAN_GUARDS=off`): every call then passes. */
|
|
56
|
-
export const guardsAreOff = (opts: { env?: Record<string, string | undefined> } = {}): boolean =>
|
|
57
|
-
(opts.env ?? process.env)[HookConstants.KILL_SWITCH_ENV] === HookConstants.KILL_SWITCH_OFF;
|
package/src/hooks/guard-git.ts
CHANGED
|
@@ -6,7 +6,7 @@ import type { IGitHit, IGitRunner } from './common/index.ts';
|
|
|
6
6
|
import { matchesBranch } from './project-guards.ts';
|
|
7
7
|
|
|
8
8
|
/** `git` and `gh` read-only queries the guard makes; `undefined` when the tool is missing, slow or fails. */
|
|
9
|
-
|
|
9
|
+
const runQuery: IGitRunner = (opts) => {
|
|
10
10
|
const result = spawnSync(opts.program, opts.args, {
|
|
11
11
|
cwd: opts.cwd,
|
|
12
12
|
encoding: 'utf8',
|
|
@@ -11,11 +11,15 @@ const FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
|
|
|
11
11
|
|
|
12
12
|
type TEnvironment = Record<string, string | undefined>;
|
|
13
13
|
|
|
14
|
-
/**
|
|
14
|
+
/**
|
|
15
|
+
* `~` and `$NAME` / `${NAME}` expanded; `undefined` when a variable is unset or the word is not a plain path.
|
|
16
|
+
* `$PWD` is the folder the command runs in (`cwd`), not the `PWD` of this hook's own process.
|
|
17
|
+
*/
|
|
15
18
|
const expandPath = (opts: {
|
|
16
19
|
word: string;
|
|
17
20
|
home: string;
|
|
18
21
|
env: TEnvironment;
|
|
22
|
+
cwd?: string;
|
|
19
23
|
}): string | undefined => {
|
|
20
24
|
if (opts.word === '' || /[`*?[]/.test(opts.word) || opts.word.includes('$(')) {
|
|
21
25
|
return undefined;
|
|
@@ -25,7 +29,7 @@ const expandPath = (opts: {
|
|
|
25
29
|
const home = opts.word === '~' || opts.word.startsWith('~/') ? opts.home : undefined;
|
|
26
30
|
const withHome = home === undefined ? opts.word : `${home}${opts.word.slice(1)}`;
|
|
27
31
|
const expanded = withHome.replace(/\$\{?(\w+)\}?/g, (_, name: string) => {
|
|
28
|
-
const value = opts.env[name];
|
|
32
|
+
const value = name === 'PWD' && opts.cwd !== undefined ? opts.cwd : opts.env[name];
|
|
29
33
|
|
|
30
34
|
if (value === undefined || value === '') {
|
|
31
35
|
unresolved = true;
|
|
@@ -61,10 +65,15 @@ const realOf = (opts: { path: string; depth?: number }): string => {
|
|
|
61
65
|
try {
|
|
62
66
|
base = realpathSync(existing);
|
|
63
67
|
} catch {
|
|
64
|
-
// A dangling link: its target is where a write through it lands.
|
|
65
|
-
|
|
68
|
+
// A dangling link: its target is where a write through it lands; a chain this long is a loop.
|
|
69
|
+
if (depth >= 8) {
|
|
70
|
+
return join(existing, ...rest);
|
|
71
|
+
}
|
|
66
72
|
|
|
67
|
-
base = realOf({
|
|
73
|
+
base = realOf({
|
|
74
|
+
path: resolve(dirname(existing), readlinkSync(existing)),
|
|
75
|
+
depth: depth + 1,
|
|
76
|
+
});
|
|
68
77
|
}
|
|
69
78
|
|
|
70
79
|
return join(base, ...rest);
|
|
@@ -111,6 +120,8 @@ interface ITarget {
|
|
|
111
120
|
message: string;
|
|
112
121
|
/** The directory a relative `word` is taken from: the hook's, moved by `cd` and `git -C`. */
|
|
113
122
|
base: string;
|
|
123
|
+
/** What `$PWD` is in `word`: the shell's folder, moved by `cd` but not by `git -C`; undefined when it is not known. */
|
|
124
|
+
pwd?: string;
|
|
114
125
|
}
|
|
115
126
|
|
|
116
127
|
const positional = (opts: { args: string[] }): string[] =>
|
|
@@ -365,7 +376,9 @@ export const inspectOutside = (opts: {
|
|
|
365
376
|
home,
|
|
366
377
|
env,
|
|
367
378
|
});
|
|
368
|
-
const start = opts.input.cwd ?? opts.projectRoot;
|
|
379
|
+
const start = resolve(opts.input.cwd ?? opts.projectRoot);
|
|
380
|
+
// `$PWD` is the call's folder only when the host said which one it is; otherwise the hook's own `PWD` stays the fallback.
|
|
381
|
+
const startPwd = opts.input.cwd === undefined ? undefined : start;
|
|
369
382
|
const tmp = commandTmpdirOf({ env, projectRoot: opts.projectRoot });
|
|
370
383
|
const targets: ITarget[] = [];
|
|
371
384
|
|
|
@@ -373,6 +386,7 @@ export const inspectOutside = (opts: {
|
|
|
373
386
|
targets.push({
|
|
374
387
|
word: opts.input.filePath,
|
|
375
388
|
base: start,
|
|
389
|
+
pwd: startPwd,
|
|
376
390
|
message: `${opts.input.tool} writes ${opts.input.filePath}`,
|
|
377
391
|
});
|
|
378
392
|
}
|
|
@@ -381,6 +395,7 @@ export const inspectOutside = (opts: {
|
|
|
381
395
|
|
|
382
396
|
if (opts.input.command !== undefined) {
|
|
383
397
|
let base = start;
|
|
398
|
+
let pwd = startPwd;
|
|
384
399
|
|
|
385
400
|
const parsed = parseShellChecked({ command: opts.input.command });
|
|
386
401
|
|
|
@@ -392,13 +407,17 @@ export const inspectOutside = (opts: {
|
|
|
392
407
|
if (basenameOf({ word: program.name }) === 'cd') {
|
|
393
408
|
const [destination] = positional({ args: program.args });
|
|
394
409
|
const expanded =
|
|
395
|
-
destination === undefined
|
|
410
|
+
destination === undefined
|
|
411
|
+
? undefined
|
|
412
|
+
: expandPath({ word: destination, home, env, cwd: pwd });
|
|
396
413
|
|
|
397
414
|
base = expanded === undefined ? base : resolve(base, expanded);
|
|
415
|
+
// A `cd` the guard cannot work out leaves the shell's folder unknown.
|
|
416
|
+
pwd = expanded === undefined ? undefined : base;
|
|
398
417
|
continue;
|
|
399
418
|
}
|
|
400
419
|
|
|
401
|
-
targets.push(...targetsOf({ command, base, tmp }));
|
|
420
|
+
targets.push(...targetsOf({ command, base, tmp }).map((target) => ({ ...target, pwd })));
|
|
402
421
|
}
|
|
403
422
|
}
|
|
404
423
|
|
|
@@ -415,7 +434,7 @@ export const inspectOutside = (opts: {
|
|
|
415
434
|
: [];
|
|
416
435
|
|
|
417
436
|
for (const target of targets) {
|
|
418
|
-
const expanded = expandPath({ word: target.word, home, env });
|
|
437
|
+
const expanded = expandPath({ word: target.word, home, env, cwd: target.pwd });
|
|
419
438
|
|
|
420
439
|
if (expanded === undefined) {
|
|
421
440
|
continue;
|
|
@@ -11,7 +11,7 @@ const NODE_MODULES = 'node_modules';
|
|
|
11
11
|
const ADD = 'bun x --no-install vulcan add';
|
|
12
12
|
const NO_HAND_WRITING = 'do not hand-write package.json, tsconfig or scripts';
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
interface IPackageVerdict {
|
|
15
15
|
/** `deny` only when a real `vulcan add` command exists for the folder; otherwise `warn`. */
|
|
16
16
|
kind: TPackageVerdictKind;
|
|
17
17
|
message: string;
|
|
@@ -21,6 +21,7 @@ interface IRecordedPreset {
|
|
|
21
21
|
spec: string;
|
|
22
22
|
side: string;
|
|
23
23
|
lib: boolean;
|
|
24
|
+
shared: boolean;
|
|
24
25
|
}
|
|
25
26
|
|
|
26
27
|
interface IProjectView {
|
|
@@ -100,10 +101,10 @@ const readProject = (opts: { start: string }): IProjectView | undefined => {
|
|
|
100
101
|
return [];
|
|
101
102
|
}
|
|
102
103
|
|
|
103
|
-
const { spec, side, lib } = entry.value;
|
|
104
|
+
const { spec, side, lib, shared } = entry.value;
|
|
104
105
|
|
|
105
106
|
return typeof spec === 'string' && typeof side === 'string'
|
|
106
|
-
? [{ spec, side, lib: typeof lib === 'string' }]
|
|
107
|
+
? [{ spec, side, lib: typeof lib === 'string', shared: typeof shared === 'string' }]
|
|
107
108
|
: [];
|
|
108
109
|
});
|
|
109
110
|
|
|
@@ -175,9 +176,14 @@ export const inspectPackageWrite = (opts: {
|
|
|
175
176
|
const folderFlag =
|
|
176
177
|
folders.length > 1 ? ` ${isLib ? '--dir' : `--${key}-dir`} ${created.folder}` : '';
|
|
177
178
|
const commands = isLib
|
|
178
|
-
?
|
|
179
|
-
.
|
|
180
|
-
|
|
179
|
+
? [
|
|
180
|
+
...project.presets
|
|
181
|
+
.filter((preset) => preset.lib)
|
|
182
|
+
.map((preset) => `${ADD} --preset ${preset.spec} --lib ${created.name}${folderFlag}`),
|
|
183
|
+
...project.presets
|
|
184
|
+
.filter((preset) => preset.shared)
|
|
185
|
+
.map((preset) => `${ADD} --preset ${preset.spec} --shared ${created.name}${folderFlag}`),
|
|
186
|
+
]
|
|
181
187
|
: project.presets
|
|
182
188
|
.filter((preset) => preset.side === key)
|
|
183
189
|
.map((preset) => appCommand({ preset, name: created.name, folderFlag }));
|
|
@@ -193,7 +199,7 @@ export const inspectPackageWrite = (opts: {
|
|
|
193
199
|
kind: PackageVerdictKinds.WARN,
|
|
194
200
|
message:
|
|
195
201
|
project.presets.length === 0
|
|
196
|
-
? `${created.folder}/${created.name} looks like a new ${what} and this project recorded no preset: ask the user which preset to use (\`vulcan add --preset <name|file:path> --app <name>\`, --lib <name> for a shared package); ${NO_HAND_WRITING}`
|
|
202
|
+
? `${created.folder}/${created.name} looks like a new ${what} and this project recorded no preset: ask the user which preset to use (\`vulcan add --preset <name|file:path> --app <name>\`, --lib <name> for a library other apps import, --shared <name> for a side-neutral package); ${NO_HAND_WRITING}`
|
|
197
203
|
: `${created.folder}/${created.name} looks like a new ${what} but no recorded preset makes a ${what}: ask the user how it should be made; ${NO_HAND_WRITING}`,
|
|
198
204
|
};
|
|
199
205
|
};
|
|
@@ -5,7 +5,7 @@ import { basenameOf, parseShell, programOf } from './shell.ts';
|
|
|
5
5
|
const SCRIPTING_PROGRAM = /^(?:python\d*(?:\.\d+)?|pip\d*(?:\.\d+)?)$/;
|
|
6
6
|
|
|
7
7
|
/** One line, worded like the rule: a preference, never a ban. */
|
|
8
|
-
|
|
8
|
+
const SCRIPTING_ADVICE =
|
|
9
9
|
'V-B-09: agent scripting uses bun by default (bun -e, bun file.ts, Bun.file()). Python or another language is fine when the task needs it (an existing project script, a tool only that language has); say so in one line when you use it.';
|
|
10
10
|
|
|
11
11
|
/** `command -v python3` asks whether a program exists; it does not run it. */
|