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,122 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { gitConfiguredRemoteDefaults, gitRemoteVerbose } from "./git-process.mjs";
4
+ // GitHub's owner-name characters. A shell expansion (`$OWNER`, a glob, `~`) never matches, so an
5
+ // owner the hook can't read literally is never mistaken for a different one.
6
+ const GITHUB_OWNER = /^[a-z\d_][a-z\d_-]*$/i;
7
+ const REPO_SELECTOR_CHARACTERS = /^[\w.:@/-]+$/;
8
+ // One `git remote -v` line: `<name>\t<url> (fetch|push)`, which a partial clone suffixes with its
9
+ // ` [<filter>]`.
10
+ const REMOTE_LINE = /^[^\t]+\t(.+) \((fetch|push)\)(?: \[[^\]]*\])?$/;
11
+ /**
12
+ * Every lowercased owner of a checkout's GitHub repositories, read the way gh reads them: the fetch
13
+ * URLs of `git remote -v` plus any `gh repo set-default` (`remote.<name>.gh-resolved`). Hostless
14
+ * (local-path) remotes are ignored, like gh does; undefined when the checkout can't be read, prints
15
+ * a remote line the hook doesn't recognize, or has a hosted remote or set-default that isn't
16
+ * OWNER/REPO.
17
+ */
18
+ export function checkoutOwners(cwd) {
19
+ const remotes = gitRemoteVerbose(cwd);
20
+ const defaults = gitConfiguredRemoteDefaults(cwd);
21
+ if (remotes === undefined || defaults === undefined) {
22
+ return undefined;
23
+ }
24
+ const owners = new Set();
25
+ for (const line of remotes.split('\n').filter(Boolean)) {
26
+ const owner = remoteLineOwner(line);
27
+ if (owner === undefined) {
28
+ return undefined;
29
+ }
30
+ if (owner !== null) {
31
+ owners.add(owner);
32
+ }
33
+ }
34
+ for (const line of defaults.split('\n')) {
35
+ const value = line.slice(line.indexOf(' ') + 1);
36
+ if (line === '' || value === 'base') {
37
+ continue;
38
+ }
39
+ const owner = ownerOfRepoSelector(value);
40
+ if (owner === undefined) {
41
+ return undefined;
42
+ }
43
+ owners.add(owner);
44
+ }
45
+ return owners;
46
+ }
47
+ /**
48
+ * A checkout's owner when {@link checkoutOwners} finds exactly one, so whichever remote gh picks is
49
+ * that owner's; undefined when there are none or several.
50
+ */
51
+ export function checkoutOwner(cwd) {
52
+ const owners = checkoutOwners(cwd);
53
+ return owners?.size === 1 ? [...owners][0] : undefined;
54
+ }
55
+ /**
56
+ * The owners a session's own checkout belongs to: its {@link checkoutOwners} plus the owner of its
57
+ * root `package.json` `repository`, so a fork-only checkout still counts the upstream it declares.
58
+ * Undefined — keep every content rule — when either is unreadable, the declared repository isn't
59
+ * a hosted OWNER/REPO, or no owner is known at all.
60
+ */
61
+ export function sessionHomeOwners(worktreeRoot) {
62
+ const owners = checkoutOwners(worktreeRoot);
63
+ const declared = declaredRepositoryOwner(worktreeRoot);
64
+ if (owners === undefined || declared === undefined) {
65
+ return undefined;
66
+ }
67
+ const home = declared === null ? owners : new Set([...owners, declared]);
68
+ return home.size === 0 ? undefined : home;
69
+ }
70
+ // gh's `[HOST/]OWNER/REPO` or repository URL form.
71
+ export function ownerOfRepoSelector(value) {
72
+ const path = value.replace(/^https?:\/\//i, '').replace(/\/$/, '');
73
+ const segments = path.split('/');
74
+ if (!REPO_SELECTOR_CHARACTERS.test(path) || segments.length < 2 || segments.length > 3) {
75
+ return undefined;
76
+ }
77
+ return segments.includes('') ? undefined : githubOwner(segments[segments.length - 2]);
78
+ }
79
+ export function githubOwner(value) {
80
+ return GITHUB_OWNER.test(value) ? value.toLowerCase() : undefined;
81
+ }
82
+ // null when package.json is absent or declares no repository; undefined when it can't be read or
83
+ // the declaration isn't a hosted OWNER/REPO URL (npm's bare `owner/repo` shorthand included).
84
+ function declaredRepositoryOwner(root) {
85
+ let manifest;
86
+ try {
87
+ manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
88
+ }
89
+ catch (err) {
90
+ return err.code === 'ENOENT' ? null : undefined;
91
+ }
92
+ const repository = manifest?.repository;
93
+ if (repository === undefined) {
94
+ return null;
95
+ }
96
+ const url = typeof repository === 'string' ? repository : repository?.url;
97
+ return typeof url === 'string' ? (ownerOfRemoteUrl(url) ?? undefined) : undefined;
98
+ }
99
+ // null for a push line or a hostless fetch URL; undefined for a line the hook doesn't recognize.
100
+ function remoteLineOwner(line) {
101
+ const match = REMOTE_LINE.exec(line);
102
+ if (match === null) {
103
+ return undefined;
104
+ }
105
+ return match[2] === 'push' ? null : ownerOfRemoteUrl(match[1]);
106
+ }
107
+ // null for a hostless remote gh ignores (a local path or file://); undefined for a hosted URL that
108
+ // isn't OWNER/REPO.
109
+ function ownerOfRemoteUrl(url) {
110
+ const withScheme = /^([a-z][a-z\d+.-]*):\/\/([^/]*)(.*)$/i.exec(url);
111
+ if (withScheme !== null) {
112
+ const [, scheme, host, path] = withScheme;
113
+ return scheme.toLowerCase() === 'file' || host === '' ? null : ownerOfRemotePath(path);
114
+ }
115
+ // git's scp-like `[user@]host:path` form needs a colon before any slash.
116
+ const scpLike = /^[^/:]+:(.*)$/.exec(url);
117
+ return scpLike === null ? null : ownerOfRemotePath(scpLike[1]);
118
+ }
119
+ function ownerOfRemotePath(path) {
120
+ const segments = path.replace(/^\/+|\/+$/g, '').split('/');
121
+ return segments.length === 2 && segments[1] !== '' ? githubOwner(segments[0]) : undefined;
122
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * The command text and every script nested in it that the GitHub policies read. A heredoc body is
3
+ * data unless a shell may read it as its script, but an unquoted-delimiter body still runs its
4
+ * command substitutions, so each candidate is read with its bodies blanked.
5
+ */
6
+ export declare function commandsToInspectForGitHubPolicy(command: string): string[];
@@ -0,0 +1,19 @@
1
+ import { extractShellCommandArguments, extractShellCommandSubstitutions, stripNonShellHeredocBodies, } from "../shell-parse/index.mjs";
2
+ /**
3
+ * The command text and every script nested in it that the GitHub policies read. A heredoc body is
4
+ * data unless a shell may read it as its script, but an unquoted-delimiter body still runs its
5
+ * command substitutions, so each candidate is read with its bodies blanked.
6
+ */
7
+ export function commandsToInspectForGitHubPolicy(command) {
8
+ const commands = [command.replace(/\\\n/g, ' ')];
9
+ const inspected = new Set();
10
+ for (const command of commands) {
11
+ const { bodySubstitutions, shellBodies, textWithoutBodies: candidate, } = stripNonShellHeredocBodies(command);
12
+ if (inspected.has(candidate)) {
13
+ continue;
14
+ }
15
+ inspected.add(candidate);
16
+ commands.push(...extractShellCommandArguments(candidate).map(({ command: shellCommand }) => shellCommand), ...extractShellCommandSubstitutions(candidate), ...shellBodies, ...bodySubstitutions);
17
+ }
18
+ return [...inspected];
19
+ }
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Working directory the `gh` token at `index` would see after sequential
3
+ * command-local `cd` and its own `env -C` wrappers. `baseCwd` is session
4
+ * `hookCwd`. Returns `undefined` when cwd is unknown so callers fail open
5
+ * instead of using the session checkout. Absolute `cd` after `&&`/`;` and an
6
+ * absolute `env -C` recover a known directory.
7
+ */
8
+ export declare function commandCwd(tokens: string[], index: number, baseCwd: string): string | undefined;
@@ -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;