vouchington-tooling 0.67.0 → 0.69.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/README.md +55 -0
- package/dist/cli/commands/coverage-scope-check.d.mts +7 -0
- package/dist/cli/commands/coverage-scope-check.mjs +69 -0
- package/dist/cli/commands/docker-image-mirror.d.mts +13 -0
- package/dist/cli/commands/docker-image-mirror.mjs +39 -0
- package/dist/cli/commands/trivy-policy.d.mts +12 -0
- package/dist/cli/commands/trivy-policy.mjs +76 -0
- package/dist/cli/index.mjs +6 -0
- package/dist/cli/parse-forwarded-commands.d.mts +7 -69
- package/dist/cli/parse-forwarded-commands.mjs +30 -47
- package/dist/cli/parse.d.mts +9 -0
- package/dist/cli/usage-text-coverage-scope.d.mts +1 -0
- package/dist/cli/usage-text-coverage-scope.mjs +7 -0
- package/dist/cli/usage-text-policy.d.mts +2 -0
- package/dist/cli/usage-text-policy.mjs +25 -0
- package/dist/cli/usage-text.d.mts +1 -1
- package/dist/cli/usage-text.mjs +3 -3
- package/dist/coverage-scope/check.d.mts +16 -0
- package/dist/coverage-scope/check.mjs +26 -0
- package/dist/coverage-scope/coverage-scope.test-helpers.d.mts +4 -0
- package/dist/coverage-scope/coverage-scope.test-helpers.mjs +38 -0
- package/dist/coverage-scope/index.d.mts +3 -0
- package/dist/coverage-scope/index.mjs +2 -0
- package/dist/coverage-scope/mismatches.d.mts +3 -0
- package/dist/coverage-scope/mismatches.mjs +17 -0
- package/dist/docker-image-mirror/images.d.mts +25 -0
- package/dist/docker-image-mirror/images.mjs +108 -0
- package/dist/docker-image-mirror/index.d.mts +16 -0
- package/dist/docker-image-mirror/index.mjs +39 -0
- package/dist/index.d.mts +4 -0
- package/dist/index.mjs +2 -0
- package/dist/trivy-policy/background.d.mts +1 -0
- package/dist/trivy-policy/background.mjs +24 -0
- package/dist/trivy-policy/gate.d.mts +5 -0
- package/dist/trivy-policy/gate.mjs +92 -0
- package/dist/trivy-policy/index.d.mts +15 -0
- package/dist/trivy-policy/index.mjs +48 -0
- package/dist/trivy-policy/invocations.d.mts +4 -0
- package/dist/trivy-policy/invocations.mjs +76 -0
- package/dist/trivy-policy/options.d.mts +26 -0
- package/dist/trivy-policy/options.mjs +17 -0
- package/dist/trivy-policy/registry.d.mts +7 -0
- package/dist/trivy-policy/registry.mjs +48 -0
- package/dist/trivy-policy/scan.d.mts +5 -0
- package/dist/trivy-policy/scan.mjs +59 -0
- package/dist/trivy-policy/shell.d.mts +2 -0
- package/dist/trivy-policy/shell.mjs +62 -0
- package/package.json +17 -1
- package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
- package/skills/agent-workflow/references/implementation.md +5 -0
- package/skills/manifest.json +20 -20
- package/skills/pr-description/SKILL.md +26 -11
- package/skills/pr-description/references/examples.md +53 -0
package/README.md
CHANGED
|
@@ -369,6 +369,61 @@ The pieces are exported from `vouchington-tooling/cloc` (`loadClocConfig`, `norm
|
|
|
369
369
|
`countFiles`, `buildRows`, `formatRows`, `createClassifier`, `createPathPolicy`,
|
|
370
370
|
`compilePatterns`).
|
|
371
371
|
|
|
372
|
+
## Checking the coverage collector scope
|
|
373
|
+
|
|
374
|
+
`vouchington coverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]...
|
|
375
|
+
[--exclude <glob>]...` fails when a `git ls-files -z` entry that a
|
|
376
|
+
[`coverage-check`](https://www.npmjs.com/package/coverage-check) rules file (default
|
|
377
|
+
`.coverage-rules.yml`) gives a `patch_coverage_min` above 0, and whose `scope` does not ignore, is
|
|
378
|
+
outside the collector's scope. Such a file would be required to have coverage that the collector can
|
|
379
|
+
never produce. Every mismatch is printed to stderr and the exit code is 1; 2 is a usage error.
|
|
380
|
+
|
|
381
|
+
The collector's scope is consumer input, mirroring the Vitest `coverage.include` and
|
|
382
|
+
`coverage.exclude` arrays: repeat `--include`/`--exclude`, or point `--scope-file` at a JSON file
|
|
383
|
+
`{ "include": [...], "exclude": [...] }` written from the Vitest config so the two cannot drift. Both
|
|
384
|
+
sources are combined, and at least one include glob is required.
|
|
385
|
+
|
|
386
|
+
```bash
|
|
387
|
+
vouchington coverage-scope-check --scope-file coverage-scope.json
|
|
388
|
+
vouchington coverage-scope-check --include '**/*.{mts,ts,tsx}' --exclude '**/fixtures/**'
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
The pure `findCoverageScopeMismatches(files, config, instrumentedScope)` and
|
|
392
|
+
`checkCoverageScope({ cwd, rulesFile, instrumentedScope, listFiles })` (which returns the
|
|
393
|
+
mismatches) are exported from `vouchington-tooling/coverage-scope`.
|
|
394
|
+
|
|
395
|
+
## Trivy policy and Docker Hub mirror checks
|
|
396
|
+
|
|
397
|
+
Two repository-file checks read the git-tracked files (`git ls-files -z`) under `--root` (default
|
|
398
|
+
the current directory), print one violation per line to stderr, and exit 1 when any exist (0 when
|
|
399
|
+
compliant, 2 on a usage error).
|
|
400
|
+
|
|
401
|
+
`vouchington trivy-policy [--ignore-file <path>] [--findings-exit-code-env <NAME>]
|
|
402
|
+
[--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]` requires every
|
|
403
|
+
Trivy package scan in tracked workflows, composite actions and shell scripts to be an auditable CLI
|
|
404
|
+
run block: no `trivy` action, wrapper, command or process substitution, `bash -c`, `eval`,
|
|
405
|
+
background job or grouped scan (shell scripts may only run `--download-db-only`). Vulnerability
|
|
406
|
+
gates must pass `--scanners vuln`, `--pkg-types os`, `--severity CRITICAL,HIGH`, `--ignore-unfixed`,
|
|
407
|
+
`--skip-db-update`, `--quiet`, `--format table --table-mode detailed`, one `--output`,
|
|
408
|
+
`--ignorefile <ignore-file>` (default `.trivyignore.yaml`) and `--exit-code "$<NAME>"` (default
|
|
409
|
+
`TRIVY_FINDINGS_EXIT_CODE`), with no other options. CycloneDX component SBOM scans must be unfiltered
|
|
410
|
+
(`--quiet --skip-db-update --exit-code 0 --format cyclonedx --output <file>`). At least `--min-gates`
|
|
411
|
+
gates and `--min-sboms` SBOM scans (default 2 each) must exist. The tracked ignore registry must list
|
|
412
|
+
exact versioned `deb`/`apk`/`rpm` purls, a `Not exploitable: <reason>. Cleanup: <issue URL>`
|
|
413
|
+
statement (the URL must start with `--cleanup-url-prefix` when given, else any GitHub issue) and an
|
|
414
|
+
`expired_at` UTC date after today and at most `--max-expiry-days` (default 30) away.
|
|
415
|
+
|
|
416
|
+
`vouchington docker-image-mirror [--mirror <host>]` reports every Docker Hub image reference in
|
|
417
|
+
tracked workflows, composite actions and Dockerfiles: `docker run|pull|create`, `container:`,
|
|
418
|
+
`services:`, `docker://` uses, `docker/setup-buildx-action` drivers, `FROM`, `COPY --from` and
|
|
419
|
+
`# syntax=`. An image is accepted when it names a registry host; `--mirror` (default
|
|
420
|
+
`mirror.gcr.io`) is the host the message tells you to use.
|
|
421
|
+
|
|
422
|
+
The checks are exported as `checkTrivyPolicy(root, trackedFiles, options)` from
|
|
423
|
+
`vouchington-tooling/trivy-policy` (plus the command parsers and `validateIgnoreRegistry`) and
|
|
424
|
+
`checkDockerImageMirrors(root, trackedFiles, { mirror })` from `vouchington-tooling/docker-image-mirror`;
|
|
425
|
+
both return violation strings.
|
|
426
|
+
|
|
372
427
|
## Running the Storybook browser tests
|
|
373
428
|
|
|
374
429
|
`vouchington storybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]...
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `vouchington coverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]...
|
|
3
|
+
* [--exclude <glob>]...`: fails when a tracked file under a positive-threshold coverage rule is not
|
|
4
|
+
* instrumented by the given include/exclude globs. Exits 0 on success, 2 on a usage error, 1 on a
|
|
5
|
+
* mismatch or when the rules cannot be loaded.
|
|
6
|
+
*/
|
|
7
|
+
export declare function runCoverageScopeCheckCommand(args: readonly string[], cwd?: string): number;
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { resolve } from 'node:path';
|
|
3
|
+
import { parseArgs } from 'node:util';
|
|
4
|
+
import { checkCoverageScope } from "../../coverage-scope/check.mjs";
|
|
5
|
+
import { commandUsage } from "../usage.mjs";
|
|
6
|
+
function readGlobs(path, value, name) {
|
|
7
|
+
if (value === undefined)
|
|
8
|
+
return [];
|
|
9
|
+
if (Array.isArray(value) && value.every((item) => typeof item === 'string'))
|
|
10
|
+
return value;
|
|
11
|
+
throw new Error(`${path}: "${name}" must be an array of strings`);
|
|
12
|
+
}
|
|
13
|
+
function parse(args, cwd) {
|
|
14
|
+
const { values } = parseArgs({
|
|
15
|
+
args: [...args],
|
|
16
|
+
allowPositionals: false,
|
|
17
|
+
options: {
|
|
18
|
+
rules: { type: 'string', default: '.coverage-rules.yml' },
|
|
19
|
+
'scope-file': { type: 'string' },
|
|
20
|
+
include: { type: 'string', multiple: true, default: [] },
|
|
21
|
+
exclude: { type: 'string', multiple: true, default: [] },
|
|
22
|
+
},
|
|
23
|
+
});
|
|
24
|
+
const path = values['scope-file'];
|
|
25
|
+
const file = path === undefined
|
|
26
|
+
? {}
|
|
27
|
+
: JSON.parse(readFileSync(resolve(cwd, path), 'utf8'));
|
|
28
|
+
const include = [...readGlobs(String(path), file.include, 'include'), ...values.include];
|
|
29
|
+
if (include.length === 0)
|
|
30
|
+
throw new Error('at least one include glob is required');
|
|
31
|
+
return {
|
|
32
|
+
rules: values.rules,
|
|
33
|
+
include,
|
|
34
|
+
exclude: [...readGlobs(String(path), file.exclude, 'exclude'), ...values.exclude],
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* `vouchington coverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]...
|
|
39
|
+
* [--exclude <glob>]...`: fails when a tracked file under a positive-threshold coverage rule is not
|
|
40
|
+
* instrumented by the given include/exclude globs. Exits 0 on success, 2 on a usage error, 1 on a
|
|
41
|
+
* mismatch or when the rules cannot be loaded.
|
|
42
|
+
*/
|
|
43
|
+
export function runCoverageScopeCheckCommand(args, cwd = process.cwd()) {
|
|
44
|
+
let options;
|
|
45
|
+
try {
|
|
46
|
+
options = parse(args, cwd);
|
|
47
|
+
}
|
|
48
|
+
catch (error) {
|
|
49
|
+
const message = error.message;
|
|
50
|
+
process.stderr.write(`vouchington: ${message}\n${commandUsage('coverage-scope-check')}`);
|
|
51
|
+
return 2;
|
|
52
|
+
}
|
|
53
|
+
try {
|
|
54
|
+
const mismatches = checkCoverageScope({
|
|
55
|
+
cwd,
|
|
56
|
+
rulesFile: options.rules,
|
|
57
|
+
instrumentedScope: options,
|
|
58
|
+
});
|
|
59
|
+
if (mismatches.length === 0)
|
|
60
|
+
return 0;
|
|
61
|
+
const lines = mismatches.map((file) => ` ${file}`).join('\n');
|
|
62
|
+
process.stderr.write(`Coverage rules require files that the collector does not instrument:\n${lines}\n`);
|
|
63
|
+
return 1;
|
|
64
|
+
}
|
|
65
|
+
catch (error) {
|
|
66
|
+
process.stderr.write(`vouchington: ${error.message}\n`);
|
|
67
|
+
return 1;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { type SharedContext } from '../../shared-context/index.mts';
|
|
2
|
+
interface Dependencies {
|
|
3
|
+
readonly buildContext?: (root: string) => Promise<SharedContext>;
|
|
4
|
+
readonly stdout?: Pick<NodeJS.WritableStream, 'write'>;
|
|
5
|
+
readonly stderr?: Pick<NodeJS.WritableStream, 'write'>;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* `vouchington docker-image-mirror [--root <dir>] [--mirror <host>]`: prints each Docker Hub image
|
|
9
|
+
* reference in tracked workflows, composite actions and Dockerfiles to stderr and exits 1; exits 2
|
|
10
|
+
* on a usage error and 0 when every image comes from the mirror or another registry.
|
|
11
|
+
*/
|
|
12
|
+
export declare function runDockerImageMirrorCommand(args: readonly string[], dependencies?: Dependencies): Promise<number>;
|
|
13
|
+
export {};
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { resolve } from 'node:path';
|
|
2
|
+
import { parseArgs } from 'node:util';
|
|
3
|
+
import { checkDockerImageMirrors } from "../../docker-image-mirror/index.mjs";
|
|
4
|
+
import { buildSharedContext } from "../../shared-context/index.mjs";
|
|
5
|
+
import { commandUsage } from "../usage.mjs";
|
|
6
|
+
/**
|
|
7
|
+
* `vouchington docker-image-mirror [--root <dir>] [--mirror <host>]`: prints each Docker Hub image
|
|
8
|
+
* reference in tracked workflows, composite actions and Dockerfiles to stderr and exits 1; exits 2
|
|
9
|
+
* on a usage error and 0 when every image comes from the mirror or another registry.
|
|
10
|
+
*/
|
|
11
|
+
export async function runDockerImageMirrorCommand(args, dependencies = {}) {
|
|
12
|
+
const stdout = dependencies.stdout ?? process.stdout;
|
|
13
|
+
const stderr = dependencies.stderr ?? process.stderr;
|
|
14
|
+
let values;
|
|
15
|
+
try {
|
|
16
|
+
values = parseArgs({
|
|
17
|
+
args: [...args],
|
|
18
|
+
allowPositionals: false,
|
|
19
|
+
options: { root: { type: 'string' }, mirror: { type: 'string' } },
|
|
20
|
+
}).values;
|
|
21
|
+
}
|
|
22
|
+
catch (error) {
|
|
23
|
+
stderr.write(`vouchington: ${error.message}\n${commandUsage('docker-image-mirror')}`);
|
|
24
|
+
return 2;
|
|
25
|
+
}
|
|
26
|
+
const root = resolve(values.root ?? process.cwd());
|
|
27
|
+
const context = await (dependencies.buildContext ?? buildSharedContext)(root);
|
|
28
|
+
if (!context.isInsideGitRepo) {
|
|
29
|
+
stderr.write(`vouchington: ${root} is not inside a git repository\n`);
|
|
30
|
+
return 1;
|
|
31
|
+
}
|
|
32
|
+
const errors = checkDockerImageMirrors(context.repoRoot, context.trackedFiles, values);
|
|
33
|
+
if (errors.length === 0) {
|
|
34
|
+
stdout.write('Docker image mirror policy: ok\n');
|
|
35
|
+
return 0;
|
|
36
|
+
}
|
|
37
|
+
stderr.write(`${errors.join('\n')}\n`);
|
|
38
|
+
return 1;
|
|
39
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { type SharedContext } from '../../shared-context/index.mts';
|
|
2
|
+
interface Dependencies {
|
|
3
|
+
readonly buildContext?: (root: string) => Promise<SharedContext>;
|
|
4
|
+
readonly stdout?: Pick<NodeJS.WritableStream, 'write'>;
|
|
5
|
+
readonly stderr?: Pick<NodeJS.WritableStream, 'write'>;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* `vouchington trivy-policy [--root <dir>] [--ignore-file <path>] ...`: prints each violation of the
|
|
9
|
+
* tracked Trivy policy to stderr and exits 1; exits 2 on a usage error and 0 when compliant.
|
|
10
|
+
*/
|
|
11
|
+
export declare function runTrivyPolicyCommand(args: readonly string[], dependencies?: Dependencies): Promise<number>;
|
|
12
|
+
export {};
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { resolve } from 'node:path';
|
|
2
|
+
import { parseArgs } from 'node:util';
|
|
3
|
+
import { buildSharedContext } from "../../shared-context/index.mjs";
|
|
4
|
+
import { checkTrivyPolicy } from "../../trivy-policy/index.mjs";
|
|
5
|
+
import { commandUsage } from "../usage.mjs";
|
|
6
|
+
function integer(name, value) {
|
|
7
|
+
if (value === undefined)
|
|
8
|
+
return undefined;
|
|
9
|
+
if (!/^\d{1,5}$/.test(value))
|
|
10
|
+
throw new Error(`--${name} must be an integer from 0 to 99999`);
|
|
11
|
+
return Number(value);
|
|
12
|
+
}
|
|
13
|
+
function parseOptions(args) {
|
|
14
|
+
const { values } = parseArgs({
|
|
15
|
+
args: [...args],
|
|
16
|
+
allowPositionals: false,
|
|
17
|
+
options: {
|
|
18
|
+
root: { type: 'string' },
|
|
19
|
+
'ignore-file': { type: 'string' },
|
|
20
|
+
'findings-exit-code-env': { type: 'string' },
|
|
21
|
+
'cleanup-url-prefix': { type: 'string' },
|
|
22
|
+
'min-gates': { type: 'string' },
|
|
23
|
+
'min-sboms': { type: 'string' },
|
|
24
|
+
'max-expiry-days': { type: 'string' },
|
|
25
|
+
},
|
|
26
|
+
});
|
|
27
|
+
const envName = values['findings-exit-code-env'];
|
|
28
|
+
if (envName !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(envName))
|
|
29
|
+
throw new Error('--findings-exit-code-env must be an environment variable name');
|
|
30
|
+
const minGates = integer('min-gates', values['min-gates']);
|
|
31
|
+
const minSboms = integer('min-sboms', values['min-sboms']);
|
|
32
|
+
const maxExpiryDays = integer('max-expiry-days', values['max-expiry-days']);
|
|
33
|
+
return {
|
|
34
|
+
root: resolve(values.root ?? process.cwd()),
|
|
35
|
+
options: {
|
|
36
|
+
...(values['ignore-file'] === undefined ? {} : { ignoreFile: values['ignore-file'] }),
|
|
37
|
+
...(values['findings-exit-code-env'] === undefined
|
|
38
|
+
? {}
|
|
39
|
+
: { findingsExitCodeEnv: values['findings-exit-code-env'] }),
|
|
40
|
+
...(values['cleanup-url-prefix'] === undefined
|
|
41
|
+
? {}
|
|
42
|
+
: { cleanupUrlPrefix: values['cleanup-url-prefix'] }),
|
|
43
|
+
...(minGates === undefined ? {} : { minGates }),
|
|
44
|
+
...(minSboms === undefined ? {} : { minSboms }),
|
|
45
|
+
...(maxExpiryDays === undefined ? {} : { maxExpiryDays }),
|
|
46
|
+
},
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* `vouchington trivy-policy [--root <dir>] [--ignore-file <path>] ...`: prints each violation of the
|
|
51
|
+
* tracked Trivy policy to stderr and exits 1; exits 2 on a usage error and 0 when compliant.
|
|
52
|
+
*/
|
|
53
|
+
export async function runTrivyPolicyCommand(args, dependencies = {}) {
|
|
54
|
+
const stdout = dependencies.stdout ?? process.stdout;
|
|
55
|
+
const stderr = dependencies.stderr ?? process.stderr;
|
|
56
|
+
let parsed;
|
|
57
|
+
try {
|
|
58
|
+
parsed = parseOptions(args);
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
stderr.write(`vouchington: ${error.message}\n${commandUsage('trivy-policy')}`);
|
|
62
|
+
return 2;
|
|
63
|
+
}
|
|
64
|
+
const context = await (dependencies.buildContext ?? buildSharedContext)(parsed.root);
|
|
65
|
+
if (!context.isInsideGitRepo) {
|
|
66
|
+
stderr.write(`vouchington: ${parsed.root} is not inside a git repository\n`);
|
|
67
|
+
return 1;
|
|
68
|
+
}
|
|
69
|
+
const violations = checkTrivyPolicy(context.repoRoot, context.trackedFiles, parsed.options);
|
|
70
|
+
if (violations.length === 0) {
|
|
71
|
+
stdout.write('Trivy policy: ok\n');
|
|
72
|
+
return 0;
|
|
73
|
+
}
|
|
74
|
+
stderr.write(`${violations.join('\n')}\n`);
|
|
75
|
+
return 1;
|
|
76
|
+
}
|
package/dist/cli/index.mjs
CHANGED
|
@@ -110,8 +110,14 @@ export function runCli(argv = process.argv) {
|
|
|
110
110
|
return import("./commands/transient-retry.mjs").then((command) => command.runTransientRetryCommand(parsed.args));
|
|
111
111
|
case 'sandbox-command-audit':
|
|
112
112
|
return import("./commands/sandbox-command-audit.mjs").then((command) => command.runSandboxCommandAuditCommand(parsed.args));
|
|
113
|
+
case 'coverage-scope-check':
|
|
114
|
+
return import("./commands/coverage-scope-check.mjs").then((command) => command.runCoverageScopeCheckCommand(parsed.args));
|
|
113
115
|
case 'cloc':
|
|
114
116
|
return import("./commands/cloc.mjs").then((command) => command.runClocCommand(parsed.args));
|
|
117
|
+
case 'trivy-policy':
|
|
118
|
+
return import("./commands/trivy-policy.mjs").then((command) => command.runTrivyPolicyCommand(parsed.args));
|
|
119
|
+
case 'docker-image-mirror':
|
|
120
|
+
return import("./commands/docker-image-mirror.mjs").then((command) => command.runDockerImageMirrorCommand(parsed.args));
|
|
115
121
|
case 'storybook-browser-runner':
|
|
116
122
|
return import("./commands/storybook-browser-runner.mjs").then((command) => command.runStorybookBrowserRunnerCommand(parsed.args));
|
|
117
123
|
case 'hook':
|
|
@@ -1,72 +1,10 @@
|
|
|
1
|
+
declare const FORWARDED: readonly ["with-host-lock", "host-storage", "pnpm-install", "vitest-blob-manifest", "vitest-report-attempt", "prepare-vitest-reports", "nuget-central-version", "verify-workflow-secrets", "dead-code", "swift-semantic-equal", "post-review", "stage-review-payload", "retrospective-transcript", "retrospective-facts", "agent-blackboard", "mcp", "hook", "worktree", "transient-retry", "sandbox-command-audit", "cloc", "coverage-scope-check", "trivy-policy", "docker-image-mirror", "storybook-browser-runner", "tmux"];
|
|
2
|
+
type Name = (typeof FORWARDED)[number];
|
|
1
3
|
type ForwardedCommand = {
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
} | {
|
|
8
|
-
kind: 'pnpm-install';
|
|
9
|
-
args: string[];
|
|
10
|
-
} | {
|
|
11
|
-
kind: 'vitest-blob-manifest';
|
|
12
|
-
args: string[];
|
|
13
|
-
} | {
|
|
14
|
-
kind: 'vitest-report-attempt';
|
|
15
|
-
args: string[];
|
|
16
|
-
} | {
|
|
17
|
-
kind: 'prepare-vitest-reports';
|
|
18
|
-
args: string[];
|
|
19
|
-
} | {
|
|
20
|
-
kind: 'nuget-central-version';
|
|
21
|
-
args: string[];
|
|
22
|
-
} | {
|
|
23
|
-
kind: 'verify-workflow-secrets';
|
|
24
|
-
args: string[];
|
|
25
|
-
} | {
|
|
26
|
-
kind: 'dead-code';
|
|
27
|
-
args: string[];
|
|
28
|
-
} | {
|
|
29
|
-
kind: 'swift-semantic-equal';
|
|
30
|
-
args: string[];
|
|
31
|
-
} | {
|
|
32
|
-
kind: 'post-review';
|
|
33
|
-
args: string[];
|
|
34
|
-
} | {
|
|
35
|
-
kind: 'stage-review-payload';
|
|
36
|
-
args: string[];
|
|
37
|
-
} | {
|
|
38
|
-
kind: 'retrospective-transcript';
|
|
39
|
-
args: string[];
|
|
40
|
-
} | {
|
|
41
|
-
kind: 'retrospective-facts';
|
|
42
|
-
args: string[];
|
|
43
|
-
} | {
|
|
44
|
-
kind: 'agent-blackboard';
|
|
45
|
-
args: string[];
|
|
46
|
-
} | {
|
|
47
|
-
kind: 'mcp';
|
|
48
|
-
args: string[];
|
|
49
|
-
} | {
|
|
50
|
-
kind: 'hook';
|
|
51
|
-
args: string[];
|
|
52
|
-
} | {
|
|
53
|
-
kind: 'worktree';
|
|
54
|
-
args: string[];
|
|
55
|
-
} | {
|
|
56
|
-
kind: 'transient-retry';
|
|
57
|
-
args: string[];
|
|
58
|
-
} | {
|
|
59
|
-
kind: 'sandbox-command-audit';
|
|
60
|
-
args: string[];
|
|
61
|
-
} | {
|
|
62
|
-
kind: 'cloc';
|
|
63
|
-
args: string[];
|
|
64
|
-
} | {
|
|
65
|
-
kind: 'storybook-browser-runner';
|
|
66
|
-
args: string[];
|
|
67
|
-
} | {
|
|
68
|
-
kind: 'tmux';
|
|
69
|
-
args: string[];
|
|
70
|
-
};
|
|
4
|
+
[K in Name]: {
|
|
5
|
+
kind: K;
|
|
6
|
+
args: string[];
|
|
7
|
+
};
|
|
8
|
+
}[Name];
|
|
71
9
|
export declare function parseForwardedCommand(command: string | undefined, args: string[]): ForwardedCommand | undefined;
|
|
72
10
|
export {};
|
|
@@ -1,49 +1,32 @@
|
|
|
1
|
+
const FORWARDED = [
|
|
2
|
+
'with-host-lock',
|
|
3
|
+
'host-storage',
|
|
4
|
+
'pnpm-install',
|
|
5
|
+
'vitest-blob-manifest',
|
|
6
|
+
'vitest-report-attempt',
|
|
7
|
+
'prepare-vitest-reports',
|
|
8
|
+
'nuget-central-version',
|
|
9
|
+
'verify-workflow-secrets',
|
|
10
|
+
'dead-code',
|
|
11
|
+
'swift-semantic-equal',
|
|
12
|
+
'post-review',
|
|
13
|
+
'stage-review-payload',
|
|
14
|
+
'retrospective-transcript',
|
|
15
|
+
'retrospective-facts',
|
|
16
|
+
'agent-blackboard',
|
|
17
|
+
'mcp',
|
|
18
|
+
'hook',
|
|
19
|
+
'worktree',
|
|
20
|
+
'transient-retry',
|
|
21
|
+
'sandbox-command-audit',
|
|
22
|
+
'cloc',
|
|
23
|
+
'coverage-scope-check',
|
|
24
|
+
'trivy-policy',
|
|
25
|
+
'docker-image-mirror',
|
|
26
|
+
'storybook-browser-runner',
|
|
27
|
+
'tmux',
|
|
28
|
+
];
|
|
1
29
|
export function parseForwardedCommand(command, args) {
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
if (command === 'host-storage')
|
|
5
|
-
return { kind: 'host-storage', args };
|
|
6
|
-
if (command === 'pnpm-install')
|
|
7
|
-
return { kind: 'pnpm-install', args };
|
|
8
|
-
if (command === 'vitest-blob-manifest')
|
|
9
|
-
return { kind: 'vitest-blob-manifest', args };
|
|
10
|
-
if (command === 'vitest-report-attempt')
|
|
11
|
-
return { kind: 'vitest-report-attempt', args };
|
|
12
|
-
if (command === 'prepare-vitest-reports')
|
|
13
|
-
return { kind: 'prepare-vitest-reports', args };
|
|
14
|
-
if (command === 'nuget-central-version')
|
|
15
|
-
return { kind: 'nuget-central-version', args };
|
|
16
|
-
if (command === 'verify-workflow-secrets')
|
|
17
|
-
return { kind: 'verify-workflow-secrets', args };
|
|
18
|
-
if (command === 'dead-code')
|
|
19
|
-
return { kind: 'dead-code', args };
|
|
20
|
-
if (command === 'swift-semantic-equal')
|
|
21
|
-
return { kind: 'swift-semantic-equal', args };
|
|
22
|
-
if (command === 'post-review')
|
|
23
|
-
return { kind: 'post-review', args };
|
|
24
|
-
if (command === 'stage-review-payload')
|
|
25
|
-
return { kind: 'stage-review-payload', args };
|
|
26
|
-
if (command === 'retrospective-transcript')
|
|
27
|
-
return { kind: 'retrospective-transcript', args };
|
|
28
|
-
if (command === 'retrospective-facts')
|
|
29
|
-
return { kind: 'retrospective-facts', args };
|
|
30
|
-
if (command === 'agent-blackboard')
|
|
31
|
-
return { kind: 'agent-blackboard', args };
|
|
32
|
-
if (command === 'mcp')
|
|
33
|
-
return { kind: 'mcp', args };
|
|
34
|
-
if (command === 'hook')
|
|
35
|
-
return { kind: 'hook', args };
|
|
36
|
-
if (command === 'worktree')
|
|
37
|
-
return { kind: 'worktree', args };
|
|
38
|
-
if (command === 'transient-retry')
|
|
39
|
-
return { kind: 'transient-retry', args };
|
|
40
|
-
if (command === 'sandbox-command-audit')
|
|
41
|
-
return { kind: 'sandbox-command-audit', args };
|
|
42
|
-
if (command === 'cloc')
|
|
43
|
-
return { kind: 'cloc', args };
|
|
44
|
-
if (command === 'storybook-browser-runner')
|
|
45
|
-
return { kind: 'storybook-browser-runner', args };
|
|
46
|
-
if (command === 'tmux')
|
|
47
|
-
return { kind: 'tmux', args };
|
|
48
|
-
return undefined;
|
|
30
|
+
const kind = FORWARDED.find((name) => name === command);
|
|
31
|
+
return kind === undefined ? undefined : { kind, args };
|
|
49
32
|
}
|
package/dist/cli/parse.d.mts
CHANGED
|
@@ -92,6 +92,15 @@ export type ParsedCli = {
|
|
|
92
92
|
} | {
|
|
93
93
|
kind: 'cloc';
|
|
94
94
|
args: string[];
|
|
95
|
+
} | {
|
|
96
|
+
kind: 'coverage-scope-check';
|
|
97
|
+
args: string[];
|
|
98
|
+
} | {
|
|
99
|
+
kind: 'trivy-policy';
|
|
100
|
+
args: string[];
|
|
101
|
+
} | {
|
|
102
|
+
kind: 'docker-image-mirror';
|
|
103
|
+
args: string[];
|
|
95
104
|
} | {
|
|
96
105
|
kind: 'storybook-browser-runner';
|
|
97
106
|
args: string[];
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare const COVERAGE_SCOPE_CHECK_USAGE = "coverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n";
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export const COVERAGE_SCOPE_CHECK_USAGE = `coverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...
|
|
2
|
+
Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)
|
|
3
|
+
gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's
|
|
4
|
+
scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the
|
|
5
|
+
include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.
|
|
6
|
+
At least one include glob is required.
|
|
7
|
+
`;
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
export declare const POLICY_COMMANDS = " coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n";
|
|
2
|
+
export declare const POLICY_USAGE = "\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI run block (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>]\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use.\n\n";
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { COVERAGE_SCOPE_CHECK_USAGE } from "./usage-text-coverage-scope.mjs";
|
|
2
|
+
export const POLICY_COMMANDS = ` coverage-scope-check Check positive-threshold coverage rules against the Vitest scope
|
|
3
|
+
trivy-policy Check tracked Trivy workflow scans and the exception registry
|
|
4
|
+
docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror
|
|
5
|
+
`;
|
|
6
|
+
export const POLICY_USAGE = `
|
|
7
|
+
${COVERAGE_SCOPE_CHECK_USAGE}
|
|
8
|
+
trivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]
|
|
9
|
+
Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).
|
|
10
|
+
Every Trivy package scan must be an auditable CLI run block (no action, wrapper, substitution or
|
|
11
|
+
background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,
|
|
12
|
+
--ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>
|
|
13
|
+
(default .trivyignore.yaml) and --exit-code "$<NAME>" (default TRIVY_FINDINGS_EXIT_CODE).
|
|
14
|
+
CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and
|
|
15
|
+
--min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS
|
|
16
|
+
packages, a "Not exploitable: ... Cleanup: <issue URL>" statement (URL must start with
|
|
17
|
+
--cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).
|
|
18
|
+
|
|
19
|
+
docker-image-mirror [--root <dir>] [--mirror <host>]
|
|
20
|
+
Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):
|
|
21
|
+
run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,
|
|
22
|
+
COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is
|
|
23
|
+
the host the message tells you to use.
|
|
24
|
+
|
|
25
|
+
`;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n runner-port-policy Print or validate a runner port policy\n with-host-lock Run a command under a host-wide lock\n host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base branch\n gitleaks-directory-scan Scan a directory with Gitleaks\n ast-grep-examples Run AST-grep rule examples\n ast-grep-pack Print shipped unconditional AST-grep pack paths as JSON\n gha-workspace-policy Check GitHub Actions workspace safety policy\n gha-output Write a collision-safe multiline GITHUB_OUTPUT record\n gha-needs-results Fail if required GitHub Actions job results failed\n download-with-diagnostics Download a URL and report HTTP status on failure\n download-optional-run-artifacts Download optional artifacts from the current run\n host-pressure-diagnostics Print a bounded host memory/OOM/PSI snapshot\n allocate-browser-safe-ports Allocate Fetch-safe localhost ports\n diagnose-port-collision Capture bounded localhost port diagnostics\n prepare-trivy-db Download the Trivy vulnerability database\n gha-artifacts-cleanup Delete classified GitHub Actions artifacts\n agent-issue-labels Map changed paths to labels; create missing repository labels\n http-origin Validate an optional HTTP(S) origin\n vitest-blob-manifest Stamp a vitest-blob-manifest:v1 identity file\n vitest-report-attempt Write or read a Vitest report-attempt marker\n prepare-vitest-reports Validate and select Vitest report JSON files\n pnpm-install Install a pnpm workspace with retry and release-age fail-fast\n check-cache-size Measure a path and decide whether to save a GHA cache\n make-shard-matrix Emit a [1..N] GitHub Actions shard matrix\n load-runner-env Overlay a runner env file onto GITHUB_ENV with injection guards\n clean-workspace Reset a persistent-runner workspace with a fork-PR trust gate\n install-github-release Download a checksum-verified GitHub Release binary\n run-with-timeout Run a command with GNU timeout or a Perl fallback\n lint-links Two-pass lychee: internal links fail, external warn\n materialize-pr-context Dump PR title/body/files/diff/comments and #N crawl\n wait-for-apt-locks Wait until apt/dpkg lock files are free\n install-playwright-chromium-arm64 Install Playwright Chromium from browsers.json\n ghcr-package-retention Delete old GHCR package versions (KEEP_MIN or --main-history)\n harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled\n gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n dead-code Gate unused code against a committed jscpd baseline\n swift-semantic-equal Compare Swift sources ignoring comments and whitespace\n post-review Post one COMMENT review from a staged payload file\n stage-review-payload Validate a review payload file into a staging directory\n retrospective-transcript Format facts from Claude-compatible, Codex, or Grok transcripts\n link-skill Link one packaged skill into an explicit consumer directory\n retrospective-facts Gather immutable facts for a retrospective\n agent-blackboard Probe an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\n cloc Count tracked lines of code by category and service with scc\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\n\nOptions:\n -h, --help Show this help\n -v, --version Print the package version\n\nrunner-port-policy\n (no args) Print the shipped policy as JSON\n --file <path> Validate and print a policy file\n --reserved <port> Print true if the port is reserved\n\nwith-host-lock\n --name <family>\n [--slots <n>]\n --timeout-seconds <n>\n [--command-timeout-seconds <n>]\n [--failure-diagnostics <absolute-script>]\n [--on-acquire-timeout fail|run-unlocked]\n -- <command> [args...]\n\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\n\ngha-runtime-audit\n [--repository owner/name] Default GITHUB_REPOSITORY\n [--branch main]\n [--median-threshold-floor <seconds>] Off unless set. Must be below the ceiling\n [--median-threshold-ceiling <seconds>] Default 360. Flags a five-sample median above this\n --pr-workflow <name|/regex/> Repeatable\n --push-workflow <name|/regex/> Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir> Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update,\n snapshot_export, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\n\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
|
|
1
|
+
export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n runner-port-policy Print or validate a runner port policy\n with-host-lock Run a command under a host-wide lock\n host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base branch\n gitleaks-directory-scan Scan a directory with Gitleaks\n ast-grep-examples Run AST-grep rule examples\n ast-grep-pack Print shipped unconditional AST-grep pack paths as JSON\n gha-workspace-policy Check GitHub Actions workspace safety policy\n gha-output Write a collision-safe multiline GITHUB_OUTPUT record\n gha-needs-results Fail if required GitHub Actions job results failed\n download-with-diagnostics Download a URL and report HTTP status on failure\n download-optional-run-artifacts Download optional artifacts from the current run\n host-pressure-diagnostics Print a bounded host memory/OOM/PSI snapshot\n allocate-browser-safe-ports Allocate Fetch-safe localhost ports\n diagnose-port-collision Capture bounded localhost port diagnostics\n prepare-trivy-db Download the Trivy vulnerability database\n gha-artifacts-cleanup Delete classified GitHub Actions artifacts\n agent-issue-labels Map changed paths to labels; create missing repository labels\n http-origin Validate an optional HTTP(S) origin\n vitest-blob-manifest Stamp a vitest-blob-manifest:v1 identity file\n vitest-report-attempt Write or read a Vitest report-attempt marker\n prepare-vitest-reports Validate and select Vitest report JSON files\n pnpm-install Install a pnpm workspace with retry and release-age fail-fast\n check-cache-size Measure a path and decide whether to save a GHA cache\n make-shard-matrix Emit a [1..N] GitHub Actions shard matrix\n load-runner-env Overlay a runner env file onto GITHUB_ENV with injection guards\n clean-workspace Reset a persistent-runner workspace with a fork-PR trust gate\n install-github-release Download a checksum-verified GitHub Release binary\n run-with-timeout Run a command with GNU timeout or a Perl fallback\n lint-links Two-pass lychee: internal links fail, external warn\n materialize-pr-context Dump PR title/body/files/diff/comments and #N crawl\n wait-for-apt-locks Wait until apt/dpkg lock files are free\n install-playwright-chromium-arm64 Install Playwright Chromium from browsers.json\n ghcr-package-retention Delete old GHCR package versions (KEEP_MIN or --main-history)\n harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled\n gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n dead-code Gate unused code against a committed jscpd baseline\n swift-semantic-equal Compare Swift sources ignoring comments and whitespace\n post-review Post one COMMENT review from a staged payload file\n stage-review-payload Validate a review payload file into a staging directory\n retrospective-transcript Format facts from Claude-compatible, Codex, or Grok transcripts\n link-skill Link one packaged skill into an explicit consumer directory\n retrospective-facts Gather immutable facts for a retrospective\n agent-blackboard Probe an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n hook Run a repository policy module as a pre/post tool-use hook\n worktree Reclaim finished git worktrees (dry run unless --yes)\n tmux Run configured dev windows in tmux; name panes; agent reminders\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n sandbox-command-audit Audit agent transcripts for sandbox escalations and denials\n cloc Count tracked lines of code by category and service with scc\n coverage-scope-check Check positive-threshold coverage rules against the Vitest scope\n trivy-policy Check tracked Trivy workflow scans and the exception registry\n docker-image-mirror Require tracked Docker images to come from a Docker Hub mirror\n storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog\n\nOptions:\n -h, --help Show this help\n -v, --version Print the package version\n\nrunner-port-policy\n (no args) Print the shipped policy as JSON\n --file <path> Validate and print a policy file\n --reserved <port> Print true if the port is reserved\n\nwith-host-lock\n --name <family>\n [--slots <n>]\n --timeout-seconds <n>\n [--command-timeout-seconds <n>]\n [--failure-diagnostics <absolute-script>]\n [--on-acquire-timeout fail|run-unlocked]\n -- <command> [args...]\n\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\n\ngha-runtime-audit\n [--repository owner/name] Default GITHUB_REPOSITORY\n [--branch main]\n [--median-threshold-floor <seconds>] Off unless set. Must be below the ceiling\n [--median-threshold-ceiling <seconds>] Default 360. Flags a five-sample median above this\n --pr-workflow <name|/regex/> Repeatable\n --push-workflow <name|/regex/> Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir> Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update,\n snapshot_export, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nhook pre-tool-use|post-tool-use --harness claude|codex|cursor|grok --policy <module> [--root <dir>] [--automation-env NAME]...\n Reads the harness hook payload on stdin. <module> default-exports a policy object (or a function\n of the hook context returning one) with a command rule table, post-tool-use checkers, and an\n optional reminder. pre-tool-use exits 2 to block, and also when the policy cannot load.\n post-tool-use is advisory and always exits 0. --root defaults to the working directory.\n Each --automation-env NAME (repeatable) marks the run unattended when that environment variable\n is set, non-empty, and not 0 or false; CI markers and claude -p are always unattended.\n\nworktree reclaim [--yes] [--json] [--max-worktrees N] [--timeout-ms N] [--pr-limit N] [--after PATH]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nsandbox-command-audit --rules <module> [--settings-path <file>] [--repo-root <dir>]... [--worktree-glob <glob>]... [--projects-dir <dir>] [--codex-sessions-dir <dir>] [--session-id <id>] [--limit N] [--since DAYS] [--json] [--raw]\n Scans Claude and Codex transcripts scoped to this repository (git roots plus any --worktree-glob\n layouts) and reports Bash escalations, denials and permission failures by command prefix.\n <module> exports an object (default or \"rules\") with loadPolicy({ settingsPath, cwd }), which\n returns { covers(list, commandOrPrefix) } for the allow/deny/excluded lists or { error }, and\n optionally classifyFailure(command, text, source), limits and worktreeGlobs. Transcript roots\n default to CLAUDE_CONFIG_DIR/projects and CODEX_HOME/sessions. --raw prints full command text.\n\ncloc --config <file> [--scc-bin <path>] [--json]\n Counts git-tracked lines with scc (SCC_BIN or --scc-bin, else \"scc\"), classified into\n source/tests/tooling and by service, and prints an aligned table (--json: rows). <file> is a .json\n file or a module whose default (or \"config\") export is the layout: services [{ name, match }],\n defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,\n excludedDirs, ignoredDirs, sccBin, missingSccHint.\n\ncoverage-scope-check [--rules <path>] [--scope-file <json>] [--include <glob>]... [--exclude <glob>]...\n Fails (exit 1) when a git-tracked file that a coverage rules file (default .coverage-rules.yml)\n gives a patch_coverage_min above 0, and its scope does not ignore, is outside the collector's\n scope. The collector scope is the repeated --include/--exclude globs plus, optionally, the\n include/exclude string arrays of a --scope-file JSON written from the Vitest coverage config.\n At least one include glob is required.\n\ntrivy-policy [--root <dir>] [--ignore-file <path>] [--findings-exit-code-env <NAME>] [--cleanup-url-prefix <url>] [--min-gates N] [--min-sboms N] [--max-expiry-days N]\n Reads git-tracked workflows, composite actions and shell scripts and prints each violation (exit 1).\n Every Trivy package scan must be an auditable CLI run block (no action, wrapper, substitution or\n background). Vulnerability gates need --scanners vuln, --pkg-types os, --severity CRITICAL,HIGH,\n --ignore-unfixed, --skip-db-update, --quiet, table output to a file, --ignorefile <ignore-file>\n (default .trivyignore.yaml) and --exit-code \"$<NAME>\" (default TRIVY_FINDINGS_EXIT_CODE).\n CycloneDX SBOM scans must be unfiltered with --exit-code 0. At least --min-gates gates and\n --min-sboms SBOM scans (default 2 each) must exist. The tracked ignore registry needs purl-exact OS\n packages, a \"Not exploitable: ... Cleanup: <issue URL>\" statement (URL must start with\n --cleanup-url-prefix when given) and an expired_at between tomorrow and --max-expiry-days (30).\n\ndocker-image-mirror [--root <dir>] [--mirror <host>]\n Prints each Docker Hub image in git-tracked workflows, composite actions and Dockerfiles (exit 1):\n run, pull and create commands, containers, services, docker:// references, buildx drivers, FROM,\n COPY --from and # syntax. Images must name a registry host; --mirror (default mirror.gcr.io) is\n the host the message tells you to use.\n\nstorybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]\n Spawns <cmd> (default pnpm) in its own process group with <argv> (default \"exec vitest run\n --project <name>\") plus the coverage args (default --coverage) and supervises it: a Vite optimizer\n cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget\n watchdogs. --result-file paths are removed before each attempt and --completion-file is the one\n whose appearance is recorded. Tuned by <PREFIX>_STARTUP_ATTEMPTS, _OPTIMIZER_STALL_MS, _HANG_MS,\n _SESSION_BUDGET_MS, _DIAGNOSTICS_FILE, _PERSISTENT_CACHE, _PERSISTENT_CACHE_DIR and _COVERAGE\n (PREFIX defaults to STORYBOOK_BROWSER). Exits with the resolved test exit code.\n\ntmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name> | read-title | post-tool | agent-reminder <event>\n Environment: TMUX_TARGET_BIN, TMUX_TARGET_ROOT, TMUX_NAME_COMMAND, AGENT_TMUX_SOCKET/PANE/WORKTREE.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
|
package/dist/cli/usage-text.mjs
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { POLICY_COMMANDS, POLICY_USAGE } from "./usage-text-policy.mjs";
|
|
1
2
|
export const USAGE = `Usage: vouchington <command> [options]
|
|
2
3
|
|
|
3
4
|
Commands:
|
|
@@ -58,7 +59,7 @@ Commands:
|
|
|
58
59
|
transient-retry Rerun a failed GitHub Actions run when an injected rule matches
|
|
59
60
|
sandbox-command-audit Audit agent transcripts for sandbox escalations and denials
|
|
60
61
|
cloc Count tracked lines of code by category and service with scc
|
|
61
|
-
storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog
|
|
62
|
+
${POLICY_COMMANDS} storybook-browser-runner Run the Storybook Vitest browser project with cache, retry and watchdog
|
|
62
63
|
|
|
63
64
|
Options:
|
|
64
65
|
-h, --help Show this help
|
|
@@ -179,8 +180,7 @@ cloc --config <file> [--scc-bin <path>] [--json]
|
|
|
179
180
|
file or a module whose default (or "config") export is the layout: services [{ name, match }],
|
|
180
181
|
defaultService, categories, testPatterns, toolingPatterns, countedRoots, countedRootFiles,
|
|
181
182
|
excludedDirs, ignoredDirs, sccBin, missingSccHint.
|
|
182
|
-
|
|
183
|
-
storybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]
|
|
183
|
+
${POLICY_USAGE}storybook-browser-runner --project <name> [--command <cmd>] [--result-file <path>]... [--completion-file <path>] [--coverage-arg=<arg>]... [--optimize-deps-config <path>] [--env-prefix <PREFIX>] [--progress-prefix <text>] [-- <argv>...]
|
|
184
184
|
Spawns <cmd> (default pnpm) in its own process group with <argv> (default "exec vitest run
|
|
185
185
|
--project <name>") plus the coverage args (default --coverage) and supervises it: a Vite optimizer
|
|
186
186
|
cache, retries on known Vite and browser start-up flakes, and stall, hang and session-budget
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/** Globs of the files the coverage collector instruments (Vitest `coverage.include`/`exclude`). */
|
|
2
|
+
export interface InstrumentedGlobs {
|
|
3
|
+
include: readonly string[];
|
|
4
|
+
exclude: readonly string[];
|
|
5
|
+
}
|
|
6
|
+
export interface CheckCoverageScopeOptions {
|
|
7
|
+
cwd: string;
|
|
8
|
+
/** Rules file, relative to `cwd`. Defaults to `.coverage-rules.yml`. */
|
|
9
|
+
rulesFile?: string;
|
|
10
|
+
instrumentedScope: InstrumentedGlobs;
|
|
11
|
+
/** Tracked repository paths. Defaults to `git ls-files -z` in `cwd`. */
|
|
12
|
+
listFiles?: (cwd: string) => readonly string[];
|
|
13
|
+
}
|
|
14
|
+
export declare function listTrackedFiles(cwd: string): string[];
|
|
15
|
+
/** Returns tracked paths a positive-threshold rule requires but the collector would not instrument. */
|
|
16
|
+
export declare function checkCoverageScope(options: CheckCoverageScopeOptions): string[];
|