@vaultcompass/conductor 0.4.7 → 0.6.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.
@@ -8,5 +8,23 @@ export declare function detectGates(root: string, pathValue: string): Set<GateRo
8
8
  * comments are half the point: a first-run policy file that explains what
9
9
  * each key is for is most of a first-run experience, and a YAML emitter
10
10
  * cannot carry them.
11
+ *
12
+ * `frozenContractPath` decides the intent gate's `enforce` default (issue
13
+ * #57): non-null when this repository already has a frozen contract at init
14
+ * time, so the ramp init would otherwise produce is already climbed, and
15
+ * leaving it unenforced would silently drop the one protection a contract
16
+ * with protected paths exists to give -- exactly what a frozen contract's
17
+ * findings NOT failing the check let happen on the public demo repository.
18
+ * False is still the default with no contract, for the same ramp reasoning
19
+ * as before: a fresh intent gate with nothing frozen yet has nothing to
20
+ * enforce against.
21
+ *
22
+ * The caller passes intent-prepare.ts's own `frozenNativeContractPath(root)`
23
+ * directly, not a boolean, so the comment below can name the path a frozen
24
+ * contract was ACTUALLY found at -- the canonical
25
+ * `.intent-guard/intent-contract.yaml` or the legacy
26
+ * `.conductor/intent-contract.yaml` -- rather than always naming the
27
+ * canonical one even when the frozen contract that triggered enforcement
28
+ * lives at the legacy path.
11
29
  */
12
- export declare function renderPolicy(detected: Set<GateRole>): string;
30
+ export declare function renderPolicy(detected: Set<GateRole>, frozenContractPath: string | null): string;
@@ -1,5 +1,6 @@
1
1
  import { statSync } from 'node:fs';
2
2
  import path from 'node:path';
3
+ import { NATIVE_CONTRACT_PATH } from './intent-prepare.js';
3
4
  import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
4
5
  import { CANDIDATES } from './resolve.js';
5
6
  export { POLICY_FILE_NAME };
@@ -38,14 +39,34 @@ const ROLE_DESCRIPTION = {
38
39
  dependencies: 'what comes in: hallucinated names, typosquats, tampered lockfile entries',
39
40
  secrets: 'what goes out: credentials about to be committed',
40
41
  intent: 'what was approved: drift from a frozen intent contract, and change budgets',
42
+ 'secrets-history': 'credentials anywhere in git history, by gitleaks (installed by you, not by conductor)',
43
+ vulnerabilities: 'known vulnerabilities in the resolved dependency tree, by osv-scanner (installed by you, not by conductor)',
41
44
  };
42
45
  /**
43
46
  * The policy file, written by hand rather than serialised, because the
44
47
  * comments are half the point: a first-run policy file that explains what
45
48
  * each key is for is most of a first-run experience, and a YAML emitter
46
49
  * cannot carry them.
50
+ *
51
+ * `frozenContractPath` decides the intent gate's `enforce` default (issue
52
+ * #57): non-null when this repository already has a frozen contract at init
53
+ * time, so the ramp init would otherwise produce is already climbed, and
54
+ * leaving it unenforced would silently drop the one protection a contract
55
+ * with protected paths exists to give -- exactly what a frozen contract's
56
+ * findings NOT failing the check let happen on the public demo repository.
57
+ * False is still the default with no contract, for the same ramp reasoning
58
+ * as before: a fresh intent gate with nothing frozen yet has nothing to
59
+ * enforce against.
60
+ *
61
+ * The caller passes intent-prepare.ts's own `frozenNativeContractPath(root)`
62
+ * directly, not a boolean, so the comment below can name the path a frozen
63
+ * contract was ACTUALLY found at -- the canonical
64
+ * `.intent-guard/intent-contract.yaml` or the legacy
65
+ * `.conductor/intent-contract.yaml` -- rather than always naming the
66
+ * canonical one even when the frozen contract that triggered enforcement
67
+ * lives at the legacy path.
47
68
  */
