@vaultcompass/conductor 0.11.0 → 0.13.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 CHANGED
@@ -92,7 +92,9 @@ required.
92
92
 
93
93
  **Globally, and that is the guidance for CI too.** A devDependency is
94
94
  fine beside it for your own pre-commit hook, and nothing about a local
95
- run changed. It is not what gates your pull requests: on a pull-request
95
+ run changed, but under the Action keep it at the Action's pin or a push
96
+ run is could-not-run (see "The Action" below). It is not what gates
97
+ your pull requests: on a pull-request
96
98
  run the umbrella never looks in `node_modules/.bin` at all, because what
97
99
  is installed there is chosen by the head's own manifest and lockfile. The
98
100
  Action installs all four packages itself, globally, at versions pinned in
@@ -166,7 +168,7 @@ required.
166
168
  A commit with a staged credential in it prints the full report and exits 1:
167
169
 
168
170
  ```
169
- conductor 0.11.0
171
+ conductor 0.13.0
170
172
  verdict-token: blocked (1)
171
173
  conductor run: 2 gate(s), 1 finding(s)
172
174
 
@@ -359,11 +361,17 @@ gates:
359
361
  secrets-history:
360
362
  product: gitleaks
361
363
  enabled: true
364
+ # Enabled because gitleaks was found on the machine that ran init. CI must
365
+ # install gitleaks itself (conductor does not); without it this gate
366
+ # reports conductor/gate-missing and the run exits 2.
362
367
  stage: ci
363
368
  enforce: true
364
369
  vulnerabilities:
365
370
  product: osv-scanner
366
371
  enabled: true
372
+ # Enabled because osv-scanner was found on the machine that ran init. CI must
373
+ # install osv-scanner itself (conductor does not); without it this gate
374
+ # reports conductor/gate-missing and the run exits 2.
367
375
  stage: ci
368
376
  enforce: true
369
377
  present-on-base: report
@@ -1093,6 +1101,29 @@ gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
1093
1101
  which arrived in git 2.31. Only that gate checks: an older git makes it
1094
1102
  could-not-run, naming the version, and the other gates run.
1095
1103
 
1104
+ ### Trying pull-request mode locally
1105
+
1106
+ To see roughly what CI would say about a branch, check it out and name the
1107
+ base as the trust base:
1108
+
1109
+ ```
1110
+ conductor run --trust-base refs/remotes/origin/main --verbose
1111
+ ```
1112
+
1113
+ `--trust-base` takes any ref git resolves in your clone, so use a clone with
1114
+ the base branch present (the CI recipes use `fetch-depth: 0` for the same
1115
+ reason). With no `GITHUB_BASE_REF` set, as on a laptop, the change set for the
1116
+ intent gate is measured from the trust base, so `--base` is optional; add
1117
+ `--base <ref>` to measure from a different ref. Add `--stage ci` to run at
1118
+ the stage the Action runs at.
1119
+
1120
+ The gotcha is the same locally as in CI: the policy and the other control
1121
+ files are read from the base ref, not from your working tree. A local edit to
1122
+ `.guardrails.yaml` has no effect on a `--trust-base` run until the change is
1123
+ on the base; it shows up as a proposal line in the report instead. To preview
1124
+ a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
1125
+ conductor" above.
1126
+
1096
1127
  ## Intent at a pull request
1097
1128
 
1098
1129
  The intent gate is the only one of the five with any ceremony: its native
@@ -1288,7 +1319,18 @@ runs `npm install -g --ignore-scripts` under the runner temp, never into the
1288
1319
  workspace, and prepends that bin directory to `PATH`, so the run step invokes
1289
1320
  `conductor` off `PATH` and each gate resolves by name the same way. The install
1290
1321
  is **unconditional**, on push and `pull_request` alike, so there is one code
1291
- path rather than one that matters and one that nobody exercises.
1322
+ path rather than one that matters and one that nobody exercises. On a push
1323
+ run, though, a repository's own devDependency on a gate in
1324
+ `node_modules/.bin` outranks that install and shadows the action's pin. Since
1325
+ 0.13.0, when a gate's version differs from the pin, wherever it was found
1326
+ (`node_modules/.bin`, `PATH` or a policy `command:`), conductor does not run
1327
+ it: the gate is could-not-run, reason `version-skew`, and the run exits 2,
1328
+ whatever the policy's `enforce` and whatever `advisory` say. It is named in
1329
+ the job log, as a `::error::` annotation, in the step summary and in the
1330
+ reports. A gate whose version cannot be read under the Action is
1331
+ could-not-run too, reason `version-unverified`. The fix is to bump the
1332
+ devDependency to the pin or remove it. A plain `conductor run` outside the
1333
+ Action sets no pin and is unchanged.
1292
1334
 
1293
1335
  **On a pull request those four inputs may not pin backward.** The shape check
1294
1336
  asks whether an input is an exact version; it says nothing about which one, and
@@ -1378,7 +1420,7 @@ request being judged, and the version-pin protection described above
1378
1420
  "protects nothing" against a tree that controls its own judge (the
1379
1421
  validate step's own comment in `action.yml` says so in those words). A tag
1380
1422
  moves when someone pushes it. Name this action by owner and the full commit
1381
- SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.11.0.
1423
+ SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.13.0.
1382
1424
 
1383
1425
  ```yaml
