vouchington-tooling 0.58.0 → 0.60.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.
Files changed (162) hide show
  1. package/README.md +80 -0
  2. package/dist/agent-issue-labels/ensure-labels.d.mts +1 -1
  3. package/dist/agent-issue-labels/ensure-labels.mjs +1 -1
  4. package/dist/browser-session-runner/tail-queue.d.mts +1 -1
  5. package/dist/browser-session-runner/tail-queue.mjs +1 -1
  6. package/dist/cli/commands/gitleaks-directory-scan.d.mts +4 -0
  7. package/dist/cli/commands/gitleaks-directory-scan.mjs +9 -0
  8. package/dist/cli/commands/hook.d.mts +2 -0
  9. package/dist/cli/commands/hook.mjs +19 -0
  10. package/dist/cli/commands/transient-retry.d.mts +13 -0
  11. package/dist/cli/commands/transient-retry.mjs +68 -0
  12. package/dist/cli/index.mjs +14 -53
  13. package/dist/cli/parse-forwarded-commands.d.mts +12 -0
  14. package/dist/cli/parse-forwarded-commands.mjs +8 -0
  15. package/dist/cli/parse.d.mts +12 -0
  16. package/dist/cli/script-paths.d.mts +5 -0
  17. package/dist/cli/script-paths.mjs +48 -0
  18. package/dist/cli/usage-text.d.mts +1 -0
  19. package/dist/cli/usage-text.mjs +170 -0
  20. package/dist/cli/usage.d.mts +2 -1
  21. package/dist/cli/usage.mjs +2 -149
  22. package/dist/command-policy/engine.d.mts +7 -0
  23. package/dist/command-policy/engine.mjs +58 -0
  24. package/dist/command-policy/git-patterns.d.mts +20 -0
  25. package/dist/command-policy/git-patterns.mjs +82 -0
  26. package/dist/command-policy/git-process.d.mts +4 -0
  27. package/dist/command-policy/git-process.mjs +54 -0
  28. package/dist/command-policy/github-checkout-owners.d.mts +22 -0
  29. package/dist/command-policy/github-checkout-owners.mjs +122 -0
  30. package/dist/command-policy/github-command-context.d.mts +6 -0
  31. package/dist/command-policy/github-command-context.mjs +19 -0
  32. package/dist/command-policy/github-command-cwd.d.mts +8 -0
  33. package/dist/command-policy/github-command-cwd.mjs +130 -0
  34. package/dist/command-policy/github-command-position.d.mts +7 -0
  35. package/dist/command-policy/github-command-position.mjs +12 -0
  36. package/dist/command-policy/github-configured-base.d.mts +25 -0
  37. package/dist/command-policy/github-configured-base.mjs +59 -0
  38. package/dist/command-policy/github-invocation.d.mts +9 -0
  39. package/dist/command-policy/github-invocation.mjs +80 -0
  40. package/dist/command-policy/github-merge-authority.d.mts +21 -0
  41. package/dist/command-policy/github-merge-authority.mjs +86 -0
  42. package/dist/command-policy/github-option-flags.d.mts +3 -0
  43. package/dist/command-policy/github-option-flags.mjs +67 -0
  44. package/dist/command-policy/github-options.d.mts +12 -0
  45. package/dist/command-policy/github-options.mjs +73 -0
  46. package/dist/command-policy/github-stack-workflow.d.mts +9 -0
  47. package/dist/command-policy/github-stack-workflow.mjs +94 -0
  48. package/dist/command-policy/github-workflow.d.mts +7 -0
  49. package/dist/command-policy/github-workflow.mjs +50 -0
  50. package/dist/command-policy/hook/args.d.mts +11 -0
  51. package/dist/command-policy/hook/args.mjs +49 -0
  52. package/dist/command-policy/hook/harness.d.mts +26 -0
  53. package/dist/command-policy/hook/harness.mjs +119 -0
  54. package/dist/command-policy/hook/policy-module.d.mts +7 -0
  55. package/dist/command-policy/hook/policy-module.mjs +48 -0
  56. package/dist/command-policy/hook/post-tool-use.d.mts +9 -0
  57. package/dist/command-policy/hook/post-tool-use.mjs +51 -0
  58. package/dist/command-policy/hook/pre-tool-use.d.mts +21 -0
  59. package/dist/command-policy/hook/pre-tool-use.mjs +45 -0
  60. package/dist/command-policy/hook/run.d.mts +17 -0
  61. package/dist/command-policy/hook/run.mjs +69 -0
  62. package/dist/command-policy/hook/types.d.mts +33 -0
  63. package/dist/command-policy/hook/types.mjs +5 -0
  64. package/dist/command-policy/index.d.mts +29 -0
  65. package/dist/command-policy/index.mjs +23 -0
  66. package/dist/command-policy/path-references.d.mts +14 -0
  67. package/dist/command-policy/path-references.mjs +68 -0
  68. package/dist/command-policy/path-rules.d.mts +11 -0
  69. package/dist/command-policy/path-rules.mjs +37 -0
  70. package/dist/command-policy/payload.d.mts +8 -0
  71. package/dist/command-policy/payload.mjs +54 -0
  72. package/dist/command-policy/types.d.mts +77 -0
  73. package/dist/command-policy/types.mjs +1 -0
  74. package/dist/dead-code/baseline.d.mts +19 -0
  75. package/dist/dead-code/baseline.mjs +124 -0
  76. package/dist/dead-code/child-command.d.mts +6 -0
  77. package/dist/dead-code/child-command.mjs +107 -0
  78. package/dist/dead-code/cli.d.mts +5 -0
  79. package/dist/dead-code/cli.mjs +71 -0
  80. package/dist/dead-code/entry-roots.d.mts +7 -0
  81. package/dist/dead-code/entry-roots.mjs +43 -0
  82. package/dist/dead-code/fixture-deadline.test-helpers.d.mts +1 -0
  83. package/dist/dead-code/fixture-deadline.test-helpers.mjs +9 -0
  84. package/dist/dead-code/gate.d.mts +29 -0
  85. package/dist/dead-code/gate.mjs +33 -0
  86. package/dist/dead-code/gate.test-helpers.d.mts +14 -0
  87. package/dist/dead-code/gate.test-helpers.mjs +35 -0
  88. package/dist/dead-code/index.d.mts +9 -0
  89. package/dist/dead-code/index.mjs +7 -0
  90. package/dist/dead-code/scan.d.mts +11 -0
  91. package/dist/dead-code/scan.mjs +37 -0
  92. package/dist/dead-code/tracked-snapshot.d.mts +2 -0
  93. package/dist/dead-code/tracked-snapshot.mjs +72 -0
  94. package/dist/index.d.mts +2 -0
  95. package/dist/index.mjs +1 -0
  96. package/dist/markdown/details-scope.d.mts +1 -1
  97. package/dist/markdown/details-scope.mjs +1 -1
  98. package/dist/tmux/cli-shared.d.mts +18 -0
  99. package/dist/tmux/cli-shared.mjs +8 -0
  100. package/dist/tmux/cli.d.mts +3 -0
  101. package/dist/tmux/cli.mjs +34 -0
  102. package/dist/tmux/config.d.mts +24 -0
  103. package/dist/tmux/config.mjs +91 -0
  104. package/dist/tmux/fake-tmux.test-helpers.d.mts +46 -0
  105. package/dist/tmux/fake-tmux.test-helpers.mjs +105 -0
  106. package/dist/tmux/hook-payload.d.mts +8 -0
  107. package/dist/tmux/hook-payload.mjs +39 -0
  108. package/dist/tmux/index.d.mts +9 -0
  109. package/dist/tmux/index.mjs +7 -0
  110. package/dist/tmux/launcher.d.mts +11 -0
  111. package/dist/tmux/launcher.mjs +127 -0
  112. package/dist/tmux/reminder-post-tool.d.mts +21 -0
  113. package/dist/tmux/reminder-post-tool.mjs +88 -0
  114. package/dist/tmux/runner.d.mts +11 -0
  115. package/dist/tmux/runner.mjs +26 -0
  116. package/dist/tmux/session-name.d.mts +5 -0
  117. package/dist/tmux/session-name.mjs +10 -0
  118. package/dist/tmux/shell-quote.d.mts +9 -0
  119. package/dist/tmux/shell-quote.mjs +16 -0
  120. package/dist/tmux/up.d.mts +2 -0
  121. package/dist/tmux/up.mjs +73 -0
  122. package/dist/tmux/windows.d.mts +18 -0
  123. package/dist/tmux/windows.mjs +50 -0
  124. package/dist/transient-retry/attempts.d.mts +1 -1
  125. package/dist/transient-retry/attempts.mjs +1 -1
  126. package/dist/transient-retry/decision-evaluator.d.mts +3 -3
  127. package/dist/transient-retry/gh-api.d.mts +30 -0
  128. package/dist/transient-retry/gh-api.mjs +68 -0
  129. package/dist/transient-retry/github-actions-log.d.mts +7 -0
  130. package/dist/transient-retry/github-actions-log.mjs +33 -0
  131. package/dist/transient-retry/index.d.mts +15 -0
  132. package/dist/transient-retry/index.mjs +8 -0
  133. package/dist/transient-retry/log-stream.d.mts +12 -0
  134. package/dist/transient-retry/log-stream.mjs +39 -0
  135. package/dist/transient-retry/log-window.d.mts +18 -0
  136. package/dist/transient-retry/log-window.mjs +94 -0
  137. package/dist/transient-retry/rerun.d.mts +23 -0
  138. package/dist/transient-retry/rerun.mjs +68 -0
  139. package/dist/transient-retry/run-context-annotations.d.mts +7 -0
  140. package/dist/transient-retry/run-context-annotations.mjs +44 -0
  141. package/dist/transient-retry/run-context-jobs.d.mts +20 -0
  142. package/dist/transient-retry/run-context-jobs.mjs +54 -0
  143. package/dist/transient-retry/run-context-logs.d.mts +12 -0
  144. package/dist/transient-retry/run-context-logs.mjs +86 -0
  145. package/dist/transient-retry/run-context-rule-attempts.d.mts +14 -0
  146. package/dist/transient-retry/run-context-rule-attempts.mjs +65 -0
  147. package/dist/transient-retry/run-context-types.d.mts +49 -0
  148. package/dist/transient-retry/run-context-types.mjs +3 -0
  149. package/dist/transient-retry/run-context.d.mts +9 -0
  150. package/dist/transient-retry/run-context.mjs +25 -0
  151. package/dist/transient-retry/run-context.test-helpers.d.mts +16 -0
  152. package/dist/transient-retry/run-context.test-helpers.mjs +56 -0
  153. package/dist/transient-retry/types.d.mts +8 -7
  154. package/dist/vitest-diagnostics/vitest-worker-exit-diagnostics-reporter.mjs +1 -1
  155. package/dist/workflow-secrets-drift/gh.d.mts +1 -1
  156. package/dist/workflow-secrets-drift/gh.mjs +1 -1
  157. package/package.json +16 -1
  158. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  159. package/scripts/tmux/tmux-agent-reminder.sh +68 -0
  160. package/scripts/tmux/tmux-name.sh +34 -0
  161. package/scripts/tmux/tmux-read-title.sh +13 -0
  162. package/scripts/tmux/tmux-target.sh +130 -0