48
- export function renderPolicy(detected) {
69
+ export function renderPolicy(detected, frozenContractPath) {
49
70
  const lines = [
50
71
  '# Guardrail policy. One file for every gate this repository runs.',
51
72
  '#',
@@ -82,14 +103,27 @@ export function renderPolicy(detected) {
82
103
  lines.push(` enabled: ${enabled ? 'true' : 'false'}`);
83
104
  lines.push(` stage: ${DEFAULT_STAGE_FOR_ROLE[role]}`);
84
105
  // The intent gate is the one with ceremony, and the ramp is what makes
85
- // that ceremony adoptable: it reports for a few pull requests before it
86
- // is allowed to refuse anybody's merge. Writing that here rather than
87
- // describing it in a comment is the difference between a fresh init
88
- // producing the ramp and three repositories being hand-edited into it.
106
+ // that ceremony adoptable: with no frozen contract yet, it reports for a
107
+ // few pull requests before it is allowed to refuse anybody's merge.
108
+ // Writing that here rather than describing it in a comment is the
109
+ // difference between a fresh init producing the ramp and three
110
+ // repositories being hand-edited into it. Once a contract IS frozen, the
111
+ // ramp is already climbed and enforcing from the start is what stops a
112
+ // frozen contract's protected paths from producing findings that never
113
+ // fail the check (issue #57).
89
114
  if (role === 'intent') {
90
- lines.push(' # It runs and reports in CI without failing the run. Flip it to');
91
- lines.push(' # true once a few pull requests show the signal is worth blocking on.');
92
- lines.push(' enforce: false');
115
+ if (frozenContractPath !== null) {
116
+ lines.push(` # A frozen contract already exists at ${frozenContractPath}, so this gate`);
117
+ lines.push(' # enforces from the start rather than only reporting.');
118
+ lines.push(' enforce: true');
119
+ }
120
+ else {
121
+ lines.push(` # No frozen contract yet (${NATIVE_CONTRACT_PATH}), so this gate runs`);
122
+ lines.push(' # and reports without failing the run. Once a contract is frozen,');
123
+ lines.push(' # set this to true by hand: conductor init never rewrites this file');
124
+ lines.push(' # once it exists.');
125
+ lines.push(' enforce: false');
126
+ }
93
127
  }
94
128
  else {
95
129
  lines.push(' enforce: true');
package/dist/init.d.ts CHANGED
@@ -19,7 +19,14 @@ export type ConflictReason = 'not-a-git-repository' | 'foreign-hook' | 'gate-hoo
19
19
  * path in it that is not contained rather than writing or deleting where it
20
20
  * points.
21
21
  */
22
- | 'manifest-path-outside-repository' | 'no-manifest' | 'manifest-unreadable' | 'changed-since-init' | 'write-failed';
22
+ | 'manifest-path-outside-repository' | 'no-manifest' | 'manifest-unreadable' | 'changed-since-init' | 'write-failed'
23
+ /**
24
+ * --adopt or --force was given on an init that does not also carry --hook.
25
+ * Both flags are about the hook alone -- replacing a gate's own, or
26
+ * overwriting one somebody edited -- and with no --hook there is no hook
27
+ * being written for either of them to act on.
28
+ */
29
+ | 'flag-requires-hook';
23
30
  export interface InitConflict {
24
31
  path: string;
25
32
  reason: ConflictReason;
@@ -35,6 +42,8 @@ export interface AdoptedHook {
35
42
  content: string;
36
43
  }
37
44
  export interface InitResult {
45
+ /** One-line notes printed after the actions, such as an external gate enabled from PATH. */
46
+ notes?: string[];
38
47
  ok: boolean;
39
48
  dryRun: boolean;
40
49
  alreadyInstalled: boolean;
@@ -42,6 +51,16 @@ export interface InitResult {
42
51
  conflicts: InitConflict[];
43
52
  /** Absolute path of the hook file, empty when there is nothing to write. */
44
53
  hookPath: string;
54
+ /**
55
+ * Whether this run was asked to write a hook at all. False is the default:
56
+ * a fresh `conductor init` writes only the policy file and the manifest,
57
+ * and `--hook` opts into the pre-commit hook on top of that. Carried on the
58
+ * result so the human renderer can say, at the end of a run that did not
59
+ * ask for one, that no hook was written and how to add one -- rather than
60
+ * a reader inferring it from an empty hookPath, which is also what a
61
+ * refused run reports.
62
+ */
63
+ hookRequested: boolean;
45
64
  /**
46
65
  * Which hook manager owns this repository's pre-commit hook, as detected.
47
66
  * `husky` means hookPath is the TRACKED file rather than the generated
@@ -78,6 +97,16 @@ export interface InitOptions {
78
97
  /** PATH used for gate detection. Injected so tests never depend on the machine. */
79
98
  pathValue: string;
80
99
  dryRun?: boolean;
100
+ /**
101
+ * Opt into the pre-commit hook. Without it, init writes only the policy
102
+ * file and the manifest: no hook is detected, written, or reported on.
103
+ * Every CI-only adopter that does not want a local hook at all otherwise
104
+ * gets one it never asked for, and a hook `.git/hooks` never carries to a
105
+ * second clone anyway, so writing one by default is a promise init cannot
106
+ * keep past the first checkout. Ignored by --revert, which always removes
107
+ * whatever a previous --hook run wrote.
108
+ */
109
+ hook?: boolean;
81
110
  /** Replace a per-gate hook with the umbrella's. Never replaces a foreign one. */
82
111
  adopt?: boolean;
83
112
  /**
package/dist/init.js CHANGED
@@ -1,4 +1,5 @@
1
- // `conductor init`: one policy file, one pre-commit hook, one manifest.
1
+ // `conductor init`: one policy file, one manifest, and with --hook one
2
+ // pre-commit hook.
2
3
  //
3
4
  // The manifest is what makes --revert honest. Without one, "undo the init"
4
5
  // means guessing which files were the tool's, and a tool that guesses about
@@ -69,6 +70,9 @@ import path from 'node:path';
69
70
  import { DEP_GUARD_HOOK_MARKER, INTENT_GUARD_HOOK_MARKER, MANAGED_HOOK_MARKER, declaredManagedHooks, detectGateHook, detectGeneratedHook, detectManagedHook, editedManagedGuidance, foreignGuidance, gateHookGuidance, generatedHookGuidance, huskyDirectoryFor, huskyShimPresent, managedHooksGuidance, } from './init-hook-detect.js';
70
71
  import { MANIFEST_RELATIVE_PATH, manifestPathInsideRepo, readIfExists, readManifest, recordedHookSha, sha256, } from './init-manifest.js';
71
72
  import { POLICY_FILE_NAME, detectGates, renderPolicy } from './init-policy.js';
73
+ import { frozenNativeContractPath } from './intent-prepare.js';
74
+ import { GATE_ROLES, PRODUCT_FOR_ROLE } from './policy.js';
75
+ import { profileFor } from './products.js';
72
76
  export { MANAGED_HOOK_MARKER, MANIFEST_RELATIVE_PATH, DEP_GUARD_HOOK_MARKER, INTENT_GUARD_HOOK_MARKER, POLICY_FILE_NAME, renderPolicy, };
73
77
  const HOOK = `#!/bin/sh
74
78
  # Guardrail pre-commit hook. ${MANAGED_HOOK_MARKER}
@@ -218,6 +222,7 @@ function samePath(left, right) {
218
222
  }
219
223
  export function planInit(options) {
220
224
  const dryRun = Boolean(options.dryRun);
225
+ const wantsHook = Boolean(options.hook);
221
226
  const actions = [];
222
227
  const conflicts = [];
223
228
  const writes = [];
@@ -230,11 +235,29 @@ export function planInit(options) {
230
235
  conflicts,
231
236
  hookPath: '',
232
237
  hookManager: 'native',
238
+ hookRequested: wantsHook,
233
239
  repoRoot: '',
234
240
  adoptedFrom: null,
235
241
  writes,
236
242
  records,
237
243
  };
244
+ // Both flags are entirely about the hook -- replacing a gate's own, or
245
+ // overwriting one somebody edited -- so neither means anything without
246
+ // --hook, and running one anyway silently does nothing rather than erroring
247
+ // is how a flag typed on the command line gets ignored without a word.
248
+ // Checked before anything about the repository, because this is wrong
249
+ // however the repository looks.
250
+ if (!wantsHook && (options.adopt || options.force)) {
251
+ const flag = options.adopt ? '--adopt' : '--force';
252
+ conflicts.push({
253
+ path: flag,
254
+ reason: 'flag-requires-hook',
255
+ guidance: `${flag} only makes sense together with --hook: without --hook, init writes no ` +
256
+ `pre-commit hook, so there is nothing for ${flag} to act on. Add --hook to the command, ` +
257
+ `or drop ${flag} if you only want the policy file.`,
258
+ });
259
+ return base;
260
+ }
238
261
  const root = repoRootOf(options.cwd);
239
262
  if (root === null) {
240
263
  conflicts.push({
@@ -244,6 +267,15 @@ export function planInit(options) {
244
267
  });
245
268
  return base;
246
269
  }
270
+ const policyPath = path.join(root, POLICY_FILE_NAME);
271
+ if (!wantsHook) {
272
+ actions.push({
273
+ kind: 'skip',
274
+ path: 'pre-commit hook',
275
+ detail: 'not written: pass --hook to add one',
276
+ });
277
+ return finishPlanWithoutHook(options, root, policyPath, base, actions, writes, records);
278
+ }
247
279
  const hooks = effectiveHooksDir(options.cwd, root);
248
280
  if (hooks.outside) {
249
281
  conflicts.push({
@@ -320,8 +352,6 @@ export function planInit(options) {
320
352
  const hookManager = husky ? 'husky' : 'native';
321
353
  const hookPath = huskyDir === null ? executedHookPath : path.join(huskyDir, 'pre-commit');
322
354
  const relHook = path.relative(root, hookPath).split(path.sep).join('/');
323
- const policyPath = path.join(root, POLICY_FILE_NAME);
324
- const manifestPath = path.join(root, MANIFEST_RELATIVE_PATH);
325
355
  // Under husky this is the TRACKED file, never the dispatcher: reading the
326
356
  // dispatcher reported a real gate hook as foreign, which is exactly what
327
357
  // made --adopt unable to adopt it.
@@ -437,15 +467,41 @@ export function planInit(options) {
437
467
  });
438
468
  writes.push({ path: hookPath, content: HOOK, executable: true, kind: 'hook' });
439
469
  }
470
+ return finishPlan(options, root, policyPath, base, actions, writes, records, {
471
+ hookPath,
472
+ hookManager,
473
+ adoptedFrom,
474
+ });
475
+ }
476
+ /**
477
+ * The tail every path through planInit shares once the hook question is
478
+ * settled, one way or the other: the policy file, which is never rewritten
479
+ * once it exists, and the manifest action, which is work even when nothing
480
+ * is written because the manifest itself still has to be rebuilt.
481
+ */
482
+ function finishPlan(options, root, policyPath, base, actions, writes, records, hook) {
440
483
  const existingPolicy = readIfExists(policyPath);
484
+ const notes = [];
441
485
  if (existingPolicy === undefined) {
486
+ const detected = detectGates(root, options.pathValue);
442
487
  writes.push({
443
488
  path: policyPath,
444
- content: renderPolicy(detectGates(root, options.pathValue)),
489
+ content: renderPolicy(detected, frozenNativeContractPath(root)),
445
490
  executable: false,
446
491
  kind: 'policy',
447
492
  });
448
493
  actions.push({ kind: 'write', path: POLICY_FILE_NAME, detail: 'create' });
494
+ // An external gate is enabled because its tool is on THIS machine's PATH.
495
+ // Nothing installs it anywhere else: the Action installs only the npm
496
+ // packages, so a workflow that does not install it too reports the gate
497
+ // could-not-run on the first pull request.
498
+ const external = GATE_ROLES.filter((role) => detected.has(role) && !profileFor(PRODUCT_FOR_ROLE[role]).managed).map((role) => `${role} (${PRODUCT_FOR_ROLE[role]})`);
499
+ if (external.length > 0) {
500
+ const one = external.length === 1;
501
+ notes.push(`Note: ${external.join(' and ')} ${one ? 'is' : 'are'} enabled because ` +
502
+ `${one ? 'its tool was' : 'their tools were'} found on this machine's PATH; your CI ` +
503
+ `workflow must install ${one ? 'it' : 'them'} too, conductor does not.`);
504
+ }
449
505
  }
450
506
  else {
451
507
  // Never rewritten. The policy file is the one artifact a user edits by
@@ -466,14 +522,30 @@ export function planInit(options) {
466
522
  ...base,
467
523
  ok: true,
468
524
  alreadyInstalled,
469
- hookPath,
470
- hookManager,
525
+ hookPath: hook.hookPath,
526
+ hookManager: hook.hookManager,
471
527
  repoRoot: root,
472
- adoptedFrom,
528
+ adoptedFrom: hook.adoptedFrom,
473
529
  writes,
474
530
  records,
531
+ notes,
475
532
  };
476
533
  }
534
+ /**
535
+ * The whole plan when --hook was not given: no hook is detected, no hook
536
+ * manager is consulted, and no hook conflict can block the policy file from
537
+ * being written. A repository wired for husky, or already hooked by another
538
+ * gate, gets its policy file exactly as readily as one with nothing wired at
539
+ * all, because none of that is in this run's way when it never touches
540
+ * .git/hooks.
541
+ */
542
+ function finishPlanWithoutHook(options, root, policyPath, base, actions, writes, records) {
543
+ return finishPlan(options, root, policyPath, base, actions, writes, records, {
544
+ hookPath: '',
545
+ hookManager: 'native',
546
+ adoptedFrom: null,
547
+ });
548
+ }
477
549
  export function applyInit(plan, options) {
478
550
  if (!plan.ok || plan.dryRun || plan.alreadyInstalled) {
479
551
  return plan;
@@ -840,18 +912,35 @@ export function renderInitHuman(result) {
840
912
  const verb = action.kind === 'skip' ? 'skip' : result.dryRun ? 'would write' : 'wrote';
841
913
  lines.push(` ${verb} ${action.path} (${action.detail})`);
842
914
  }
843
- // Two different answers, and saying only the second one is wrong about the
844
- // hook this command just wrote. The pre-commit hook runs `conductor run
845
- // --staged --stage commit` with no --trust-base, and policyForRun reads the
846
- // working tree when trustBase is undefined, so the hook honours this file on
847
- // the very next commit. A pull request is the opposite: it is judged by the
848
- // base branch's own copy, never by the one it is proposing, so the first
849
- // pull request after adoption is inert and reports could-not-run. Said once,
850
- // here, at the point of use, rather than left for somebody to discover from
851
- // a could-not-run comment on their first pull request.
852
- lines.push(`Note: the pre-commit hook uses ${POLICY_FILE_NAME} from your working tree right away. ` +
853
- 'On a pull request conductor reads it from the base branch instead, so pull requests ' +
854
- 'report could-not-run until this file is merged there.');
915
+ // One line per external gate init enabled from this machine's PATH (N6).
916
+ lines.push(...(result.notes ?? []));
917
+ if (result.hookRequested) {
918
+ // Two different answers, and saying only the second one is wrong about
919
+ // the hook this command just wrote. The pre-commit hook runs `conductor
920
+ // run --staged --stage commit` with no --trust-base, and policyForRun
921
+ // reads the working tree when trustBase is undefined, so the hook
922
+ // honours this file on the very next commit. A pull request is the
923
+ // opposite: it is judged by the base branch's own copy, never by the one
924
+ // it is proposing, so the first pull request after adoption is inert and
925
+ // reports could-not-run. Said once, here, at the point of use, rather
926
+ // than left for somebody to discover from a could-not-run comment on
927
+ // their first pull request.
928
+ lines.push(`Note: the pre-commit hook uses ${POLICY_FILE_NAME} from your working tree right away. ` +
929
+ 'On a pull request conductor reads it from the base branch instead, so pull requests ' +
930
+ 'report could-not-run until this file is merged there.');
931
+ }
932
+ else {
933
+ // The line #48 exists for: .git/hooks is never part of a clone, so
934
+ // saying nothing here leaves a second contributor to discover the gap
935
+ // from a commit nothing ever checked. Printed on every run that did not
936
+ // ask for a hook, including one where a hook from an earlier --hook run
937
+ // is still sitting on disk untouched, because that hook still is not
938
+ // what THIS run did.
939
+ lines.push('No pre-commit hook was written: conductor init only writes one when --hook is given. ' +
940
+ 'Run "conductor init --hook" to add it on this machine. .git/hooks is never part of a ' +
941
+ 'clone, so a second clone or a teammate\'s checkout needs its own "conductor init ' +
942
+ '--hook" too; the manifest this writes is per machine.');
943
+ }
855
944
  return lines.join('\n');
856
945
  }
857
946
  export function renderRevertHuman(result) {
@@ -1,7 +1,16 @@
1
- import { type Finding, type NormalizedGateOutput } from './envelope.js';
1
+ import { type Finding, type NormalizedGateOutput, type Severity } from './envelope.js';
2
2
  import type { GateRole, Product } from './policy.js';
3
- export declare function normalizeDepGuard(raw: unknown, version: string | null): NormalizedGateOutput;
3
+ export declare function normalizeDepGuard(raw: unknown, version: string | null,
4
+ /** Whether the umbrella passed --online to dep-guard, read from its own argv. */
5
+ onlineRequested?: boolean): NormalizedGateOutput;
4
6
  export declare function normalizeVaultGuard(raw: unknown, version: string | null): NormalizedGateOutput;
7
+ /**
8
+ * intent-guard's own namespace for its advance-notice warnings, not the
9
+ * umbrella's: the umbrella never mints a `conductor/` id for this, because
10
+ * the statement being relayed is entirely intent-guard's own (see AGENTS.md
11
+ * on the umbrella's fixed set of ids).
12
+ */
13
+ export declare const INTENT_WARNING = "intent-guard/warning";
5
14
  /**
6
15
  * The three ways the intent gate can block on the STATE of the contract
7
16
  * rather than on anything in the diff.
@@ -36,6 +45,14 @@ export type GateStateReasonKind = (typeof GATE_STATE_REASON_KINDS)[number];
36
45
  /** Which gate-state reason this is, or null when it is a budget or drift reason. */
37
46
  export declare function classifyGateStateReason(reason: string): GateStateReasonKind | null;
38
47
  export declare function normalizeIntentGuard(raw: unknown, version: string | null): NormalizedGateOutput;
48
+ export declare function normalizeGitleaks(raw: unknown, version: string | null, blocked: boolean): NormalizedGateOutput;
49
+ /** CVSS base score onto the shared four-level ladder, by the CVSS v3 bands. */
50
+ export declare function cvssToSeverity(score: number | null): Severity;
51
+ export declare function normalizeOsvScanner(raw: unknown, version: string | null, blocked: boolean,
52
+ /** The scan root as a path osv-scanner may have printed it, in any spelling. */
53
+ roots?: readonly string[],
54
+ /** The lockfiles the umbrella passed with --lockfile, repository-relative. */
55
+ lockfiles?: readonly string[]): NormalizedGateOutput;
39
56
  export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-unparseable' | 'conductor/gate-failed';
40
57
  /**
41
58
  * The finding raised when an ENABLED gate's binary cannot be found.