polyctl 0.7.0__py3-none-any.whl
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.
- polyctl/__init__.py +7 -0
- polyctl/__main__.py +5 -0
- polyctl/a2a.py +226 -0
- polyctl/a2a_mcp.py +546 -0
- polyctl/acp.py +417 -0
- polyctl/adapters/README.md +101 -0
- polyctl/adapters/aider.json +32 -0
- polyctl/adapters/amazon-q.json +15 -0
- polyctl/adapters/amp.json +16 -0
- polyctl/adapters/antigravity.json +120 -0
- polyctl/adapters/claude-code.json +229 -0
- polyctl/adapters/cloud-generic.json +57 -0
- polyctl/adapters/codex.json +47 -0
- polyctl/adapters/command-code.json +45 -0
- polyctl/adapters/copilot.json +17 -0
- polyctl/adapters/cursor-agent.json +29 -0
- polyctl/adapters/deepseek.json +13 -0
- polyctl/adapters/droid.json +34 -0
- polyctl/adapters/gemini.json +30 -0
- polyctl/adapters/grok.json +22 -0
- polyctl/adapters/hermes.json +34 -0
- polyctl/adapters/kilocode.json +30 -0
- polyctl/adapters/kimi.json +23 -0
- polyctl/adapters/kiro.json +332 -0
- polyctl/adapters/ollama.json +29 -0
- polyctl/adapters/omp.json +34 -0
- polyctl/adapters/openai-api.json +68 -0
- polyctl/adapters/opencode.json +162 -0
- polyctl/adapters/pi.json +24 -0
- polyctl/adapters/pr-agent.json +54 -0
- polyctl/adapters/profiles.json +9 -0
- polyctl/adapters/qoder.json +163 -0
- polyctl/adapters/qwen.json +27 -0
- polyctl/adapters/reasonix.json +25 -0
- polyctl/adapters/rewriters/rtk.json +24 -0
- polyctl/adapters/trae.json +31 -0
- polyctl/adapters/vendors.json +42 -0
- polyctl/adapters/warp.json +88 -0
- polyctl/allowlist.py +1756 -0
- polyctl/api_review.py +920 -0
- polyctl/cli.py +835 -0
- polyctl/conformance_harness.py +9 -0
- polyctl/demo.py +503 -0
- polyctl/drivers.py +146 -0
- polyctl/email.py +160 -0
- polyctl/features.py +98 -0
- polyctl/journal.py +144 -0
- polyctl/language.py +945 -0
- polyctl/lib.py +1296 -0
- polyctl/matrix.py +660 -0
- polyctl/mcp.py +1362 -0
- polyctl/ntfy.py +169 -0
- polyctl/outbound.py +39 -0
- polyctl/parts/__init__.py +5 -0
- polyctl/parts/cli_authority.py +2615 -0
- polyctl/parts/cli_channels.py +1325 -0
- polyctl/parts/cli_checks.py +2293 -0
- polyctl/parts/cli_completion.py +686 -0
- polyctl/parts/cli_evidence.py +141 -0
- polyctl/parts/cli_gain.py +375 -0
- polyctl/parts/cli_harness.py +392 -0
- polyctl/parts/cli_hooks.py +1816 -0
- polyctl/parts/cli_install.py +638 -0
- polyctl/parts/cli_lanes.py +106 -0
- polyctl/parts/cli_maintenance.py +2536 -0
- polyctl/parts/cli_next.py +248 -0
- polyctl/parts/cli_pr.py +53 -0
- polyctl/parts/cli_project.py +2857 -0
- polyctl/parts/cli_review.py +5158 -0
- polyctl/parts/cli_status.py +898 -0
- polyctl/parts/lib_adapters.py +2933 -0
- polyctl/parts/lib_alarms.py +2106 -0
- polyctl/parts/lib_events.py +224 -0
- polyctl/parts/lib_evidence.py +412 -0
- polyctl/parts/lib_gates.py +2099 -0
- polyctl/parts/lib_lanes.py +829 -0
- polyctl/parts/lib_mail.py +1541 -0
- polyctl/parts/lib_next.py +652 -0
- polyctl/parts/lib_pr.py +331 -0
- polyctl/parts/lib_slices.py +3337 -0
- polyctl/parts/lib_state.py +2415 -0
- polyctl/parts/lib_transcript.py +4118 -0
- polyctl/pressure.py +325 -0
- polyctl/prices.json +47 -0
- polyctl/procs.py +1194 -0
- polyctl/settings.py +505 -0
- polyctl/skill/SKILL.md +365 -0
- polyctl/skillkit.py +503 -0
- polyctl/storage.py +2055 -0
- polyctl/telegram.py +327 -0
- polyctl/tiers.py +123 -0
- polyctl/verdicts.py +41 -0
- polyctl/watchdog.py +3887 -0
- polyctl/web.py +337 -0
- polyctl-0.7.0.dist-info/METADATA +235 -0
- polyctl-0.7.0.dist-info/RECORD +99 -0
- polyctl-0.7.0.dist-info/WHEEL +4 -0
- polyctl-0.7.0.dist-info/entry_points.txt +5 -0
- polyctl-0.7.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,829 @@
|
|
|
1
|
+
"""Lanes: one git worktree per board item, so parallel work never shares a checkout (LANE-START).
|
|
2
|
+
|
|
3
|
+
A part of src/polyctl/lib.py, run in its namespace by `_part` as the parts split out of it are; it is
|
|
4
|
+
not importable on its own.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
# ---- a lane: one worktree per READY board item (LANE-START) -------------------------------
|
|
9
|
+
|
|
10
|
+
LANE_BRANCH = "lane/"
|
|
11
|
+
LANE_SETTINGS = ("lane.link_paths", "lane.env", "lane.env_file", "lane.post_create", "lane.post_create_timeout")
|
|
12
|
+
# Above the lines polyctl adds to the repository's exclude file, so whoever reads that file knows why they are there.
|
|
13
|
+
LANE_EXCLUDE_HEADING = "# polyctl lane start: links and files it puts in a lane, never to be committed (LANE-START)"
|
|
14
|
+
# How long a lane's stopped post-create command may take to be gone.
|
|
15
|
+
LANE_STOP_SECONDS = 5
|
|
16
|
+
_LANE_UNSAFE = re.compile(r"[^A-Za-z0-9._-]+")
|
|
17
|
+
_ENV_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class LaneRefused(Exception):
|
|
21
|
+
"""What polyctl will not do with a lane, as the sentence a person reads; nothing was made or removed."""
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def lane_name(item):
|
|
25
|
+
"""The name a board item's lane goes by: its directory, its branch and its record in .polyctl/lanes/.
|
|
26
|
+
|
|
27
|
+
A board id may hold what no directory or branch name can - `ACME-187/1` - so each run of
|
|
28
|
+
other characters becomes one hyphen. Two ids that come to one name would share a lane,
|
|
29
|
+
and the second is refused as a lane that already exists.
|
|
30
|
+
"""
|
|
31
|
+
return _LANE_UNSAFE.sub("-", str(item or "")).strip(".-")
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _real_path(path):
|
|
35
|
+
return os.path.normcase(os.path.realpath(path))
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _lanes_beside(trees):
|
|
39
|
+
"""(the main checkout, the directory its lanes are made in), from git's list of worktrees.
|
|
40
|
+
|
|
41
|
+
Beside the main checkout, not the checkout asking: a linked worktree often lives inside the
|
|
42
|
+
main one, and a lane made beside it would sit in the main checkout's tree, where that
|
|
43
|
+
checkout's `git status`, tests and tools would read the lane's files as their own.
|
|
44
|
+
"""
|
|
45
|
+
main = os.path.normpath(trees[0]["path"])
|
|
46
|
+
return main, os.path.join(os.path.dirname(main), os.path.basename(main) + "-lanes")
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def lane_home(root):
|
|
50
|
+
"""(the main checkout, the directory its lanes are made in): `<main checkout>-lanes`, beside it."""
|
|
51
|
+
trees = worktree_list(root)
|
|
52
|
+
if not trees:
|
|
53
|
+
raise LaneRefused("git lists no worktree here, and a lane is one")
|
|
54
|
+
return _lanes_beside(trees)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def lane_record_path(root, name):
|
|
58
|
+
return os.path.join(root, ".polyctl", "lanes", f"{name}.json")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def lane_log_path(root, name):
|
|
62
|
+
return os.path.join(root, ".polyctl", "lanes", f"{name}.log")
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def lane_records(root):
|
|
66
|
+
"""Every lane this checkout started, by name, each with `name`; one that cannot be read says so."""
|
|
67
|
+
directory = os.path.join(root, ".polyctl", "lanes")
|
|
68
|
+
try:
|
|
69
|
+
entries = sorted(os.listdir(directory))
|
|
70
|
+
except OSError:
|
|
71
|
+
return []
|
|
72
|
+
out = []
|
|
73
|
+
for entry in entries:
|
|
74
|
+
# A record is replaced through a hidden temporary file beside it; that file is no lane.
|
|
75
|
+
if entry.startswith(".") or not entry.endswith(".json"):
|
|
76
|
+
continue
|
|
77
|
+
try:
|
|
78
|
+
with open(os.path.join(directory, entry), encoding=UTF8) as fh:
|
|
79
|
+
record = json.load(fh)
|
|
80
|
+
except (OSError, ValueError, RecursionError):
|
|
81
|
+
record = None
|
|
82
|
+
out.append(dict(record if isinstance(record, dict) else {"state": "unreadable"}, name=entry[:-5]))
|
|
83
|
+
return out
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def lane_record(root, item):
|
|
87
|
+
"""The lane an item, or a lane's own name, has in this checkout, or None."""
|
|
88
|
+
name = lane_name(item)
|
|
89
|
+
return next((record for record in lane_records(root) if record["name"] == name), None)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def lane_not_ready(root, item, data=None):
|
|
93
|
+
"""Why a board item may not start now, as a sentence; None when it is READY (#33).
|
|
94
|
+
|
|
95
|
+
READY is board_graph's alone. This only says which of its reasons holds, so a refusal
|
|
96
|
+
names what to do: land a dependency, answer who it waits on, or mend an edge. `data` is
|
|
97
|
+
the board as one reading took it, which `polyctl slice start` moves the item on
|
|
98
|
+
(SLICE-LIFECYCLE-2).
|
|
99
|
+
"""
|
|
100
|
+
graph = board_graph(root, data)
|
|
101
|
+
if any(entry["id"] == item for entry in graph["ready"]):
|
|
102
|
+
return None
|
|
103
|
+
b = board(root, data)
|
|
104
|
+
state, entry = next(((column, row) for column in BOARD_STATES for row in b[column] if row["id"] == item),
|
|
105
|
+
(None, None))
|
|
106
|
+
if state is None:
|
|
107
|
+
return f"{item} is not on the board"
|
|
108
|
+
if state != "queued":
|
|
109
|
+
return f"{item} is {state} on the board, and only a queued item can be READY"
|
|
110
|
+
broken = [problem for problem in graph["problems"]
|
|
111
|
+
if re.search(rf"(?<![\w-]){re.escape(item)}(?![\w-])", problem)]
|
|
112
|
+
if broken:
|
|
113
|
+
return f"{item} stands on a broken edge of the board: {'; '.join(broken)}"
|
|
114
|
+
if "waiting" in entry["notes"]:
|
|
115
|
+
return f"{item} is waiting on {entry['notes']['waiting'] or 'someone'}"
|
|
116
|
+
landed = {row["id"] for column in ("done", "verified") for row in b[column]}
|
|
117
|
+
needs = set(_edge_ids(entry, "needs")) | {row["id"] for column in BOARD_STATES for row in b[column]
|
|
118
|
+
if item in _edge_ids(row, "unlocks")}
|
|
119
|
+
unmet = sorted(needs - landed)
|
|
120
|
+
if unmet:
|
|
121
|
+
return f"{item} needs {', '.join(unmet)}, which {'has' if len(unmet) == 1 else 'have'} not landed"
|
|
122
|
+
return f"{item} is not READY"
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _lane_relative(named):
|
|
126
|
+
"""A path inside a checkout as a setting names it, with forward slashes, or None.
|
|
127
|
+
|
|
128
|
+
Relative, never climbing out with `..`, never into `.git`: a lane is prepared inside
|
|
129
|
+
itself, from inside the main checkout, and nowhere else. No control character either: the
|
|
130
|
+
path becomes one line of git's exclude file (_lane_ignore).
|
|
131
|
+
"""
|
|
132
|
+
text = str(named or "").replace("\\", "/").strip()
|
|
133
|
+
if not text or text.startswith("/") or re.match(r"^[A-Za-z]:", text) or any(ord(ch) < 32 for ch in text):
|
|
134
|
+
return None
|
|
135
|
+
parts = [part for part in text.split("/") if part not in ("", ".")]
|
|
136
|
+
if not parts or ".." in parts or parts[0] == ".git":
|
|
137
|
+
return None
|
|
138
|
+
return "/".join(parts)
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def lane_settings(cfg):
|
|
142
|
+
"""The lane.* settings a start prepares a lane with, by their last word; LaneRefused names any polyctl cannot use.
|
|
143
|
+
|
|
144
|
+
settings.get passes a value it cannot use over for the default, and the default of a list
|
|
145
|
+
is nothing: `"make setup && npm ci"` as lane.post_create - one shell string where a list of
|
|
146
|
+
words belongs - ran nothing, and the lane was called ready unprepared. So a start reads
|
|
147
|
+
each setting's problem as well, and every value is checked here, before anything is made.
|
|
148
|
+
"""
|
|
149
|
+
wanted, problems = {}, []
|
|
150
|
+
for key in LANE_SETTINGS:
|
|
151
|
+
value, _, problem = settings.resolve(cfg, key)
|
|
152
|
+
wanted[key.split(".", 1)[1]] = value
|
|
153
|
+
if problem:
|
|
154
|
+
problems.append(problem)
|
|
155
|
+
problems += [f"lane.link_paths names {named!r}, which is not a path inside a checkout"
|
|
156
|
+
for named in wanted["link_paths"] if _lane_relative(named) is None]
|
|
157
|
+
for entry in wanted["env"]:
|
|
158
|
+
key, equals, value = entry.partition("=")
|
|
159
|
+
if not equals or not _ENV_NAME.fullmatch(key) or any(ch in value for ch in "\r\n\0"):
|
|
160
|
+
problems.append(f"lane.env holds {entry!r}, which is not one NAME=value line")
|
|
161
|
+
if wanted["env"] and _lane_relative(wanted["env_file"]) is None:
|
|
162
|
+
problems.append(f"lane.env_file is {wanted['env_file']!r}, which names no file in the lane")
|
|
163
|
+
if problems:
|
|
164
|
+
raise LaneRefused("; ".join(problems) + "; a lane is prepared as its settings say or not started, and "
|
|
165
|
+
"`polyctl config list` says what each one takes")
|
|
166
|
+
return wanted
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def _lanes_directory(root):
|
|
170
|
+
""".polyctl/lanes/, made on first use with a .gitignore of its own that ignores all of it.
|
|
171
|
+
|
|
172
|
+
A record names directories on this machine, and a log holds whatever a post-create command
|
|
173
|
+
printed, a DATABASE_URL among it. A project set up before lanes existed has no line for
|
|
174
|
+
them in its own .gitignore, and `git add -A` there would commit both.
|
|
175
|
+
"""
|
|
176
|
+
directory = os.path.join(root, ".polyctl", "lanes")
|
|
177
|
+
os.makedirs(directory, exist_ok=True)
|
|
178
|
+
ignore = os.path.join(directory, ".gitignore")
|
|
179
|
+
if not os.path.exists(ignore):
|
|
180
|
+
with open(ignore, "w", encoding=UTF8, newline="\n") as fh:
|
|
181
|
+
fh.write("# what polyctl lane start records here names this machine's directories (LANE-START)\n*\n")
|
|
182
|
+
return directory
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def _write_lane(root, name, record):
|
|
186
|
+
from .storage import replace_file_durably
|
|
187
|
+
replace_file_durably(lane_record_path(root, name),
|
|
188
|
+
(json.dumps(record, indent=2, ensure_ascii=False) + "\n").encode(UTF8))
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
def _forget_lane(root, name):
|
|
192
|
+
for path in (lane_record_path(root, name), lane_log_path(root, name)):
|
|
193
|
+
try:
|
|
194
|
+
os.remove(path)
|
|
195
|
+
except FileNotFoundError:
|
|
196
|
+
pass
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def _process_of(pid):
|
|
200
|
+
"""A process as a lane's record names it: its pid, and when it started, so a pid handed on is not taken for it."""
|
|
201
|
+
try:
|
|
202
|
+
start = _process_start(pid, refresh=True)
|
|
203
|
+
except Exception:
|
|
204
|
+
start = None
|
|
205
|
+
return {"pid": pid, "start": start}
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def _polyctl_alive(process):
|
|
209
|
+
"""Whether the polyctl a record names as preparing its lane still runs as that process."""
|
|
210
|
+
pid = (process or {}).get("pid")
|
|
211
|
+
if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0 or not _pid_alive(pid):
|
|
212
|
+
return False
|
|
213
|
+
started, now = process.get("start"), _process_start(pid)
|
|
214
|
+
return started is None or now is None or started == now
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
def _command_state(command):
|
|
218
|
+
"""Whether a lane's post-create command, or what it started, still runs: "running", "unknown" or "gone".
|
|
219
|
+
|
|
220
|
+
The command leads a process group of its own, and what it started stays in that group
|
|
221
|
+
after it exits. It is "running" only while its own process answers and started when the
|
|
222
|
+
record says: then it is the command, and stopping its group is stopping the command. A
|
|
223
|
+
group that answers without that process may be what the command left behind or a stranger's
|
|
224
|
+
that took its number, and a process that answers with no start to compare may be either:
|
|
225
|
+
"unknown", which a remove refuses on and never stops.
|
|
226
|
+
"""
|
|
227
|
+
pid = (command or {}).get("pid")
|
|
228
|
+
if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0:
|
|
229
|
+
return "gone"
|
|
230
|
+
if _pid_alive(pid):
|
|
231
|
+
started, now = command.get("start"), _process_start(pid)
|
|
232
|
+
if started is None or now is None:
|
|
233
|
+
return "unknown"
|
|
234
|
+
return "running" if started == now else "gone"
|
|
235
|
+
if os.name == "nt":
|
|
236
|
+
return "gone"
|
|
237
|
+
try:
|
|
238
|
+
os.killpg(pid, 0)
|
|
239
|
+
except OSError:
|
|
240
|
+
return "gone"
|
|
241
|
+
return "unknown"
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
def lane_holder(lane):
|
|
245
|
+
"""Who is still preparing a lane, as a sentence, or None when nothing is.
|
|
246
|
+
|
|
247
|
+
The polyctl that started it while it runs, or the post-create command that polyctl started, which
|
|
248
|
+
runs on once that polyctl is killed outright - nothing can catch that - with nobody holding it to
|
|
249
|
+
lane.post_create_timeout.
|
|
250
|
+
"""
|
|
251
|
+
if lane.get("state") != "preparing":
|
|
252
|
+
return None
|
|
253
|
+
process, command = lane.get("process") or {}, lane.get("command") or {}
|
|
254
|
+
if _polyctl_alive(process):
|
|
255
|
+
return f"polyctl, process {process['pid']}, is preparing it"
|
|
256
|
+
state = _command_state(command)
|
|
257
|
+
if state == "running":
|
|
258
|
+
return (f"its post-create command, process {command['pid']}, runs on with no polyctl waiting on it; "
|
|
259
|
+
f"`polyctl lane remove {lane.get('item') or lane['name']}` stops it")
|
|
260
|
+
if state == "unknown":
|
|
261
|
+
return f"process group {command['pid']} may still run its post-create command"
|
|
262
|
+
return None
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def _settle_lane(root, name, record, problem):
|
|
266
|
+
"""Record how a start ended - ready, or failed and why - and return the lane with its name."""
|
|
267
|
+
for key in ("process", "command"):
|
|
268
|
+
record.pop(key, None)
|
|
269
|
+
record["state"] = "failed" if problem else "ready"
|
|
270
|
+
if problem:
|
|
271
|
+
record["problem"] = problem
|
|
272
|
+
_write_lane(root, name, record)
|
|
273
|
+
return dict(record, name=name)
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def _drop_lane_branch(root, branch, base):
|
|
277
|
+
"""Delete the branch a start made when git then could not make its worktree; None, or what stays and why.
|
|
278
|
+
|
|
279
|
+
`git worktree add -b` makes the branch before the checkout, and when the checkout fails - a
|
|
280
|
+
required filter such as a missing git-lfs - git removes the worktree and keeps the branch.
|
|
281
|
+
The start found no such branch and made it at base, so while it stands there it holds
|
|
282
|
+
nothing of anyone's; left, it would refuse every later start of the item.
|
|
283
|
+
"""
|
|
284
|
+
head = git_text(root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
|
|
285
|
+
if not head:
|
|
286
|
+
return None
|
|
287
|
+
if head != base:
|
|
288
|
+
return f"the branch {branch} stays: it has moved to {head[:10]} since this start made it"
|
|
289
|
+
for attempt in range(2):
|
|
290
|
+
try:
|
|
291
|
+
_git_output(root, "branch", "-D", branch)
|
|
292
|
+
return None
|
|
293
|
+
except RuntimeError as exc:
|
|
294
|
+
if attempt:
|
|
295
|
+
return f"the branch {branch} stays ({exc}); `git branch -D {branch}` removes it"
|
|
296
|
+
# A worktree git gave up on may still be listed, and git keeps a listed worktree's branch.
|
|
297
|
+
try:
|
|
298
|
+
_git_worktree_cleanup(root, "prune")
|
|
299
|
+
except RuntimeError as exc:
|
|
300
|
+
return f"the branch {branch} stays: {exc}"
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
def lane_harness_hold(root):
|
|
304
|
+
"""Why no lane may start from this checkout now, as the sentence a person reads; None when nothing holds it
|
|
305
|
+
(HARNESS-CONFIG).
|
|
306
|
+
|
|
307
|
+
What a harness reads from a project - hooks, plugins, MCP servers, instructions - and an agent changed here acts
|
|
308
|
+
wherever a harness starts on it, and a lane links its paths from this checkout and runs its post-create command, an
|
|
309
|
+
agent's own among the commands it can name, in what it made. So, as no wake, refill, nudge or hunt starts here
|
|
310
|
+
while a change to it stands unseen, no lane does either, nor while it cannot be read.
|
|
311
|
+
"""
|
|
312
|
+
try:
|
|
313
|
+
unseen = unseen_harness_config(root)
|
|
314
|
+
except Exception as exc:
|
|
315
|
+
return (f"what a harness reads from this checkout cannot be read ({' '.join(str(exc).split())[:200]}), and "
|
|
316
|
+
"nothing polyctl starts here runs until it can")
|
|
317
|
+
if not unseen:
|
|
318
|
+
return None
|
|
319
|
+
return (f"this checkout holds harness configuration nobody has seen: {harness_config_line(unseen, limit=20)}; "
|
|
320
|
+
"nothing polyctl starts here runs until a person reads it with `polyctl harness seen --by <name>`")
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
def lane_cap_hold(root, cfg, name=None):
|
|
324
|
+
"""Why this checkout may start no further lane, as a person reads it; None while it may (MACHINE-PRESSURE).
|
|
325
|
+
|
|
326
|
+
Five lanes each running a suite swap a laptop into uselessness while each looks reasonable, so
|
|
327
|
+
`limits.max_write_lanes` caps them. It counts every lane .polyctl/lanes/ records, whatever its state: a
|
|
328
|
+
failed lane's worktree stands until `polyctl lane remove` retires it, as its item is refused a second
|
|
329
|
+
one until then. Two starts at once both find room before either has a record, so a start asks
|
|
330
|
+
again once its own record, `name`, is made, counting every other: whichever of two asks second
|
|
331
|
+
sees the first, so two never both go on past the cap, though both may give way.
|
|
332
|
+
"""
|
|
333
|
+
cap = settings.get(cfg, "limits.max_write_lanes")
|
|
334
|
+
lanes = [lane for lane in lane_records(root) if lane["name"] != name]
|
|
335
|
+
if len(lanes) < cap:
|
|
336
|
+
return None
|
|
337
|
+
named = ", ".join(f"{lane.get('item') or lane['name']} ({lane.get('state') or 'unreadable'})" for lane in lanes)
|
|
338
|
+
return (f"this checkout has {len(lanes)} lane{'' if len(lanes) == 1 else 's'} already, as many as "
|
|
339
|
+
f"limits.max_write_lanes allows: {named}; `polyctl lane remove <item>` retires one, or "
|
|
340
|
+
"`polyctl config set limits.max_write_lanes <n>` changes the cap")
|
|
341
|
+
|
|
342
|
+
|
|
343
|
+
def start_lane(root, cfg, item, now=None):
|
|
344
|
+
"""Start a READY board item's lane: a worktree of its own on a branch of its own, prepared from the settings.
|
|
345
|
+
|
|
346
|
+
Everything that can refuse is asked before anything is made, the settings among it, and the
|
|
347
|
+
record in .polyctl/lanes/ is created exclusively, so two starts of one item cannot both make it.
|
|
348
|
+
The worktree is `<main checkout>-lanes/<name>` on the new branch `lane/<name>`, from this
|
|
349
|
+
checkout's HEAD, and prepare_lane prepares it. Returns the record: `ready`, or `failed` with
|
|
350
|
+
its problem and the worktree left where it is for a person to inspect. Raises LaneRefused
|
|
351
|
+
for a lane polyctl will not start, and RuntimeError when git could not add it; then neither the
|
|
352
|
+
record nor the branch is left. Stopped while it works - Ctrl-C, SIGTERM, SIGHUP - it records
|
|
353
|
+
the lane failed, or leaves nothing where git had not made the worktree yet, and stops too.
|
|
354
|
+
|
|
355
|
+
A lane past `limits.max_write_lanes` is refused, and so is one the machine has no room for: after
|
|
356
|
+
every other question, the machine is read once - memory, paging and disk - and a start, which
|
|
357
|
+
waits for no lock, is refused at once when one is past its limit (MACHINE-PRESSURE).
|
|
358
|
+
"""
|
|
359
|
+
name = lane_name(item)
|
|
360
|
+
if not name:
|
|
361
|
+
raise LaneRefused(f"{item!r} cannot name a lane: it holds no letter or digit")
|
|
362
|
+
held = lane_record(root, item)
|
|
363
|
+
if held is not None:
|
|
364
|
+
raise LaneRefused(f"{item} already has a lane, {held.get('state') or 'unreadable'}, at "
|
|
365
|
+
f"{held.get('path') or 'an unrecorded path'}; `polyctl lane remove {item}` retires it")
|
|
366
|
+
crowded = lane_cap_hold(root, cfg)
|
|
367
|
+
if crowded:
|
|
368
|
+
raise LaneRefused(crowded)
|
|
369
|
+
why = lane_not_ready(root, item)
|
|
370
|
+
if why:
|
|
371
|
+
raise LaneRefused(f"{why}; a lane starts only for a READY item, and `polyctl board ready` lists them")
|
|
372
|
+
wanted = lane_settings(cfg)
|
|
373
|
+
unseen = lane_harness_hold(root)
|
|
374
|
+
if unseen:
|
|
375
|
+
raise LaneRefused(unseen)
|
|
376
|
+
branch = LANE_BRANCH + name
|
|
377
|
+
if subprocess.run([git_binary(), "check-ref-format", "--branch", branch], cwd=root,
|
|
378
|
+
capture_output=True).returncode:
|
|
379
|
+
raise LaneRefused(f"{item} cannot name a branch: git refuses {branch}")
|
|
380
|
+
try:
|
|
381
|
+
trees = worktree_list(root)
|
|
382
|
+
except RuntimeError as exc:
|
|
383
|
+
raise LaneRefused(f"a lane is a git worktree, and this checkout's worktrees cannot be read ({exc})") from None
|
|
384
|
+
if not trees:
|
|
385
|
+
raise LaneRefused("git lists no worktree here, and a lane is one")
|
|
386
|
+
main, home = _lanes_beside(trees)
|
|
387
|
+
path = os.path.join(home, name)
|
|
388
|
+
taken = next((tree for tree in trees if _real_path(tree["path"]) == _real_path(path)), None)
|
|
389
|
+
if taken:
|
|
390
|
+
raise LaneRefused(f"{path} is already a worktree of this repository, on {taken['branch'] or 'no branch'}: "
|
|
391
|
+
"a lane another checkout started, or one made by hand, and `polyctl lane list` in the "
|
|
392
|
+
"checkout that started it shows it")
|
|
393
|
+
inside = next((tree["path"] for tree in trees if _within(path, tree["path"])), None)
|
|
394
|
+
if inside:
|
|
395
|
+
raise LaneRefused(f"{path} would lie inside the worktree {inside}, and a lane never nests in another")
|
|
396
|
+
if os.path.lexists(path):
|
|
397
|
+
raise LaneRefused(f"{path} already exists, and a lane is never made over what is there")
|
|
398
|
+
if git_text(root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"):
|
|
399
|
+
raise LaneRefused(f"the branch {branch} already exists, and a lane starts on a branch of its own")
|
|
400
|
+
base = git_text(root, "rev-parse", "--verify", "--quiet", "HEAD^{commit}")
|
|
401
|
+
if not base:
|
|
402
|
+
raise LaneRefused("this checkout has no commit to start a lane from")
|
|
403
|
+
from . import pressure
|
|
404
|
+
short = pressure.wait_for_room(cfg, 0, "the lane")
|
|
405
|
+
if short:
|
|
406
|
+
raise LaneRefused(short)
|
|
407
|
+
record = {"item": item, "branch": branch, "path": path, "base": base,
|
|
408
|
+
"started_at": int(time.time() if now is None else now), "state": "preparing",
|
|
409
|
+
"process": _process_of(os.getpid()), "prepared": [], "steps": []}
|
|
410
|
+
_lanes_directory(root)
|
|
411
|
+
try:
|
|
412
|
+
with open(lane_record_path(root, name), "x", encoding=UTF8) as fh:
|
|
413
|
+
json.dump(record, fh, indent=2, ensure_ascii=False)
|
|
414
|
+
except FileExistsError:
|
|
415
|
+
raise LaneRefused(f"{item} already has a lane; `polyctl lane list` shows it") from None
|
|
416
|
+
crowded = lane_cap_hold(root, cfg, name)
|
|
417
|
+
if crowded: # another start made its record meanwhile
|
|
418
|
+
_forget_lane(root, name)
|
|
419
|
+
raise LaneRefused(crowded)
|
|
420
|
+
try:
|
|
421
|
+
made = subprocess.run([git_binary(), "worktree", "add", "-b", branch, path, base], cwd=root,
|
|
422
|
+
capture_output=True)
|
|
423
|
+
except BaseException:
|
|
424
|
+
# Git removes a worktree it could not finish when it hears the interrupt too.
|
|
425
|
+
if os.path.isdir(path):
|
|
426
|
+
_settle_lane(root, name, record, "polyctl was stopped while git added the worktree")
|
|
427
|
+
else:
|
|
428
|
+
_drop_lane_branch(root, branch, base)
|
|
429
|
+
_forget_lane(root, name)
|
|
430
|
+
raise
|
|
431
|
+
said = "; ".join(line.strip() for line in made.stderr.decode(UTF8, "replace").splitlines() if line.strip()) \
|
|
432
|
+
or f"exit {made.returncode}"
|
|
433
|
+
if made.returncode and not os.path.isdir(path):
|
|
434
|
+
left = _drop_lane_branch(root, branch, base)
|
|
435
|
+
_forget_lane(root, name)
|
|
436
|
+
raise RuntimeError(f"git could not add the worktree: {said}" + (f"; {left}" if left else ""))
|
|
437
|
+
if made.returncode:
|
|
438
|
+
# A post-checkout hook fails after git made the worktree: it stands, and it is no lane ready.
|
|
439
|
+
return _settle_lane(root, name, record, f"git worktree add failed after making the worktree: {said}")
|
|
440
|
+
try:
|
|
441
|
+
problem = prepare_lane(root, name, record, main, wanted)
|
|
442
|
+
except KeyboardInterrupt:
|
|
443
|
+
_settle_lane(root, name, record, "polyctl was stopped before the lane was prepared"
|
|
444
|
+
+ ("; its post-create command was stopped with it" if record.get("command") else ""))
|
|
445
|
+
raise
|
|
446
|
+
except Exception as exc:
|
|
447
|
+
# A lane stuck at `preparing` would read as another start still running: say it failed.
|
|
448
|
+
problem = f"preparation stopped: {type(exc).__name__}: {exc}"
|
|
449
|
+
return _settle_lane(root, name, record, problem)
|
|
450
|
+
|
|
451
|
+
|
|
452
|
+
def prepare_lane(root, name, record, main, wanted):
|
|
453
|
+
"""Prepare a new lane as its settings say (lane_settings), stopping at the first step that fails.
|
|
454
|
+
|
|
455
|
+
`lane.link_paths` are linked from the main checkout, `lane.env` is written into
|
|
456
|
+
`lane.env_file` as NAME=value lines, and `lane.post_create` runs in the lane with those
|
|
457
|
+
variables. `{item}`, `{lane}` and `{path}` in a value or an argument stand for the lane's
|
|
458
|
+
own. Nothing is put over what the lane already has: a link over a path its branch tracks
|
|
459
|
+
would hide it, and a file written through a link would change the main checkout. Git ignores
|
|
460
|
+
all polyctl puts there (_lane_ignore). Each path polyctl put in the lane goes into record["prepared"]
|
|
461
|
+
and each step into record["steps"] as it is done, so a start that is stopped still names
|
|
462
|
+
them. Returns None, or what failed.
|
|
463
|
+
"""
|
|
464
|
+
words = {"{item}": record["item"], "{lane}": name, "{path}": record["path"]}
|
|
465
|
+
|
|
466
|
+
def fill(text):
|
|
467
|
+
for word, value in words.items():
|
|
468
|
+
text = text.replace(word, value)
|
|
469
|
+
return text
|
|
470
|
+
|
|
471
|
+
prepared, steps = record["prepared"], record["steps"]
|
|
472
|
+
for rel in (_lane_relative(named) for named in wanted["link_paths"]):
|
|
473
|
+
if rel in prepared:
|
|
474
|
+
continue # named twice: linked once
|
|
475
|
+
source, target = os.path.join(main, *rel.split("/")), os.path.join(record["path"], *rel.split("/"))
|
|
476
|
+
if not os.path.lexists(source):
|
|
477
|
+
return f"lane.link_paths names {rel}, which the main checkout {main} does not have"
|
|
478
|
+
if os.path.lexists(target):
|
|
479
|
+
return f"lane.link_paths names {rel}, which the lane's branch already has, and a link would hide it"
|
|
480
|
+
problem = _lane_ignore(record["path"], rel)
|
|
481
|
+
if problem:
|
|
482
|
+
return problem
|
|
483
|
+
try:
|
|
484
|
+
os.makedirs(os.path.dirname(target), exist_ok=True)
|
|
485
|
+
os.symlink(source, target, target_is_directory=os.path.isdir(source))
|
|
486
|
+
except OSError as exc:
|
|
487
|
+
return f"{rel} could not be linked from the main checkout ({exc.strerror or exc})"
|
|
488
|
+
prepared.append(rel)
|
|
489
|
+
steps.append(f"linked {rel}")
|
|
490
|
+
variables = {}
|
|
491
|
+
for entry in wanted["env"]:
|
|
492
|
+
key, _, value = entry.partition("=")
|
|
493
|
+
value = fill(value)
|
|
494
|
+
if any(ch in value for ch in "\r\n\0"):
|
|
495
|
+
return f"lane.env holds {entry!r}, which with this lane's own words is more than one line"
|
|
496
|
+
variables[key] = value
|
|
497
|
+
if variables:
|
|
498
|
+
rel = _lane_relative(wanted["env_file"])
|
|
499
|
+
target = os.path.join(record["path"], rel)
|
|
500
|
+
if os.path.lexists(target):
|
|
501
|
+
return f"the lane already has {rel}, and lane.env is never written over a file"
|
|
502
|
+
problem = _lane_ignore(record["path"], rel)
|
|
503
|
+
if problem:
|
|
504
|
+
return problem
|
|
505
|
+
try:
|
|
506
|
+
# "x" creates or fails, and never follows a link that stands at the name.
|
|
507
|
+
with open(target, "x", encoding=UTF8, newline="\n") as fh:
|
|
508
|
+
fh.write("".join(f"{key}={value}\n" for key, value in variables.items()))
|
|
509
|
+
except FileExistsError:
|
|
510
|
+
return f"the lane already has {rel}, and lane.env is never written over a file"
|
|
511
|
+
except OSError as exc:
|
|
512
|
+
return f"lane.env could not be written to {rel} ({exc.strerror or exc})"
|
|
513
|
+
prepared.append(rel)
|
|
514
|
+
steps.append(f"wrote {len(variables)} variable(s) to {rel}")
|
|
515
|
+
argv = [fill(word) for word in wanted["post_create"]]
|
|
516
|
+
if argv:
|
|
517
|
+
problem = _lane_post_create(root, name, record, argv, variables, wanted["post_create_timeout"])
|
|
518
|
+
if problem:
|
|
519
|
+
return problem
|
|
520
|
+
steps.append(f"ran {' '.join(argv)}")
|
|
521
|
+
return None
|
|
522
|
+
|
|
523
|
+
|
|
524
|
+
def _exclude_line(rel):
|
|
525
|
+
"""The line of an exclude file that matches rel, and nothing else, from the top of a checkout."""
|
|
526
|
+
line = "/" + re.sub(r"([\\*?\[])", r"\\\1", rel)
|
|
527
|
+
kept = line.rstrip(" ")
|
|
528
|
+
return kept + "\\ " * (len(line) - len(kept)) # a trailing space is kept only escaped
|
|
529
|
+
|
|
530
|
+
|
|
531
|
+
def _lane_ignore(path, rel):
|
|
532
|
+
"""Make git ignore rel in a lane before polyctl puts a link or a file there; None, or why it cannot.
|
|
533
|
+
|
|
534
|
+
What polyctl puts in a lane is untracked, and `git add -A` there commits whatever git does not
|
|
535
|
+
ignore: a link whose target is the main checkout on this machine, or a file holding the
|
|
536
|
+
lane's port and secrets. The usual `node_modules/` ignores a directory, never a link at
|
|
537
|
+
that name. So where git would not ignore rel, a line naming exactly it goes into the
|
|
538
|
+
repository's own exclude file - read by every worktree of the repository, committed by
|
|
539
|
+
none - and the main checkout ignores that name too, as it should. Asked before rel exists,
|
|
540
|
+
git answers as it will for a link or a file there: a pattern for directories matches neither.
|
|
541
|
+
"""
|
|
542
|
+
def ignored():
|
|
543
|
+
return subprocess.run([git_binary(), "check-ignore", "-q", "--", rel], cwd=path, capture_output=True)
|
|
544
|
+
|
|
545
|
+
if ignored().returncode == 0:
|
|
546
|
+
return None
|
|
547
|
+
exclude = git_text(path, "rev-parse", "--git-path", "info/exclude")
|
|
548
|
+
if not exclude:
|
|
549
|
+
return f"git cannot name the repository's exclude file, and {rel} would be committed from the lane"
|
|
550
|
+
exclude = os.path.join(path, exclude)
|
|
551
|
+
line = _exclude_line(rel)
|
|
552
|
+
try:
|
|
553
|
+
try:
|
|
554
|
+
with open(exclude, encoding=UTF8, errors="replace") as fh:
|
|
555
|
+
text = fh.read()
|
|
556
|
+
except FileNotFoundError:
|
|
557
|
+
text = ""
|
|
558
|
+
lines = text.split("\n")
|
|
559
|
+
if line not in lines:
|
|
560
|
+
os.makedirs(os.path.dirname(exclude), exist_ok=True)
|
|
561
|
+
with open(exclude, "a", encoding=UTF8, newline="\n") as fh:
|
|
562
|
+
fh.write(("" if not text or text.endswith("\n") else "\n")
|
|
563
|
+
+ ("" if LANE_EXCLUDE_HEADING in lines else LANE_EXCLUDE_HEADING + "\n") + line + "\n")
|
|
564
|
+
except OSError as exc:
|
|
565
|
+
return f"{rel} could not be added to git's exclude file {exclude} ({exc.strerror or exc})"
|
|
566
|
+
asked = ignored()
|
|
567
|
+
if asked.returncode == 0:
|
|
568
|
+
return None
|
|
569
|
+
why = ("a .gitignore of the branch names it again with `!`" if asked.returncode == 1 else
|
|
570
|
+
" ".join(asked.stderr.decode(UTF8, "replace").split()) or f"git check-ignore exited {asked.returncode}")
|
|
571
|
+
return (f"git would not ignore {rel} in the lane even with {line} in {exclude}, and a commit there would "
|
|
572
|
+
f"carry it: {why}")
|
|
573
|
+
|
|
574
|
+
|
|
575
|
+
def _raise_interrupt(signum, frame):
|
|
576
|
+
raise KeyboardInterrupt(f"signal {signum}")
|
|
577
|
+
|
|
578
|
+
|
|
579
|
+
def _hear_stop_signals():
|
|
580
|
+
"""Make SIGTERM and SIGHUP interrupt polyctl as Ctrl-C does, while a lane's post-create command runs.
|
|
581
|
+
|
|
582
|
+
Returns what _restore_signals puts back. The command leads a process group of its own, so no
|
|
583
|
+
signal the terminal sends reaches it, and by default either signal ends polyctl on the spot and
|
|
584
|
+
leaves the command running in a lane nobody prepares. As an interrupt, it stops the command
|
|
585
|
+
first. A signal polyctl was set to ignore, as nohup ignores SIGHUP, stays ignored, and only the
|
|
586
|
+
main thread may set a handler at all.
|
|
587
|
+
"""
|
|
588
|
+
import signal
|
|
589
|
+
import threading
|
|
590
|
+
saved = {}
|
|
591
|
+
if threading.current_thread() is not threading.main_thread():
|
|
592
|
+
return saved
|
|
593
|
+
for signum in (getattr(signal, "SIGTERM", None), getattr(signal, "SIGHUP", None)):
|
|
594
|
+
if signum is not None and signal.getsignal(signum) is signal.SIG_DFL:
|
|
595
|
+
saved[signum] = signal.signal(signum, _raise_interrupt)
|
|
596
|
+
return saved
|
|
597
|
+
|
|
598
|
+
|
|
599
|
+
def _restore_signals(saved):
|
|
600
|
+
import signal
|
|
601
|
+
for signum, handler in saved.items():
|
|
602
|
+
signal.signal(signum, handler)
|
|
603
|
+
|
|
604
|
+
|
|
605
|
+
def _kill_lane_group(pid):
|
|
606
|
+
"""Stop a lane's post-create command and everything it started: its process group, or on Windows its tree.
|
|
607
|
+
|
|
608
|
+
Returns what of it still runs on Windows, each process asked, where taskkill can be refused
|
|
609
|
+
(WINDOWS-STOP-PROVEN); a group sent SIGKILL returns [].
|
|
610
|
+
"""
|
|
611
|
+
import signal
|
|
612
|
+
if os.name == "nt":
|
|
613
|
+
return kill_turn(pid, signal.SIGTERM) or [] # taskkill /T /F, whatever the signal
|
|
614
|
+
try:
|
|
615
|
+
os.killpg(pid, signal.SIGKILL)
|
|
616
|
+
except OSError:
|
|
617
|
+
pass
|
|
618
|
+
return []
|
|
619
|
+
|
|
620
|
+
|
|
621
|
+
def _lane_post_create(root, name, record, argv, variables, timeout):
|
|
622
|
+
"""Run a new lane's post-create command in the lane; None when it exited 0, else what went wrong.
|
|
623
|
+
|
|
624
|
+
Never through a shell: the setting is a list of words, and no word is read as shell text.
|
|
625
|
+
A program named bare is looked for where polyctl looks for any (runnable_binary); one named with
|
|
626
|
+
a path is taken from the lane. It reads nothing, it leads its own process group so a
|
|
627
|
+
timeout stops whatever it started, and what it prints goes to .polyctl/lanes/<name>.log. The
|
|
628
|
+
record names it while it runs, so a list or a remove still finds it should polyctl be killed
|
|
629
|
+
outright, and a Ctrl-C, SIGTERM or SIGHUP stops it before polyctl stops.
|
|
630
|
+
"""
|
|
631
|
+
program, command = argv[0], " ".join(argv)
|
|
632
|
+
# Asked again as late as the watchdog asks before a turn: an agent can change what a harness reads while git makes
|
|
633
|
+
# the worktree (HARNESS-CONFIG).
|
|
634
|
+
unseen = lane_harness_hold(root)
|
|
635
|
+
if unseen:
|
|
636
|
+
return f"lane.post_create `{command}` was not run: {unseen}"
|
|
637
|
+
if os.path.isabs(program):
|
|
638
|
+
found = program
|
|
639
|
+
elif "/" in program or os.sep in program:
|
|
640
|
+
found = os.path.join(record["path"], program)
|
|
641
|
+
else:
|
|
642
|
+
found = runnable_binary(program)
|
|
643
|
+
if not found or not os.path.isfile(found):
|
|
644
|
+
return f"lane.post_create runs {program}, which is not a program polyctl can find"
|
|
645
|
+
log = f".polyctl/lanes/{name}.log"
|
|
646
|
+
group = ({"creationflags": getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)} if os.name == "nt"
|
|
647
|
+
else {"start_new_session": True})
|
|
648
|
+
saved = _hear_stop_signals()
|
|
649
|
+
try:
|
|
650
|
+
with open(lane_log_path(root, name), "wb") as out:
|
|
651
|
+
try:
|
|
652
|
+
proc = subprocess.Popen([found, *argv[1:]], cwd=record["path"], env=dict(os.environ, **variables),
|
|
653
|
+
stdin=subprocess.DEVNULL, stdout=out, stderr=subprocess.STDOUT, **group)
|
|
654
|
+
except OSError as exc:
|
|
655
|
+
return f"lane.post_create `{command}` could not be started ({exc.strerror or exc})"
|
|
656
|
+
try:
|
|
657
|
+
record["command"] = _process_of(proc.pid)
|
|
658
|
+
_write_lane(root, name, record)
|
|
659
|
+
code = proc.wait(timeout=timeout)
|
|
660
|
+
except BaseException as exc:
|
|
661
|
+
# Its group is its pid, and no other process can hold that pid until this one is reaped.
|
|
662
|
+
left = _kill_lane_group(proc.pid)
|
|
663
|
+
try:
|
|
664
|
+
proc.wait(timeout=LANE_STOP_SECONDS)
|
|
665
|
+
except subprocess.TimeoutExpired:
|
|
666
|
+
pass
|
|
667
|
+
if not isinstance(exc, subprocess.TimeoutExpired):
|
|
668
|
+
raise
|
|
669
|
+
if left:
|
|
670
|
+
# It said the command was stopped whatever taskkill did (WINDOWS-STOP-PROVEN).
|
|
671
|
+
return (f"lane.post_create `{command}` ran past {timeout} seconds, and {len(left)} process(es) "
|
|
672
|
+
f"of it still run after it was stopped: {left} - stop them by hand before the lane is "
|
|
673
|
+
f"removed; its output is in {log}")
|
|
674
|
+
return (f"lane.post_create `{command}` ran past {timeout} seconds and was stopped; "
|
|
675
|
+
f"its output is in {log}")
|
|
676
|
+
finally:
|
|
677
|
+
_restore_signals(saved)
|
|
678
|
+
if code:
|
|
679
|
+
return f"lane.post_create `{command}` exited {code}; its output is in {log}"
|
|
680
|
+
return None
|
|
681
|
+
|
|
682
|
+
|
|
683
|
+
def lane_changes(path, lane):
|
|
684
|
+
"""What a lane's worktree holds that nobody committed, as `git status` names it, less what polyctl put there.
|
|
685
|
+
|
|
686
|
+
Every untracked file is named, not its directory, so a link polyctl made inside a directory it
|
|
687
|
+
made is still told from a file someone wrote beside it. What polyctl put there is passed over
|
|
688
|
+
only while it is untracked, as polyctl made it: once it is staged or tracked, it is a change.
|
|
689
|
+
Git ignores all of it (_lane_ignore); this holds should the exclude file lose its lines.
|
|
690
|
+
"""
|
|
691
|
+
raw = _git_output(path, "status", "--porcelain", "-z", "--untracked-files=all")
|
|
692
|
+
ours = set(lane.get("prepared") or [])
|
|
693
|
+
fields, out, index = os.fsdecode(raw).split("\0"), [], 0
|
|
694
|
+
while index < len(fields):
|
|
695
|
+
entry = fields[index]
|
|
696
|
+
index += 1
|
|
697
|
+
if len(entry) < 4:
|
|
698
|
+
continue
|
|
699
|
+
status, name = entry[:2], entry[3:]
|
|
700
|
+
if "R" in status or "C" in status:
|
|
701
|
+
index += 1 # the name it had before follows
|
|
702
|
+
if not (status == "??" and name in ours):
|
|
703
|
+
out.append(f"{status.strip()} {name}")
|
|
704
|
+
return out
|
|
705
|
+
|
|
706
|
+
|
|
707
|
+
def lane_rows(root):
|
|
708
|
+
"""Every lane this checkout started, with where its item stands on the board and what its worktree holds."""
|
|
709
|
+
b = board(root)
|
|
710
|
+
where = {entry["id"]: state for state in BOARD_STATES for entry in b[state]}
|
|
711
|
+
lanes = lane_records(root)
|
|
712
|
+
try:
|
|
713
|
+
home = lane_home(root)[1] if lanes else None
|
|
714
|
+
except (LaneRefused, RuntimeError):
|
|
715
|
+
home = None
|
|
716
|
+
rows = []
|
|
717
|
+
for lane in lanes:
|
|
718
|
+
state = lane.get("state") or "unreadable"
|
|
719
|
+
held = lane_holder(lane)
|
|
720
|
+
if state == "preparing" and not held:
|
|
721
|
+
state = "interrupted" # its start ended before it could say how
|
|
722
|
+
# A record that cannot be read still names its lane by its file: the lane is where polyctl makes it.
|
|
723
|
+
path = lane.get("path") or (os.path.join(home, lane["name"]) if home else None)
|
|
724
|
+
exists = bool(path) and os.path.isdir(path)
|
|
725
|
+
try:
|
|
726
|
+
changes = lane_changes(path, lane) if exists else []
|
|
727
|
+
except RuntimeError:
|
|
728
|
+
changes = None
|
|
729
|
+
rows.append(dict(lane, state=state, held=held, path=path, exists=exists, changes=changes,
|
|
730
|
+
board=where.get(lane.get("item"))))
|
|
731
|
+
return rows
|
|
732
|
+
|
|
733
|
+
|
|
734
|
+
def lane_keeps(root, trees):
|
|
735
|
+
"""{real path: why it stays} for each worktree that is a lane: `polyctl worktrees` never retires one.
|
|
736
|
+
|
|
737
|
+
A lane starts at its base, so it reads as merged the moment it starts, and pruning it took
|
|
738
|
+
the worktree an agent had just been given. Each lane this checkout started is known by its
|
|
739
|
+
record; one another checkout started, by where it stands and the branch it is on.
|
|
740
|
+
"""
|
|
741
|
+
out = {}
|
|
742
|
+
for lane in lane_records(root):
|
|
743
|
+
item = lane.get("item") or lane["name"]
|
|
744
|
+
if lane.get("path"):
|
|
745
|
+
out[_real_path(lane["path"])] = f"the lane of {item}: `polyctl lane remove {item}` retires it"
|
|
746
|
+
if trees:
|
|
747
|
+
home = _real_path(_lanes_beside(trees)[1])
|
|
748
|
+
for tree in trees[1:]:
|
|
749
|
+
real = _real_path(tree["path"])
|
|
750
|
+
# The name as git gives the path: the compared path is case-folded on Windows, and a lane's
|
|
751
|
+
# branch keeps the case of its item, so lane/B was no lane there (WINDOWS-LANE-4).
|
|
752
|
+
name = os.path.basename(os.path.normpath(tree["path"]))
|
|
753
|
+
if (real not in out and os.path.dirname(real) == home
|
|
754
|
+
and tree["branch"] == LANE_BRANCH + name):
|
|
755
|
+
out[real] = "a lane another checkout started: `polyctl lane remove` there retires it"
|
|
756
|
+
return out
|
|
757
|
+
|
|
758
|
+
|
|
759
|
+
def remove_lane(root, item, now=None):
|
|
760
|
+
"""Retire an item's lane as `polyctl worktrees prune` retires a worktree (#42), refusing while it holds work.
|
|
761
|
+
|
|
762
|
+
Refused while its worktree holds changes nobody committed - other than the links and the
|
|
763
|
+
file polyctl put there to prepare it - or a review in flight, or while the polyctl that started it is
|
|
764
|
+
still preparing it. A post-create command that polyctl left running when it was killed is
|
|
765
|
+
stopped first, once it is certain to be that command. Then polyctl's own links go, so no removal
|
|
766
|
+
can reach through one into the main checkout, and prune_worktree archives the lane's .polyctl/
|
|
767
|
+
state and its branch tip and removes the worktree and the branch. Returns the steps done.
|
|
768
|
+
|
|
769
|
+
The record is a file under .polyctl/, which the agents polyctl governs can write, so it is not taken
|
|
770
|
+
at its word: polyctl removes only the path where it makes this lane, and only when git lists it
|
|
771
|
+
as a worktree of this repository, and the branch it removes is always `lane/<name>`.
|
|
772
|
+
"""
|
|
773
|
+
lane = lane_record(root, item)
|
|
774
|
+
if lane is None:
|
|
775
|
+
raise LaneRefused(f"{item} has no lane here; `polyctl lane list` shows the lanes this checkout started")
|
|
776
|
+
name = lane["name"]
|
|
777
|
+
preparing = lane.get("state") == "preparing"
|
|
778
|
+
process, command = lane.get("process") or {}, lane.get("command") or {}
|
|
779
|
+
if preparing and process.get("pid") != os.getpid() and _polyctl_alive(process):
|
|
780
|
+
raise LaneRefused(f"lane {name} is still being prepared by polyctl, process {process['pid']}")
|
|
781
|
+
try:
|
|
782
|
+
home = lane_home(root)[1]
|
|
783
|
+
trees = worktree_list(root)
|
|
784
|
+
except RuntimeError as exc:
|
|
785
|
+
raise LaneRefused(f"this checkout's worktrees cannot be read ({exc}), so lane {name} stays") from None
|
|
786
|
+
path = os.path.join(home, name)
|
|
787
|
+
if lane.get("path") and _real_path(lane["path"]) != _real_path(path):
|
|
788
|
+
raise LaneRefused(f"the record of lane {name} names {lane['path']}, and polyctl makes it at {path}; it stays")
|
|
789
|
+
if os.path.lexists(path) and not any(_real_path(tree["path"]) == _real_path(path) for tree in trees[1:]):
|
|
790
|
+
raise LaneRefused(f"{path} is not a worktree of this repository, and polyctl removes only a lane it made")
|
|
791
|
+
steps = []
|
|
792
|
+
state = _command_state(command) if preparing else "gone"
|
|
793
|
+
if state == "unknown":
|
|
794
|
+
raise LaneRefused(f"process group {command['pid']} may still run lane {name}'s post-create command, and "
|
|
795
|
+
"polyctl cannot tell that it is the one it started; stop that group, then remove the lane")
|
|
796
|
+
if state == "running":
|
|
797
|
+
_kill_lane_group(command["pid"])
|
|
798
|
+
deadline = time.monotonic() + LANE_STOP_SECONDS
|
|
799
|
+
while _command_state(command) != "gone" and time.monotonic() < deadline:
|
|
800
|
+
time.sleep(0.1)
|
|
801
|
+
if _command_state(command) != "gone":
|
|
802
|
+
raise LaneRefused(f"lane {name}'s post-create command, process {command['pid']}, did not stop")
|
|
803
|
+
steps.append(f"stop the post-create command polyctl left running (process {command['pid']})")
|
|
804
|
+
if os.path.lexists(path):
|
|
805
|
+
try:
|
|
806
|
+
changes = lane_changes(path, lane)
|
|
807
|
+
except RuntimeError as exc:
|
|
808
|
+
raise LaneRefused(f"what lane {name} holds at {path} cannot be read ({exc}), so it stays") from None
|
|
809
|
+
if changes:
|
|
810
|
+
shown = ", ".join(changes[:5]) + (f" and {len(changes) - 5} more" if len(changes) > 5 else "")
|
|
811
|
+
raise LaneRefused(f"lane {name} holds {len(changes)} uncommitted change(s) at {path}: {shown}; "
|
|
812
|
+
"commit or discard them, then remove it")
|
|
813
|
+
flying = reviews_in_flight(path)
|
|
814
|
+
if flying:
|
|
815
|
+
raise LaneRefused(f"lane {name} has a review in flight: {', '.join(flying)}")
|
|
816
|
+
for rel in lane.get("prepared") or []:
|
|
817
|
+
target = os.path.join(path, *str(rel).split("/"))
|
|
818
|
+
if _lane_relative(rel) == rel and os.path.islink(target):
|
|
819
|
+
os.unlink(target)
|
|
820
|
+
branch = LANE_BRANCH + name
|
|
821
|
+
head = git_text(root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
|
|
822
|
+
steps += prune_worktree(root, {"path": path, "branch": branch if head else None, "head": head},
|
|
823
|
+
apply=True, now=now, lane=lane)
|
|
824
|
+
_forget_lane(root, name)
|
|
825
|
+
try:
|
|
826
|
+
os.rmdir(home) # only once it is empty: polyctl made it for its lanes, and the last one is gone
|
|
827
|
+
except OSError:
|
|
828
|
+
pass
|
|
829
|
+
return steps
|