@venizia/vulcan 0.4.10-2 → 0.4.10-21
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/README.md +30 -23
- package/base/checks/wiki-source-links.ts +17 -1
- package/base/claude/events.json +1 -11
- package/base/claude/settings.json +5 -76
- package/base/extensions/vulcan-guards.ts +81 -18
- package/base/hooks/guard-git.ts +95 -19
- package/base/hooks/guard-outside.ts +163 -43
- package/base/hooks/guard-writes.ts +15 -36
- package/base/hooks/session-start.ts +1 -1
- package/base/make/vulcan.mk +8 -5
- package/base/packs/venizia.md +16 -0
- package/base/references/delegation-brief.md +3 -5
- package/base/references/testing.md +1 -9
- package/base/rules.md +33 -38
- package/base/skills/build-a-feature/SKILL.md +4 -4
- package/base/skills/docs-update/SKILL.md +19 -8
- package/base/skills/fix-a-bug/SKILL.md +4 -2
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/research/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +2 -2
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +3 -3
- package/base/skills/visualize-work/references/spec.md +6 -3
- package/base/templates/AGENTS.md +9 -7
- package/base/templates/board.html +10 -110
- package/package.json +3 -3
- package/src/agents/atlas-block.ts +8 -31
- package/src/agents/codex-hooks.ts +1 -1
- package/src/agents/generated-block.ts +52 -0
- package/src/agents/hooks-json.ts +22 -3
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +15 -2
- package/src/agents/resolve.ts +1 -0
- package/src/agents/rules-block.ts +92 -0
- package/src/board/command.ts +92 -30
- package/src/board/common/constants.ts +26 -0
- package/src/board/common/types.ts +10 -3
- package/src/board/fold.ts +1 -1
- package/src/board/github.ts +1 -2
- package/src/board/gitlab.ts +436 -0
- package/src/board/index.ts +1 -0
- package/src/board/logo.ts +49 -0
- package/src/board/open-file.ts +110 -0
- package/src/board/page.ts +57 -5
- package/src/board/schema.ts +4 -1
- package/src/board/server.ts +87 -3
- package/src/board/settings.ts +21 -24
- package/src/commands/changelog.command.ts +40 -0
- package/src/commands/clean.command.ts +6 -1
- package/src/commands/help.command.ts +2 -63
- package/src/commands/index.ts +6 -1
- package/src/commands/migrate.command.ts +71 -0
- package/src/commands/profile.command.ts +1 -1
- package/src/commands/runners.command.ts +43 -0
- package/src/commands/sync.command.ts +8 -4
- package/src/commands/table.ts +362 -0
- package/src/commit/check.ts +1 -0
- package/src/commit/common/constants.ts +4 -0
- package/src/commit/hook.ts +112 -8
- package/src/common/constants.ts +11 -9
- package/src/common/env-variables.ts +41 -0
- package/src/common/index.ts +1 -0
- package/src/common/layout-folder.ts +3 -4
- package/src/common/record.ts +5 -0
- package/src/config/common/constants.ts +28 -22
- package/src/config/loader.ts +22 -0
- package/src/config/schema.ts +330 -146
- package/src/create/add-app.ts +7 -2
- package/src/create/add-lib.ts +2 -4
- package/src/create/common/constants.ts +5 -3
- package/src/create/preset.ts +1 -0
- package/src/create/scratch.ts +2 -1
- package/src/doctor/checks.ts +277 -448
- package/src/doctor/common/constants.ts +27 -19
- package/src/doctor/private-values.ts +4 -1
- package/src/doctor/runner.ts +5 -12
- package/src/doctor/schema.ts +4 -0
- package/src/events/common/actor-names.ts +12 -0
- package/src/events/common/constants.ts +65 -38
- package/src/events/common/index.ts +1 -0
- package/src/events/hook.ts +5 -56
- package/src/events/text.ts +41 -6
- package/src/hooks/command-view.ts +80 -19
- package/src/hooks/common/constants.ts +26 -17
- package/src/hooks/common/types.ts +13 -24
- package/src/hooks/decision.ts +30 -12
- package/src/hooks/git-queries.ts +113 -0
- package/src/hooks/guard-git.ts +76 -24
- package/src/hooks/guard-outside.ts +334 -311
- package/src/hooks/guard-runner.ts +206 -0
- package/src/hooks/guard-writes.ts +87 -184
- package/src/hooks/hook-input.ts +57 -0
- package/src/hooks/index.ts +3 -6
- package/src/hooks/link-makers.ts +315 -0
- package/src/hooks/package-runners.ts +268 -0
- package/src/hooks/project-guards.ts +81 -44
- package/src/hooks/project-tmp.ts +39 -4
- package/src/hooks/runner-scan.ts +257 -0
- package/src/hooks/script-runners.ts +400 -0
- package/src/hooks/session-digest.ts +27 -117
- package/src/hooks/shell-folders.ts +760 -0
- package/src/hooks/shell-writes.ts +646 -0
- package/src/hooks/shell.ts +1421 -194
- package/src/hooks/subagent-card.ts +2 -2
- package/src/hooks/write-commands.ts +898 -0
- package/src/init/scaffold.ts +2 -3
- package/src/local/auto-clean.ts +2 -1
- package/src/local/browser-socket.ts +33 -0
- package/src/local/clean.ts +37 -6
- package/src/local/constants.ts +15 -1
- package/src/local/index.ts +1 -0
- package/src/local/scan.ts +41 -10
- package/src/manifest/render.ts +84 -30
- package/src/owner/constants.ts +4 -5
- package/src/owner/index.ts +0 -2
- package/src/owner/profile.ts +1 -0
- package/src/owner/schema.ts +51 -27
- package/src/owner/survey.ts +0 -3
- package/src/owner/view.ts +0 -9
- package/src/router.ts +8 -132
- package/src/rules/base.ts +12 -7
- package/src/rules/index.ts +1 -0
- package/src/rules/packs.ts +44 -0
- package/src/runners/check.ts +130 -0
- package/src/skills/frontmatter.ts +1 -0
- package/src/sync/agents-block.ts +104 -0
- package/src/sync/base-rules.ts +3 -3
- package/src/sync/claude-launch.ts +12 -12
- package/src/sync/common/constants.ts +0 -2
- package/src/sync/index.ts +1 -1
- package/src/sync/local-choice.ts +32 -3
- package/src/sync/planner.ts +2 -15
- package/src/sync/settings.ts +0 -17
- package/src/theme/index.ts +1 -0
- package/src/theme/tokens.ts +410 -0
- package/src/ui/prompt.ts +1 -0
- package/src/visualize/architecture.ts +504 -0
- package/src/visualize/assets.ts +41 -30
- package/src/visualize/compare-render.ts +22 -24
- package/src/visualize/constants.ts +27 -0
- package/src/visualize/diagrams.ts +13 -121
- package/src/visualize/kinds-render.ts +2 -2
- package/src/visualize/kinds-schema.ts +49 -0
- package/src/visualize/labels-vi.ts +25 -0
- package/src/visualize/labels.ts +2 -0
- package/src/visualize/layout.ts +415 -66
- package/src/visualize/page.ts +82 -15
- package/src/visualize/render.ts +2 -1
- package/src/visualize/schema.ts +29 -1
- package/src/visualize/sections.ts +78 -9
- package/src/visualize/theme.ts +49 -18
- package/src/wiki/anchors.ts +1 -0
- package/src/wiki/command.ts +10 -3
- package/src/wiki/source-links.ts +57 -18
- package/base/ci-global.json +0 -13
- package/base/claude/remote-hosts.json +0 -15
- package/base/hooks/guard-manifest.ts +0 -27
- package/base/hooks/guard-package.ts +0 -30
- package/base/hooks/guard-remote-hosts.ts +0 -70
- package/base/hooks/guard-scripting.ts +0 -32
- package/base/hooks/post-tool.ts +0 -37
- package/base/hooks/prompt-submit.ts +0 -54
- package/base/hooks/stop.ts +0 -40
- package/base/skills/build-a-feature/evals/evals.json +0 -29
- package/base/skills/docs-update/evals/evals.json +0 -23
- package/base/skills/docs-writing/evals/evals.json +0 -17
- package/base/skills/fix-a-bug/evals/evals.json +0 -17
- package/base/skills/knowledge-sync/SKILL.md +0 -81
- package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
- package/base/skills/knowledge-sync/references/workflow.md +0 -44
- package/base/skills/plan-a-change/evals/evals.json +0 -47
- package/base/skills/report-back/evals/evals.json +0 -23
- package/base/skills/research/evals/evals.json +0 -17
- package/base/skills/retro/evals/evals.json +0 -17
- package/base/skills/review-a-change/evals/evals.json +0 -17
- package/base/skills/ship/evals/evals.json +0 -23
- package/base/skills/visualize-work/evals/evals.json +0 -17
- package/base/templates/ci/github-actions.yml +0 -75
- package/base/templates/ci/gitlab-ci.yml +0 -52
- package/base/templates/trusted-hosts.local.example +0 -11
- package/src/ci/affected.ts +0 -176
- package/src/ci/command.ts +0 -166
- package/src/ci/common/constants.ts +0 -76
- package/src/ci/common/index.ts +0 -2
- package/src/ci/common/types.ts +0 -37
- package/src/ci/git.ts +0 -72
- package/src/ci/global.ts +0 -48
- package/src/ci/graph.ts +0 -43
- package/src/ci/index.ts +0 -7
- package/src/ci/workspace.ts +0 -119
- package/src/commands/ci.command.ts +0 -4
- package/src/hooks/guard-manifest.ts +0 -109
- package/src/hooks/guard-package.ts +0 -226
- package/src/hooks/guard-scripting.ts +0 -36
- package/src/hooks/host-pattern.ts +0 -17
- package/src/hooks/owner-reply.ts +0 -162
- package/src/hooks/post-tool.ts +0 -138
- package/src/hooks/remote-hosts.ts +0 -1013
- package/src/hooks/trusted-scripts.ts +0 -212
- package/src/owner/shape.ts +0 -496
- package/src/owner/violations.ts +0 -332
- package/src/signals/claims.ts +0 -73
- package/src/signals/classify.ts +0 -137
- package/src/signals/constants.ts +0 -88
- package/src/signals/index.ts +0 -5
- package/src/signals/loop.ts +0 -48
- package/src/signals/state.ts +0 -271
- package/src/sync/atlas-block.ts +0 -56
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { existsSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
|
-
import
|
|
3
|
+
import { GuardDecisions, HookConstants } from './common/index.ts';
|
|
4
4
|
|
|
5
5
|
/** A command the project says is a database write or a deploy: guard-writes asks on a match. */
|
|
6
6
|
export interface IProjectCommandCheck {
|
|
@@ -13,8 +13,19 @@ export interface IProjectCommandCheck {
|
|
|
13
13
|
interface IGuardPolicy {
|
|
14
14
|
commands: IProjectCommandCheck[];
|
|
15
15
|
askPush: string[];
|
|
16
|
-
/** `guard.
|
|
17
|
-
|
|
16
|
+
/** `guard.outside`: what guard-outside does with a write outside the project; the strictest of `VULCAN_GUARD_OUTSIDE` and the manifest, `ask` when neither says `deny`. */
|
|
17
|
+
outside: string;
|
|
18
|
+
/**
|
|
19
|
+
* `guard.asks`: `deny` makes every answer that would ask a human a refusal. The strictest of the launch environment
|
|
20
|
+
* (`VULCAN_GUARD_ASKS`), the manifest, and a manifest that exists but cannot be read; `ask` when none says otherwise.
|
|
21
|
+
*/
|
|
22
|
+
asks: string;
|
|
23
|
+
/** What the answer adds when an ask is held: which of the three held it; `undefined` when asks stay asks. */
|
|
24
|
+
asksNote?: string;
|
|
25
|
+
/** `guard.toolOwnedPaths`: stores a tool manages itself, which guard-outside lets through. */
|
|
26
|
+
toolOwnedPaths: string[];
|
|
27
|
+
/** `guard.runners.allow`: the package names bunx, `bun x`, npx and `pnpm dlx` may run beyond `@venizia/*`. */
|
|
28
|
+
runnersAllow: string[];
|
|
18
29
|
}
|
|
19
30
|
|
|
20
31
|
/** Spelt out: the blocking hooks import nothing that reads the package. */
|
|
@@ -64,41 +75,57 @@ const commandOf = (opts: { value: unknown }): IProjectCommandCheck | undefined =
|
|
|
64
75
|
}
|
|
65
76
|
};
|
|
66
77
|
|
|
67
|
-
const readOnlyScriptOf = (opts: { value: unknown }): IReadOnlyScript | undefined => {
|
|
68
|
-
const holder = { value: opts.value };
|
|
69
|
-
const script = isRecord(holder) ? holder.value['script'] : undefined;
|
|
70
|
-
const listed = isRecord(holder) ? holder.value['readOnly'] : undefined;
|
|
71
|
-
const words = Array.isArray(listed)
|
|
72
|
-
? listed.filter((word): word is string => typeof word === 'string' && word !== '')
|
|
73
|
-
: [];
|
|
74
|
-
|
|
75
|
-
if (
|
|
76
|
-
typeof script !== 'string' ||
|
|
77
|
-
script === '' ||
|
|
78
|
-
!Array.isArray(listed) ||
|
|
79
|
-
words.length !== listed.length
|
|
80
|
-
) {
|
|
81
|
-
note({
|
|
82
|
-
message:
|
|
83
|
-
'ignoring a guard.writes.readOnlyScripts entry that has no script or no readOnly list of words',
|
|
84
|
-
});
|
|
85
|
-
|
|
86
|
-
return undefined;
|
|
87
|
-
}
|
|
88
|
-
|
|
89
|
-
return { script, readOnly: words };
|
|
90
|
-
};
|
|
91
|
-
|
|
92
78
|
export class ProjectGuards {
|
|
79
|
+
/** The committed manifest, which a hook reads instead of the config. */
|
|
80
|
+
static readonly MANIFEST_FILE = GUARD_MANIFEST_FILE;
|
|
81
|
+
|
|
93
82
|
/**
|
|
94
|
-
* The commands
|
|
83
|
+
* The commands and push targets a project lists, from the committed manifest (`vulcan sync` renders
|
|
95
84
|
* them from the config), so a hook reads them with no config loader and no zod. A project with no
|
|
96
85
|
* manifest, or none of the block, has none; an entry that cannot be used is skipped, said once on
|
|
97
86
|
* stderr, and the others stay.
|
|
98
87
|
*/
|
|
99
|
-
static readPolicy(opts: {
|
|
88
|
+
static readPolicy(opts: {
|
|
89
|
+
root: string;
|
|
90
|
+
env?: Record<string, string | undefined>;
|
|
91
|
+
}): IGuardPolicy {
|
|
92
|
+
const policy = ProjectGuards.readManifest({ root: opts.root });
|
|
93
|
+
const env = opts.env ?? process.env;
|
|
94
|
+
const isEnvAsks = env[HookConstants.ENV_ASKS] === GuardDecisions.DENY;
|
|
95
|
+
const isEnvOutside = env[HookConstants.ENV_OUTSIDE] === GuardDecisions.DENY;
|
|
96
|
+
const isAsksDenied = isEnvAsks || policy.asks === GuardDecisions.DENY;
|
|
97
|
+
// Where the environment holds deny, the manifest is not trusted to loosen anything: the stores it would allow and the runners it would add are ignored.
|
|
98
|
+
const isEnvHeld = isEnvAsks || isEnvOutside;
|
|
99
|
+
|
|
100
|
+
return {
|
|
101
|
+
...policy,
|
|
102
|
+
toolOwnedPaths: isEnvHeld ? [] : policy.toolOwnedPaths,
|
|
103
|
+
runnersAllow: isEnvHeld ? [] : policy.runnersAllow,
|
|
104
|
+
asks: isAsksDenied ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
105
|
+
asksNote: isEnvAsks ? HookConstants.HELD_ASK_ENV : policy.asksNote,
|
|
106
|
+
outside:
|
|
107
|
+
isEnvOutside || policy.outside === GuardDecisions.DENY
|
|
108
|
+
? GuardDecisions.DENY
|
|
109
|
+
: GuardDecisions.ASK,
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** What the manifest sets, before the launch environment tightens it. A manifest that exists and cannot be read holds every ask. */
|
|
114
|
+
private static readManifest(opts: { root: string }): IGuardPolicy {
|
|
100
115
|
const path = join(opts.root, GUARD_MANIFEST_FILE);
|
|
101
|
-
const empty: IGuardPolicy = {
|
|
116
|
+
const empty: IGuardPolicy = {
|
|
117
|
+
commands: [],
|
|
118
|
+
askPush: [],
|
|
119
|
+
outside: GuardDecisions.ASK,
|
|
120
|
+
asks: GuardDecisions.ASK,
|
|
121
|
+
toolOwnedPaths: [],
|
|
122
|
+
runnersAllow: [],
|
|
123
|
+
};
|
|
124
|
+
const unreadable: IGuardPolicy = {
|
|
125
|
+
...empty,
|
|
126
|
+
asks: GuardDecisions.DENY,
|
|
127
|
+
asksNote: HookConstants.MANIFEST_UNREADABLE,
|
|
128
|
+
};
|
|
102
129
|
|
|
103
130
|
if (!existsSync(path)) {
|
|
104
131
|
return empty;
|
|
@@ -110,14 +137,21 @@ export class ProjectGuards {
|
|
|
110
137
|
manifest = JSON.parse(readFileSync(path, 'utf8'));
|
|
111
138
|
} catch (error) {
|
|
112
139
|
note({
|
|
113
|
-
message: `the manifest could not be read, so the project's own patterns are off (${error instanceof Error ? error.message : String(error)})`,
|
|
140
|
+
message: `the manifest could not be read, so the project's own patterns are off and every ask is a deny (${error instanceof Error ? error.message : String(error)})`,
|
|
114
141
|
});
|
|
115
142
|
|
|
116
|
-
return
|
|
143
|
+
return unreadable;
|
|
117
144
|
}
|
|
118
145
|
|
|
119
146
|
const top = { value: manifest };
|
|
120
|
-
|
|
147
|
+
|
|
148
|
+
if (!isRecord(top)) {
|
|
149
|
+
note({ message: 'the manifest is not an object, so every ask is a deny' });
|
|
150
|
+
|
|
151
|
+
return unreadable;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
const guard = { value: top.value['guard'] };
|
|
121
155
|
|
|
122
156
|
if (!isRecord(guard)) {
|
|
123
157
|
return empty;
|
|
@@ -126,13 +160,13 @@ export class ProjectGuards {
|
|
|
126
160
|
const writes = { value: guard.value['writes'] };
|
|
127
161
|
const git = { value: guard.value['git'] };
|
|
128
162
|
const listed = isRecord(writes) ? writes.value['commands'] : undefined;
|
|
129
|
-
const scripts = isRecord(writes) ? writes.value['readOnlyScripts'] : undefined;
|
|
130
163
|
const targets = isRecord(git) ? git.value['askPush'] : undefined;
|
|
131
|
-
const
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
164
|
+
const owned = guard.value['toolOwnedPaths'];
|
|
165
|
+
const runners = { value: guard.value['runners'] };
|
|
166
|
+
const words = (value: unknown): string[] =>
|
|
167
|
+
(Array.isArray(value) ? value : []).filter(
|
|
168
|
+
(item): item is string => typeof item === 'string' && item !== '',
|
|
169
|
+
);
|
|
136
170
|
|
|
137
171
|
return {
|
|
138
172
|
commands: (Array.isArray(listed) ? listed : []).flatMap((entry) => {
|
|
@@ -140,10 +174,13 @@ export class ProjectGuards {
|
|
|
140
174
|
|
|
141
175
|
return check === undefined ? [] : [check];
|
|
142
176
|
}),
|
|
143
|
-
askPush: (
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
177
|
+
askPush: words(targets),
|
|
178
|
+
outside:
|
|
179
|
+
guard.value['outside'] === GuardDecisions.DENY ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
180
|
+
asks: guard.value['asks'] === GuardDecisions.DENY ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
181
|
+
asksNote: guard.value['asks'] === GuardDecisions.DENY ? HookConstants.HELD_ASK : undefined,
|
|
182
|
+
toolOwnedPaths: words(owned),
|
|
183
|
+
runnersAllow: isRecord(runners) ? words(runners.value['allow']) : [],
|
|
147
184
|
};
|
|
148
185
|
}
|
|
149
186
|
|
package/src/hooks/project-tmp.ts
CHANGED
|
@@ -1,14 +1,49 @@
|
|
|
1
|
-
import { appendFileSync, mkdirSync } from 'node:fs';
|
|
1
|
+
import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
|
+
import { LayoutFolder } from '../common/layout-folder.ts';
|
|
4
|
+
import { RecordValue } from '../common/record.ts';
|
|
3
5
|
import { HookConstants } from './common/index.ts';
|
|
6
|
+
import { ProjectGuards } from './project-guards.ts';
|
|
4
7
|
|
|
5
8
|
/** A word for `sh`, whatever it holds: in single quotes, a quote itself closed, escaped and opened again. */
|
|
6
9
|
const shellQuote = (opts: { text: string }): string => `'${opts.text.replaceAll("'", "'\\''")}'`;
|
|
7
10
|
|
|
8
11
|
export class ProjectTmp {
|
|
9
|
-
/**
|
|
10
|
-
|
|
11
|
-
|
|
12
|
+
/**
|
|
13
|
+
* The folder the project names for its temporary files, relative to its root: `local.tmp` of the committed manifest
|
|
14
|
+
* (which `vulcan sync` renders from the config), read here so a hook needs no config loader. A missing manifest, a
|
|
15
|
+
* missing key or a value that is not a layout folder gives the default, `.agents/local/tmp`.
|
|
16
|
+
*/
|
|
17
|
+
static relativeOf(opts: { root: string }): string {
|
|
18
|
+
try {
|
|
19
|
+
const manifest: unknown = JSON.parse(
|
|
20
|
+
readFileSync(join(opts.root, ProjectGuards.MANIFEST_FILE), 'utf8'),
|
|
21
|
+
);
|
|
22
|
+
const local = RecordValue.isRecord(manifest) ? manifest['local'] : undefined;
|
|
23
|
+
const tmp = RecordValue.isRecord(local) ? local['tmp'] : undefined;
|
|
24
|
+
|
|
25
|
+
return typeof tmp === 'string' &&
|
|
26
|
+
LayoutFolder.layoutFolderProblem({ folder: tmp }) === undefined
|
|
27
|
+
? tmp
|
|
28
|
+
: HookConstants.PROJECT_TMP;
|
|
29
|
+
} catch {
|
|
30
|
+
return HookConstants.PROJECT_TMP;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** What a caller that holds the config passes as `tmp`: the key, or the default when the project does not set it (never the manifest, which `sync` has not rewritten yet). */
|
|
35
|
+
static configuredOf(opts: { tmp: string | undefined }): string {
|
|
36
|
+
return opts.tmp ?? HookConstants.PROJECT_TMP;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Where a session's temporary files go, absolute: the guard, the session digest, the session-start export, the launch
|
|
41
|
+
* file, `vulcan clean` and the scratch of `add` all call this. `tmp` is the config's `local.tmp` for a caller that
|
|
42
|
+
* has just read the config (`sync`, which writes the manifest after it plans the launch file); the others leave it
|
|
43
|
+
* out and get the manifest's.
|
|
44
|
+
*/
|
|
45
|
+
static projectOf(opts: { root: string; tmp?: string }): string {
|
|
46
|
+
return join(opts.root, opts.tmp ?? ProjectTmp.relativeOf({ root: opts.root }));
|
|
12
47
|
}
|
|
13
48
|
|
|
14
49
|
/**
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
import { PackageRunners } from './package-runners.ts';
|
|
2
|
+
import type { IRunnerCall } from './package-runners.ts';
|
|
3
|
+
|
|
4
|
+
/** One command that fetches a package and runs it: `bunx`, `bun x`, `npx`, `npm exec`, `pnpm dlx`, `yarn dlx`, `pnpx`. */
|
|
5
|
+
export interface IRunnerUse {
|
|
6
|
+
/** The runner as written (`bunx`, `bun x`, `npx`, ...). */
|
|
7
|
+
runner: string;
|
|
8
|
+
/** The first word after the flags: the package or bin the command runs, as written (a version included); empty when none is given (`xargs bunx`). */
|
|
9
|
+
name: string;
|
|
10
|
+
/** The package a `-p` or `--package` flag names, as written; the command runs a bin of that package. */
|
|
11
|
+
packageName?: string;
|
|
12
|
+
/** The exact flag `--no-install` stands before the name. */
|
|
13
|
+
hasNoInstall: boolean;
|
|
14
|
+
/** Every flag on the way to the name, and the flags before the runner's subcommand (`bun --cwd other x`). */
|
|
15
|
+
flags: string[];
|
|
16
|
+
/** The line the command starts on, from 1 (a continuation joins the lines that follow it). */
|
|
17
|
+
line: number;
|
|
18
|
+
/** The command runs a command string in a shell (`npx -c`), and no package is named: nothing is fetched by name. */
|
|
19
|
+
runsCommand: boolean;
|
|
20
|
+
/** The line is marked as an example (`<!-- runners: example -->`) in a Markdown file. */
|
|
21
|
+
isExample: boolean;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** What may stand before a runner for the text to be a command and not a sentence about one. */
|
|
25
|
+
const COMMAND_START = /(?:^|[\s&|;(`"':>$=])$|(?:^|\s)[@+-]+$/;
|
|
26
|
+
const COMMAND_WORDS =
|
|
27
|
+
/(?:^|\s)(?:sudo|time|exec|env|command|nohup|then|do|else|RUN|CMD|ENTRYPOINT)$/;
|
|
28
|
+
const ENVIRONMENT = /(?:^|\s)[A-Za-z_][A-Za-z0-9_]*=\S*\s+$/;
|
|
29
|
+
/** Every program that may start a runner command; `PackageRunners.find` decides whether the words after it make one. */
|
|
30
|
+
const PROGRAM = /(?<![\w./-])(bunx|pnpx|npx|bun|npm|pnpm|yarn|corepack)(?![\w.-])/g;
|
|
31
|
+
/** An array of quoted words, the form a script or a test spells a command in. */
|
|
32
|
+
const ARRAY_FORM = /\[\s*(['"][^'"]*['"](?:\s*,\s*['"][^'"]*['"])*)/g;
|
|
33
|
+
const QUOTED = /['"]([^'"]*)['"]/g;
|
|
34
|
+
/** A comment that marks the line or the fenced block after it as an example of a command that is refused (Markdown only). */
|
|
35
|
+
const EXAMPLE_MARKER = /^\s*<!--\s*runners:\s*example\s*-->\s*$/;
|
|
36
|
+
const FENCE = /^\s*(`{3,}|~{3,})/;
|
|
37
|
+
|
|
38
|
+
/** A version, a tag or a range: no `:` (so no `npm:` or `github:` alias), no `/`. */
|
|
39
|
+
const VERSION = '[\\w.^~*<>=+-]+';
|
|
40
|
+
/** `@scope/name`, any scope, with a version, or a shell placeholder for one (the pinned form of a workflow). */
|
|
41
|
+
const SCOPED = new RegExp(`^@[a-z0-9][\\w.-]*/[\\w.-]+(?:@${VERSION})?$`, 'i');
|
|
42
|
+
/** The same, with the pinned form of a workflow: `$(...)` or `${...}` after the `@`. A file may carry it, a typed command may not (a variable could print `npm:<name>`). */
|
|
43
|
+
const SCOPED_PINNED = new RegExp(
|
|
44
|
+
`^@[a-z0-9][\\w.-]*/[\\w.-]+(?:@(?:${VERSION}|\\$\\(.*|\\$\\{.*))?$`,
|
|
45
|
+
'i',
|
|
46
|
+
);
|
|
47
|
+
const SPEC_VERSION = new RegExp(`^${VERSION}$`);
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Finds the commands of a text that run a package fetched by name. One scan serves the tracked-file check and the
|
|
51
|
+
* guard on an agent's command, so the cases of what counts as one are decided, and tested, once.
|
|
52
|
+
*/
|
|
53
|
+
export class RunnerScan {
|
|
54
|
+
/** `text` with each `\` continuation joined to its line, and the line number each logical line starts on. */
|
|
55
|
+
private static logicalLines(opts: {
|
|
56
|
+
text: string;
|
|
57
|
+
}): { text: string; line: number; end: number }[] {
|
|
58
|
+
const lines = opts.text.split('\n');
|
|
59
|
+
const joined: { text: string; line: number; end: number }[] = [];
|
|
60
|
+
|
|
61
|
+
for (let index = 0; index < lines.length; index += 1) {
|
|
62
|
+
let text = lines[index];
|
|
63
|
+
const line = index + 1;
|
|
64
|
+
|
|
65
|
+
while (/\\\s*$/.test(text) && index + 1 < lines.length) {
|
|
66
|
+
index += 1;
|
|
67
|
+
text = `${text.replace(/\\\s*$/, ' ')}${lines[index]}`;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
joined.push({ text, line, end: index + 1 });
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
return joined;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** The lines, from 1, that a marker comment sets apart: the line after it, or the whole fenced block that opens there. */
|
|
77
|
+
private static exampleLines(opts: { text: string }): Set<number> {
|
|
78
|
+
const lines = opts.text.split('\n');
|
|
79
|
+
const marked = new Set<number>();
|
|
80
|
+
|
|
81
|
+
for (let index = 0; index < lines.length; index += 1) {
|
|
82
|
+
if (!EXAMPLE_MARKER.test(lines[index] ?? '')) {
|
|
83
|
+
continue;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const next = index + 1;
|
|
87
|
+
const fence = FENCE.exec(lines[next] ?? '')?.[1];
|
|
88
|
+
|
|
89
|
+
if (fence === undefined) {
|
|
90
|
+
marked.add(next + 1);
|
|
91
|
+
continue;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
let end = next + 1;
|
|
95
|
+
|
|
96
|
+
while (end < lines.length) {
|
|
97
|
+
const closing = FENCE.exec(lines[end] ?? '')?.[1];
|
|
98
|
+
|
|
99
|
+
if (closing !== undefined && closing[0] === fence[0] && closing.length >= fence.length) {
|
|
100
|
+
break;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
end += 1;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
// a fence that never closes would cover the rest of the file: it counts as no marker
|
|
107
|
+
if (end >= lines.length) {
|
|
108
|
+
continue;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
for (let at = next; at <= end; at += 1) {
|
|
112
|
+
marked.add(at + 1);
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
return marked;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** Whether `before` ends where a command may begin: a line start, a separator, a prompt, a quote, a keyword. */
|
|
120
|
+
private static isCommandPosition(opts: { before: string }): boolean {
|
|
121
|
+
let before = opts.before;
|
|
122
|
+
|
|
123
|
+
while (ENVIRONMENT.test(before)) {
|
|
124
|
+
before = before.replace(ENVIRONMENT, ' ');
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
const trimmed = before.trimEnd();
|
|
128
|
+
|
|
129
|
+
// a comma right against the program is an argument separator of a make `$(foreach ...)`; a comma and a space is prose
|
|
130
|
+
return (
|
|
131
|
+
trimmed === '' ||
|
|
132
|
+
before.endsWith(',') ||
|
|
133
|
+
COMMAND_START.test(trimmed) ||
|
|
134
|
+
COMMAND_WORDS.test(trimmed)
|
|
135
|
+
);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** The command a runner call makes: the package it runs and the flags on the way to it. */
|
|
139
|
+
static useOf(opts: { call: IRunnerCall; line: number; isExample: boolean }): IRunnerUse {
|
|
140
|
+
const target = PackageRunners.targetOf({ words: opts.call.words, runner: opts.call.runner });
|
|
141
|
+
|
|
142
|
+
return {
|
|
143
|
+
runner: opts.call.runner,
|
|
144
|
+
name: target.name,
|
|
145
|
+
...(target.packageName === undefined ? {} : { packageName: target.packageName }),
|
|
146
|
+
hasNoInstall: target.hasNoInstall,
|
|
147
|
+
flags: [...opts.call.leading, ...target.flags],
|
|
148
|
+
runsCommand: target.isCommandString && PackageRunners.COMMAND_RUNNERS.has(opts.call.runner),
|
|
149
|
+
line: opts.line,
|
|
150
|
+
isExample: opts.isExample,
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/** Every command of `text` that runs a package by name, in order. `isMarkdown` lets a marker comment set a line apart as an example. */
|
|
155
|
+
static find(opts: { text: string; isMarkdown?: boolean }): IRunnerUse[] {
|
|
156
|
+
const uses: IRunnerUse[] = [];
|
|
157
|
+
const examples =
|
|
158
|
+
opts.isMarkdown === true ? RunnerScan.exampleLines({ text: opts.text }) : undefined;
|
|
159
|
+
const lines = RunnerScan.logicalLines({ text: opts.text });
|
|
160
|
+
|
|
161
|
+
for (const [at, { text, line }] of lines.entries()) {
|
|
162
|
+
const isExample = examples?.has(line) ?? false;
|
|
163
|
+
|
|
164
|
+
for (const match of text.matchAll(PROGRAM)) {
|
|
165
|
+
const index = match.index ?? 0;
|
|
166
|
+
|
|
167
|
+
if (!RunnerScan.isCommandPosition({ before: text.slice(0, index) })) {
|
|
168
|
+
continue;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
const rest = text.slice(index + match[0].length);
|
|
172
|
+
|
|
173
|
+
// `bunx` straight into a quote or a backtick is a word in a sentence, not the start of a command
|
|
174
|
+
if (!/^\s+\S/.test(rest)) {
|
|
175
|
+
continue;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
const words = rest.trim().split(/\s+/);
|
|
179
|
+
let call = PackageRunners.find({ program: match[1], args: words });
|
|
180
|
+
|
|
181
|
+
if (call === undefined) {
|
|
182
|
+
continue;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
let use = RunnerScan.useOf({ call, line, isExample });
|
|
186
|
+
|
|
187
|
+
// a Markdown wrap can leave the name on the next line, after the flags
|
|
188
|
+
if (use.name === '' && use.packageName === undefined && use.flags.length > 0) {
|
|
189
|
+
const following = lines[at + 1]?.text.trim().split(/\s+/) ?? [];
|
|
190
|
+
|
|
191
|
+
call = PackageRunners.find({ program: match[1], args: [...words, ...following] });
|
|
192
|
+
use = call === undefined ? use : RunnerScan.useOf({ call, line, isExample });
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
if (
|
|
196
|
+
(use.name !== '' || use.packageName !== undefined) &&
|
|
197
|
+
!RunnerScan.isCommandString({ use })
|
|
198
|
+
) {
|
|
199
|
+
uses.push(use);
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
for (const array of text.matchAll(ARRAY_FORM)) {
|
|
204
|
+
const [program, ...args] = [...(array[1] ?? '').matchAll(QUOTED)].map(
|
|
205
|
+
(word) => word[1] ?? '',
|
|
206
|
+
);
|
|
207
|
+
const call = PackageRunners.find({ program: program ?? '', args });
|
|
208
|
+
const use = call === undefined ? undefined : RunnerScan.useOf({ call, line, isExample });
|
|
209
|
+
|
|
210
|
+
if (
|
|
211
|
+
use !== undefined &&
|
|
212
|
+
(use.name !== '' || use.packageName !== undefined) &&
|
|
213
|
+
!RunnerScan.isCommandString({ use })
|
|
214
|
+
) {
|
|
215
|
+
uses.push(use);
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
return uses;
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/** Whether the command runs a command string and names no package: `-c` takes that string, so the word after it is no name. */
|
|
224
|
+
static isCommandString(opts: { use: IRunnerUse }): boolean {
|
|
225
|
+
return opts.use.runsCommand && opts.use.packageName === undefined;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/** `shadcn@latest` is `shadcn`; a scoped name keeps its scope. */
|
|
229
|
+
static bareName(opts: { name: string }): string {
|
|
230
|
+
return opts.name.replace(/(?<=.)@[^@]*$/, '');
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* The name a command runs that a project may not accept, or `undefined`. A scoped package (`@scope/name`, any scope: an
|
|
235
|
+
* owner holds it and nobody can register it) passes, and so does a name on the allow-list, with a version or a tag after
|
|
236
|
+
* it and nothing else: `shadcn@npm:tool` and `shadcn@github:owner/repo` are other packages. A `-p` package decides when
|
|
237
|
+
* there is one: the command runs a bin of that package. A command with no name at all is refused (the empty name).
|
|
238
|
+
*/
|
|
239
|
+
static refusedName(opts: {
|
|
240
|
+
use: IRunnerUse;
|
|
241
|
+
allow: string[];
|
|
242
|
+
/** True for a tracked file: it may pin a scoped package with `$(...)` or `${...}`. */
|
|
243
|
+
isFile?: boolean;
|
|
244
|
+
}): string | undefined {
|
|
245
|
+
const name = opts.use.packageName ?? opts.use.name;
|
|
246
|
+
|
|
247
|
+
if ((opts.isFile === true ? SCOPED_PINNED : SCOPED).test(name)) {
|
|
248
|
+
return undefined;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
const bareName = RunnerScan.bareName({ name });
|
|
252
|
+
const spec = name.slice(bareName.length);
|
|
253
|
+
const isSpecKnown = spec === '' || SPEC_VERSION.test(spec.slice(1));
|
|
254
|
+
|
|
255
|
+
return opts.allow.includes(bareName) && isSpecKnown ? undefined : name;
|
|
256
|
+
}
|
|
257
|
+
}
|