@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.
- package/README.md +147 -2
- package/dist/cli.js +96 -15
- package/dist/envelope.d.ts +16 -0
- package/dist/gate-runner.d.ts +118 -2
- package/dist/gate-runner.js +211 -9
- package/dist/init.d.ts +15 -1
- package/dist/init.js +215 -33
- package/dist/intent-prepare.d.ts +16 -0
- package/dist/intent-prepare.js +18 -0
- package/dist/normalize.d.ts +14 -1
- package/dist/normalize.js +76 -0
- package/dist/output-sarif.d.ts +11 -0
- package/dist/output-sarif.js +230 -19
- package/dist/output-text.js +134 -3
- package/dist/policy.js +24 -3
- package/dist/resolve.d.ts +11 -0
- package/dist/resolve.js +4 -0
- package/dist/run.d.ts +92 -0
- package/dist/run.js +119 -5
- package/dist/trust-base.d.ts +142 -0
- package/dist/trust-base.js +414 -0
- package/package.json +1 -1
package/dist/gate-runner.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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 [
|
|
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
|
|
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
|
-
|
|
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'
|
|
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
|
-
|
|
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 &&
|
|
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
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1155
|
-
|
|
1156
|
-
//
|
|
1157
|
-
//
|
|
1158
|
-
|
|
1159
|
-
|
|
1160
|
-
|
|
1161
|
-
|
|
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
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
path
|
|
1171
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|