@vaultcompass/conductor 0.2.3 → 0.3.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.
@@ -19,7 +19,95 @@ import { spawnSync } from 'node:child_process';
19
19
  import { NormalizeError } from './envelope.js';
20
20
  import { normalizeDepGuard, normalizeFailedGate, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
21
21
  import { renderOptionFlags } from './policy.js';
22
+ import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
22
23
  import { ResolveError, candidateNames, resolveGateBinary } from './resolve.js';
24
+ /**
25
+ * The first version of each gate that understands `--trust-base`.
26
+ *
27
+ * A TABLE rather than a boolean, because the three gates get pull-request
28
+ * mode in three separate releases and the umbrella has to keep working
29
+ * against every combination in the meantime. A product missing from this
30
+ * table has no pull-request mode yet and is never handed the flag; a product
31
+ * in it is handed the flag only when the installed build says it is at least
32
+ * this version. Both directions matter: handing an older build a flag it does
33
+ * not parse makes it exit non-zero with no JSON, which the umbrella correctly
34
+ * reports as could-not-run, so a wrong guess here turns a working repository's
35
+ * pull requests red rather than merely leaving a gate un-hardened.
36
+ *
37
+ * The umbrella is deliberately NOT the place a version pin lives otherwise
38
+ * (nothing here imports any gate's package), and this is the one exception:
39
+ * it is a statement about a command-line flag, which is the only interface
40
+ * this package has to those tools.
41
+ */
42
+ export const TRUST_BASE_MIN_VERSION = {
43
+ 'intent-guard': '1.4.0',
44
+ 'vault-guard': '1.7.0',
45
+ 'dep-guard': '0.6.0',
46
+ // All three products are in. The table stays a table rather than becoming
47
+ // a boolean: a fourth role can arrive without one, and the "no
48
+ // pull-request mode yet" branch below is what keeps that gate from being
49
+ // handed a flag it would reject.
50
+ };
51
+ /**
52
+ * Whether this gate can be handed `--trust-base`, and why not when it cannot.
53
+ *
54
+ * Exported so the decision can be tested directly rather than only through a
55
+ * spawned child, and so there is exactly one copy of it.
56
+ *
57
+ * THE PROJECT DIRECTORY IS THE FIRST TEST, not the version. The flag names a
58
+ * git ref, and intent-guard resolves it against its own `--project`. On a
59
+ * run with an imported contract that directory is a temporary one the
60
+ * umbrella made, holding a contract and nothing else, with no repository in
61
+ * it: the child would exit 2 on a ref it could not resolve, and the gate that
62
+ * was working a moment ago would report could-not-run. So the flag goes only
63
+ * where `--project` is the repository itself.
64
+ */
65
+ export function decideTrustBase(gate, intent, trustBase, productVersion) {
66
+ if (trustBase === undefined) {
67
+ return undefined;
68
+ }
69
+ const withheld = (reason) => ({
70
+ ref: trustBase,
71
+ withheld: reason,
72
+ refused: null,
73
+ proposals: [],
74
+ });
75
+ const refused = (reason) => ({
76
+ ref: trustBase,
77
+ withheld: null,
78
+ refused: reason,
79
+ proposals: [],
80
+ });
81
+ if (intent !== undefined && intent.contractSource.kind !== 'native') {
82
+ return withheld('the intent gate is running against a contract imported for this run, which lives in a ' +
83
+ 'temporary directory with no repository in it, so there is no ref there to read control ' +
84
+ 'inputs from. The contract it is judging against came from a spec in the head tree.');
85
+ }
86
+ const minimum = TRUST_BASE_MIN_VERSION[gate.product];
87
+ if (minimum === undefined) {
88
+ return withheld(`${gate.product} has no pull-request mode yet, so it read its own configuration from the ` +
89
+ 'tree being judged.');
90
+ }
91
+ // An UNREADABLE version is refused, not withheld, and only for a product in
92
+ // the table. The old code folded the two together and interpolated the
93
+ // missing version straight into the sentence, which read "intent-guard
94
+ // reported no version does not understand --trust-base": not a sentence,
95
+ // and it named a version that does not exist. Worse than the wording, it
96
+ // said the gate had been left outside the boundary on purpose when what had
97
+ // actually happened is that the umbrella could not tell.
98
+ if (productVersion === null) {
99
+ return refused(`${gate.product} is expected to run in pull-request mode from ${minimum} onwards, and its ` +
100
+ 'version could not be read, so the umbrella cannot establish that this gate would take ' +
101
+ 'its rules from the base ref. Nothing was checked by it. Running it anyway would put it ' +
102
+ 'quietly outside the trust boundary on exactly the runs where something is already wrong.');
103
+ }
104
+ if (!atLeastVersion(productVersion, minimum)) {
105
+ return withheld(`${gate.product} ${productVersion} does not understand --trust-base, which arrived in ` +
106
+ `${minimum}, so it read its own control inputs from the tree being judged. Upgrade it to ` +
107
+ 'put this gate into pull-request mode.');
108
+ }
109
+ return { ref: trustBase, withheld: null, refused: null, proposals: [] };
110
+ }
23
111
  /**
24
112
  * A gate that never got as far as being spawned.
25
113
  *
@@ -69,19 +157,41 @@ const EMPTY_RUN = {
69
157
  * decided by that gate's own argument parser rather than by anything the
70
158
  * user could read in their own policy file.
71
159
  */
72
- export function gateArgs(gate, staged, intent) {
160
+ export function gateArgs(gate, staged, intent,
161
+ /**
162
+ * The trust base to hand THIS gate, or undefined. Already decided by
163
+ * `decideTrustBase`; nothing here re-decides it, so a gate that cannot take
164
+ * the flag is never handed one by a second opinion written in this switch.
165
+ */
166
+ trustBase) {
73
167
  const passthrough = renderOptionFlags(gate.options);
168
+ const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
74
169
  switch (gate.product) {
75
170
  case 'dep-guard':
76
- return [...(staged ? ['--staged'] : []), '--format', 'json', ...passthrough];
171
+ // `scan` takes --trust-base from 0.6.0. It sits beside whatever the
172
+ // umbrella already passes rather than replacing it: --trust-base says
173
+ // where the RULES come from and the mode flags say what is scanned,
174
+ // and a pull-request run passes both.
175
+ return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...passthrough];
77
176
  case 'vault-guard':
78
177
  // No path argument: the CLI defaults it to "." and the umbrella runs
79
178
  // with cwd at the repository root anyway. Passing one would also risk
80
179
  // a passthrough value being read as the positional.
81
- return [...(staged ? ['--staged'] : []), '-f', 'json', ...passthrough];
180
+ //
181
+ // `scan` takes --trust-base from 1.7.0, and on exit 2 it prints one
182
+ // line on stderr and NO document at all, which the could-not-run path
183
+ // above already handles before JSON.parse is reached.
184
+ return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
82
185
  case 'intent-guard': {
83
186
  if (intent === undefined) {
84
- return ['--project', '.', ...(staged ? ['--staged'] : []), '--json', ...passthrough];
187
+ return [
188
+ '--project',
189
+ '.',
190
+ ...(staged ? ['--staged'] : []),
191
+ ...trust,
192
+ '--json',
193
+ ...passthrough,
194
+ ];
85
195
  }
86
196
  // A prepared run replaces --staged entirely rather than adding to it.
87
197
  // The two path sources are ADDITIVE in intent-guard, so leaving
@@ -99,6 +209,10 @@ export function gateArgs(gate, staged, intent) {
99
209
  ? ['--staged']
100
210
  : []
101
211
  : ['--paths', intent.paths.join(',')]),
212
+ // Beside --paths on purpose, and they are independent: --trust-base
213
+ // says where the RULES come from, --paths says which paths are
214
+ // judged. A pull-request run passes both.
215
+ ...trust,
102
216
  '--json',
103
217
  ...passthrough,
104
218
  ];
@@ -178,14 +292,25 @@ export function runGate(gate, options) {
178
292
  // Carried on every return path below, including the failures: which
179
293
  // contract a gate WOULD have used is exactly as interesting when it could
180
294
  // not run as when it could.
181
- ...(options.intent === undefined
182
- ? {}
183
- : {
295
+ ...(options.intent !== undefined
296
+ ? {
184
297
  intent: {
185
298
  contractSource: options.intent.contractSource,
186
299
  baseRef: options.intent.baseRef,
187
300
  },
188
- }),
301
+ }
302
+ : options.intentContract === undefined
303
+ ? {}
304
+ : {
305
+ // No preparation, but the repository has a frozen contract and
306
+ // the child will read it from `--project .`. Same shape, and the
307
+ // base is null because nothing was diffed: this run is the index
308
+ // or the working tree, not a branch against a ref.
309
+ intent: {
310
+ contractSource: { kind: 'native', path: options.intentContract },
311
+ baseRef: null,
312
+ },
313
+ }),
189
314
  };
190
315
  const started = Date.now();
191
316
  try {
@@ -257,8 +382,71 @@ function runGateInner(gate, options, started, progress) {
257
382
  diagnostics: [],
258
383
  };
259
384
  }
385
+ // BEFORE the version probe, and that ordering is the whole of it: the probe
386
+ // RUNS the program, so asking a head-controlled binary for its version is
387
+ // already executing it. A planted stub answering "1.7.0" is the cheapest
388
+ // version of this attack and it would have been run before anything checked
389
+ // where it came from.
390
+ if (options.trustBase !== undefined) {
391
+ const refusal = refuseHeadControlledProgram(options.repoRoot, options.trustBase, binary.program);
392
+ if (refusal !== null) {
393
+ return {
394
+ ...base,
395
+ binary,
396
+ durationMs: Date.now() - started,
397
+ // ENFORCED, whatever the policy says. enforce: false is a standing
398
+ // decision about what a gate's FINDINGS are worth, and this gate
399
+ // produced none: the umbrella refused to run a program the pull
400
+ // request chose. Letting an unenforced gate swallow that would let a
401
+ // pull request pick its own judge and keep the run green.
402
+ enforce: true,
403
+ trustBase: { ref: options.trustBase, withheld: null, refused: refusal, proposals: [] },
404
+ couldNotRun: { reason: 'gate-program-refused', detail: refusal },
405
+ findings: [normalizeFailedGate(gate.role, gate.product, refusal)],
406
+ run: EMPTY_RUN,
407
+ diagnostics: [],
408
+ };
409
+ }
410
+ }
260
411
  const version = probeVersion(binary, options.repoRoot, timeoutMs);
261
- const argv = [...binary.argvPrefix, ...gateArgs(gate, options.staged, options.intent)];
412
+ // AFTER the version probe and BEFORE the command line is built, because the
413
+ // decision reads the version. That ordering is the whole capability gate:
414
+ // an intent-guard older than 1.4.0 must not be handed a flag it would
415
+ // reject, and a gate IN the table whose version could not be read is
416
+ // refused rather than run outside the boundary.
417
+ const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
418
+ if (trustBase !== undefined && trustBase.refused !== null) {
419
+ return {
420
+ ...base,
421
+ productVersion: version,
422
+ binary,
423
+ durationMs: Date.now() - started,
424
+ // ENFORCED, whatever the policy says, for the same reason a refused
425
+ // program is: the gate produced no findings for `enforce: false` to be
426
+ // a decision about, and this is the umbrella saying it could not
427
+ // establish that the gate was inside the boundary.
428
+ //
429
+ // Reachable now only as a PACKAGING problem, not as an attack: the
430
+ // program check above runs first, and with its directory-subtree rule a
431
+ // pull request can no longer put a program here whose version probe it
432
+ // controls. Before that rule it could, through the wrapper shape: a
433
+ // head-replaced inner script exiting 3 on --version landed exactly
434
+ // here, with enforce false and exit 0. A packaging quirk that
435
+ // fails a build loudly is the better failure: the alternative is a
436
+ // boundary that quietly downgrades itself on the runs where something
437
+ // is already wrong, which is the shape of every bug in this file.
438
+ enforce: true,
439
+ trustBase,
440
+ couldNotRun: { reason: 'trust-base-unverified', detail: trustBase.refused },
441
+ findings: [normalizeFailedGate(gate.role, gate.product, trustBase.refused)],
442
+ run: EMPTY_RUN,
443
+ diagnostics: [],
444
+ };
445
+ }
446
+ const argv = [
447
+ ...binary.argvPrefix,
448
+ ...gateArgs(gate, options.staged, options.intent, trustBase === undefined || trustBase.withheld !== null ? undefined : trustBase.ref),
449
+ ];
262
450
  const child = spawnSync(binary.command, argv, {
263
451
  cwd: options.repoRoot,
264
452
  encoding: 'utf8',
@@ -272,6 +460,12 @@ function runGateInner(gate, options, started, progress) {
272
460
  binary,
273
461
  durationMs: Date.now() - started,
274
462
  stderr: child.stderr ?? '',
463
+ // Carried on every return path below, the failures included: WHETHER
464
+ // this gate was in pull-request mode is exactly as interesting when it
465
+ // could not run as when it could, and the withheld reason is the only
466
+ // place a report can say a gate read its own rules out of the tree under
467
+ // judgment.
468
+ ...(trustBase === undefined ? {} : { trustBase }),
275
469
  };
276
470
  // Keep the backstop's view current, so an unexpected throw below still
277
471
  // reports which binary ran and what it printed.
@@ -339,6 +533,14 @@ function runGateInner(gate, options, started, progress) {
339
533
  findings: normalized.findings,
340
534
  run: normalized.run,
341
535
  diagnostics: normalized.diagnostics,
536
+ // The gate's own answer about the control inputs, folded onto the
537
+ // decision the umbrella made before spawning it. A gate that was NOT
538
+ // put into pull-request mode reports no proposals, and its trustBase
539
+ // keeps the withheld reason rather than being overwritten with an
540
+ // empty list that would read as "nothing was proposed".
541
+ ...(trustBase === undefined || normalized.trustBase === undefined
542
+ ? {}
543
+ : { trustBase: { ...trustBase, proposals: normalized.trustBase.proposals } }),
342
544
  };
343
545
  }
344
546
  catch (err) {
package/dist/init.d.ts CHANGED
@@ -40,7 +40,14 @@ export type ConflictReason = 'not-a-git-repository' | 'foreign-hook' | 'gate-hoo
40
40
  * remedy is different -- there is no config file of the manager's own to
41
41
  * point at, only a key in package.json that conductor will not write.
42
42
  */
43
- | 'managed-hooks' | 'hooks-path-outside-repository' | 'no-manifest' | 'manifest-unreadable' | 'changed-since-init' | 'write-failed';
43
+ | 'managed-hooks' | 'hooks-path-outside-repository'
44
+ /**
45
+ * A path recorded in the manifest resolves outside the repository. The
46
+ * manifest is a committed, untrusted file, so revert and apply refuse any
47
+ * path in it that is not contained rather than writing or deleting where it
48
+ * points.
49
+ */
50
+ | 'manifest-path-outside-repository' | 'no-manifest' | 'manifest-unreadable' | 'changed-since-init' | 'write-failed';
44
51
  export interface InitConflict {
45
52
  path: string;
46
53
  reason: ConflictReason;
@@ -121,6 +128,13 @@ export interface RevertResult {
121
128
  ok: boolean;
122
129
  actions: InitAction[];
123
130
  conflicts: InitConflict[];
131
+ /**
132
+ * A dry run planned the revert and touched nothing. The actions describe
133
+ * what it WOULD have removed or restored, and `ok` is what the same revert
134
+ * would have returned for real, so `--revert --dry-run` exits the way the
135
+ * revert it previews would.
136
+ */
137
+ dryRun: boolean;
124
138
  }
125
139
  /**
126
140
  * Removes exactly what init wrote, and nothing else.
package/dist/init.js CHANGED
@@ -65,7 +65,7 @@
65
65
  // as installed. See detectManagedHook and declaredManagedHooks.
66
66
  import { createHash } from 'node:crypto';
67
67
  import { execFileSync } from 'node:child_process';
68
- import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, rmdirSync, statSync, writeFileSync, } from 'node:fs';
68
+ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, rmdirSync, statSync, writeFileSync, } from 'node:fs';
69
69
  import path from 'node:path';
70
70
  import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
71
71
  import { CANDIDATES } from './resolve.js';
@@ -436,6 +436,93 @@ exit "$conductor_status"
436
436
  function sha256(content) {
437
437
  return createHash('sha256').update(content).digest('hex');
438
438
  }
439
+ /**
440
+ * Whether a path the manifest names is contained to the repository.
441
+ *
442
+ * The manifest is committed input, so a path in it is whatever a commit put
443
+ * there. Revert and apply run this over every path they would write to or
444
+ * delete before touching anything, and refuse the whole operation if any one
445
+ * of them is not contained.
446
+ *
447
+ * Two conditions, because a path can escape two ways. The resolved path,
448
+ * treated as plain strings, must be inside the root: this refuses an absolute
449
+ * path and one that climbs out with ../. And no component of the path may be a
450
+ * SYMLINK. A committed dangling symlink (its target does not exist) is the case
451
+ * that broke an earlier version of this: existsSync FOLLOWS the link, finds the
452
+ * missing target, and reports the link absent, so a walk that resolved only the
453
+ * deepest existing ancestor judged the link a plain not-yet-existing leaf and
454
+ * let writeFileSync and chmodSync, which DO follow the final link, land the
455
+ * write on the outside target. lstatSync does not follow, so it catches a
456
+ * symlink component even when its target is gone. init never writes through a
457
+ * symlink, so a symlink anywhere along the path means this is not a path init
458
+ * wrote, and it is refused whatever it points at.
459
+ *
460
+ * Paths here need not exist yet: an adopted hook is restored to a path revert
461
+ * has just removed, and a recorded file may be legitimately gone. The scan
462
+ * stops at the first component that does not exist, because nothing below a
463
+ * missing component exists either, so there is no symlink left to find. A
464
+ * relative candidate is taken against the repository root, which is how the
465
+ * real attack lands: a person running revert has cd'd into the checkout.
466
+ */
467
+ function manifestPathInsideRepo(repoRoot, candidate) {
468
+ try {
469
+ const root = realpathSync(repoRoot);
470
+ const abs = path.resolve(root, candidate);
471
+ // Deepest ancestor of abs that exists on disk. realpathSync on the whole
472
+ // path throws when the leaf is not there, so resolve the part that exists
473
+ // and keep the rest as a tail. existsSync FOLLOWS symlinks, which is why a
474
+ // dangling symlink is not trusted here; the tail is scanned with lstatSync
475
+ // below.
476
+ let ancestor = abs;
477
+ while (!existsSync(ancestor)) {
478
+ const parent = path.dirname(ancestor);
479
+ if (parent === ancestor) {
480
+ break;
481
+ }
482
+ ancestor = parent;
483
+ }
484
+ const realAncestor = realpathSync(ancestor);
485
+ const tail = path.relative(ancestor, abs);
486
+ // Containment, on resolved paths so a macOS temp dir reached through
487
+ // /var -> /private/var does not read as an escape, and so an existing
488
+ // symlink directory that points outside is caught by its resolved target.
489
+ const resolved = tail === '' ? realAncestor : path.join(realAncestor, tail);
490
+ const inside = path.relative(root, resolved);
491
+ if (inside === '' ||
492
+ inside === '..' ||
493
+ inside.startsWith(`..${path.sep}`) ||
494
+ path.isAbsolute(inside)) {
495
+ return false;
496
+ }
497
+ // No component of the tail may be a symlink. lstatSync does not follow, so
498
+ // a committed DANGLING symlink is caught even though existsSync reported it
499
+ // absent: existsSync followed the link to its missing target, which let an
500
+ // earlier version treat the link as a plain not-yet-existing leaf and then
501
+ // let writeFileSync and chmodSync, which DO follow the final link, land the
502
+ // write on the outside target. init never writes through a symlink, so any
503
+ // symlink component means this is not a path init wrote. The scan starts at
504
+ // the resolved ancestor, whose own components are already real, and walks
505
+ // to the leaf, stopping at the first component that does not exist.
506
+ let current = realAncestor;
507
+ for (const segment of tail === '' ? [] : tail.split(path.sep)) {
508
+ current = path.join(current, segment);
509
+ let entry;
510
+ try {
511
+ entry = lstatSync(current);
512
+ }
513
+ catch {
514
+ break;
515
+ }
516
+ if (entry.isSymbolicLink()) {
517
+ return false;
518
+ }
519
+ }
520
+ return true;
521
+ }
522
+ catch {
523
+ return false;
524
+ }
525
+ }
439
526
  function gitOutput(cwd, args) {
440
527
  try {
441
528
  return execFileSync('git', args, {
@@ -942,6 +1029,30 @@ export function applyInit(plan, options) {
942
1029
  product: plan.adoptedFrom.product,
943
1030
  },
944
1031
  };
1032
+ // Contain every path before writing, the same rule revert applies. These
1033
+ // paths are computed by planning rather than read straight from the manifest,
1034
+ // but the adopted record is carried forward from the committed manifest, and
1035
+ // a write that lands outside the repository is a write apply should refuse
1036
+ // whatever produced the path.
1037
+ const escaping = [
1038
+ ...plan.writes.map((write) => write.path),
1039
+ ...(manifest.adopted === null ? [] : [manifest.adopted.path]),
1040
+ ].filter((candidate) => !manifestPathInsideRepo(plan.repoRoot, candidate));
1041
+ if (escaping.length > 0) {
1042
+ return {
1043
+ ...plan,
1044
+ ok: false,
1045
+ conflicts: [
1046
+ ...plan.conflicts,
1047
+ ...escaping.map((candidate) => ({
1048
+ path: candidate,
1049
+ reason: 'manifest-path-outside-repository',
1050
+ guidance: `${candidate} resolves outside this repository, so nothing was written. Apply ` +
1051
+ 'contains every path it writes to the repository.',
1052
+ })),
1053
+ ],
1054
+ };
1055
+ }
945
1056
  try {
946
1057
  for (const write of plan.writes) {
947
1058
  mkdirSync(path.dirname(write.path), { recursive: true });
@@ -1028,6 +1139,12 @@ export function revertInit(options) {
1028
1139
  const actions = [];
1029
1140
  const conflicts = [];
1030
1141
  const force = Boolean(options.force);
1142
+ // A dry run runs every read and every decision and skips only the writes,
1143
+ // so what it reports is exactly what a real revert from the same state would
1144
+ // do. The CLI routed --revert past --dry-run and revertInit had no branch
1145
+ // for it, so the flag whose help promised it would write nothing performed a
1146
+ // real destructive revert.
1147
+ const dryRun = Boolean(options.dryRun);
1031
1148
  const root = repoRootOf(options.cwd);
1032
1149
  if (root === null) {
1033
1150
  conflicts.push({
@@ -1035,7 +1152,7 @@ export function revertInit(options) {
1035
1152
  reason: 'not-a-git-repository',
1036
1153
  guidance: 'Nothing to revert: this is not a git repository.',
1037
1154
  });
1038
- return { ok: false, actions, conflicts };
1155
+ return { ok: false, actions, conflicts, dryRun };
1039
1156
  }
1040
1157
  const manifestPath = path.join(root, MANIFEST_RELATIVE_PATH);
1041
1158
  const raw = readIfExists(manifestPath);
@@ -1046,7 +1163,7 @@ export function revertInit(options) {
1046
1163
  guidance: `No ${MANIFEST_RELATIVE_PATH}, so there is no record of what init wrote. Nothing was ` +
1047
1164
  "removed: guessing which files were ours is how a revert deletes somebody's work.",
1048
1165
  });
1049
- return { ok: false, actions, conflicts };
1166
+ return { ok: false, actions, conflicts, dryRun };
1050
1167
  }
1051
1168
  // Not routed through readManifest, which answers null for both a missing
1052
1169
  // file and an unparseable one. Revert has to tell those apart: a missing
@@ -1068,9 +1185,32 @@ export function revertInit(options) {
1068
1185
  'anything. Only then delete it and remove the hook and the policy file yourself, and ' +
1069
1186
  're-run init.',
1070
1187
  });
1071
- return { ok: false, actions, conflicts };
1188
+ return { ok: false, actions, conflicts, dryRun };
1072
1189
  }
1073
1190
  const relative = (file) => path.relative(root, file).split(path.sep).join('/');
1191
+ // The manifest is committed input, so every path it names is contained to
1192
+ // the repository before anything is written or deleted. A crafted manifest
1193
+ // could otherwise make revert delete a file anywhere on disk, or, through
1194
+ // adopted.path, write an executable one anywhere, and exit 0. Refused as a
1195
+ // whole rather than skipped one path at a time: a manifest with a path that
1196
+ // escapes is a manifest nothing should act on.
1197
+ const escaping = [
1198
+ ...manifest.files.map((file) => file.path),
1199
+ ...(manifest.adopted === null ? [] : [manifest.adopted.path]),
1200
+ ].filter((candidate) => !manifestPathInsideRepo(root, candidate));
1201
+ if (escaping.length > 0) {
1202
+ for (const candidate of escaping) {
1203
+ conflicts.push({
1204
+ path: relative(candidate),
1205
+ reason: 'manifest-path-outside-repository',
1206
+ guidance: `${candidate} is recorded in ${MANIFEST_RELATIVE_PATH} but resolves outside this ` +
1207
+ 'repository, so nothing was written or removed. The manifest is a committed file, and ' +
1208
+ 'a path in it that points out of the repository is not one revert will act on. Repair ' +
1209
+ 'or delete the manifest by hand.',
1210
+ });
1211
+ }
1212
+ return { ok: false, actions, conflicts, dryRun };
1213
+ }
1074
1214
  const planned = manifest.files.map((file) => {
1075
1215
  const current = readIfExists(file.path);
1076
1216
  const state = current === undefined ? 'gone' : sha256(current) === file.sha256 ? 'match' : 'changed';
@@ -1094,7 +1234,7 @@ export function revertInit(options) {
1094
1234
  detail: entry.state === 'changed' ? 'changed since init, left alone' : 'left alone',
1095
1235
  });
1096
1236
  }
1097
- return { ok: false, actions, conflicts };
1237
+ return { ok: false, actions, conflicts, dryRun };
1098
1238
  }
1099
1239
  const remaining = [];
1100
1240
  for (const { file, state } of planned) {
@@ -1113,7 +1253,9 @@ export function revertInit(options) {
1113
1253
  remaining.push(file);
1114
1254
  continue;
1115
1255
  }
1116
- rmSync(file.path, { force: true });
1256
+ if (!dryRun) {
1257
+ rmSync(file.path, { force: true });
1258
+ }
1117
1259
  actions.push({
1118
1260
  kind: 'remove',
1119
1261
  path: rel,
@@ -1134,12 +1276,24 @@ export function revertInit(options) {
1134
1276
  // the flag and restore a hook next to a surviving one. existsSync says what
1135
1277
  // is there, which is the thing the rule is about.
1136
1278
  const recordedHooks = planned.filter((entry) => entry.file.kind === 'hook');
1137
- const umbrellaHookGone = recordedHooks.length > 0 && recordedHooks.every((entry) => !existsSync(entry.file.path));
1279
+ const umbrellaHookGone = recordedHooks.length > 0 &&
1280
+ recordedHooks.every((entry) =>
1281
+ // A dry run left the hook on disk, so existsSync would say it is still
1282
+ // there and the restore would be mispredicted. Ask the plan instead:
1283
+ // every recorded hook that reached this point is either already gone or
1284
+ // slated for removal, because a changed hook with no --force returns at
1285
+ // the blocked-hook check far above, so by here a 'changed' state means
1286
+ // --force is on.
1287
+ dryRun
1288
+ ? entry.state === 'gone' || entry.state === 'match' || force
1289
+ : !existsSync(entry.file.path));
1138
1290
  let adopted = manifest.adopted;
1139
1291
  if (adopted !== null && umbrellaHookGone) {
1140
- mkdirSync(path.dirname(adopted.path), { recursive: true });
1141
- writeFileSync(adopted.path, adopted.content, 'utf8');
1142
- chmodSync(adopted.path, 0o755);
1292
+ if (!dryRun) {
1293
+ mkdirSync(path.dirname(adopted.path), { recursive: true });
1294
+ writeFileSync(adopted.path, adopted.content, 'utf8');
1295
+ chmodSync(adopted.path, 0o755);
1296
+ }
1143
1297
  actions.push({
1144
1298
  kind: 'restore',
1145
1299
  path: relative(adopted.path),
@@ -1148,39 +1302,57 @@ export function revertInit(options) {
1148
1302
  adopted = null;
1149
1303
  }
1150
1304
  if (remaining.length === 0 && adopted === null) {
1151
- rmSync(manifestPath, { force: true });
1305
+ if (!dryRun) {
1306
+ rmSync(manifestPath, { force: true });
1307
+ }
1152
1308
  actions.push({ kind: 'remove', path: MANIFEST_RELATIVE_PATH, detail: 'removed' });
1153
1309
  const manifestDir = path.dirname(MANIFEST_RELATIVE_PATH);
1154
- try {
1155
- // rmdirSync, not rmSync: rmSync on a directory without recursive: true
1156
- // throws before it removes anything, so this swallowed its own error
1157
- // every time and left an empty .guardrails behind after a revert that
1158
- // said it had removed everything. rmdirSync removes an empty directory
1159
- // and refuses a non-empty one, which is exactly the rule wanted here.
1160
- rmdirSync(path.dirname(manifestPath));
1161
- actions.push({ kind: 'remove', path: manifestDir, detail: 'removed, it was empty' });
1310
+ const dirWouldBeEmpty = () => readdirSync(path.dirname(manifestPath)).every((entry) => path.join(path.dirname(manifestPath), entry) === manifestPath);
1311
+ if (dryRun) {
1312
+ // A dry run cannot rmdir to find out whether the directory would be
1313
+ // empty, so it looks: with the manifest gone, is anything else left?
1314
+ actions.push(dirWouldBeEmpty()
1315
+ ? { kind: 'remove', path: manifestDir, detail: 'removed, it was empty' }
1316
+ : {
1317
+ kind: 'skip',
1318
+ path: manifestDir,
1319
+ detail: 'kept: it holds something else, which is not ours to remove',
1320
+ });
1162
1321
  }
1163
- catch {
1164
- // The directory holds something else, so it stays. Reported rather
1165
- // than passed over: a directory this tool created and then left
1166
- // behind, with nothing said about it, reads as something revert
1167
- // forgot rather than as something it decided.
1168
- actions.push({
1169
- kind: 'skip',
1170
- path: manifestDir,
1171
- detail: 'kept: it holds something else, which is not ours to remove',
1172
- });
1322
+ else {
1323
+ try {
1324
+ // rmdirSync, not rmSync: rmSync on a directory without recursive: true
1325
+ // throws before it removes anything, so this swallowed its own error
1326
+ // every time and left an empty .guardrails behind after a revert that
1327
+ // said it had removed everything. rmdirSync removes an empty directory
1328
+ // and refuses a non-empty one, which is exactly the rule wanted here.
1329
+ rmdirSync(path.dirname(manifestPath));
1330
+ actions.push({ kind: 'remove', path: manifestDir, detail: 'removed, it was empty' });
1331
+ }
1332
+ catch {
1333
+ // The directory holds something else, so it stays. Reported rather
1334
+ // than passed over: a directory this tool created and then left
1335
+ // behind, with nothing said about it, reads as something revert
1336
+ // forgot rather than as something it decided.
1337
+ actions.push({
1338
+ kind: 'skip',
1339
+ path: manifestDir,
1340
+ detail: 'kept: it holds something else, which is not ours to remove',
1341
+ });
1342
+ }
1173
1343
  }
1174
- return { ok: true, actions, conflicts };
1344
+ return { ok: true, actions, conflicts, dryRun };
1175
1345
  }
1176
1346
  // Something is left, so the manifest stays and keeps describing it.
1177
- writeFileSync(manifestPath, `${JSON.stringify({ ...manifest, files: remaining, adopted }, null, 2)}\n`, 'utf8');
1347
+ if (!dryRun) {
1348
+ writeFileSync(manifestPath, `${JSON.stringify({ ...manifest, files: remaining, adopted }, null, 2)}\n`, 'utf8');
1349
+ }
1178
1350
  actions.push({
1179
1351
  kind: 'skip',
1180
1352
  path: MANIFEST_RELATIVE_PATH,
1181
1353
  detail: 'kept: it still records what was left behind',
1182
1354
  });
1183
- return { ok: false, actions, conflicts };
1355
+ return { ok: false, actions, conflicts, dryRun };
1184
1356
  }
1185
1357
  export function renderInitHuman(result) {
1186
1358
  const lines = [];
@@ -1214,8 +1386,18 @@ export function renderRevertHuman(result) {
1214
1386
  if (result.ok) {
1215
1387
  lines[0] = 'conductor init --revert:';
1216
1388
  }
1389
+ if (result.dryRun) {
1390
+ // Every action here is what a real revert WOULD do, so the header and the
1391
+ // verbs say so, and the summary above is rewritten: nothing was removed
1392
+ // because nothing is ever removed on a dry run.
1393
+ lines[0] =
1394
+ removed === 0
1395
+ ? 'conductor init --revert (dry run): would remove nothing.'
1396
+ : 'conductor init --revert (dry run): would change the files below, and write nothing now.';
1397
+ }
1217
1398
  for (const action of result.actions) {
1218
- lines.push(` ${action.kind} ${action.path} (${action.detail})`);
1399
+ const verb = result.dryRun && action.kind !== 'skip' ? `would ${action.kind}` : action.kind;
1400
+ lines.push(` ${verb} ${action.path} (${action.detail})`);
1219
1401
  }
1220
1402
  // The conflicts go LAST rather than first, so the thing the user has to
1221
1403
  // act on is the last line on their terminal rather than scrolled off the