vouchington-tooling 0.59.0 → 0.61.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 (141) hide show
  1. package/README.md +108 -0
  2. package/dist/cli/commands/hook.d.mts +2 -0
  3. package/dist/cli/commands/hook.mjs +19 -0
  4. package/dist/cli/commands/sandbox-command-audit.d.mts +7 -0
  5. package/dist/cli/commands/sandbox-command-audit.mjs +27 -0
  6. package/dist/cli/index.mjs +8 -0
  7. package/dist/cli/parse-forwarded-commands.d.mts +9 -0
  8. package/dist/cli/parse-forwarded-commands.mjs +6 -0
  9. package/dist/cli/parse.d.mts +9 -0
  10. package/dist/cli/usage-text.d.mts +1 -0
  11. package/dist/cli/usage-text.mjs +179 -0
  12. package/dist/cli/usage.d.mts +2 -1
  13. package/dist/cli/usage.mjs +2 -156
  14. package/dist/command-policy/engine.d.mts +7 -0
  15. package/dist/command-policy/engine.mjs +58 -0
  16. package/dist/command-policy/git-patterns.d.mts +20 -0
  17. package/dist/command-policy/git-patterns.mjs +82 -0
  18. package/dist/command-policy/git-process.d.mts +4 -0
  19. package/dist/command-policy/git-process.mjs +54 -0
  20. package/dist/command-policy/github-checkout-owners.d.mts +22 -0
  21. package/dist/command-policy/github-checkout-owners.mjs +122 -0
  22. package/dist/command-policy/github-command-context.d.mts +6 -0
  23. package/dist/command-policy/github-command-context.mjs +19 -0
  24. package/dist/command-policy/github-command-cwd.d.mts +8 -0
  25. package/dist/command-policy/github-command-cwd.mjs +130 -0
  26. package/dist/command-policy/github-command-position.d.mts +7 -0
  27. package/dist/command-policy/github-command-position.mjs +12 -0
  28. package/dist/command-policy/github-configured-base.d.mts +25 -0
  29. package/dist/command-policy/github-configured-base.mjs +59 -0
  30. package/dist/command-policy/github-invocation.d.mts +9 -0
  31. package/dist/command-policy/github-invocation.mjs +80 -0
  32. package/dist/command-policy/github-merge-authority.d.mts +21 -0
  33. package/dist/command-policy/github-merge-authority.mjs +86 -0
  34. package/dist/command-policy/github-option-flags.d.mts +3 -0
  35. package/dist/command-policy/github-option-flags.mjs +67 -0
  36. package/dist/command-policy/github-options.d.mts +12 -0
  37. package/dist/command-policy/github-options.mjs +73 -0
  38. package/dist/command-policy/github-stack-workflow.d.mts +9 -0
  39. package/dist/command-policy/github-stack-workflow.mjs +94 -0
  40. package/dist/command-policy/github-workflow.d.mts +7 -0
  41. package/dist/command-policy/github-workflow.mjs +50 -0
  42. package/dist/command-policy/hook/args.d.mts +11 -0
  43. package/dist/command-policy/hook/args.mjs +49 -0
  44. package/dist/command-policy/hook/harness.d.mts +26 -0
  45. package/dist/command-policy/hook/harness.mjs +119 -0
  46. package/dist/command-policy/hook/policy-module.d.mts +7 -0
  47. package/dist/command-policy/hook/policy-module.mjs +48 -0
  48. package/dist/command-policy/hook/post-tool-use.d.mts +9 -0
  49. package/dist/command-policy/hook/post-tool-use.mjs +51 -0
  50. package/dist/command-policy/hook/pre-tool-use.d.mts +21 -0
  51. package/dist/command-policy/hook/pre-tool-use.mjs +45 -0
  52. package/dist/command-policy/hook/run.d.mts +17 -0
  53. package/dist/command-policy/hook/run.mjs +69 -0
  54. package/dist/command-policy/hook/types.d.mts +33 -0
  55. package/dist/command-policy/hook/types.mjs +5 -0
  56. package/dist/command-policy/index.d.mts +29 -0
  57. package/dist/command-policy/index.mjs +23 -0
  58. package/dist/command-policy/path-references.d.mts +14 -0
  59. package/dist/command-policy/path-references.mjs +68 -0
  60. package/dist/command-policy/path-rules.d.mts +11 -0
  61. package/dist/command-policy/path-rules.mjs +37 -0
  62. package/dist/command-policy/payload.d.mts +8 -0
  63. package/dist/command-policy/payload.mjs +54 -0
  64. package/dist/command-policy/types.d.mts +77 -0
  65. package/dist/command-policy/types.mjs +1 -0
  66. package/dist/index.d.mts +2 -0
  67. package/dist/index.mjs +1 -0
  68. package/dist/sandbox-command-audit/args.d.mts +20 -0
  69. package/dist/sandbox-command-audit/args.mjs +64 -0
  70. package/dist/sandbox-command-audit/classify-prefixes.d.mts +23 -0
  71. package/dist/sandbox-command-audit/classify-prefixes.mjs +50 -0
  72. package/dist/sandbox-command-audit/classify.d.mts +46 -0
  73. package/dist/sandbox-command-audit/classify.mjs +74 -0
  74. package/dist/sandbox-command-audit/claude-extract.d.mts +23 -0
  75. package/dist/sandbox-command-audit/claude-extract.mjs +76 -0
  76. package/dist/sandbox-command-audit/claude-tool-uses.d.mts +15 -0
  77. package/dist/sandbox-command-audit/claude-tool-uses.mjs +53 -0
  78. package/dist/sandbox-command-audit/codex-extract.d.mts +21 -0
  79. package/dist/sandbox-command-audit/codex-extract.mjs +77 -0
  80. package/dist/sandbox-command-audit/codex-scan.d.mts +11 -0
  81. package/dist/sandbox-command-audit/codex-scan.mjs +98 -0
  82. package/dist/sandbox-command-audit/codex-spool.d.mts +14 -0
  83. package/dist/sandbox-command-audit/codex-spool.mjs +46 -0
  84. package/dist/sandbox-command-audit/discover-files.d.mts +44 -0
  85. package/dist/sandbox-command-audit/discover-files.mjs +85 -0
  86. package/dist/sandbox-command-audit/failure-text.d.mts +7 -0
  87. package/dist/sandbox-command-audit/failure-text.mjs +34 -0
  88. package/dist/sandbox-command-audit/fixtures.test-helpers.d.mts +34 -0
  89. package/dist/sandbox-command-audit/fixtures.test-helpers.mjs +41 -0
  90. package/dist/sandbox-command-audit/index.d.mts +26 -0
  91. package/dist/sandbox-command-audit/index.mjs +15 -0
  92. package/dist/sandbox-command-audit/json-record.d.mts +6 -0
  93. package/dist/sandbox-command-audit/json-record.mjs +16 -0
  94. package/dist/sandbox-command-audit/limits.d.mts +30 -0
  95. package/dist/sandbox-command-audit/limits.mjs +66 -0
  96. package/dist/sandbox-command-audit/repo-scope.d.mts +25 -0
  97. package/dist/sandbox-command-audit/repo-scope.mjs +79 -0
  98. package/dist/sandbox-command-audit/report-raw.d.mts +16 -0
  99. package/dist/sandbox-command-audit/report-raw.mjs +55 -0
  100. package/dist/sandbox-command-audit/report.d.mts +10 -0
  101. package/dist/sandbox-command-audit/report.mjs +61 -0
  102. package/dist/sandbox-command-audit/run.d.mts +36 -0
  103. package/dist/sandbox-command-audit/run.mjs +70 -0
  104. package/dist/sandbox-command-audit/scan.d.mts +10 -0
  105. package/dist/sandbox-command-audit/scan.mjs +79 -0
  106. package/dist/sandbox-command-audit/transcript-cwd.d.mts +14 -0
  107. package/dist/sandbox-command-audit/transcript-cwd.mjs +153 -0
  108. package/dist/sandbox-command-audit/types.d.mts +59 -0
  109. package/dist/sandbox-command-audit/types.mjs +23 -0
  110. package/dist/tmux/cli-shared.d.mts +18 -0
  111. package/dist/tmux/cli-shared.mjs +8 -0
  112. package/dist/tmux/cli.d.mts +3 -0
  113. package/dist/tmux/cli.mjs +34 -0
  114. package/dist/tmux/config.d.mts +24 -0
  115. package/dist/tmux/config.mjs +91 -0
  116. package/dist/tmux/fake-tmux.test-helpers.d.mts +46 -0
  117. package/dist/tmux/fake-tmux.test-helpers.mjs +105 -0
  118. package/dist/tmux/hook-payload.d.mts +8 -0
  119. package/dist/tmux/hook-payload.mjs +39 -0
  120. package/dist/tmux/index.d.mts +9 -0
  121. package/dist/tmux/index.mjs +7 -0
  122. package/dist/tmux/launcher.d.mts +11 -0
  123. package/dist/tmux/launcher.mjs +127 -0
  124. package/dist/tmux/reminder-post-tool.d.mts +21 -0
  125. package/dist/tmux/reminder-post-tool.mjs +88 -0
  126. package/dist/tmux/runner.d.mts +11 -0
  127. package/dist/tmux/runner.mjs +26 -0
  128. package/dist/tmux/session-name.d.mts +5 -0
  129. package/dist/tmux/session-name.mjs +10 -0
  130. package/dist/tmux/shell-quote.d.mts +9 -0
  131. package/dist/tmux/shell-quote.mjs +16 -0
  132. package/dist/tmux/up.d.mts +2 -0
  133. package/dist/tmux/up.mjs +73 -0
  134. package/dist/tmux/windows.d.mts +18 -0
  135. package/dist/tmux/windows.mjs +50 -0
  136. package/package.json +16 -1
  137. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  138. package/scripts/tmux/tmux-agent-reminder.sh +68 -0
  139. package/scripts/tmux/tmux-name.sh +34 -0
  140. package/scripts/tmux/tmux-read-title.sh +13 -0
  141. package/scripts/tmux/tmux-target.sh +130 -0
