claude-dev-env 8.119.2 → 8.120.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.
- package/hooks/blocking/gh_api_budget_gate.py +286 -0
- package/hooks/blocking/test_bash_dispatcher_interpreter_starts.py +8 -3
- package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py +1 -0
- package/hooks/blocking/test_gh_api_budget_gate.py +602 -0
- package/hooks/features/bash-dispatchers.md +3 -0
- package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py +4 -0
- package/hooks/hooks_constants/gh_api_budget.py +186 -0
- package/hooks/hooks_constants/gh_api_budget_gate_constants.py +215 -0
- package/hooks/hooks_constants/gh_argument_lists.py +169 -0
- package/hooks/hooks_constants/gh_shell_loop_scan.py +386 -0
- package/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py +5 -1
- package/hooks/hooks_constants/test_gh_api_budget.py +125 -0
- package/hooks/hooks_constants/test_gh_argument_lists.py +49 -0
- package/hooks/hooks_constants/test_gh_shell_loop_scan.py +50 -0
- package/package.json +1 -1
|
@@ -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)
|