@vaultcompass/conductor 0.2.2 → 0.2.4

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/dist/init.js CHANGED
@@ -50,9 +50,22 @@
50
50
  // points init at the repository root, and the second fails exactly
51
51
  // after a `git clean -xdf` has removed the gitignored generated
52
52
  // directory, which is the state this whole property exists to survive.
53
+ //
54
+ // 6. A MANAGER WHOSE HOOK TEXT LIVES IN package.json IS REFUSED, AND THE
55
+ // DECLARATION IS THE SIGNAL. simple-git-hooks and yorkie generate
56
+ // .git/hooks/pre-commit from a key in package.json and rewrite it on
57
+ // every install, and neither has a tracked file to write instead. What
58
+ // makes them different from lefthook is that the declaration is there
59
+ // BEFORE the manager has ever run: a fresh clone has no generated hook
60
+ // to read, and that is exactly the state somebody runs init in. So the
61
+ // package.json key is checked as well as the file, and either one alone
62
+ // is enough. Found by running this tool against two of the eight public
63
+ // repositories in a dogfood run: both would have taken the umbrella hook
64
+ // and lost it at the next install, with the manifest still recording it
65
+ // as installed. See detectManagedHook and declaredManagedHooks.
53
66
  import { createHash } from 'node:crypto';
54
67
  import { execFileSync } from 'node:child_process';
55
- import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, rmdirSync, statSync, writeFileSync, } from 'node:fs';
68
+ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, rmdirSync, statSync, writeFileSync, } from 'node:fs';
56
69
  import path from 'node:path';
57
70
  import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
58
71
  import { CANDIDATES } from './resolve.js';
@@ -69,6 +82,21 @@ export const MANIFEST_RELATIVE_PATH = '.guardrails/manifest.json';
69
82
  */
70
83
  export const DEP_GUARD_HOOK_MARKER = 'dep-guard-managed-hook: v1';
71
84
  export const INTENT_GUARD_HOOK_MARKER = 'conductor-managed-pre-commit';