@@ -0,0 +1,130 @@
1
+ import { isAbsolute, resolve } from 'node:path';
2
+ import { commandPrefixAt, commandSegmentStart } from "./github-command-position.mjs";
3
+ import { isShellCommandSeparator, nextShellCommandSeparatorIndex, } from "../shell-parse/index.mjs";
4
+ const CD_JOINERS = new Set(['&&', ';', '\n', '(']);
5
+ const CONDITIONAL_PREFIXES = new Set(['then', 'else', 'elif', 'do']);
6
+ const UNRESOLVED_DIRECTORY = /[$`~*?[{]/;
7
+ // Wrappers that still run the shell's own `cd` builtin; the rest exec a separate `cd` process
8
+ // whose directory change dies with it.
9
+ const BUILTIN_CD_WRAPPERS = new Set(['builtin', 'command', 'time']);
10
+ /**
11
+ * Working directory the `gh` token at `index` would see after sequential
12
+ * command-local `cd` and its own `env -C` wrappers. `baseCwd` is session
13
+ * `hookCwd`. Returns `undefined` when cwd is unknown so callers fail open
14
+ * instead of using the session checkout. Absolute `cd` after `&&`/`;` and an
15
+ * absolute `env -C` recover a known directory.
16
+ */
17
+ export function commandCwd(tokens, index, baseCwd) {
18
+ const shellCwd = sequentialShellCwd(tokens, index, baseCwd);
19
+ const prefix = commandPrefixAt(tokens, index);
20
+ return prefix === null ? shellCwd : applyEnvChdir(prefix, shellCwd);
21
+ }
22
+ function applyEnvChdir(prefix, shellCwd) {
23
+ let current = shellCwd;
24
+ for (const directory of prefix.chdir) {
25
+ if (UNRESOLVED_DIRECTORY.test(directory))
26
+ return undefined;
27
+ if (isAbsolute(directory))
28
+ current = resolve(directory);
29
+ else
30
+ current = current === undefined ? undefined : resolve(current, directory);
31
+ }
32
+ return current;
33
+ }
34
+ function sequentialShellCwd(tokens, index, baseCwd) {
35
+ const stack = [baseCwd];
36
+ let functionDepth = 0;
37
+ for (let cursor = 0; cursor < index; cursor += 1) {
38
+ const token = tokens[cursor];
39
+ if (token === '{') {
40
+ // Inside a function body every nested `{` also opens a group, so its `}` must not end the body.
41
+ if (functionDepth > 0 || tokens[cursor - 1] === ')' || tokens[cursor - 2] === 'function') {
42
+ functionDepth += 1;
43
+ }
44
+ continue;
45
+ }
46
+ if (token === '}') {
47
+ if (functionDepth > 0)
48
+ functionDepth -= 1;
49
+ continue;
50
+ }
51
+ if (token === '(') {
52
+ stack.push(stack.at(-1));
53
+ continue;
54
+ }
55
+ if (token === ')') {
56
+ if (stack.length > 1)
57
+ stack.pop();
58
+ continue;
59
+ }
60
+ if (functionDepth > 0)
61
+ continue;
62
+ if (token !== 'cd' || !runsBuiltinCd(tokens, cursor))
63
+ continue;
64
+ const joinerIndex = nextShellCommandSeparatorIndex(tokens, cursor);
65
+ const joiner = joinerIndex < tokens.length ? tokens[joinerIndex] : undefined;
66
+ if (joiner === undefined || joinerIndex >= index)
67
+ continue;
68
+ const previous = previousJoiner(tokens, cursor);
69
+ if (previous === '|')
70
+ continue;
71
+ if (joiner === '||' || previous === '||') {
72
+ stack[stack.length - 1] = undefined;
73
+ continue;
74
+ }
75
+ if (!CD_JOINERS.has(joiner))
76
+ continue;
77
+ if (cdIsConditional(tokens, cursor)) {
78
+ stack[stack.length - 1] = undefined;
79
+ continue;
80
+ }
81
+ const directory = cdDirectoryOperand(tokens, cursor);
82
+ if (directory === undefined) {
83
+ stack[stack.length - 1] = undefined;
84
+ continue;
85
+ }
86
+ const current = stack.at(-1);
87
+ if (isAbsolute(directory)) {
88
+ stack[stack.length - 1] = resolve(directory);
89
+ continue;
90
+ }
91
+ stack[stack.length - 1] = current === undefined ? undefined : resolve(current, directory);
92
+ }
93
+ return stack.at(-1);
94
+ }
95
+ function runsBuiltinCd(tokens, cdIndex) {
96
+ const prefix = commandPrefixAt(tokens, cdIndex);
97
+ return prefix !== null && prefix.wrappers.every((wrapper) => BUILTIN_CD_WRAPPERS.has(wrapper));
98
+ }
99
+ function cdIsConditional(tokens, cdIndex) {
100
+ return tokens
101
+ .slice(commandSegmentStart(tokens, cdIndex), cdIndex)
102
+ .some((token) => CONDITIONAL_PREFIXES.has(token));
103
+ }
104
+ function previousJoiner(tokens, index) {
105
+ const start = commandSegmentStart(tokens, index);
106
+ return start > 0 ? tokens[start - 1] : undefined;
107
+ }
108
+ function cdDirectoryOperand(tokens, cdIndex) {
109
+ let operandIndex = cdIndex + 1;
110
+ if (tokens[operandIndex] === '--')
111
+ operandIndex += 1;
112
+ let physical = false;
113
+ while (tokens[operandIndex] === '-P' || tokens[operandIndex] === '-L') {
114
+ if (tokens[operandIndex] === '-P')
115
+ physical = true;
116
+ operandIndex += 1;
117
+ }
118
+ const directory = tokens[operandIndex];
119
+ const rest = tokens[operandIndex + 1];
120
+ if (physical ||
121
+ directory === undefined ||
122
+ isShellCommandSeparator(directory) ||
123
+ directory === '-' ||
124
+ directory.startsWith('-') ||
125
+ UNRESOLVED_DIRECTORY.test(directory) ||
126
+ (rest !== undefined && !isShellCommandSeparator(rest))) {
127
+ return undefined;
128
+ }
129
+ return directory;
130
+ }
@@ -0,0 +1,7 @@
1
+ import { type CommandPrefix } from '../shell-parse/index.mts';
2
+ export declare function commandSegmentStart(tokens: string[], index: number): number;
3
+ /**
4
+ * The wrapper chain before `tokens[index]` in its command segment, or null when `tokens[index]`
5
+ * is an argument rather than the command the shell runs. See shell-command-wrappers.mts.
6
+ */
7
+ export declare function commandPrefixAt(tokens: string[], index: number): CommandPrefix | null;
@@ -0,0 +1,12 @@
1
+ import { isGhCommandSeparator } from "./github-options.mjs";
2
+ import { commandSegmentStart as shellSegmentStart, parseCommandPrefix, } from "../shell-parse/index.mjs";
3
+ export function commandSegmentStart(tokens, index) {
4
+ return shellSegmentStart(tokens, index, isGhCommandSeparator);
5
+ }
6
+ /**
7
+ * The wrapper chain before `tokens[index]` in its command segment, or null when `tokens[index]`
8
+ * is an argument rather than the command the shell runs. See shell-command-wrappers.mts.
9
+ */
10
+ export function commandPrefixAt(tokens, index) {
11
+ return parseCommandPrefix(tokens.slice(commandSegmentStart(tokens, index), index));
12
+ }
@@ -0,0 +1,25 @@
1
+ import type { BlockDecision, GitProbe } from './types.mts';
2
+ export type ResolvedStackPolicy = {
3
+ baseBranch: string;
4
+ remote: string;
5
+ guidance: string;
6
+ draftFollowUp: string;
7
+ git: GitProbe;
8
+ };
9
+ /** Appends the caller's guidance to a reason. */
10
+ export declare function withGuidance(reason: string, guidance: string): string;
11
+ /**
12
+ * Effective base `gh pr create` uses when `--base`/`-B` is omitted:
13
+ * `branch.<current>.gh-merge-base`, else undefined (repo default).
14
+ */
15
+ export declare function configuredPullRequestBase(cwd: string, git: GitProbe): string | undefined;
16
+ /**
17
+ * Root guard for `gh stack init`: a stack rooted off the base branch cannot drain if its parent is
18
+ * ever abandoned. Scoped to `init` only, since `gh stack add` only appends to an existing stack. An
19
+ * explicit `--base` needs no checkout; the HEAD ancestry and local-base freshness checks read
20
+ * `cwd`, so an unknown `cwd` skips just those. gh-stack roots the first layer at the local base
21
+ * branch, never the remote one, so a stale local base misroots the stack even when HEAD passed the
22
+ * ancestry check. A missing local base is fine: gh-stack creates it from the remote.
23
+ */
24
+ export declare function findStackInitBaseBlock(optionTokens: string[], cwd: string | undefined, policy: ResolvedStackPolicy): BlockDecision | null;
25
+ export declare function findHandRolledStackBaseBlock(action: string, optionTokens: string[], cwd: string | undefined, policy: ResolvedStackPolicy): BlockDecision | null;
@@ -0,0 +1,59 @@
1
+ import { lastNamedOption } from "./github-option-flags.mjs";
2
+ /** Appends the caller's guidance to a reason. */
3
+ export function withGuidance(reason, guidance) {
4
+ return guidance === '' ? reason : `${reason} ${guidance}`;
5
+ }
6
+ /**
7
+ * Effective base `gh pr create` uses when `--base`/`-B` is omitted:
8
+ * `branch.<current>.gh-merge-base`, else undefined (repo default).
9
+ */
10
+ export function configuredPullRequestBase(cwd, git) {
11
+ const branch = git.currentBranch(cwd);
12
+ return branch === undefined ? undefined : git.configValue(cwd, `branch.${branch}.gh-merge-base`);
13
+ }
14
+ /**
15
+ * Root guard for `gh stack init`: a stack rooted off the base branch cannot drain if its parent is
16
+ * ever abandoned. Scoped to `init` only, since `gh stack add` only appends to an existing stack. An
17
+ * explicit `--base` needs no checkout; the HEAD ancestry and local-base freshness checks read
18
+ * `cwd`, so an unknown `cwd` skips just those. gh-stack roots the first layer at the local base
19
+ * branch, never the remote one, so a stale local base misroots the stack even when HEAD passed the
20
+ * ancestry check. A missing local base is fine: gh-stack creates it from the remote.
21
+ */
22
+ export function findStackInitBaseBlock(optionTokens, cwd, policy) {
23
+ const { baseBranch, git, guidance, remote } = policy;
24
+ const remoteBase = `${remote}/${baseBranch}`;
25
+ const base = lastNamedOption(optionTokens, 'base', 'b');
26
+ if (base !== undefined && base !== baseBranch) {
27
+ return {
28
+ reason: withGuidance(`gh stack init must root on ${baseBranch}, not an unmerged branch - omit --base/-b (it defaults to the repo default branch) or pass --base ${baseBranch}.`, guidance),
29
+ };
30
+ }
31
+ if (cwd !== undefined && git.isAncestor(cwd, 'HEAD', remoteBase) === false) {
32
+ return {
33
+ reason: withGuidance(`gh stack init must run from a commit already merged into ${remoteBase} (HEAD is not an ancestor of ${remoteBase}) - check out an up-to-date ${baseBranch} before initializing a stack.`, guidance),
34
+ };
35
+ }
36
+ const localBase = cwd === undefined ? undefined : git.resolveRef(cwd, `refs/heads/${baseBranch}`);
37
+ const remoteHead = cwd === undefined ? undefined : git.resolveRef(cwd, `refs/remotes/${remote}/${baseBranch}`);
38
+ if (localBase !== undefined && remoteHead !== undefined && localBase !== remoteHead) {
39
+ return {
40
+ reason: withGuidance(`gh stack init roots the stack at local \`${baseBranch}\`, which differs from ${remoteBase} (stale local ${baseBranch}). Fast-forward it first without touching another checkout: if no worktree has ${baseBranch} checked out, run \`git fetch ${remote} ${baseBranch}:${baseBranch}\`; if it is checked out in the primary checkout, have that checkout fast-forward itself - never move ${baseBranch} from this worktree, and do not check it out here.`, guidance),
41
+ };
42
+ }
43
+ return null;
44
+ }
45
+ // An explicit `--base` needs no checkout; only the configured default reads gh's directory, so a
46
+ // `cwd` the hook cannot resolve skips just that fallback.
47
+ export function findHandRolledStackBaseBlock(action, optionTokens, cwd, policy) {
48
+ const base = lastNamedOption(optionTokens, 'base', 'B');
49
+ const effectiveBase = base ??
50
+ (cwd !== undefined && (action === 'create' || action === 'new')
51
+ ? configuredPullRequestBase(cwd, policy.git)
52
+ : undefined);
53
+ if (effectiveBase === undefined || effectiveBase === policy.baseBranch) {
54
+ return null;
55
+ }
56
+ return {
57
+ reason: withGuidance(`PRs must target ${policy.baseBranch} unless they are part of a native GitHub stack. Use \`gh stack\`, not \`gh pr create/edit --base <unmerged-branch>\`.`, policy.guidance),
58
+ };
59
+ }
@@ -0,0 +1,9 @@
1
+ export type GhInvocation = {
2
+ action: string;
3
+ area: string;
4
+ arguments: string[];
5
+ optionTokenIndexes: number[];
6
+ optionTokens: string[];
7
+ };
8
+ export declare function parseGhOrGhStackInvocation(tokens: string[], index: number): GhInvocation | null;
9
+ export declare function parseGhInvocation(tokens: string[], ghIndex: number): GhInvocation | null;
@@ -0,0 +1,80 @@
1
+ import { attachedShortOptionValue, isGhCommandSeparator, optionValueFromLongToken, } from "./github-options.mjs";
2
+ import { isShellRedirectionOperatorToken } from "../shell-parse/index.mjs";
3
+ export function parseGhOrGhStackInvocation(tokens, index) {
4
+ const executable = tokens[index].split('/').at(-1);
5
+ if (executable === 'gh-stack') {
6
+ const invocation = parseGhInvocation(ghStackAsGh(tokens, index), 0);
7
+ // The rewritten array starts `gh stack`, two words standing for the one gh-stack word at `index`.
8
+ return (invocation && {
9
+ ...invocation,
10
+ optionTokenIndexes: invocation.optionTokenIndexes.map((i) => i + index - 1),
11
+ });
12
+ }
13
+ if (executable === 'gh') {
14
+ return parseGhInvocation(tokens, index);
15
+ }
16
+ return null;
17
+ }
18
+ export function parseGhInvocation(tokens, ghIndex) {
19
+ const { actionIndex, areaIndex, optionTokenIndexes, optionTokens } = scanGhInvocation(tokens, ghIndex);
20
+ if (areaIndex === undefined || actionIndex === undefined) {
21
+ return null;
22
+ }
23
+ return {
24
+ action: tokens[actionIndex],
25
+ area: tokens[areaIndex],
26
+ arguments: tokens.slice(actionIndex + 1),
27
+ optionTokenIndexes,
28
+ optionTokens,
29
+ };
30
+ }
31
+ function ghStackAsGh(tokens, index) {
32
+ return ['gh', 'stack', ...tokens.slice(index + 1)];
33
+ }
34
+ function scanGhInvocation(tokens, ghIndex) {
35
+ let areaIndex;
36
+ let actionIndex;
37
+ const optionTokenIndexes = [];
38
+ const optionTokens = [];
39
+ for (let index = ghIndex + 1; index < tokens.length; index += 1) {
40
+ const token = tokens[index];
41
+ if (isGhCommandSeparator(token)) {
42
+ break;
43
+ }
44
+ // A redirection target (e.g. the `--auto` in `gh pr merge 123 > --auto`) is a filename the
45
+ // shell consumes, never an argument `gh` itself sees — drop the operator and its target so a
46
+ // redirect can never be mistaken for a real flag.
47
+ if (isShellRedirectionOperatorToken(token)) {
48
+ index += 1;
49
+ continue;
50
+ }
51
+ if (token === '--repo' || token === '-R') {
52
+ optionTokens.push(token);
53
+ optionTokenIndexes.push(index);
54
+ const value = tokens[index + 1];
55
+ if (value !== undefined && !isGhCommandSeparator(value)) {
56
+ optionTokens.push(value);
57
+ optionTokenIndexes.push(index + 1);
58
+ index += 1;
59
+ }
60
+ continue;
61
+ }
62
+ if (optionValueFromLongToken(token, '--repo') !== null ||
63
+ attachedShortOptionValue(token, '-R') !== null) {
64
+ optionTokens.push(token);
65
+ optionTokenIndexes.push(index);
66
+ continue;
67
+ }
68
+ if (areaIndex === undefined) {
69
+ areaIndex = index;
70
+ continue;
71
+ }
72
+ if (actionIndex === undefined) {
73
+ actionIndex = index;
74
+ continue;
75
+ }
76
+ optionTokens.push(token);
77
+ optionTokenIndexes.push(index);
78
+ }
79
+ return { actionIndex, areaIndex, optionTokenIndexes, optionTokens };
80
+ }
@@ -0,0 +1,21 @@
1
+ import type { BlockDecision } from './types.mts';
2
+ /**
3
+ * Automation never receives merge authority. The check is deliberately coarse and parses no
4
+ * wrappers: a command that names gh and has a merge-shaped word in any script the hook reads
5
+ * blocks. Overmatches (a `git merge` beside gh, merge help, quoted prose) are accepted.
6
+ * Interactively this returns null.
7
+ */
8
+ export declare function findAutomationMergeBlock(command: string, automationContext: boolean, guidance?: string): BlockDecision | null;
9
+ /**
10
+ * The 'confirm' disposition for an interactive merge, which a caller may render as a silent allow
11
+ * in an attended session. Call it last, so any block anywhere in the command wins; only a command
12
+ * that is one plain merge qualifies.
13
+ */
14
+ export declare function findInteractiveMergeConfirm(command: string, automationContext: boolean, guidance?: string): BlockDecision | null;
15
+ /**
16
+ * True only for a command that is exactly one `gh pr merge`, or one `gh stack merge` with a
17
+ * numeric selector, optionally after plain `NAME=value` assignments or `env NAME=value`. The
18
+ * raw-text check rejects every compound, wrapped, or expanded form before tokenizing, so a lone
19
+ * merge can never carry a second command along with the allow.
20
+ */
21
+ export declare function isLoneMergeCommand(command: string): boolean;
@@ -0,0 +1,86 @@
1
+ import { commandsToInspectForGitHubPolicy } from "./github-command-context.mjs";
2
+ import { parseGhOrGhStackInvocation } from "./github-invocation.mjs";
3
+ import { hasNumericPrSelector } from "./github-option-flags.mjs";
4
+ import { plainShellAssignment, tokenizeShellWords } from "../shell-parse/index.mjs";
5
+ // `gh` or `gh-stack` as a word of its own, including a path (`/usr/bin/gh`).
6
+ const GH_WORD = /(?:^|[^\w.-])gh(?:-stack)?(?![\w.-])/;
7
+ const MERGE_WORD = /(?<![\w-])merge(?![\w-])/;
8
+ const MERGE_ENDPOINT = /\/merges?(?:$|[/?#])|mergePullRequest|enablePullRequestAutoMerge/;
9
+ function suffix(guidance) {
10
+ return guidance === '' ? '' : ` ${guidance}`;
11
+ }
12
+ /**
13
+ * Automation never receives merge authority. The check is deliberately coarse and parses no
14
+ * wrappers: a command that names gh and has a merge-shaped word in any script the hook reads
15
+ * blocks. Overmatches (a `git merge` beside gh, merge help, quoted prose) are accepted.
16
+ * Interactively this returns null.
17
+ */
18
+ export function findAutomationMergeBlock(command, automationContext, guidance = '') {
19
+ if (!automationContext || !mentionsGhMerge(command))
20
+ return null;
21
+ return {
22
+ disposition: 'block',
23
+ reason: `Merge authority is never delegated to an agent in automation. This command names gh together with a merge (\`gh pr merge\`, \`gh stack merge\`, or a \`gh api\` merge endpoint or mutation), so it is blocked in automation; a human performs the merge. If the merge text is only prose, split the command or move the prose into a --body-file.${suffix(guidance)}`,
24
+ };
25
+ }
26
+ function mentionsGhMerge(command) {
27
+ // Tokens, not raw text: a shell-composed name like `g"h"` still runs gh.
28
+ return commandsToInspectForGitHubPolicy(command).some((inspected) => {
29
+ const tokens = tokenizeShellWords(inspected, { splitRedirections: true });
30
+ return tokens.some((token) => GH_WORD.test(token)) && tokens.some(isMergeShaped);
31
+ });
32
+ }
33
+ function isMergeShaped(token) {
34
+ return (token === 'merge' ||
35
+ MERGE_ENDPOINT.test(token) ||
36
+ (GH_WORD.test(token) && MERGE_WORD.test(token)));
37
+ }
38
+ /**
39
+ * The 'confirm' disposition for an interactive merge, which a caller may render as a silent allow
40
+ * in an attended session. Call it last, so any block anywhere in the command wins; only a command
41
+ * that is one plain merge qualifies.
42
+ */
43
+ export function findInteractiveMergeConfirm(command, automationContext, guidance = '') {
44
+ if (automationContext || !isLoneMergeCommand(command)) {
45
+ return null;
46
+ }
47
+ return {
48
+ disposition: 'confirm',
49
+ reason: `Merging is a human decision - confirm you want this exact merge before it proceeds.${suffix(guidance)}`,
50
+ };
51
+ }
52
+ // Anything that can join, redirect, substitute, expand, glob, escape, or comment shell text.
53
+ const SHELL_METACHARACTERS = /[;&|<>()`$\\\n\r{}*?[\]#!]/;
54
+ /**
55
+ * True only for a command that is exactly one `gh pr merge`, or one `gh stack merge` with a
56
+ * numeric selector, optionally after plain `NAME=value` assignments or `env NAME=value`. The
57
+ * raw-text check rejects every compound, wrapped, or expanded form before tokenizing, so a lone
58
+ * merge can never carry a second command along with the allow.
59
+ */
60
+ export function isLoneMergeCommand(command) {
61
+ if (SHELL_METACHARACTERS.test(command)) {
62
+ return false;
63
+ }
64
+ const tokens = tokenizeShellWords(command);
65
+ let index = skipAssignments(tokens, 0);
66
+ if (tokens[index] === 'env') {
67
+ index = skipAssignments(tokens, index + 1);
68
+ }
69
+ const executable = tokens[index]?.split('/').at(-1);
70
+ if (executable !== 'gh' && executable !== 'gh-stack') {
71
+ return false;
72
+ }
73
+ const invocation = parseGhOrGhStackInvocation(tokens, index);
74
+ if (invocation?.action !== 'merge') {
75
+ return false;
76
+ }
77
+ return (invocation.area === 'pr' ||
78
+ (invocation.area === 'stack' && hasNumericPrSelector(invocation.optionTokens)));
79
+ }
80
+ function skipAssignments(tokens, start) {
81
+ let index = start;
82
+ while (index < tokens.length && plainShellAssignment(tokens[index]) !== null) {
83
+ index += 1;
84
+ }
85
+ return index;
86
+ }
@@ -0,0 +1,3 @@
1
+ export declare function lastNamedOption(optionTokens: string[], name: string, shortFlag?: string): string | undefined;
2
+ export declare function hasNamedFlag(optionTokens: string[], name: string): boolean;
3
+ export declare function hasNumericPrSelector(optionTokens: string[]): boolean;
@@ -0,0 +1,67 @@
1
+ import { attachedShortOptionValue, optionValueFromLongToken } from "./github-options.mjs";
2
+ const FALSE_FLAG_VALUES = new Set(['false', '0', 'no', 'off']);
3
+ function clusteredShortOptionValue(token, shortName) {
4
+ if (!token.startsWith('-') || token.startsWith('--') || shortName.length !== 1) {
5
+ return null;
6
+ }
7
+ const body = token.slice(1);
8
+ const flagIndex = body.indexOf(shortName);
9
+ if (flagIndex === -1) {
10
+ return null;
11
+ }
12
+ // pflag reads `-B=main` as the value `main`.
13
+ return body.slice(flagIndex + 1).replace(/^=/, '');
14
+ }
15
+ export function lastNamedOption(optionTokens, name, shortFlag) {
16
+ const flag = `--${name}`;
17
+ const short = shortFlag === undefined ? undefined : `-${shortFlag}`;
18
+ let value;
19
+ for (let index = 0; index < optionTokens.length; index += 1) {
20
+ const token = optionTokens[index];
21
+ if (token === flag || (short !== undefined && token === short)) {
22
+ const next = optionTokens[index + 1];
23
+ if (next !== undefined && !next.startsWith('-')) {
24
+ value = next;
25
+ index += 1;
26
+ }
27
+ continue;
28
+ }
29
+ const clustered = shortFlag === undefined ? null : clusteredShortOptionValue(token, shortFlag);
30
+ if (clustered !== null) {
31
+ if (clustered !== '') {
32
+ value = clustered;
33
+ continue;
34
+ }
35
+ const next = optionTokens[index + 1];
36
+ if (next !== undefined && !next.startsWith('-')) {
37
+ value = next;
38
+ index += 1;
39
+ }
40
+ continue;
41
+ }
42
+ const attached = optionValueFromLongToken(token, flag) ??
43
+ (short === undefined ? null : attachedShortOptionValue(token, short));
44
+ if (attached !== null) {
45
+ value = attached;
46
+ }
47
+ }
48
+ return value;
49
+ }
50
+ export function hasNamedFlag(optionTokens, name) {
51
+ const flag = `--${name}`;
52
+ let enabled = false;
53
+ for (const token of optionTokens) {
54
+ if (token === flag) {
55
+ enabled = true;
56
+ continue;
57
+ }
58
+ const attached = optionValueFromLongToken(token, flag);
59
+ if (attached !== null) {
60
+ enabled = !FALSE_FLAG_VALUES.has(attached.toLowerCase());
61
+ }
62
+ }
63
+ return enabled;
64
+ }
65
+ export function hasNumericPrSelector(optionTokens) {
66
+ return optionTokens.some((token) => /^\d+$/.test(token));
67
+ }
@@ -0,0 +1,12 @@
1
+ export declare function attachedShortOptionValue(token: string, flag: string): string | null;
2
+ export declare function optionValueFromLongToken(token: string, option: string): string | null;
3
+ export declare function isGhCommandSeparator(token: string): boolean;
4
+ export type GhOptions = {
5
+ body: string[];
6
+ bodyFile: string[];
7
+ draft: boolean;
8
+ label: string[];
9
+ repo: string[];
10
+ title: string[];
11
+ };
12
+ export declare function parseGhOptions(tokens: string[]): GhOptions;
@@ -0,0 +1,73 @@
1
+ function addOptionValue(options, key, value) {
2
+ if (value === undefined) {
3
+ return false;
4
+ }
5
+ options[key].push(value);
6
+ return true;
7
+ }
8
+ export function attachedShortOptionValue(token, flag) {
9
+ if (token.startsWith(`${flag}=`)) {
10
+ return token.slice(flag.length + 1);
11
+ }
12
+ if (token.startsWith(flag) && token.length > flag.length) {
13
+ return token.slice(flag.length);
14
+ }
15
+ return null;
16
+ }
17
+ export function optionValueFromLongToken(token, option) {
18
+ if (!token.startsWith(`${option}=`)) {
19
+ return null;
20
+ }
21
+ return token.slice(option.length + 1);
22
+ }
23
+ export function isGhCommandSeparator(token) {
24
+ return (token === '&&' ||
25
+ token === '&' ||
26
+ token === '(' ||
27
+ token === ')' ||
28
+ token === ';' ||
29
+ token === '|' ||
30
+ token === '||' ||
31
+ token === '\n');
32
+ }
33
+ const OPTION_SPECS = [
34
+ ['body', '--body', '-b'],
35
+ ['bodyFile', '--body-file', '-F'],
36
+ ['label', '--label', '-l'],
37
+ ['repo', '--repo', '-R'],
38
+ ['title', '--title', '-t'],
39
+ ];
40
+ // Records the value for the first spec `token` names and returns how many tokens it consumed
41
+ // (2 for a separate value, 1 for an attached one, 0 when no spec matches).
42
+ function consumeOption(options, token, next) {
43
+ // A separator ends the command, so it is never an option's value.
44
+ const nextToken = next !== undefined && isGhCommandSeparator(next) ? undefined : next;
45
+ for (const [key, long, short] of OPTION_SPECS) {
46
+ if ((token === long || token === short) && addOptionValue(options, key, nextToken))
47
+ return 2;
48
+ const attached = optionValueFromLongToken(token, long) ?? attachedShortOptionValue(token, short);
49
+ if (addOptionValue(options, key, attached ?? undefined))
50
+ return 1;
51
+ }
52
+ return 0;
53
+ }
54
+ export function parseGhOptions(tokens) {
55
+ const options = {
56
+ body: [],
57
+ bodyFile: [],
58
+ draft: false,
59
+ label: [],
60
+ repo: [],
61
+ title: [],
62
+ };
63
+ for (let index = 0; index < tokens.length; index += 1) {
64
+ const token = tokens[index];
65
+ if (isGhCommandSeparator(token))
66
+ break;
67
+ if (token === '--draft')
68
+ options.draft = true;
69
+ else
70
+ index += Math.max(consumeOption(options, token, tokens[index + 1]) - 1, 0);
71
+ }
72
+ return options;
73
+ }
@@ -0,0 +1,9 @@
1
+ import { type ResolvedStackPolicy } from './github-configured-base.mts';
2
+ import type { GhInvocation } from './github-invocation.mts';
3
+ import type { BlockDecision } from './types.mts';
4
+ /**
5
+ * `cwd` is the invocation's working directory, or undefined when it could not be determined (an
6
+ * unresolved `cd` target). The init HEAD-ancestry guard fails open in that case rather than
7
+ * substitute the session cwd.
8
+ */
9
+ export declare function findGitHubStackWorkflowBlock(invocation: GhInvocation, cwd: string | undefined, policy: ResolvedStackPolicy): BlockDecision | null;