@@ -0,0 +1,21 @@
1
+ import type { CommandPolicy, HookPayload } from '../types.mts';
2
+ import type { HookHarness } from './types.mts';
3
+ /**
4
+ * What a pre-tool-use hook writes and exits with. Exit 2 is the block all four harnesses honor.
5
+ * Claude, Codex, and Grok surface the stderr reason; Cursor surfaces the stdout JSON. Exit 0 with
6
+ * empty stdio is no opinion.
7
+ */
8
+ export type PreToolUseResult = {
9
+ exitCode: 0 | 2;
10
+ stderr: string;
11
+ stdout: string;
12
+ };
13
+ export type PreToolUseOptions = {
14
+ harness?: HookHarness | undefined;
15
+ /** True only when the harness marked the session attended (see isAttendedClaudeSession). */
16
+ attended?: boolean | undefined;
17
+ /** See EvaluateOptions.automationContext. */
18
+ automationContext?: boolean | undefined;
19
+ cwd?: string | undefined;
20
+ };
21
+ export declare function preToolUseOutput(payload: HookPayload, policy: CommandPolicy | undefined, options?: PreToolUseOptions): PreToolUseResult;
@@ -0,0 +1,45 @@
1
+ import { evaluateCommandPolicy } from "../engine.mjs";
2
+ export function preToolUseOutput(payload, policy, options = {}) {
3
+ // A policy module without a command table has no opinion, merge authority included.
4
+ if (policy === undefined) {
5
+ return { exitCode: 0, stderr: '', stdout: noOpinion(options) };
6
+ }
7
+ const decision = evaluateCommandPolicy(payload, policy, {
8
+ ...(options.automationContext === undefined
9
+ ? {}
10
+ : { automationContext: options.automationContext }),
11
+ ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
12
+ });
13
+ if (decision === null) {
14
+ return { exitCode: 0, stderr: '', stdout: noOpinion(options) };
15
+ }
16
+ if (decision.disposition === 'confirm') {
17
+ return { exitCode: 0, stderr: '', stdout: renderConfirm(policy, options) };
18
+ }
19
+ return {
20
+ exitCode: 2,
21
+ stderr: `${decision.reason}\n`,
22
+ stdout: JSON.stringify({ decision: 'deny', reason: decision.reason }),
23
+ };
24
+ }
25
+ // Cursor treats a hook that prints nothing as failed (and blocks the call under `failClosed`), so
26
+ // "no opinion" there is an empty JSON object. Every other harness reads empty stdio as no opinion.
27
+ function noOpinion(options) {
28
+ return options.harness === 'cursor' ? '{}' : '';
29
+ }
30
+ // Only an attended Claude session gets a silent allow: the human already made the merge decision by
31
+ // asking for it, so a second tool-level click is redundant. Codex, Cursor, Grok, and an unattended
32
+ // Claude session (`claude -p`) get no opinion, so the harness's own prompt or classifier decides.
33
+ function renderConfirm(policy, options) {
34
+ if (options.harness !== 'claude' || options.attended !== true) {
35
+ return noOpinion(options);
36
+ }
37
+ const guidance = policy.mergeGuidance === undefined ? '' : ` ${policy.mergeGuidance}`;
38
+ return JSON.stringify({
39
+ hookSpecificOutput: {
40
+ hookEventName: 'PreToolUse',
41
+ permissionDecision: 'allow',
42
+ permissionDecisionReason: `Interactive merge: proceeding on the human decision already made in this session.${guidance}`,
43
+ },
44
+ });
45
+ }
@@ -0,0 +1,17 @@
1
+ export type HookIo = {
2
+ readStdin: () => Promise<string>;
3
+ stdout: {
4
+ write(text: string): unknown;
5
+ };
6
+ stderr: {
7
+ write(text: string): unknown;
8
+ };
9
+ env: NodeJS.ProcessEnv;
10
+ cwd: string;
11
+ };
12
+ /**
13
+ * `vouchington hook <event> --harness <h> --policy <module>`. Pre-tool-use fails closed (exit 2) when
14
+ * its policy cannot load, because the gates it enforces are a security boundary; post-tool-use is
15
+ * advisory and always exits 0. Bad arguments exit 2 before anything is read.
16
+ */
17
+ export declare function runHook(args: readonly string[], io: HookIo): Promise<number>;
@@ -0,0 +1,69 @@
1
+ import { resolve } from 'node:path';
2
+ import { hookCwd } from "../payload.mjs";
3
+ import { parseHookArgs } from "./args.mjs";
4
+ import { isAttendedClaudeSession, isAutomationContext, parseHookPayload, resolveHarness, } from "./harness.mjs";
5
+ import { loadHookPolicy } from "./policy-module.mjs";
6
+ import { postToolUseOutput } from "./post-tool-use.mjs";
7
+ import { preToolUseOutput } from "./pre-tool-use.mjs";
8
+ /**
9
+ * `vouchington hook <event> --harness <h> --policy <module>`. Pre-tool-use fails closed (exit 2) when
10
+ * its policy cannot load, because the gates it enforces are a security boundary; post-tool-use is
11
+ * advisory and always exits 0. Bad arguments exit 2 before anything is read.
12
+ */
13
+ export async function runHook(args, io) {
14
+ let parsed;
15
+ try {
16
+ parsed = parseHookArgs(args);
17
+ }
18
+ catch (error) {
19
+ io.stderr.write(`${error.message}\n`);
20
+ // Post-tool-use is advisory: an argument typo must not reject an already-completed tool call.
21
+ return args[0] === 'post-tool-use' ? 0 : 2;
22
+ }
23
+ const blocking = parsed.event === 'pre-tool-use';
24
+ try {
25
+ const payload = parseHookPayload(await io.readStdin(), blocking);
26
+ const context = {
27
+ harness: resolveHarness(parsed.harness, io.env, payload),
28
+ payload,
29
+ env: io.env,
30
+ root: resolve(io.cwd, parsed.root ?? '.'),
31
+ };
32
+ const policy = await loadHookPolicy(parsed.policy, context);
33
+ await runOnPayload(policy, context, io);
34
+ if (blocking) {
35
+ const result = preToolUseOutput(payload, policy.command, {
36
+ harness: context.harness,
37
+ attended: isAttendedClaudeSession(io.env),
38
+ automationContext: isAutomationContext(io.env, parsed.automationEnv),
39
+ // The configured root, not the hook process's directory, when the payload names none.
40
+ cwd: hookCwd(payload, context.root),
41
+ });
42
+ if (result.stdout !== '')
43
+ io.stdout.write(result.stdout);
44
+ if (result.stderr !== '')
45
+ io.stderr.write(result.stderr);
46
+ return result.exitCode;
47
+ }
48
+ const output = await postToolUseOutput(context, policy);
49
+ if (output !== '')
50
+ io.stdout.write(output);
51
+ return 0;
52
+ }
53
+ catch (error) {
54
+ const message = error instanceof Error ? error.message : String(error);
55
+ io.stderr.write(`vouchington hook ${parsed.event}: ${message}\n`);
56
+ return blocking ? 2 : 0;
57
+ }
58
+ }
59
+ // A failing side effect (for example persisting a session id) is reported, never allowed to
60
+ // suppress the command policy or the post-tool-use checks.
61
+ async function runOnPayload(policy, context, io) {
62
+ try {
63
+ await policy.onPayload?.(context);
64
+ }
65
+ catch (error) {
66
+ const message = error instanceof Error ? error.message : String(error);
67
+ io.stderr.write(`vouchington hook: onPayload failed: ${message}\n`);
68
+ }
69
+ }
@@ -0,0 +1,33 @@
1
+ import type { CommandPolicy, HookPayload } from '../types.mts';
2
+ export declare const HOOK_HARNESSES: readonly ["claude", "codex", "cursor", "grok"];
3
+ export type HookHarness = (typeof HOOK_HARNESSES)[number];
4
+ export type HookContext = {
5
+ harness: HookHarness;
6
+ payload: HookPayload;
7
+ env: NodeJS.ProcessEnv;
8
+ /** Repository root: `--root`, else the hook process's working directory. */
9
+ root: string;
10
+ };
11
+ export type PostToolUseWarning = {
12
+ level: 'warn' | 'error';
13
+ message: string;
14
+ };
15
+ /** A file check run after an Edit/Write. `filePath` is as the tool reported it. */
16
+ export type PostToolUseChecker = {
17
+ matches: (filePath: string, root: string) => boolean;
18
+ check: (filePath: string, root: string) => PostToolUseWarning[];
19
+ };
20
+ /** What a `--policy <module>` exports, as its default export or a function returning it. */
21
+ export type HookPolicy = {
22
+ /** Rule table for `pre-tool-use`. Without it the hook has no opinion. */
23
+ command?: CommandPolicy;
24
+ /** File checks for `post-tool-use`. */
25
+ checkers?: readonly PostToolUseChecker[];
26
+ /** Extra context for the model after a tool call, or nothing. Must not throw to matter. */
27
+ reminder?: (context: HookContext) => string | null | undefined | Promise<string | null | undefined>;
28
+ /** Runs first on both events, for example to persist the harness session id. */
29
+ onPayload?: (context: HookContext) => void | Promise<void>;
30
+ };
31
+ export type HookPolicyExport = HookPolicy | ((context: HookContext) => HookPolicy | Promise<HookPolicy>);
32
+ /** Identity helper that types a policy module's default export. */
33
+ export declare function defineHookPolicy<T extends HookPolicyExport>(policy: T): T;
@@ -0,0 +1,5 @@
1
+ export const HOOK_HARNESSES = ['claude', 'codex', 'cursor', 'grok'];
2
+ /** Identity helper that types a policy module's default export. */
3
+ export function defineHookPolicy(policy) {
4
+ return policy;
5
+ }
@@ -0,0 +1,29 @@
1
+ export { evaluateCommandPolicy } from './engine.mts';
2
+ export { parseHookArgs } from './hook/args.mts';
3
+ export { isAttendedClaudeSession, isAutomationContext, normalizeCursorShellPayload, parseHookPayload, resolveHarness, } from './hook/harness.mts';
4
+ export { loadHookPolicy } from './hook/policy-module.mts';
5
+ export { checkFile, postToolUseOutput } from './hook/post-tool-use.mts';
6
+ export { preToolUseOutput } from './hook/pre-tool-use.mts';
7
+ export type { PreToolUseOptions, PreToolUseResult } from './hook/pre-tool-use.mts';
8
+ export { runHook } from './hook/run.mts';
9
+ export type { HookIo } from './hook/run.mts';
10
+ export { HOOK_HARNESSES, defineHookPolicy } from './hook/types.mts';
11
+ export type { HookContext, HookHarness, HookPolicy, HookPolicyExport, PostToolUseChecker, PostToolUseWarning, } from './hook/types.mts';
12
+ export { PLAIN_FORCE_PUSH_REASON, findBlockedPatternReason, standardGitPatterns, } from './git-patterns.mts';
13
+ export { defaultGitProbe } from './git-process.mts';
14
+ export { checkoutOwner, checkoutOwners, githubOwner, ownerOfRepoSelector, sessionHomeOwners, } from './github-checkout-owners.mts';
15
+ export { commandsToInspectForGitHubPolicy } from './github-command-context.mts';
16
+ export { commandCwd } from './github-command-cwd.mts';
17
+ export { commandPrefixAt, commandSegmentStart } from './github-command-position.mts';
18
+ export { configuredPullRequestBase, findHandRolledStackBaseBlock, } from './github-configured-base.mts';
19
+ export { parseGhInvocation, parseGhOrGhStackInvocation } from './github-invocation.mts';
20
+ export type { GhInvocation } from './github-invocation.mts';
21
+ export { findAutomationMergeBlock, findInteractiveMergeConfirm, isLoneMergeCommand, } from './github-merge-authority.mts';
22
+ export { hasNamedFlag, hasNumericPrSelector, lastNamedOption } from './github-option-flags.mts';
23
+ export { isGhCommandSeparator, parseGhOptions } from './github-options.mts';
24
+ export type { GhOptions } from './github-options.mts';
25
+ export { findGitHubStackWorkflowBlock } from './github-stack-workflow.mts';
26
+ export { findGitHubWorkflowBlock } from './github-workflow.mts';
27
+ export { extractToolCommand, hookCwd, hookFilePath, hookSessionId, hookToolInput, hookToolName, } from './payload.mts';
28
+ export { findPathTypo, protectedPathMatch, referencesProtectedPath } from './path-rules.mts';
29
+ export type { BlockDecision, CommandPolicy, EvaluateOptions, GitProbe, HookPayload, PathTypoRule, PatternRule, ProtectedPaths, StackPolicy, } from './types.mts';
@@ -0,0 +1,23 @@
1
+ export { evaluateCommandPolicy } from "./engine.mjs";
2
+ export { parseHookArgs } from "./hook/args.mjs";
3
+ export { isAttendedClaudeSession, isAutomationContext, normalizeCursorShellPayload, parseHookPayload, resolveHarness, } from "./hook/harness.mjs";
4
+ export { loadHookPolicy } from "./hook/policy-module.mjs";
5
+ export { checkFile, postToolUseOutput } from "./hook/post-tool-use.mjs";
6
+ export { preToolUseOutput } from "./hook/pre-tool-use.mjs";
7
+ export { runHook } from "./hook/run.mjs";
8
+ export { HOOK_HARNESSES, defineHookPolicy } from "./hook/types.mjs";
9
+ export { PLAIN_FORCE_PUSH_REASON, findBlockedPatternReason, standardGitPatterns, } from "./git-patterns.mjs";
10
+ export { defaultGitProbe } from "./git-process.mjs";
11
+ export { checkoutOwner, checkoutOwners, githubOwner, ownerOfRepoSelector, sessionHomeOwners, } from "./github-checkout-owners.mjs";
12
+ export { commandsToInspectForGitHubPolicy } from "./github-command-context.mjs";
13
+ export { commandCwd } from "./github-command-cwd.mjs";
14
+ export { commandPrefixAt, commandSegmentStart } from "./github-command-position.mjs";
15
+ export { configuredPullRequestBase, findHandRolledStackBaseBlock, } from "./github-configured-base.mjs";
16
+ export { parseGhInvocation, parseGhOrGhStackInvocation } from "./github-invocation.mjs";
17
+ export { findAutomationMergeBlock, findInteractiveMergeConfirm, isLoneMergeCommand, } from "./github-merge-authority.mjs";
18
+ export { hasNamedFlag, hasNumericPrSelector, lastNamedOption } from "./github-option-flags.mjs";
19
+ export { isGhCommandSeparator, parseGhOptions } from "./github-options.mjs";
20
+ export { findGitHubStackWorkflowBlock } from "./github-stack-workflow.mjs";
21
+ export { findGitHubWorkflowBlock } from "./github-workflow.mjs";
22
+ export { extractToolCommand, hookCwd, hookFilePath, hookSessionId, hookToolInput, hookToolName, } from "./payload.mjs";
23
+ export { findPathTypo, protectedPathMatch, referencesProtectedPath } from "./path-rules.mjs";
@@ -0,0 +1,14 @@
1
+ import type { HookPayload } from './types.mts';
2
+ /**
3
+ * The files an apply_patch leaves behind: added files and move destinations, plus updated files
4
+ * that are not moved. Deleted files and the pre-move side of a move are gone afterwards.
5
+ */
6
+ export declare function patchResultPaths(patch: string): string[];
7
+ /**
8
+ * Whether a path-shaped reference in the payload or the command satisfies `matches`: the payload's
9
+ * path-like string fields, an apply_patch's header lines, and the command's shell words. The
10
+ * command's own `command` field is read as shell text, never as a field value.
11
+ */
12
+ export declare function referencesPath(payload: HookPayload, command: string, matches: (token: string) => boolean, options?: {
13
+ splitRedirections?: boolean;
14
+ }): boolean;
@@ -0,0 +1,68 @@
1
+ import { tokenizeShellWords } from "../shell-parse/index.mjs";
2
+ import { commandsToInspectForGitHubPolicy } from "./github-command-context.mjs";
3
+ import { isRecord } from "./payload.mjs";
4
+ const PATCH_BEGIN = '*** Begin Patch';
5
+ const PATCH_HEADER_PREFIX = /^(?:\*\*\* (?:Add|Delete|Update) File:|\*\*\* Move to:)\s+/;
6
+ const KEY_PATH_LIKE_RE = /(?:^|_)(?:cwd|file|filename|path|workdir|workspace)(?:_|$)/i;
7
+ function keyLooksPathLike(key) {
8
+ const snake = key.replaceAll(/[A-Z]/g, (match) => `_${match.toLowerCase()}`);
9
+ return KEY_PATH_LIKE_RE.test(snake);
10
+ }
11
+ /** Header lines name the files an apply_patch touches; body text that mentions a path does not. */
12
+ function patchHeaderPaths(patch) {
13
+ return patch
14
+ .split('\n')
15
+ .filter((line) => PATCH_HEADER_PREFIX.test(line))
16
+ .map((line) => line.replace(PATCH_HEADER_PREFIX, ''));
17
+ }
18
+ /**
19
+ * The files an apply_patch leaves behind: added files and move destinations, plus updated files
20
+ * that are not moved. Deleted files and the pre-move side of a move are gone afterwards.
21
+ */
22
+ export function patchResultPaths(patch) {
23
+ const lines = patch.split('\n').filter((line) => PATCH_HEADER_PREFIX.test(line));
24
+ return lines.flatMap((line, index) => {
25
+ const path = line.replace(PATCH_HEADER_PREFIX, '');
26
+ if (line.startsWith('*** Delete File:'))
27
+ return [];
28
+ const moved = lines[index + 1]?.startsWith('*** Move to:') === true;
29
+ return line.startsWith('*** Update File:') && moved ? [] : [path];
30
+ });
31
+ }
32
+ /**
33
+ * Whether a path-shaped reference in the payload or the command satisfies `matches`: the payload's
34
+ * path-like string fields, an apply_patch's header lines, and the command's shell words. The
35
+ * command's own `command` field is read as shell text, never as a field value.
36
+ */
37
+ export function referencesPath(payload, command, matches, options = {}) {
38
+ return valueReferences(payload, matches) || commandReferences(command, matches, options);
39
+ }
40
+ function commandReferences(command, matches, options) {
41
+ if (command.trimStart().startsWith(PATCH_BEGIN)) {
42
+ return patchHeaderPaths(command).some(matches);
43
+ }
44
+ // `apply_patch <<'EOF'` carries its patch in a data heredoc that shell scanning blanks out.
45
+ if (command.includes(PATCH_BEGIN) &&
46
+ tokenizeShellWords(command, { splitRedirections: true }).includes('apply_patch') &&
47
+ patchHeaderPaths(command).some(matches)) {
48
+ return true;
49
+ }
50
+ // Without splitRedirections a no-space redirect like `>dir/file` stays fused to its operator.
51
+ // Nested scripts (`sh -c`, substitutions, heredoc shell bodies) are read like the outer command.
52
+ return commandsToInspectForGitHubPolicy(command).some((script) => tokenizeShellWords(script, options).some(matches));
53
+ }
54
+ function valueReferences(value, matches, key) {
55
+ if (typeof value === 'string') {
56
+ if (value.startsWith(PATCH_BEGIN)) {
57
+ return patchHeaderPaths(value).some(matches);
58
+ }
59
+ return key !== undefined && keyLooksPathLike(key) && matches(value);
60
+ }
61
+ if (Array.isArray(value)) {
62
+ return value.some((nested) => valueReferences(nested, matches, key));
63
+ }
64
+ if (!isRecord(value)) {
65
+ return false;
66
+ }
67
+ return Object.entries(value).some(([nestedKey, nested]) => nestedKey !== 'command' && valueReferences(nested, matches, nestedKey));
68
+ }
@@ -0,0 +1,11 @@
1
+ import type { HookPayload, PathTypoRule, ProtectedPaths } from './types.mts';
2
+ /** The first typo rule the payload or command references, or undefined. */
3
+ export declare function findPathTypo(payload: HookPayload, command: string, rules: readonly PathTypoRule[]): PathTypoRule | undefined;
4
+ /**
5
+ * Whether `rawToken` names a protected file or directory. Dot segments collapse
6
+ * (`dir/./hooks/x` -> `dir/hooks/x`) so redundant path noise cannot hide a literal match. The match
7
+ * is deliberately not resolved against the command's cwd, so a `cd` plus a relative path is the
8
+ * indirection this check does not catch.
9
+ */
10
+ export declare function protectedPathMatch(rawToken: string, protectedPaths: ProtectedPaths): boolean;
11
+ export declare function referencesProtectedPath(payload: HookPayload, command: string, protectedPaths: ProtectedPaths): boolean;
@@ -0,0 +1,37 @@
1
+ import { posix } from 'node:path';
2
+ import { referencesPath } from "./path-references.mjs";
3
+ /** True when `token` is the segment, or has it as a leading, trailing, or interior path segment. */
4
+ function tokenReferencesSegment(token, segment) {
5
+ return (token === segment ||
6
+ token.startsWith(`${segment}/`) ||
7
+ token.endsWith(`/${segment}`) ||
8
+ token.includes(`/${segment}/`));
9
+ }
10
+ /** The first typo rule the payload or command references, or undefined. */
11
+ export function findPathTypo(payload, command, rules) {
12
+ return rules.find((rule) => referencesPath(payload, command, (token) => tokenReferencesSegment(token, rule.segment)));
13
+ }
14
+ /**
15
+ * Whether `rawToken` names a protected file or directory. Dot segments collapse
16
+ * (`dir/./hooks/x` -> `dir/hooks/x`) so redundant path noise cannot hide a literal match. The match
17
+ * is deliberately not resolved against the command's cwd, so a `cd` plus a relative path is the
18
+ * indirection this check does not catch.
19
+ */
20
+ export function protectedPathMatch(rawToken, protectedPaths) {
21
+ const token = rawToken === '' ? rawToken : posix.normalize(rawToken);
22
+ if (protectedPaths.exactFiles.some((file) => token === file || token.endsWith(`/${file}`))) {
23
+ return true;
24
+ }
25
+ return protectedPaths.dirPrefixes.some((prefix) => {
26
+ const bareDir = prefix.slice(0, -1);
27
+ return (token === bareDir ||
28
+ token.startsWith(prefix) ||
29
+ token.endsWith(`/${bareDir}`) ||
30
+ token.includes(`/${prefix}`));
31
+ });
32
+ }
33
+ export function referencesProtectedPath(payload, command, protectedPaths) {
34
+ return referencesPath(payload, command, (token) => protectedPathMatch(token, protectedPaths), {
35
+ splitRedirections: true,
36
+ });
37
+ }
@@ -0,0 +1,8 @@
1
+ import type { HookPayload } from './types.mts';
2
+ export declare function isRecord(value: unknown): value is Record<string, unknown>;
3
+ export declare function hookToolInput(payload: HookPayload): Record<string, unknown> | undefined;
4
+ export declare function extractToolCommand(payload: HookPayload): string;
5
+ export declare function hookToolName(payload: HookPayload): string;
6
+ export declare function hookSessionId(payload: HookPayload): string;
7
+ export declare function hookFilePath(payload: HookPayload): string;
8
+ export declare function hookCwd(payload: HookPayload, fallback?: string): string;
@@ -0,0 +1,54 @@
1
+ export function isRecord(value) {
2
+ return typeof value === 'object' && value !== null;
3
+ }
4
+ export function hookToolInput(payload) {
5
+ if (isRecord(payload.tool_input))
6
+ return payload.tool_input;
7
+ if (isRecord(payload.toolInput))
8
+ return payload.toolInput;
9
+ return undefined;
10
+ }
11
+ export function extractToolCommand(payload) {
12
+ const toolInput = hookToolInput(payload);
13
+ if (toolInput && typeof toolInput.command === 'string')
14
+ return toolInput.command;
15
+ if (typeof payload.command === 'string')
16
+ return payload.command;
17
+ return '';
18
+ }
19
+ function firstString(values) {
20
+ for (const value of values) {
21
+ if (typeof value === 'string' && value.trim() !== '')
22
+ return value.trim();
23
+ }
24
+ return '';
25
+ }
26
+ export function hookToolName(payload) {
27
+ return firstString([payload.tool_name, payload.toolName]);
28
+ }
29
+ export function hookSessionId(payload) {
30
+ return firstString([payload.session_id, payload.sessionId, payload.conversation_id]);
31
+ }
32
+ export function hookFilePath(payload) {
33
+ if (typeof payload.file_path === 'string' && payload.file_path !== '')
34
+ return payload.file_path;
35
+ if (typeof payload.filePath === 'string' && payload.filePath !== '')
36
+ return payload.filePath;
37
+ const toolInput = hookToolInput(payload);
38
+ if (!toolInput)
39
+ return '';
40
+ for (const key of ['file_path', 'filePath', 'path']) {
41
+ const value = toolInput[key];
42
+ if (typeof value === 'string' && value !== '')
43
+ return value;
44
+ }
45
+ return '';
46
+ }
47
+ export function hookCwd(payload, fallback = process.cwd()) {
48
+ const toolInput = hookToolInput(payload);
49
+ for (const value of [toolInput?.cwd, toolInput?.workdir, payload.cwd, payload.workspaceRoot]) {
50
+ if (typeof value === 'string' && value !== '')
51
+ return value;
52
+ }
53
+ return fallback;
54
+ }
@@ -0,0 +1,77 @@
1
+ export type HookPayload = {
2
+ tool_input?: unknown;
3
+ toolInput?: unknown;
4
+ session_id?: unknown;
5
+ sessionId?: unknown;
6
+ conversation_id?: unknown;
7
+ tool_name?: unknown;
8
+ toolName?: unknown;
9
+ command?: unknown;
10
+ cwd?: unknown;
11
+ workspaceRoot?: unknown;
12
+ [key: string]: unknown;
13
+ };
14
+ export type BlockDecision = {
15
+ reason: string;
16
+ /**
17
+ * 'block' (the default when omitted) rejects the tool call outright. 'confirm' marks an
18
+ * interactive lone merge, which a caller may render as a silent allow in an attended session.
19
+ * Only `findInteractiveMergeConfirm` produces 'confirm', and the engine consults it after every
20
+ * block, so a block anywhere in the command always wins.
21
+ */
22
+ disposition?: 'block' | 'confirm';
23
+ };
24
+ export type PatternRule = {
25
+ pattern: RegExp;
26
+ reason: string;
27
+ };
28
+ /** Paths that automation must not write. Directory prefixes end in `/`. */
29
+ export type ProtectedPaths = {
30
+ dirPrefixes: readonly string[];
31
+ exactFiles: readonly string[];
32
+ reason: string;
33
+ };
34
+ /** A mistyped path segment (for example a misspelled dot-directory) and the reason to refuse it. */
35
+ export type PathTypoRule = {
36
+ segment: string;
37
+ reason: string;
38
+ };
39
+ /** Read-only git probes; every one returns undefined when git cannot answer. */
40
+ export type GitProbe = {
41
+ currentBranch(cwd: string): string | undefined;
42
+ configValue(cwd: string, key: string): string | undefined;
43
+ isAncestor(cwd: string, ancestor: string, descendant: string): boolean | undefined;
44
+ resolveRef(cwd: string, ref: string): string | undefined;
45
+ };
46
+ export type StackPolicy = {
47
+ /** Branch a stack must root on and a PR must target. Defaults to `main`. */
48
+ baseBranch?: string;
49
+ /** Remote whose `<remote>/<baseBranch>` HEAD must descend from. Defaults to `origin`. */
50
+ remote?: string;
51
+ /** Appended to stack reasons, for example a pointer to the repository's stacking skill. */
52
+ guidance?: string;
53
+ /** What to do after a draft PR opens, for example the description tool to call. */
54
+ draftFollowUp?: string;
55
+ /** Probe override for tests and sandboxes. */
56
+ git?: GitProbe;
57
+ };
58
+ export type CommandPolicy = {
59
+ typoPaths?: readonly PathTypoRule[];
60
+ protectedPaths?: ProtectedPaths;
61
+ /** Tested against every command and nested script, before the git rules. */
62
+ commandPatterns?: readonly PatternRule[];
63
+ /** Tested against nested scripts, only when the command mentions git. */
64
+ gitPatterns?: readonly PatternRule[];
65
+ /** Reason for an interactive `git rebase --continue`; omit to allow it. */
66
+ rebaseContinueReason?: string;
67
+ /** Appended to merge reasons, for example a pointer to the merge-authority document. */
68
+ mergeGuidance?: string;
69
+ /** GitHub stack rules apply only when this is present. */
70
+ stack?: StackPolicy;
71
+ };
72
+ export type EvaluateOptions = {
73
+ /** Whether the call runs in unattended automation. Defaults to true, the strict choice. */
74
+ automationContext?: boolean;
75
+ /** Directory the call runs in. Defaults to the payload's own, else `process.cwd()`. */
76
+ cwd?: string;
77
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,19 @@
1
+ export type FindingIdentity = {
2
+ category: string;
3
+ path: string;
4
+ parent: string;
5
+ name: string;
6
+ symbolKind: string;
7
+ };
8
+ export type BaselineRow = FindingIdentity & {
9
+ count: number;
10
+ };
11
+ export declare function rowsFromReport(value: unknown, include?: (finding: FindingIdentity, raw: Record<string, unknown>) => boolean): BaselineRow[];
12
+ export declare function parseBaseline(value: unknown): BaselineRow[];
13
+ export declare function compareRows(current: readonly BaselineRow[], baseline: readonly BaselineRow[]): {
14
+ added: BaselineRow[];
15
+ stale: BaselineRow[];
16
+ };
17
+ export declare function readBaseline(path: string): Promise<BaselineRow[]>;
18
+ export declare function writeBaseline(path: string, rows: readonly BaselineRow[]): Promise<void>;
19
+ export declare function reconcileBaseline(path: string, current: readonly BaselineRow[], operation: 'check' | 'seed' | 'update'): Promise<number>;