claude-dev-env 8.119.2 → 8.121.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 (44) hide show
  1. package/bin/ever-registered-hooks.mjs +1 -0
  2. package/hooks/advisory/auto_mode_denial_quick_fix.py +275 -27
  3. package/hooks/advisory/auto_mode_rule_flow_eval/auto_mode_rule_flow_cases.json +3475 -0
  4. package/hooks/advisory/auto_mode_rule_flow_eval/auto_mode_rule_flow_runner.py +849 -0
  5. package/hooks/advisory/auto_mode_rule_flow_eval/stub_allow_hook.py +20 -0
  6. package/hooks/advisory/auto_mode_rule_flow_eval/stub_hold_hook.py +54 -0
  7. package/hooks/advisory/auto_mode_rule_flow_eval/test_auto_mode_rule_flow_runner.py +143 -0
  8. package/hooks/advisory/test_auto_mode_denial_quick_fix.py +533 -9
  9. package/hooks/auto_mode_question_transcript.py +215 -0
  10. package/hooks/auto_mode_refusal_ledger.py +481 -0
  11. package/hooks/auto_mode_refusal_ledger_files.py +336 -0
  12. package/hooks/auto_mode_rule_steps.py +177 -0
  13. package/hooks/blocking/auto_mode_refusal_stop_gate.py +384 -0
  14. package/hooks/blocking/gh_api_budget_gate.py +286 -0
  15. package/hooks/blocking/test_auto_mode_refusal_stop_gate.py +484 -0
  16. package/hooks/blocking/test_bash_dispatcher_interpreter_starts.py +8 -3
  17. package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py +1 -0
  18. package/hooks/blocking/test_gh_api_budget_gate.py +602 -0
  19. package/hooks/features/README.md +1 -1
  20. package/hooks/features/bash-dispatchers.md +3 -0
  21. package/hooks/features/session-context.md +5 -2
  22. package/hooks/hooks.json +5 -0
  23. package/hooks/hooks_constants/auto_mode_denial_quick_fix_constants.py +51 -3
  24. package/hooks/hooks_constants/auto_mode_refusal_ledger_constants.py +85 -0
  25. package/hooks/hooks_constants/auto_mode_refusal_stop_gate_constants.py +80 -0
  26. package/hooks/hooks_constants/auto_mode_rule_flow_runner_constants.py +225 -0
  27. package/hooks/hooks_constants/auto_mode_rule_steps_constants.py +82 -0
  28. package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py +4 -0
  29. package/hooks/hooks_constants/gh_api_budget.py +186 -0
  30. package/hooks/hooks_constants/gh_api_budget_gate_constants.py +215 -0
  31. package/hooks/hooks_constants/gh_argument_lists.py +169 -0
  32. package/hooks/hooks_constants/gh_shell_loop_scan.py +386 -0
  33. package/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py +5 -1
  34. package/hooks/hooks_constants/test_gh_api_budget.py +125 -0
  35. package/hooks/hooks_constants/test_gh_argument_lists.py +49 -0
  36. package/hooks/hooks_constants/test_gh_shell_loop_scan.py +50 -0
  37. package/hooks/test_auto_mode_question_transcript.py +113 -0
  38. package/hooks/test_auto_mode_refusal_ledger.py +398 -0
  39. package/hooks/test_auto_mode_refusal_ledger_files.py +155 -0
  40. package/hooks/test_auto_mode_rule_steps.py +210 -0
  41. package/package.json +1 -1
  42. package/scripts/policy_lint/adapter_configuration.py +5 -0
  43. package/scripts/policy_lint/config/constants.py +1 -0
  44. package/scripts/tests/test_adapter_configuration.py +8 -0