85
+ /**
86
+ * The standalone config files simple-git-hooks reads, exactly as its own
87
+ * README lists them. yorkie has no equivalent: its config is the
88
+ * `gitHooks` key and nothing else.
89
+ */
90
+ const SIMPLE_GIT_HOOKS_CONFIG_FILES = [
91
+ '.simple-git-hooks.cjs',
92
+ '.simple-git-hooks.js',
93
+ '.simple-git-hooks.mjs',
94
+ '.simple-git-hooks.json',
95
+ 'simple-git-hooks.cjs',
96
+ 'simple-git-hooks.js',
97
+ 'simple-git-hooks.mjs',
98
+ 'simple-git-hooks.json',
99
+ ];
72
100
  /**
73
101
  * The `.husky` directory whose generated subdirectory git has been pointed
74
102
  * at, or null when this is not that arrangement.
@@ -168,6 +196,146 @@ function generatedHookGuidance(manager, relPath) {
168
196
  `${owner}, ${stanza} in ${config}. Note that ${owner} owns the commit's exit code, so the ` +
169
197
  "umbrella's 1 (a gate blocked) and 2 (a gate could not run) do not survive it.");
170
198
  }
199
+ /**
200
+ * The manager that generated this hook, for the two whose hook text comes
201
+ * out of package.json. Checked against real installs, captured in
202
+ * tests/fixtures/hooks.
203
+ *
204
+ * simple-git-hooks is recognised by `SKIP_SIMPLE_GIT_HOOKS`, the opt-out
205
+ * variable its generated hook tests on its first line. Verified against
206
+ * 2.14.0 and 2.11.1.
207
+ *
208
+ * IT IS NOT IN EVERY VERSION, and that is the whole reason the package.json
209
+ * key below exists rather than being belt and braces. simple-git-hooks 2.8.0
210
+ * writes the shebang and the user's own command and nothing else: there is
211
+ * no string in that file belonging to simple-git-hooks, so no content rule
212
+ * can recognise it, at any price. A repository on that version is
213
+ * unrecognisable from its hook alone and would have had the umbrella hook
214
+ * written into a file the next install rewrites.
215
+ *
216
+ * yorkie is recognised by `yorkie/src/runner.js`, the script its generated
217
+ * hook invokes. Verified against 2.0.0, which writes it relative, and 1.0.2,
218
+ * which writes the same suffix under an absolute path, so the suffix is what
219
+ * both have in common. The `#yorkie ` version stamp on the second line is a
220
+ * second alternative and is present in both captures too; it is second
221
+ * because it is a comment, and a comment is the part of a generated file
222
+ * most likely to be reworded.
223
+ */
224
+ function detectManagedHook(content) {
225
+ if (content.includes('SKIP_SIMPLE_GIT_HOOKS')) {
226
+ return 'simple-git-hooks';
227
+ }
228
+ if (content.includes('yorkie/src/runner.js') || content.includes('#yorkie ')) {
229
+ return 'yorkie';
230
+ }
231
+ return null;
232
+ }
233
+ function declaredManagedHooks(root) {
234
+ // A standalone config file counts as a declaration on its own. Taken
235
+ // verbatim from simple-git-hooks' own README, which says the config may
236
+ // live in ".simple-git-hooks.cjs, .simple-git-hooks.js,
237
+ // .simple-git-hooks.mjs, .simple-git-hooks.json, or
238
+ // simple-git-hooks.{cjs,js,mjs,json}". It is an EXACT list rather than a
239
+ // prefix or extension test, so a simple-git-hooks.yaml or a
240
+ // simple-git-hooks.md is what it looks like -- somebody's notes -- and not
241
+ // a reason to refuse an install.
242
+ //
243
+ // This is the third signal and the only one that fires for the repository
244
+ // that has all the others against it: a standalone config plus an older
245
+ // simple-git-hooks, whose generated hook carries no marker at all.
246
+ // Checked BEFORE package.json, and the order is the same one
247
+ // simple-git-hooks resolves in: it reads package.json last, so whichever
248
+ // of these exists is the file that actually decides the hook.
249
+ const configFile = SIMPLE_GIT_HOOKS_CONFIG_FILES.find((file) => isFile(path.join(root, file)));
250
+ if (configFile !== undefined) {
251
+ return { manager: 'simple-git-hooks', detectedIn: { kind: 'config-file', file: configFile } };
252
+ }
253
+ const raw = readIfExists(path.join(root, 'package.json'));
254
+ if (raw === undefined) {
255
+ return null;
256
+ }
257
+ let parsed;
258
+ try {
259
+ parsed = JSON.parse(raw);
260
+ }
261
+ catch {
262
+ return null;
263
+ }
264
+ if (typeof parsed !== 'object' || parsed === null) {
265
+ return null;
266
+ }
267
+ const manifest = parsed;
268
+ if (isPlainObject(manifest['simple-git-hooks'])) {
269
+ return { manager: 'simple-git-hooks', detectedIn: { kind: 'package.json' } };
270
+ }
271
+ if (isPlainObject(manifest.gitHooks)) {
272
+ return { manager: 'yorkie', detectedIn: { kind: 'package.json' } };
273
+ }
274
+ return null;
275
+ }
276
+ function isPlainObject(value) {
277
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
278
+ }
279
+ /**
280
+ * What init says when it finds one of those two, and why it says nothing
281
+ * else.
282
+ *
283
+ * The honest answer here is a refusal, not an offer. These managers have no
284
+ * tracked hook file to redirect into and no config file of their own to name:
285
+ * the only place the umbrella's command could go is a key in package.json,
286
+ * and init does not write package.json. That is not squeamishness. Init
287
+ * writes a hook, a policy file and a manifest, and the manifest is what
288
+ * makes --revert honest; an edit merged into somebody's package.json has no
289
+ * revert story that is not a guess about which of their later edits were
290
+ * theirs. So the guidance says exactly what to add and leaves the adding to
291
+ * the person whose file it is.
292
+ *
293
+ * The exit-code sentence differs between the two, and both halves are held
294
+ * against the captured fixtures rather than against anybody's memory:
295
+ * simple-git-hooks runs the entry as the last command of a plain `sh`
296
+ * script, so the umbrella's status is the hook's status, while yorkie wraps
297
+ * its runner in `|| { ...; exit 1; }` and turns every non-zero exit into 1.
298
+ */
299
+ function managedHooksGuidance(manager, relPath, detectedIn) {
300
+ // WHERE THE ENTRY GOES IS WHERE THE DECLARATION ALREADY IS.
301
+ // simple-git-hooks reads package.json LAST, so while a standalone config
302
+ // file exists an entry added to package.json is precisely the one it
303
+ // ignores. Naming package.json there would send somebody to edit a file
304
+ // that will not be read, and leave them with the umbrella uninstalled and
305
+ // no error to explain it.
306
+ const home = detectedIn.kind === 'config-file' ? detectedIn.file : 'package.json';
307
+ const entry = detectedIn.kind === 'config-file'
308
+ ? `the "pre-commit" entry in ${detectedIn.file}`
309
+ : manager === 'simple-git-hooks'
310
+ ? 'the "pre-commit" entry under "simple-git-hooks" in package.json'
311
+ : 'the "pre-commit" entry under "gitHooks" in package.json';
312
+ const reinstall = manager === 'simple-git-hooks'
313
+ ? 're-run "npx simple-git-hooks"'
314
+ : 're-run the install (yorkie rewrites its hooks on postinstall)';
315
+ const exitCodes = manager === 'simple-git-hooks'
316
+ ? `${manager} runs that entry as the last command of the hook it generates, so the ` +
317
+ "umbrella's exit codes reach git unchanged: 1 means a gate blocked, 2 means a gate " +
318
+ 'could not run.'
319
+ : `${manager}'s generated hook turns every non-zero exit into 1, so the umbrella's 2 ` +
320
+ '(a gate could not run, and nothing was checked) reaches git as 1 (a gate blocked). ' +
321
+ 'Both still stop the commit.';
322
+ const lead = detectedIn.kind === 'hook'
323
+ ? `${relPath} was generated by ${manager} from its own declaration, and is rewritten on ` +
324
+ 'every install.'
325
+ : `${home} declares ${manager}, which generates ${relPath} from that declaration and ` +
326
+ 'rewrites it on every install.';
327
+ return (`${lead} A hook written there is gone after the next install while ` +
328
+ `${MANIFEST_RELATIVE_PATH} still records it as installed, so the repository would report a ` +
329
+ 'guardrail it no longer has. Nothing was changed, and --force does not override this: that ' +
330
+ `file was never conductor's to hold. To run the umbrella under ${manager}, set ${entry} ` +
331
+ 'to "conductor run --staged --stage commit" yourself, and ' +
332
+ `${reinstall}. If something is already in that entry, put the umbrella LAST, as its own ` +
333
+ 'command rather than chained behind && : a chain stops at the first failure, so an ' +
334
+ "umbrella in front of it hides the other command's verdict and one behind an && never " +
335
+ `runs at all once anything ahead of it fails. conductor does not edit ${home}, so it ` +
336
+ 'cannot do that for you; a later release may offer to. ' +
337
+ exitCodes);
338
+ }
171
339
  function detectGateHook(content) {
172
340
  if (content.includes(DEP_GUARD_HOOK_MARKER)) {
173
341
  return 'dep-guard';
@@ -268,6 +436,93 @@ exit "$conductor_status"
268
436
  function sha256(content) {
269
437
  return createHash('sha256').update(content).digest('hex');
270
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
+ }
271
526
  function gitOutput(cwd, args) {
272
527
  try {
273
528
  return execFileSync('git', args, {
@@ -293,11 +548,12 @@ function repoRootOf(cwd) {
293
548
  function effectiveHooksDir(cwd, root) {
294
549
  const gitDir = gitOutput(cwd, ['rev-parse', '--git-dir']);
295
550
  const hooksPath = gitOutput(cwd, ['config', '--get', 'core.hooksPath']) ?? '';
551
+ // With no core.hooksPath, hooks live in the git DIRECTORY, which is not
552
+ // the working-tree root: for a linked worktree or a submodule it is
553
+ // somewhere else entirely, so this one resolves against gitDir.
554
+ const defaultDir = path.join(path.resolve(cwd, gitDir ?? '.git'), 'hooks');
296
555
  if (hooksPath.length === 0) {
297
- // With no core.hooksPath, hooks live in the git DIRECTORY, which is not
298
- // the working-tree root: for a linked worktree or a submodule it is
299
- // somewhere else entirely, so this one resolves against gitDir.
300
- return { dir: path.join(path.resolve(cwd, gitDir ?? '.git'), 'hooks'), outside: false };
556
+ return { dir: defaultDir, outside: false, isDefault: true };
301
557
  }
302
558
  // A RELATIVE core.hooksPath resolves against the WORKING-TREE ROOT.
303
559
  // Verified by experiment rather than by reading the documentation that
@@ -305,7 +561,31 @@ function effectiveHooksDir(cwd, root) {
305
561
  const dir = path.isAbsolute(hooksPath) ? hooksPath : path.join(root, hooksPath);
306
562
  const relative = path.relative(root, dir);
307
563
  const outside = relative.startsWith('..') || path.isAbsolute(relative);
308
- return { dir, outside };
564
+ return { dir, outside, isDefault: samePath(dir, defaultDir) };
565
+ }
566
+ /**
567
+ * Whether two paths name the same directory.
568
+ *
569
+ * Through `realpath`, not string comparison, because the two sides arrive by
570
+ * different routes: the default is built from the working directory the
571
+ * caller passed in, and a configured `core.hooksPath` resolves against the
572
+ * root git reported, which git has already resolved. On macOS the system
573
+ * temporary directory is a symlink, so those two spell the same directory
574
+ * two ways and a string compare answers "different" for a repository git
575
+ * treats as one place. Falls back to the resolved strings when a path does
576
+ * not exist yet, which is the ordinary case for a hooks directory init is
577
+ * about to create.
578
+ */
579
+ function samePath(left, right) {
580
+ const real = (candidate) => {
581
+ try {
582
+ return realpathSync(candidate);
583
+ }
584
+ catch {
585
+ return path.resolve(candidate);
586
+ }
587
+ };
588
+ return real(left) === real(right);
309
589
  }
310
590
  function readIfExists(file) {
311
591
  try {
@@ -524,16 +804,51 @@ export function planInit(options) {
524
804
  // repository is still husky's).
525
805
  const huskyDir = huskyDirectoryFor(hooks.dir);
526
806
  const husky = huskyDir !== null;
527
- if (!husky && executedHook !== undefined) {
528
- const generatedBy = detectGeneratedHook(executedHook);
529
- if (generatedBy !== null) {
530
- const rel = path.relative(root, executedHookPath).split(path.sep).join('/');
807
+ if (!husky) {
808
+ const rel = path.relative(root, executedHookPath).split(path.sep).join('/');
809
+ if (executedHook !== undefined) {
810
+ const generatedBy = detectGeneratedHook(executedHook);
811
+ if (generatedBy !== null) {
812
+ conflicts.push({
813
+ path: rel,
814
+ reason: 'generated-hook',
815
+ guidance: generatedHookGuidance(generatedBy, rel),
816
+ });
817
+ return { ...base, repoRoot: root, hookPath: executedHookPath, hookManager: generatedBy };
818
+ }
819
+ }
820
+ // The installed file first, then the declaration. The file says what is
821
+ // there now; the declaration says what the next install will put there,
822
+ // and on a fresh clone it is the only one of the two that exists. Either
823
+ // alone is enough, and the refusal is the same either way: only the
824
+ // opening sentence of the guidance changes, so a reader is told which of
825
+ // the two was actually seen.
826
+ //
827
+ // This is checked only on the native path, and only where git actually
828
+ // runs .git/hooks. BOTH conditions are about the same fact: these two
829
+ // managers write .git/hooks/pre-commit directly and neither one reads
830
+ // core.hooksPath. Under husky, and under any other configured hooks
831
+ // directory, the file they rewrite is not the file git runs, so the
832
+ // umbrella's hook is in no danger from them and a refusal would name a
833
+ // file the manager never touches while blocking an install that is
834
+ // perfectly safe.
835
+ const fromHook = executedHook === undefined ? null : detectManagedHook(executedHook);
836
+ const declared = fromHook === null
837
+ ? declaredManagedHooks(root)
838
+ : { manager: fromHook, detectedIn: { kind: 'hook' } };
839
+ const managedBy = hooks.isDefault ? declared : null;
840
+ if (managedBy !== null) {
531
841
  conflicts.push({
532
842
  path: rel,
533
- reason: 'generated-hook',
534
- guidance: generatedHookGuidance(generatedBy, rel),
843
+ reason: 'managed-hooks',
844
+ guidance: managedHooksGuidance(managedBy.manager, rel, managedBy.detectedIn),
535
845
  });
536
- return { ...base, repoRoot: root, hookPath: executedHookPath, hookManager: generatedBy };
846
+ return {
847
+ ...base,
848
+ repoRoot: root,
849
+ hookPath: executedHookPath,
850
+ hookManager: managedBy.manager,
851
+ };
537
852
  }
538
853
  }
539
854
  const hookManager = husky ? 'husky' : 'native';
@@ -714,6 +1029,30 @@ export function applyInit(plan, options) {
714
1029
  product: plan.adoptedFrom.product,
715
1030
  },
716
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
+ }
717
1056
  try {
718
1057
  for (const write of plan.writes) {
719
1058
  mkdirSync(path.dirname(write.path), { recursive: true });
@@ -800,6 +1139,12 @@ export function revertInit(options) {
800
1139
  const actions = [];
801
1140
  const conflicts = [];
802
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);
803
1148
  const root = repoRootOf(options.cwd);
804
1149
  if (root === null) {
805
1150
  conflicts.push({
@@ -807,7 +1152,7 @@ export function revertInit(options) {
807
1152
  reason: 'not-a-git-repository',
808
1153
  guidance: 'Nothing to revert: this is not a git repository.',
809
1154
  });
810
- return { ok: false, actions, conflicts };
1155
+ return { ok: false, actions, conflicts, dryRun };
811
1156
  }
812
1157
  const manifestPath = path.join(root, MANIFEST_RELATIVE_PATH);
813
1158
  const raw = readIfExists(manifestPath);
@@ -818,7 +1163,7 @@ export function revertInit(options) {
818
1163
  guidance: `No ${MANIFEST_RELATIVE_PATH}, so there is no record of what init wrote. Nothing was ` +
819
1164
  "removed: guessing which files were ours is how a revert deletes somebody's work.",
820
1165
  });
821
- return { ok: false, actions, conflicts };
1166
+ return { ok: false, actions, conflicts, dryRun };
822
1167
  }
823
1168
  // Not routed through readManifest, which answers null for both a missing
824
1169
  // file and an unparseable one. Revert has to tell those apart: a missing
@@ -840,9 +1185,32 @@ export function revertInit(options) {
840
1185
  'anything. Only then delete it and remove the hook and the policy file yourself, and ' +
841
1186
  're-run init.',
842
1187
  });
843
- return { ok: false, actions, conflicts };
1188
+ return { ok: false, actions, conflicts, dryRun };
844
1189
  }
845
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
+ }
846
1214
  const planned = manifest.files.map((file) => {
847
1215
  const current = readIfExists(file.path);
848
1216
  const state = current === undefined ? 'gone' : sha256(current) === file.sha256 ? 'match' : 'changed';
@@ -866,7 +1234,7 @@ export function revertInit(options) {
866
1234
  detail: entry.state === 'changed' ? 'changed since init, left alone' : 'left alone',
867
1235
  });
868
1236
  }
869
- return { ok: false, actions, conflicts };
1237
+ return { ok: false, actions, conflicts, dryRun };
870
1238
  }
871
1239
  const remaining = [];
872
1240
  for (const { file, state } of planned) {
@@ -885,7 +1253,9 @@ export function revertInit(options) {
885
1253
  remaining.push(file);
886
1254
  continue;
887
1255
  }
888
- rmSync(file.path, { force: true });
1256
+ if (!dryRun) {
1257
+ rmSync(file.path, { force: true });
1258
+ }
889
1259
  actions.push({
890
1260
  kind: 'remove',
891
1261
  path: rel,
@@ -906,12 +1276,24 @@ export function revertInit(options) {
906
1276
  // the flag and restore a hook next to a surviving one. existsSync says what
907
1277
  // is there, which is the thing the rule is about.
908
1278
  const recordedHooks = planned.filter((entry) => entry.file.kind === 'hook');
909
- 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));
910
1290
  let adopted = manifest.adopted;
911
1291
  if (adopted !== null && umbrellaHookGone) {
912
- mkdirSync(path.dirname(adopted.path), { recursive: true });
913
- writeFileSync(adopted.path, adopted.content, 'utf8');
914
- 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
+ }
915
1297
  actions.push({
916
1298
  kind: 'restore',
917
1299
  path: relative(adopted.path),
@@ -920,39 +1302,57 @@ export function revertInit(options) {
920
1302
  adopted = null;
921
1303
  }
922
1304
  if (remaining.length === 0 && adopted === null) {
923
- rmSync(manifestPath, { force: true });
1305
+ if (!dryRun) {
1306
+ rmSync(manifestPath, { force: true });
1307
+ }
924
1308
  actions.push({ kind: 'remove', path: MANIFEST_RELATIVE_PATH, detail: 'removed' });
925
1309
  const manifestDir = path.dirname(MANIFEST_RELATIVE_PATH);
926
- try {
927
- // rmdirSync, not rmSync: rmSync on a directory without recursive: true
928
- // throws before it removes anything, so this swallowed its own error
929
- // every time and left an empty .guardrails behind after a revert that
930
- // said it had removed everything. rmdirSync removes an empty directory
931
- // and refuses a non-empty one, which is exactly the rule wanted here.
932
- rmdirSync(path.dirname(manifestPath));
933
- 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
+ });
934
1321
  }
935
- catch {
936
- // The directory holds something else, so it stays. Reported rather
937
- // than passed over: a directory this tool created and then left
938
- // behind, with nothing said about it, reads as something revert
939
- // forgot rather than as something it decided.
940
- actions.push({
941
- kind: 'skip',
942
- path: manifestDir,
943
- detail: 'kept: it holds something else, which is not ours to remove',
944
- });
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
+ }
945
1343
  }
946
- return { ok: true, actions, conflicts };
1344
+ return { ok: true, actions, conflicts, dryRun };
947
1345
  }
948
1346
  // Something is left, so the manifest stays and keeps describing it.
949
- 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
+ }
950
1350
  actions.push({
951
1351
  kind: 'skip',
952
1352
  path: MANIFEST_RELATIVE_PATH,
953
1353
  detail: 'kept: it still records what was left behind',
954
1354
  });
955
- return { ok: false, actions, conflicts };
1355
+ return { ok: false, actions, conflicts, dryRun };
956
1356
  }
957
1357
  export function renderInitHuman(result) {
958
1358
  const lines = [];
@@ -986,8 +1386,18 @@ export function renderRevertHuman(result) {
986
1386
  if (result.ok) {
987
1387
  lines[0] = 'conductor init --revert:';
988
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
+ }
989
1398
  for (const action of result.actions) {
990
- 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})`);
991
1401
  }
992
1402
  // The conflicts go LAST rather than first, so the thing the user has to
993
1403
  // act on is the last line on their terminal rather than scrolled off the