1384
1426
  name: guardrails
@@ -1400,7 +1442,7 @@ jobs:
1400
1442
  with:
1401
1443
  node-version: '22.11.0'
1402
1444
  - id: conductor
1403
- uses: vaultcompasshq/conductor@v0.11.0
1445
+ uses: vaultcompasshq/conductor@v0.13.0
1404
1446
  with:
1405
1447
  output: conductor.sarif
1406
1448
  - uses: github/codeql-action/upload-sarif@v3
@@ -1475,7 +1517,7 @@ jobs:
1475
1517
  # installs those itself, globally. Leave conductor-version unset so the
1476
1518
  # umbrella is the default in the pinned action.yml.
1477
1519
  - id: conductor
1478
- uses: vaultcompasshq/conductor@v0.11.0
1520
+ uses: vaultcompasshq/conductor@v0.13.0
1479
1521
  with:
1480
1522
  output: conductor.sarif
1481
1523
  # Exact versions, never a range and never "latest". These three
@@ -1486,9 +1528,9 @@ jobs:
1486
1528
  # request of their own. On a pull request the action refuses a pin
1487
1529
  # below what the pinned action.yml ships, and the three lines can
1488
1530
  # be left out entirely to take that action's own versions.
1489
- dep-guard-version: 0.14.0
1490
- vault-guard-version: 1.11.0
1491
- intent-guard-version: 1.10.0
1531
+ dep-guard-version: 0.15.0
1532
+ vault-guard-version: 1.12.1
1533
+ intent-guard-version: 1.10.1
1492
1534
  - uses: github/codeql-action/upload-sarif@v3
1493
1535
  # Always: the log is most worth having on the run that failed.
1494
1536
  if: always()
@@ -1681,7 +1723,7 @@ jobs:
1681
1723
  node-version: '22.11.0'
1682
1724
  - id: conductor
1683
1725
  timeout-minutes: 5
1684
- uses: vaultcompasshq/conductor@v0.11.0
1726
+ uses: vaultcompasshq/conductor@v0.13.0
1685
1727
  with:
1686
1728
  pr-comment: true
1687
1729
  advisory: true
@@ -1817,7 +1859,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1817
1859
  # the pull request runs before the action in this job: no install, build
1818
1860
  # or test step here; those belong in a separate job. ...
1819
1861
  - id: conductor
1820
- uses: vaultcompasshq/conductor@v0.11.0
1862
+ uses: vaultcompasshq/conductor@v0.13.0
1821
1863
  with:
1822
1864
  output: conductor.sarif
1823
1865
  pr-comment: true
@@ -1896,12 +1938,12 @@ per pull request.
1896
1938
 
1897
1939
  ```yaml
1898
1940
  - id: conductor-package-a
1899
- uses: vaultcompasshq/conductor@v0.11.0
1941
+ uses: vaultcompasshq/conductor@v0.13.0
1900
1942
  with:
1901
1943
  pr-comment: true
1902
1944
  pr-comment-marker: 'package-a'
1903
1945
  - id: conductor-package-b
1904
- uses: vaultcompasshq/conductor@v0.11.0
1946
+ uses: vaultcompasshq/conductor@v0.13.0
1905
1947
  with:
1906
1948
  pr-comment: true
1907
1949
  pr-comment-marker: 'package-b'
@@ -2001,6 +2043,64 @@ is one snapshot of one run: no per-finding state, nothing to dismiss, no
2001
2043
  history between runs, and a new comment every time rather than an alert that
2002
2044
  closes when the finding goes away.
2003
2045
 
2046
+ ## Upgrading
2047
+
2048
+ An adopter pins two numbers, and they control different things.
2049
+
2050
+ - **The action ref**, `uses: vaultcompasshq/conductor@<tag or SHA>`, picks
2051
+ which `action.yml` runs. That file carries the defaults for the four
2052
+ version inputs and the constants the pull-request backward-pin rule
2053
+ measures a pin against.
2054
+ - **The `conductor-version` input** picks which `@vaultcompass/conductor`
2055
+ the install step installs. The same step installs the three gates at
2056
+ `dep-guard-version`, `vault-guard-version` and `intent-guard-version`.
2057
+ Each input defaults to the version the tag shipped.
2058
+
2059
+ **The recommended shape is to leave all four version inputs unset** and move
2060
+ only the action ref. On a pull request, the validate step refuses an input
2061
+ naming a version below the one the tag ships, so an explicit old pin breaks
2062
+ the day you upgrade the ref (see "The Action" above). Outside a pull request
2063
+ an explicit pin is unaffected, which is how a stale pin can sit unnoticed
2064
+ until the first pull request after the upgrade.
2065
+
2066
+ **Pin the action ref to a full commit SHA** with the tag as a comment, for
2067
+ example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.13.0`. To
2068
+ find the SHA for a tag, run
2069
+ `gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
2070
+ the Releases page.
2071
+
2072
+ **Dependabot or Renovate bumping that SHA changes the action ref only.** It
2073
+ does not touch a `dep-guard-version`, `vault-guard-version`,
2074
+ `intent-guard-version` or `conductor-version` you set by hand, so such a pin
2075
+ must be raised or removed by hand in the same pull request, or that pull
2076
+ request is refused by the rule above.
2077
+
2078
+ **An action-only tag moves the tag while the npm package stays.** The
2079
+ CHANGELOG marks these as "An action-only release" and says which
2080
+ `conductor-version` default stays. `@vaultcompass/conductor` does not change
2081
+ on those, so `conductor-version` need not change either; the gate defaults
2082
+ may.
2083
+
2084
+ Defaults per tag, taken only from CHANGELOG.md entries that state them. A
2085
+ tag with no row here has an entry that does not state its defaults; read
2086
+ `action.yml` at that tag.
2087
+
2088
+ | Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
2089
+ | --- | --- | --- | --- |
2090
+ | v0.13.0 | package | 0.13.0 | none (gate defaults unchanged) |
2091
+ | v0.12.0 | package | 0.12.0 | vault-guard 1.12.1 (from 1.12.0), intent-guard 1.10.1 (from 1.10.0) |
2092
+ | v0.11.1 | action-only | 0.11.0 | dep-guard 0.15.0 (from 0.14.0), vault-guard 1.12.0 (from 1.11.0) |
2093
+ | v0.11.0 | package | 0.11.0 | dep-guard 0.14.0, intent-guard 1.10.0 |
2094
+ | v0.10.0 | package | 0.10.0 | dep-guard 0.13.0, vault-guard 1.11.0 |
2095
+ | v0.8.2 | action-only | 0.8.1 | dep-guard 0.11.1 (from 0.10.1) |
2096
+ | v0.8.1 | package | 0.8.1 | dep-guard 0.10.1, vault-guard 1.9.1, intent-guard 1.8.1 |
2097
+ | v0.8.0 | package | 0.8.0 | dep-guard 0.10.0, vault-guard 1.9.0, intent-guard 1.8.0 |
2098
+ | v0.7.0 | package | 0.7.0 | none |
2099
+ | v0.6.0 | package | 0.6.0 | dep-guard 0.9.0 (from 0.8.0), intent-guard 1.7.0 (from 1.6.0) |
2100
+ | v0.5.1 | action-only | 0.5.0 | dep-guard 0.8.0 (from 0.7.0), intent-guard 1.6.0 (from 1.5.2) |
2101
+ | v0.4.4 | action-only | 0.4.0 | dep-guard 0.7.0 (from 0.6.0), vault-guard 1.8.0 (from 1.7.0) |
2102
+ | v0.4.3 | action-only | 0.4.0 | intent-guard 1.5.2 (from 1.4.0) |
2103
+
2004
2104
  ## What is in and what is out
2005
2105
 
2006
2106
  In: the policy file and its schema, `init` with dry-run, revert, and adopt,
package/dist/cli.js CHANGED
@@ -6,7 +6,7 @@
6
6
  // parses arguments and prints. That split is what lets every one of those
7
7
  // decisions be tested without a subprocess.
8
8
  import { Command, CommanderError } from 'commander';
9
- import { closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
9
+ import { appendFileSync, closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
10
10
  import os from 'node:os';
11
11
  import path from 'node:path';
12
12
  import { fileURLToPath } from 'node:url';
@@ -14,7 +14,7 @@ import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
14
14
  import { absolutePathEntries, createGitShim, pinGitOutside, pinnedGitInside, realPathInside, removeGitShim, runGit, tempInsideTreeMessage, workTreeAbove, } from './git.js';
15
15
  import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
16
16
  import { renderSarif } from './output-sarif.js';
17
- import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewWarnings, } from './output-text.js';
17
+ import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewAnnotations, versionSkewSummaryLines, versionSkewWarnings, } from './output-text.js';
18
18
  import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
19
19
  import { refusedTrustBase, runAll } from './run.js';
20
20
  import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
@@ -708,6 +708,32 @@ export function buildProgram() {
708
708
  if (logLines.length > 0) {
709
709
  process.stderr.write(`${logLines.join('\n')}\n`);
710
710
  }
711
+ // IN GITHUB ACTIONS, A VERSION SKEW IS ALSO AN ANNOTATION AND A
712
+ // STEP-SUMMARY LINE, so a run on a stale gate is visible on the run's
713
+ // page without anybody opening the log (audit 2026-10-18: every guard
714
+ // repository's own push runs used a stale devDependency for weeks and
715
+ // only the log said which version ran). Since 0.13.0 that gate is
716
+ // could-not-run, decided in runGate; these lines only say so. The
717
+ // annotation goes to stdout when stdout is not the report (--output
718
+ // given, which is how the Action runs), and to stderr otherwise. A
719
+ // summary that cannot be written is skipped: it never changes the
720
+ // exit code.
721
+ if (process.env.GITHUB_ACTIONS === 'true') {
722
+ const annotations = versionSkewAnnotations(result);
723
+ if (annotations.length > 0) {
724
+ (options.output !== undefined ? process.stdout : process.stderr).write(`${annotations.join('\n')}\n`);
725
+ }
726
+ const summaryFile = process.env.GITHUB_STEP_SUMMARY;
727
+ const summaryLines = versionSkewSummaryLines(result);
728
+ if (summaryFile !== undefined && summaryFile !== '' && summaryLines.length > 0) {
729
+ try {
730
+ appendFileSync(summaryFile, summaryLines.map((line) => `${line}\n\n`).join(''));
731
+ }
732
+ catch {
733
+ // The annotation and the log line above already say it.
734
+ }
735
+ }
736
+ }
711
737
  process.exitCode = applyAdvisory(result.exitCode, advisory);
712
738
  }
713
739
  catch (err) {
@@ -21,7 +21,13 @@ export type Subject = {
21
21
  manifest: string;
22
22
  lockfile?: string;
23
23
  }
24
- /** `column` and `endColumn` are 1-based here even where the source is 0-based. */
24
+ /**
25
+ * `column` and `endColumn` are 1-based here even where the source is
26
+ * 0-based (SARIF 2.1.0 sets a minimum of 1 on both). The gitleaks
27
+ * normalizer enforces it: a column below 1 becomes 1, and an `endColumn`
28
+ * is kept only when it is at least `column` and on the same line.
29
+ * vault-guard's is its 0-based column plus one, with no `endColumn`.
30
+ */
25
31
  | {
26
32
  kind: 'location';
27
33
  file: string;
@@ -2,7 +2,7 @@ import type { Diagnostic, Finding, RunSummary } from './envelope.js';
2
2
  import type { ContractSource, IntentPreparation } from './intent-prepare.js';
3
3
  import type { GatePolicy, GateRole, GateStage, Product } from './policy.js';
4
4
  import { type BaseComparison } from './osv-baseline.js';
5
- import type { ResolvedBinary } from './resolve.js';
5
+ import type { ResolutionSource, ResolvedBinary } from './resolve.js';
6
6
  export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing' | 'spawn-failed' | 'gate-error' | 'unparseable-output'
7
7
  /**
8
8
  * The gate was never spawned because the run could not be set up for it:
@@ -58,7 +58,35 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
58
58
  * Raised for the version probe, the scan, and the intent gate's
59
59
  * preparation steps; `timedOut.step` says which spawn was stopped.
60
60
  */
61
- | 'timed-out';
61
+ | 'timed-out'
62
+ /**
63
+ * The vulnerabilities gate on a decided trust base: a handed lockfile read
64
+ * no packages at the head, or a base lockfile is gone from the head with
65
+ * no populated replacement in its directory, and the base copy had
66
+ * packages, so the dependency set the head removed cannot be judged.
67
+ * Fail closed by design
68
+ * (docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md).
69
+ */
70
+ | 'lockfile-emptied'
71
+ /**
72
+ * The run was told which version of this gate must judge it (the Action's
73
+ * pin, `RunGateOptions.expectedVersion`) and the resolved binary reports
74
+ * another one, from whichever location resolution took it. The gate's
75
+ * check was not run. Design:
76
+ * docs/superpowers/specs/2026-10-18-version-skew-could-not-run.md.
77
+ */
78
+ | 'version-skew'
79
+ /**
80
+ * The same expectation, and the resolved binary's version could not be
81
+ * read, so it is not known to be the expected one. Fail closed.
82
+ */
83
+ | 'version-unverified'
84
+ /**
85
+ * The same check could not clear the head: a base copy unreadable, a base
86
+ * run that failed or printed no count, a command-line mismatch, or a head
87
+ * run whose stderr carries no package count (a lowered verbosity).
88
+ */
89
+ | 'lockfile-emptied-unverified';
62
90
  /** Where a gate's time limit came from: the test hook, the policy, or the product default. */
63
91
  export type TimeLimitSource = 'override' | 'policy' | 'default';
64
92
  export interface TimeLimit {
@@ -66,7 +94,7 @@ export interface TimeLimit {
66
94
  source: TimeLimitSource;
67
95
  }
68
96
  /** Which of a gate's spawns was stopped at the limit. The intent gate's check is `scan`. */
69
- export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze';
97
+ export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze' | 'base-check';
70
98
  export interface TimedOut {
71
99
  step: TimedOutStep;
72
100
  limitSeconds: number;
@@ -105,6 +133,22 @@ export declare function breakWorkflowMarkers(text: string): string;
105
133
  * it, as opposed to something the gate itself said or did.
106
134
  */
107
135
  export declare const CONDUCTOR_OWN_REASONS: ReadonlySet<CouldNotRunReason>;
136
+ /**
137
+ * A probed version as it may be printed. The probe for the family gates
138
+ * accepts anything after x.y.z on the first line, and the text reaches a
139
+ * workflow command, the step summary and the reports, so only version
140
+ * characters are kept.
141
+ */
142
+ export declare function versionCharacters(raw: string): string;
143
+ /** Where a resolved binary came from, in words. Never a machine path. */
144
+ export declare function resolutionPlace(source: ResolutionSource): string;
145
+ /**
146
+ * The remedy for a gate that is not at the expected version, which depends
147
+ * on where the binary came from. THE ONE PLACE it is written: the
148
+ * could-not-run detail and every version-skew line in src/output-text.ts
149
+ * call this.
150
+ */
151
+ export declare function versionSkewRemedy(product: string, source: ResolutionSource, expected: string): string;
108
152
  /**
109
153
  * A gate's time limit, and where it came from. THE ONE PLACE the precedence
110
154
  * is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
@@ -308,15 +352,25 @@ export interface GateOutcome {
308
352
  */
309
353
  nodeModulesSkipped?: string;
310
354
  /**
311
- * Present only when this gate was resolved from PATH, the version it
312
- * reported differs from the one the run was told to expect (the Action's
313
- * pin, handed over as an environment variable), and both are known. A
314
- * statement for a warning, never an input to a decision: resolution,
315
- * trust-base handling and the exit code are all settled without it.
355
+ * Present only when the version this gate reported differs from the one
356
+ * the run was told to expect (the Action's pin, handed over as an
357
+ * environment variable), and both are known, WHEREVER the binary was
358
+ * resolved from. Since 0.13.0 it is present exactly on a `version-skew`
359
+ * could-not-run, and carries the facts the warning surfaces print; it is
360
+ * the outcome, not this record, that the exit code reads.
361
+ *
362
+ * Every location, not only PATH (audit 2026-10-18, the intent-guard
363
+ * audit's MB3). Outside a pull request a repository's own devDependency in
364
+ * node_modules/.bin outranks the Action's global install by design, and
365
+ * recording PATH alone left every guard repository's own push runs on
366
+ * stale gates with the pins set and nothing said. `path` is
367
+ * repository-relative when the binary is inside the repository (it
368
+ * reaches a published log through the reports), and absolute otherwise.
316
369
  */
317
370
  versionSkew?: {
318
371
  expected: string;
319
372
  found: string;
373
+ source: ResolutionSource;
320
374
  path: string;
321
375
  };
322
376
  /**
@@ -347,8 +401,10 @@ export interface GateOutcome {
347
401
  export interface RunGateOptions {
348
402
  /**
349
403
  * The version this run expects of the gate, when something says so (the
350
- * Action passes its pin). Compared with what the PATH binary reports, for a
351
- * warning only. Absent means no expectation, which is every local run.
404
+ * Action passes its pin). Compared with what the resolved binary reports,
405
+ * wherever it was found: another version is `version-skew` and an
406
+ * unreadable one `version-unverified`, both could-not-run (0.13.0). Absent
407
+ * means no expectation, which is every local run, and changes nothing.
352
408
  */
353
409
  expectedVersion?: string;
354
410
  repoRoot: string;