@@ -0,0 +1,186 @@
1
+ """Read the GitHub core REST limit for the gh API budget gate, at most once every five minutes.
2
+
3
+ ::
4
+
5
+ cache under five minutes old CoreRateBudget(limit=5000, used=4000, reset=...)
6
+ cache stale or missing runs gh api rate_limit, then caches the answer
7
+ gh missing, slow or broken None, and the failure is cached for five minutes
8
+
9
+ The cache file is ``<managed root>/cache/gh_api_budget.json``, where the
10
+ managed root is ``CLAUDE_CONFIG_DIR``, else ``~/.claude``. It holds
11
+ ``{"read_at": <epoch seconds>, "limit": 5000, "used": 4000, "reset": <epoch
12
+ seconds>}``, and a failed read holds null limit, used and reset. A cache file
13
+ that does not parse counts as stale.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ import os
20
+ import subprocess
21
+ import tempfile
22
+ import time
23
+ from dataclasses import dataclass
24
+ from pathlib import Path
25
+
26
+ from hooks_constants.subprocess_window import hidden_window_creation_flags
27
+ from hooks_constants.gh_api_budget_gate_constants import (
28
+ ALL_RATE_LIMIT_QUERY_ARGUMENTS,
29
+ CACHE_DIRECTORY_NAME,
30
+ CACHE_FILE_NAME,
31
+ CACHE_MAXIMUM_AGE_SECONDS,
32
+ CACHE_READ_AT_KEY,
33
+ CACHE_TEMPORARY_SUFFIX,
34
+ LIMIT_KEY,
35
+ RATE_LIMIT_CORE_KEY,
36
+ RATE_LIMIT_QUERY_TIMEOUT_SECONDS,
37
+ RATE_LIMIT_RESOURCES_KEY,
38
+ RESET_KEY,
39
+ SPENT_FRACTION_DENOMINATOR,
40
+ SPENT_FRACTION_NUMERATOR,
41
+ USED_KEY,
42
+ )
43
+ from hooks_constants.mod_handoff_constants import (
44
+ CLAUDE_CONFIG_DIR_ENV_VAR,
45
+ DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME,
46
+ )
47
+
48
+ __all__ = ["CoreRateBudget", "is_core_budget_spent", "read_core_rate_budget"]
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class CoreRateBudget:
53
+ """The core REST limit, the calls used against it, and its reset time in epoch seconds."""
54
+
55
+ limit: int
56
+ used: int
57
+ reset: int | None
58
+
59
+
60
+ @dataclass(frozen=True)
61
+ class _CachedRead:
62
+ """One rate limit read as the cache file holds it; a failed read has no budget."""
63
+
64
+ read_at: float
65
+ budget: CoreRateBudget | None
66
+
67
+
68
+ def is_core_budget_spent(budget: CoreRateBudget) -> bool:
69
+ """Return True when four fifths or more of a readable core limit is used.
70
+
71
+ Args:
72
+ budget: The core limit and the calls used against it.
73
+ """
74
+ if budget.limit <= 0:
75
+ return False
76
+ return budget.used * SPENT_FRACTION_DENOMINATOR >= budget.limit * SPENT_FRACTION_NUMERATOR
77
+
78
+
79
+ def _budget_cache_path() -> Path:
80
+ configured_directory = os.environ.get(CLAUDE_CONFIG_DIR_ENV_VAR, "").strip()
81
+ managed_root = (
82
+ Path(configured_directory)
83
+ if configured_directory
84
+ else Path.home() / DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME
85
+ )
86
+ return managed_root / CACHE_DIRECTORY_NAME / CACHE_FILE_NAME
87
+
88
+
89
+ def _whole_number(candidate: object) -> int | None:
90
+ if isinstance(candidate, bool) or not isinstance(candidate, int):
91
+ return None
92
+ return candidate
93
+
94
+
95
+ def _budget_from_fields(all_fields: dict[str, object]) -> CoreRateBudget | None:
96
+ """Return the budget the limit, used and reset fields hold, or None when limit or used is missing."""
97
+ limit = _whole_number(all_fields.get(LIMIT_KEY))
98
+ used = _whole_number(all_fields.get(USED_KEY))
99
+ if limit is None or used is None:
100
+ return None
101
+ return CoreRateBudget(limit=limit, used=used, reset=_whole_number(all_fields.get(RESET_KEY)))
102
+
103
+
104
+ def _fresh_cached_read(cache_path: Path, now: float) -> _CachedRead | None:
105
+ """Return the cached read when it is under five minutes old and well formed, else None."""
106
+ try:
107
+ cached_fields = json.loads(cache_path.read_text(encoding="utf-8"))
108
+ except (OSError, ValueError):
109
+ return None
110
+ if not isinstance(cached_fields, dict):
111
+ return None
112
+ read_at = cached_fields.get(CACHE_READ_AT_KEY)
113
+ if isinstance(read_at, bool) or not isinstance(read_at, (int, float)):
114
+ return None
115
+ if not 0 <= now - read_at < CACHE_MAXIMUM_AGE_SECONDS:
116
+ return None
117
+ return _CachedRead(read_at=float(read_at), budget=_budget_from_fields(cached_fields))
118
+
119
+
120
+ def _queried_core_budget() -> CoreRateBudget | None:
121
+ """Run ``gh api rate_limit`` and return its core budget, or None when the read fails."""
122
+ try:
123
+ completed = subprocess.run(
124
+ list(ALL_RATE_LIMIT_QUERY_ARGUMENTS),
125
+ stdin=subprocess.DEVNULL,
126
+ capture_output=True,
127
+ text=True,
128
+ encoding="utf-8",
129
+ timeout=RATE_LIMIT_QUERY_TIMEOUT_SECONDS,
130
+ check=False,
131
+ creationflags=hidden_window_creation_flags(),
132
+ )
133
+ if completed.returncode != 0:
134
+ return None
135
+ rate_limit_report = json.loads(completed.stdout)
136
+ except (OSError, subprocess.SubprocessError, ValueError):
137
+ return None
138
+ if not isinstance(rate_limit_report, dict):
139
+ return None
140
+ all_resources = rate_limit_report.get(RATE_LIMIT_RESOURCES_KEY)
141
+ core_fields = (
142
+ all_resources.get(RATE_LIMIT_CORE_KEY) if isinstance(all_resources, dict) else None
143
+ )
144
+ if not isinstance(core_fields, dict):
145
+ return None
146
+ return _budget_from_fields(core_fields)
147
+
148
+
149
+ def _write_cached_read(cache_path: Path, cached_read: _CachedRead) -> None:
150
+ """Write the read to the cache file through a temporary file, leaving the old file on failure."""
151
+ budget = cached_read.budget
152
+ cached_fields = {
153
+ CACHE_READ_AT_KEY: cached_read.read_at,
154
+ LIMIT_KEY: budget.limit if budget else None,
155
+ USED_KEY: budget.used if budget else None,
156
+ RESET_KEY: budget.reset if budget else None,
157
+ }
158
+ temporary_path: str | None = None
159
+ try:
160
+ cache_path.parent.mkdir(parents=True, exist_ok=True)
161
+ file_descriptor, temporary_path = tempfile.mkstemp(
162
+ dir=cache_path.parent, prefix=cache_path.name, suffix=CACHE_TEMPORARY_SUFFIX
163
+ )
164
+ with os.fdopen(file_descriptor, "w", encoding="utf-8") as temporary_file:
165
+ json.dump(cached_fields, temporary_file)
166
+ os.replace(temporary_path, cache_path)
167
+ except OSError:
168
+ if temporary_path is not None:
169
+ Path(temporary_path).unlink(missing_ok=True)
170
+
171
+
172
+ def read_core_rate_budget() -> CoreRateBudget | None:
173
+ """Return the core REST budget from a cache under five minutes old, else from ``gh api rate_limit``.
174
+
175
+ A fresh read, failed or not, is written back to the cache, so a broken gh
176
+ is asked again only after five minutes. Returns None when the limit cannot
177
+ be read.
178
+ """
179
+ cache_path = _budget_cache_path()
180
+ now = time.time()
181
+ cached_read = _fresh_cached_read(cache_path, now)
182
+ if cached_read is not None:
183
+ return cached_read.budget
184
+ fresh_read = _CachedRead(read_at=now, budget=_queried_core_budget())
185
+ _write_cached_read(cache_path, fresh_read)
186
+ return fresh_read.budget
@@ -0,0 +1,215 @@
1
+ """Constants for the gate that keeps agents from draining the GitHub API limit.
2
+
3
+ Holds the gh command paths that watch a run, the shell loop keywords and sleep
4
+ spellings the loop reader knows, the table of gh reads that draw on the core
5
+ REST limit, the rate limit query and its cache file, the four fifths rule, and
6
+ the three deny messages.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import re
12
+
13
+ __all__ = [
14
+ "GH_PROGRAM_NAME",
15
+ "GH_COMMAND_PATH_LENGTH",
16
+ "ALL_GH_RUN_WATCH_COMMAND_WORDS",
17
+ "ALL_GH_PR_CHECKS_COMMAND_WORDS",
18
+ "GH_WATCH_OPTION",
19
+ "WATCH_PROGRAM_NAME",
20
+ "ALL_WATCH_INTERVAL_OPTIONS",
21
+ "ALL_WATCH_OPTIONS_WITH_A_VALUE",
22
+ "WATCH_SHORT_INTERVAL_OPTION",
23
+ "WATCH_LONG_INTERVAL_OPTION_PREFIX",
24
+ "WATCH_DEFAULT_INTERVAL_SECONDS",
25
+ "ALL_LOOP_KEYWORDS",
26
+ "ALL_CONDITION_LOOP_KEYWORDS",
27
+ "ALL_BASH_LOOP_HEADER_KEYWORDS",
28
+ "ALL_LEADING_SHELL_KEYWORDS",
29
+ "COUNTED_LOOP_KEYWORD",
30
+ "LOOP_BODY_KEYWORD",
31
+ "LOOP_END_KEYWORD",
32
+ "BLOCK_START_CHARACTER",
33
+ "BLOCK_END_CHARACTER",
34
+ "ALL_QUOTE_CHARACTERS",
35
+ "LOOP_HEADER_OPENER",
36
+ "LOOP_HEADER_CHARACTERS",
37
+ "ENDLESS_FOR_HEADER_MARKER",
38
+ "ALL_ENDLESS_CONDITIONS_BY_LOOP_KEYWORD",
39
+ "ALL_SLEEP_PROGRAM_NAMES",
40
+ "SLEEP_DURATION_PATTERN",
41
+ "SLEEP_DURATION_AMOUNT_GROUP",
42
+ "SLEEP_DURATION_UNIT_GROUP",
43
+ "SECONDS_BY_SLEEP_UNIT",
44
+ "SLEEP_TIMESPAN_PATTERN",
45
+ "SLEEP_TIMESPAN_FIELD_SEPARATOR",
46
+ "ALL_SECONDS_BY_TIMESPAN_FIELD",
47
+ "ALL_SHELL_EXPANSION_MARKERS",
48
+ "OPTION_PREFIX",
49
+ "SLEEP_PARAMETER_VALUE_SEPARATOR",
50
+ "START_SLEEP_SECONDS_PARAMETER",
51
+ "START_SLEEP_MILLISECONDS_PARAMETER",
52
+ "START_SLEEP_DURATION_PARAMETER",
53
+ "MINIMUM_START_SLEEP_DURATION_PARAMETER_LENGTH",
54
+ "MINIMUM_START_SLEEP_PARAMETER_LENGTH",
55
+ "MILLISECONDS_PER_SECOND",
56
+ "BLOCK_CLOSER_CHARACTERS",
57
+ "MINIMUM_POLL_INTERVAL_SECONDS",
58
+ "POWERSHELL_VARIABLE_PATTERN",
59
+ "ALL_POWERSHELL_ASSIGNMENT_OPERATORS",
60
+ "POWERSHELL_ASSIGNMENT_PREFIX_LENGTH",
61
+ "ALL_GH_READ_SUBCOMMANDS_BY_COMMAND_GROUP",
62
+ "ALL_GH_READ_COMMAND_GROUPS",
63
+ "ALL_GH_API_METHOD_OPTIONS",
64
+ "GH_API_SHORT_METHOD_OPTION",
65
+ "ALL_GH_API_READ_METHODS",
66
+ "ALL_GH_API_BODY_OPTIONS",
67
+ "ALL_GH_API_SHORT_BODY_OPTIONS",
68
+ "GH_SHORT_OPTION_LENGTH",
69
+ "ALL_GH_API_UNBUDGETED_ENDPOINTS",
70
+ "ALL_RATE_LIMIT_QUERY_ARGUMENTS",
71
+ "RATE_LIMIT_QUERY_TIMEOUT_SECONDS",
72
+ "RATE_LIMIT_RESOURCES_KEY",
73
+ "RATE_LIMIT_CORE_KEY",
74
+ "CACHE_DIRECTORY_NAME",
75
+ "CACHE_FILE_NAME",
76
+ "CACHE_TEMPORARY_SUFFIX",
77
+ "CACHE_MAXIMUM_AGE_SECONDS",
78
+ "CACHE_READ_AT_KEY",
79
+ "LIMIT_KEY",
80
+ "USED_KEY",
81
+ "RESET_KEY",
82
+ "SPENT_FRACTION_NUMERATOR",
83
+ "SPENT_FRACTION_DENOMINATOR",
84
+ "RESET_TIME_FORMAT",
85
+ "GATE_HOOK_NAME",
86
+ "WATCH_COMMAND_DENY_REASON",
87
+ "TIGHT_POLLING_LOOP_DENY_REASON",
88
+ "SPENT_BUDGET_DENY_REASON_TEMPLATE",
89
+ "SPENT_BUDGET_RESET_SENTENCE_TEMPLATE",
90
+ ]
91
+
92
+ GH_PROGRAM_NAME: str = "gh"
93
+ GH_COMMAND_PATH_LENGTH: int = 2
94
+ ALL_GH_RUN_WATCH_COMMAND_WORDS: tuple[str, str] = ("run", "watch")
95
+ ALL_GH_PR_CHECKS_COMMAND_WORDS: tuple[str, str] = ("pr", "checks")
96
+ GH_WATCH_OPTION: str = "--watch"
97
+
98
+ WATCH_PROGRAM_NAME: str = "watch"
99
+ ALL_WATCH_INTERVAL_OPTIONS: frozenset[str] = frozenset({"-n", "--interval"})
100
+ ALL_WATCH_OPTIONS_WITH_A_VALUE: frozenset[str] = frozenset({"-q", "--equexit"})
101
+ WATCH_SHORT_INTERVAL_OPTION: str = "-n"
102
+ WATCH_LONG_INTERVAL_OPTION_PREFIX: str = "--interval="
103
+ WATCH_DEFAULT_INTERVAL_SECONDS: float = 2.0
104
+
105
+ ALL_LOOP_KEYWORDS: frozenset[str] = frozenset(
106
+ {"while", "until", "for", "foreach", "do", "foreach-object", "%"}
107
+ )
108
+ ALL_CONDITION_LOOP_KEYWORDS: frozenset[str] = frozenset({"while", "until"})
109
+ ALL_BASH_LOOP_HEADER_KEYWORDS: frozenset[str] = frozenset({"while", "until", "for"})
110
+ ALL_LEADING_SHELL_KEYWORDS: frozenset[str] = frozenset({"then", "else", "elif", "{", "!", "time"})
111
+ COUNTED_LOOP_KEYWORD: str = "for"
112
+ LOOP_BODY_KEYWORD: str = "do"
113
+ LOOP_END_KEYWORD: str = "done"
114
+ BLOCK_START_CHARACTER: str = "{"
115
+ BLOCK_END_CHARACTER: str = "}"
116
+ ALL_QUOTE_CHARACTERS: str = "\"'"
117
+ LOOP_HEADER_OPENER: str = "("
118
+ LOOP_HEADER_CHARACTERS: str = "(); "
119
+ ENDLESS_FOR_HEADER_MARKER: str = ";;"
120
+ ALL_ENDLESS_CONDITIONS_BY_LOOP_KEYWORD: dict[str, frozenset[str]] = {
121
+ "while": frozenset({"true", ":", "$true", "1"}),
122
+ "until": frozenset({"false", "$false"}),
123
+ }
124
+
125
+ ALL_SLEEP_PROGRAM_NAMES: frozenset[str] = frozenset({"sleep", "start-sleep"})
126
+ SLEEP_DURATION_PATTERN: re.Pattern[str] = re.compile(r"(?P<amount>\d+(?:\.\d*)?|\.\d+)(?P<unit>[smhd]?)")
127
+ SLEEP_DURATION_AMOUNT_GROUP: str = "amount"
128
+ SLEEP_DURATION_UNIT_GROUP: str = "unit"
129
+ SECONDS_BY_SLEEP_UNIT: dict[str, float] = {"": 1.0, "s": 1.0, "m": 60.0, "h": 3600.0, "d": 86400.0}
130
+ SLEEP_TIMESPAN_PATTERN: re.Pattern[str] = re.compile(r"\d+:\d+(?::\d+(?:\.\d+)?)?")
131
+ SLEEP_TIMESPAN_FIELD_SEPARATOR: str = ":"
132
+ ALL_SECONDS_BY_TIMESPAN_FIELD: tuple[float, ...] = (3600.0, 60.0, 1.0)
133
+ ALL_SHELL_EXPANSION_MARKERS: tuple[str, ...] = ("$", "`")
134
+ OPTION_PREFIX: str = "-"
135
+ SLEEP_PARAMETER_VALUE_SEPARATOR: str = ":"
136
+ START_SLEEP_SECONDS_PARAMETER: str = "-seconds"
137
+ START_SLEEP_MILLISECONDS_PARAMETER: str = "-milliseconds"
138
+ START_SLEEP_DURATION_PARAMETER: str = "-duration"
139
+ MINIMUM_START_SLEEP_DURATION_PARAMETER_LENGTH: int = 3
140
+ MINIMUM_START_SLEEP_PARAMETER_LENGTH: int = 2
141
+ MILLISECONDS_PER_SECOND: float = 1000.0
142
+ BLOCK_CLOSER_CHARACTERS: str = "})"
143
+ MINIMUM_POLL_INTERVAL_SECONDS: float = 60.0
144
+
145
+ POWERSHELL_VARIABLE_PATTERN: re.Pattern[str] = re.compile(r"\$(?:\{[^}]*\}|[\w:]+)")
146
+ ALL_POWERSHELL_ASSIGNMENT_OPERATORS: frozenset[str] = frozenset(
147
+ {"=", "+=", "-=", "*=", "/=", "%=", "??="}
148
+ )
149
+ POWERSHELL_ASSIGNMENT_PREFIX_LENGTH: int = 2
150
+
151
+ ALL_GH_READ_SUBCOMMANDS_BY_COMMAND_GROUP: dict[str, frozenset[str]] = {
152
+ "pr": frozenset({"view", "list", "status", "checks", "diff"}),
153
+ "issue": frozenset({"view", "list", "status"}),
154
+ "run": frozenset({"view", "list", "download"}),
155
+ "release": frozenset({"view", "list", "download"}),
156
+ "repo": frozenset({"view", "list"}),
157
+ "workflow": frozenset({"view", "list"}),
158
+ "gist": frozenset({"view", "list"}),
159
+ "cache": frozenset({"list"}),
160
+ "label": frozenset({"list"}),
161
+ "ruleset": frozenset({"view", "list", "check"}),
162
+ "secret": frozenset({"list"}),
163
+ "variable": frozenset({"list", "get"}),
164
+ "org": frozenset({"list"}),
165
+ "project": frozenset({"view", "list", "field-list", "item-list"}),
166
+ }
167
+ ALL_GH_READ_COMMAND_GROUPS: frozenset[str] = frozenset({"search", "status"})
168
+ ALL_GH_API_METHOD_OPTIONS: frozenset[str] = frozenset({"-X", "--method"})
169
+ GH_API_SHORT_METHOD_OPTION: str = "-X"
170
+ ALL_GH_API_READ_METHODS: frozenset[str] = frozenset({"GET", "HEAD"})
171
+ ALL_GH_API_BODY_OPTIONS: frozenset[str] = frozenset(
172
+ {"-f", "-F", "--field", "--raw-field", "--input"}
173
+ )
174
+ ALL_GH_API_SHORT_BODY_OPTIONS: frozenset[str] = frozenset({"-f", "-F"})
175
+ GH_SHORT_OPTION_LENGTH: int = 2
176
+ ALL_GH_API_UNBUDGETED_ENDPOINTS: frozenset[str] = frozenset({"graphql", "rate_limit"})
177
+
178
+ ALL_RATE_LIMIT_QUERY_ARGUMENTS: tuple[str, ...] = ("gh", "api", "rate_limit")
179
+ RATE_LIMIT_QUERY_TIMEOUT_SECONDS: float = 10.0
180
+ RATE_LIMIT_RESOURCES_KEY: str = "resources"
181
+ RATE_LIMIT_CORE_KEY: str = "core"
182
+ CACHE_DIRECTORY_NAME: str = "cache"
183
+ CACHE_FILE_NAME: str = "gh_api_budget.json"
184
+ CACHE_TEMPORARY_SUFFIX: str = ".tmp"
185
+ CACHE_MAXIMUM_AGE_SECONDS: float = 300.0
186
+ CACHE_READ_AT_KEY: str = "read_at"
187
+ LIMIT_KEY: str = "limit"
188
+ USED_KEY: str = "used"
189
+ RESET_KEY: str = "reset"
190
+ SPENT_FRACTION_NUMERATOR: int = 4
191
+ SPENT_FRACTION_DENOMINATOR: int = 5
192
+ RESET_TIME_FORMAT: str = "%Y-%m-%d %H:%M UTC"
193
+
194
+ GATE_HOOK_NAME: str = "gh_api_budget_gate.py"
195
+ WATCH_COMMAND_DENY_REASON: str = (
196
+ "BLOCKED: gh run watch and gh pr checks --watch poll the GitHub API every few seconds "
197
+ "until the run ends, and that drains the shared API limit. "
198
+ "Make one timed read instead. Run a background loop that sleeps at least 60 seconds "
199
+ "between gh run view calls, such as "
200
+ "`while :; do gh run view $RUN_ID --json status -q .status | grep -q completed && break; "
201
+ "sleep 60; done`, or make a single gh run view read when the task notification arrives."
202
+ )
203
+ TIGHT_POLLING_LOOP_DENY_REASON: str = (
204
+ "BLOCKED: this shell loop calls gh with less than 60 seconds of sleep between calls, "
205
+ "and that drains the shared GitHub API limit. "
206
+ "Sleep at least 60 seconds between gh calls, such as sleep 60 in Bash "
207
+ "or Start-Sleep -Seconds 60 in PowerShell."
208
+ )
209
+ SPENT_BUDGET_DENY_REASON_TEMPLATE: str = (
210
+ "BLOCKED: the GitHub core API limit is {used} of {limit} used, four fifths or more, "
211
+ "so gh reads wait until it resets. {reset_sentence}"
212
+ "Wait for the reset, or read files already in the checkout with git, "
213
+ "such as git log, git show, or git diff."
214
+ )
215
+ SPENT_BUDGET_RESET_SENTENCE_TEMPLATE: str = "It resets at {reset_time}. "
@@ -0,0 +1,169 @@
1
+ """Find the gh calls a shell command runs, past wrappers, glued braces, assignments and ``watch``.
2
+
3
+ ::
4
+
5
+ gh pr view 12 [["pr", "view", "12"]]
6
+ $s = gh run watch 1 [["run", "watch", "1"]]
7
+ {gh run view 1} [["run", "view", "1"]]
8
+ watch -n 5 gh run view 1 [["run", "view", "1"]]
9
+ echo "gh run watch" []
10
+
11
+ ``blocking/gh_api_budget_gate.py`` and ``gh_shell_loop_scan`` read gh calls
12
+ through this module.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from collections import deque
18
+
19
+ from hooks_constants.gh_api_budget_gate_constants import (
20
+ ALL_POWERSHELL_ASSIGNMENT_OPERATORS,
21
+ ALL_QUOTE_CHARACTERS,
22
+ ALL_WATCH_INTERVAL_OPTIONS,
23
+ ALL_WATCH_OPTIONS_WITH_A_VALUE,
24
+ BLOCK_END_CHARACTER,
25
+ BLOCK_START_CHARACTER,
26
+ GH_PROGRAM_NAME,
27
+ OPTION_PREFIX,
28
+ POWERSHELL_ASSIGNMENT_PREFIX_LENGTH,
29
+ POWERSHELL_VARIABLE_PATTERN,
30
+ WATCH_DEFAULT_INTERVAL_SECONDS,
31
+ WATCH_LONG_INTERVAL_OPTION_PREFIX,
32
+ WATCH_PROGRAM_NAME,
33
+ WATCH_SHORT_INTERVAL_OPTION,
34
+ )
35
+ from hooks_constants.piped_pytest_blocker_constants import WRAPPED_COMMAND_TOKEN_JOIN
36
+ from hooks_constants.pytest_invocation import unquoted_token
37
+ from hooks_constants.shell_command_wrappers import (
38
+ all_wrapped_command_segments,
39
+ segment_program_and_arguments,
40
+ )
41
+
42
+
43
+ def _watch_option_interval(option: str, all_remaining_arguments: deque[str]) -> str | None:
44
+ """Return the interval text one ``watch`` option sets, taking its separate value when it has one.
45
+
46
+ Returns None when the option sets no interval.
47
+ """
48
+ if option in ALL_WATCH_INTERVAL_OPTIONS or option in ALL_WATCH_OPTIONS_WITH_A_VALUE:
49
+ option_value = all_remaining_arguments.popleft() if all_remaining_arguments else ""
50
+ return option_value if option in ALL_WATCH_INTERVAL_OPTIONS else None
51
+ if option.startswith(WATCH_LONG_INTERVAL_OPTION_PREFIX):
52
+ return option.removeprefix(WATCH_LONG_INTERVAL_OPTION_PREFIX)
53
+ if option.startswith(WATCH_SHORT_INTERVAL_OPTION):
54
+ return option.removeprefix(WATCH_SHORT_INTERVAL_OPTION)
55
+ return None
56
+
57
+
58
+ def watch_interval_and_command(all_arguments: list[str]) -> tuple[float | None, str]:
59
+ """Return a ``watch`` call's interval in seconds, None when unreadable, and the command it runs."""
60
+ interval_text: str | None = None
61
+ all_remaining_arguments = deque(unquoted_token(each) for each in all_arguments)
62
+ while all_remaining_arguments and all_remaining_arguments[0].startswith(OPTION_PREFIX):
63
+ option = all_remaining_arguments.popleft()
64
+ option_interval = _watch_option_interval(option, all_remaining_arguments)
65
+ interval_text = interval_text if option_interval is None else option_interval
66
+ watched_command = WRAPPED_COMMAND_TOKEN_JOIN.join(all_remaining_arguments)
67
+ if interval_text is None:
68
+ return WATCH_DEFAULT_INTERVAL_SECONDS, watched_command
69
+ try:
70
+ return float(interval_text), watched_command
71
+ except ValueError:
72
+ return None, watched_command
73
+
74
+
75
+ def _brace_split_tokens(token: str) -> list[str]:
76
+ """Return one token with its glued PowerShell braces split off.
77
+
78
+ ::
79
+
80
+ {gh ["{", "gh"]
81
+ 5} ["5", "}"]
82
+ {} ["{", "}"]
83
+ ${name} ["${name}"]
84
+
85
+ Quoted text, which holds a quote or a space, stays whole.
86
+ """
87
+ is_quoted_text = token.startswith(tuple(ALL_QUOTE_CHARACTERS)) or any(
88
+ each_character.isspace() for each_character in token
89
+ )
90
+ if is_quoted_text:
91
+ return [token]
92
+ body = token.lstrip(BLOCK_START_CHARACTER)
93
+ opening_count = len(token) - len(body)
94
+ closing_count = 0
95
+ while body.endswith(BLOCK_END_CHARACTER) and body.count(BLOCK_END_CHARACTER) > body.count(
96
+ BLOCK_START_CHARACTER
97
+ ):
98
+ body = body.removesuffix(BLOCK_END_CHARACTER)
99
+ closing_count += 1
100
+ return [
101
+ *[BLOCK_START_CHARACTER] * opening_count,
102
+ *([body] if body else []),
103
+ *[BLOCK_END_CHARACTER] * closing_count,
104
+ ]
105
+
106
+
107
+ def brace_split_segments(all_segment_tokens: list[str]) -> list[list[str]]:
108
+ """Return one segment split at each glued ``{``, so ``{gh run view 1}`` runs gh.
109
+
110
+ Each new segment starts with its ``{``, the way a ``{`` the pipeline
111
+ parser splits at opens the next segment in ``gh_shell_loop_scan``.
112
+ """
113
+ all_parts = [
114
+ each_part
115
+ for each_token in all_segment_tokens
116
+ for each_part in _brace_split_tokens(each_token)
117
+ ]
118
+ all_segments: list[list[str]] = [[]]
119
+ for each_part in all_parts:
120
+ if each_part == BLOCK_START_CHARACTER:
121
+ all_segments.append([])
122
+ all_segments[-1].append(each_part)
123
+ return [each_segment for each_segment in all_segments if each_segment]
124
+
125
+
126
+ def all_gh_call_argument_lists(command: str, is_inside_watch: bool = False) -> list[list[str]]:
127
+ """Return the arguments of each gh call the command runs, past wrappers, braces and ``watch``."""
128
+ return [
129
+ each_gh_arguments
130
+ for each_wrapped_segment in all_wrapped_command_segments(command)
131
+ for each_segment in brace_split_segments(each_wrapped_segment)
132
+ for each_gh_arguments in _segment_gh_argument_lists(each_segment, is_inside_watch)
133
+ ]
134
+
135
+
136
+ def _tokens_past_assignment(all_segment_tokens: list[str]) -> list[str]:
137
+ """Return a segment's tokens past a leading PowerShell ``$name =`` prefix.
138
+
139
+ ::
140
+
141
+ $s = gh run watch 1 ["gh", "run", "watch", "1"]
142
+ $script:s += gh pr view 1 ["gh", "pr", "view", "1"]
143
+ gh run view 1 ["gh", "run", "view", "1"]
144
+ """
145
+ assignment_prefix = all_segment_tokens[:POWERSHELL_ASSIGNMENT_PREFIX_LENGTH]
146
+ is_assignment = (
147
+ len(assignment_prefix) == POWERSHELL_ASSIGNMENT_PREFIX_LENGTH
148
+ and POWERSHELL_VARIABLE_PATTERN.fullmatch(assignment_prefix[0]) is not None
149
+ and assignment_prefix[1] in ALL_POWERSHELL_ASSIGNMENT_OPERATORS
150
+ )
151
+ if is_assignment:
152
+ return all_segment_tokens[POWERSHELL_ASSIGNMENT_PREFIX_LENGTH:]
153
+ return all_segment_tokens
154
+
155
+
156
+ def _segment_gh_argument_lists(
157
+ all_segment_tokens: list[str], is_inside_watch: bool
158
+ ) -> list[list[str]]:
159
+ """Return the arguments of the gh call one segment runs, directly, as an assigned value, or through ``watch``."""
160
+ program_name, all_arguments = segment_program_and_arguments(
161
+ _tokens_past_assignment(all_segment_tokens)
162
+ )
163
+ normalized_program_name = program_name.lower()
164
+ if normalized_program_name == GH_PROGRAM_NAME:
165
+ return [all_arguments]
166
+ if normalized_program_name != WATCH_PROGRAM_NAME or is_inside_watch:
167
+ return []
168
+ _interval, watched_command = watch_interval_and_command(all_arguments)
169
+ return all_gh_call_argument_lists(watched_command, True)