phiward 0.2.0b1__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.
Files changed (53) hide show
  1. phiward/__init__.py +8 -0
  2. phiward/__main__.py +5 -0
  3. phiward/_toml.py +211 -0
  4. phiward/adapters/__init__.py +105 -0
  5. phiward/adapters/claude.py +429 -0
  6. phiward/broker.py +831 -0
  7. phiward/carryover.py +1613 -0
  8. phiward/claude_settings.py +1307 -0
  9. phiward/cli.py +110 -0
  10. phiward/config.py +936 -0
  11. phiward/confine.py +476 -0
  12. phiward/copying.py +533 -0
  13. phiward/core.py +105 -0
  14. phiward/data/agents-section.md +43 -0
  15. phiward/doctor.py +1132 -0
  16. phiward/fasthook.py +70 -0
  17. phiward/fsinfo.py +241 -0
  18. phiward/gateway.py +159 -0
  19. phiward/githooks.py +248 -0
  20. phiward/guards/__init__.py +0 -0
  21. phiward/guards/protected_paths.py +1138 -0
  22. phiward/hidden.py +281 -0
  23. phiward/init.py +155 -0
  24. phiward/install.py +828 -0
  25. phiward/inventory.py +173 -0
  26. phiward/mcp.py +186 -0
  27. phiward/mcp_config.py +1736 -0
  28. phiward/names.py +5 -0
  29. phiward/packs/dates.toml +17 -0
  30. phiward/packs/genomics.toml +51 -0
  31. phiward/packs/msk.toml +32 -0
  32. phiward/pathid.py +403 -0
  33. phiward/pathmatch.py +98 -0
  34. phiward/paths.py +942 -0
  35. phiward/pin.py +214 -0
  36. phiward/procinfo.py +73 -0
  37. phiward/remote.py +448 -0
  38. phiward/run.py +788 -0
  39. phiward/safeio.py +84 -0
  40. phiward/sanitize.py +691 -0
  41. phiward/selfcheck.py +1506 -0
  42. phiward/service.py +321 -0
  43. phiward/session_note.py +86 -0
  44. phiward/setup_cmd.py +886 -0
  45. phiward/shell.py +504 -0
  46. phiward/wholetool.py +1463 -0
  47. phiward-0.2.0b1.dist-info/METADATA +147 -0
  48. phiward-0.2.0b1.dist-info/RECORD +53 -0
  49. phiward-0.2.0b1.dist-info/WHEEL +5 -0
  50. phiward-0.2.0b1.dist-info/entry_points.txt +3 -0
  51. phiward-0.2.0b1.dist-info/licenses/LICENSE +662 -0
  52. phiward-0.2.0b1.dist-info/licenses/NOTICE +16 -0
  53. phiward-0.2.0b1.dist-info/top_level.txt +1 -0
phiward/selfcheck.py ADDED
@@ -0,0 +1,1506 @@
1
+ """The trusted runtime checks itself: before `launch` starts a tool, phiward's
2
+ own installed files must match the hashes its installer recorded (pip and uv write them to the
3
+ distribution's RECORD), and must not be writable by anyone but their owner, who must be the
4
+ operator or root. A file changed since install (by an earlier session that ran without
5
+ `launch`, for example) makes `launch` refuse.
6
+
7
+ The check runs in a separate interpreter (`-I -S -B`, its bytecode prefix a path that cannot
8
+ exist: `-B` only stops writing, so a prefix in a folder another program can write would let it
9
+ plant a `.pyc` that runs), from this file as a script, so no compiled file changes the check. It
10
+ also finds:
11
+ - a compiled file (`__pycache__/*.pyc`) whose code is not the code of its source: Python runs a
12
+ `.pyc` whose header matches the source, and an unchecked hash-based one always;
13
+ - a file in the package that the record does not list: an extension module (`cli.*.so`) is
14
+ imported before `cli.py`.
15
+
16
+ Limits: the check is phiward's own code. Code that changes the launcher so that it skips the
17
+ check is not found by it; reinstall when in doubt. An install without a record (a source
18
+ checkout, an editable install) has nothing to check against: `launch` refuses it unless
19
+ PHIWARD_DEV=1 is set.
20
+
21
+ Standard library only: this file runs with no site folder."""
22
+
23
+ import base64
24
+ import contextlib
25
+ import csv
26
+ import hashlib
27
+ import io
28
+ import json
29
+ import marshal
30
+ import os
31
+ import re
32
+ import stat
33
+ import subprocess
34
+ import sys
35
+ from typing import Any, Dict, List, NamedTuple, Optional, Tuple
36
+
37
+ DIST = "phiward"
38
+ PACKAGE = "phiward"
39
+
40
+
41
+ class _NotRegular(OSError):
42
+ """A file phiward reads (`_open_regular`) is not a regular file."""
43
+
44
+
45
+ def _open_regular(path: str) -> int:
46
+ """Open a file to read it, never through a link and never waiting (a FIFO): O_NOFOLLOW and
47
+ O_NONBLOCK, then fstat; `_NotRegular` when it is not a regular file."""
48
+ fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | getattr(os, "O_CLOEXEC", 0))
49
+ try:
50
+ if not stat.S_ISREG(os.fstat(fd).st_mode):
51
+ raise _NotRegular(path)
52
+ except OSError:
53
+ os.close(fd)
54
+ raise
55
+ return fd
56
+
57
+
58
+ def _read_regular(path: str) -> bytes:
59
+ fd = _open_regular(path)
60
+ try:
61
+ chunks = []
62
+ while True:
63
+ b = os.read(fd, 1 << 20)
64
+ if not b:
65
+ return b"".join(chunks)
66
+ chunks.append(b)
67
+ finally:
68
+ os.close(fd)
69
+
70
+
71
+ def _sha256_b64(path: str) -> str:
72
+ h = hashlib.sha256()
73
+ fd = _open_regular(path)
74
+ try:
75
+ while True:
76
+ b = os.read(fd, 1 << 20)
77
+ if not b:
78
+ break
79
+ h.update(b)
80
+ finally:
81
+ os.close(fd)
82
+ return base64.urlsafe_b64encode(h.digest()).rstrip(b"=").decode("ascii")
83
+
84
+
85
+ HOME_PROBLEM = "your home folder can be written by your group"
86
+ OUTSIDE = "(outside your home folder)"
87
+ OUTSIDE_MINE = "(outside your home folder; yours)"
88
+ # the rule's two whys (the texts tests, doctor and fix_text read)
89
+ WRITABLE = "writable by others"
90
+ NOT_MINE = "owned by another user"
91
+ # the home folder itself, owned by another account (`_where`)
92
+ HOME_OWNER = "~/: " + NOT_MINE
93
+ # what `check_isolated` and `check_full_isolated` say when the check's child gives no answer
94
+ CHECK_FAILED = "the self-check could not run"
95
+ CHECK_SLOW = "the self-check did not finish in time"
96
+
97
+
98
+ def _home() -> str:
99
+ """The user's home folder, from the account database and never `$HOME` (the check runs with
100
+ an empty environment), as a real path; "" when the account is not known."""
101
+ try:
102
+ import pwd
103
+ return os.path.realpath(pwd.getpwuid(os.getuid()).pw_dir)
104
+ except (ImportError, KeyError):
105
+ return ""
106
+
107
+
108
+ def foreign_writable(st: Any) -> bool:
109
+ """Whether another account could write a file with this `os.stat` result: its group or its
110
+ other write bit is set. phiward does not try to tell the user's own private group from a
111
+ shared one: ACLs, accounts it cannot list (LDAP, sssd) and NFS homes made every such guess
112
+ unreliable, and clearing the group bit costs a private group nothing."""
113
+ return bool(st.st_mode & (stat.S_IWGRP | stat.S_IWOTH))
114
+
115
+
116
+ _BREW = ("/opt/homebrew", "/usr/local")
117
+
118
+
119
+ def _homebrew_admin(path: str, st: Any) -> bool:
120
+ """The one exception to the rule: on macOS, one of Homebrew's own folders, which the `admin`
121
+ group may write (its members can use sudo already): group `admin`, owned by the user or root,
122
+ not writable by others, its real path one of Homebrew's two prefixes or below one."""
123
+ if sys.platform != "darwin" or st.st_mode & stat.S_IWOTH or not _mine(st):
124
+ return False
125
+ try:
126
+ import grp
127
+ if grp.getgrgid(st.st_gid).gr_name != "admin":
128
+ return False
129
+ except (ImportError, KeyError):
130
+ return False
131
+ real = os.path.realpath(path)
132
+ return any(real == b or real.startswith(b + "/") for b in _BREW)
133
+
134
+
135
+ def _inside(path: str, folder: str) -> bool:
136
+ """`pathid.inside`, written out: this file runs as a script with the standard library only
137
+ (the self-check's child), so it cannot import it. No folder (no venv, no stdlib) holds
138
+ nothing here."""
139
+ if not folder:
140
+ return False
141
+ return path == folder or path.startswith(folder.rstrip("/") + "/") or folder == "/"
142
+
143
+
144
+ def _entry_problem(path: str, st: Any) -> Optional[str]:
145
+ """The rule for one entry, without the folders above it. A link's own mode never counts (on
146
+ Linux every link shows 0777): its folder and its target are judged instead."""
147
+ if not _mine(st):
148
+ return NOT_MINE
149
+ if not stat.S_ISLNK(st.st_mode) and foreign_writable(st) and not _homebrew_admin(path, st):
150
+ return WRITABLE
151
+ return None
152
+
153
+
154
+ def _shown(path: str, home: str) -> str:
155
+ """`path` from the home folder (`~/REL`) when it is inside it, as spelled or as its folder
156
+ really is (a linked `/home`); else as it is."""
157
+ if not home:
158
+ return path
159
+ real = os.path.join(os.path.realpath(os.path.dirname(path)), os.path.basename(path))
160
+ for p, h in ((path, home), (real, os.path.realpath(home))):
161
+ if _inside(p, h) and os.path.normpath(p) != os.path.normpath(h):
162
+ return "~/" + os.path.relpath(p, h)
163
+ return path
164
+
165
+
166
+ # the folders already judged, within one check (`_cached`); None outside one, where nothing is
167
+ # kept (the broker asks again and again, and a folder's mode can change)
168
+ _CACHE: Optional[Dict[Any, Optional[str]]] = None
169
+
170
+
171
+ @contextlib.contextmanager
172
+ def _cached() -> Any:
173
+ global _CACHE
174
+ old = _CACHE
175
+ _CACHE = {} if old is None else old
176
+ try:
177
+ yield
178
+ finally:
179
+ _CACHE = old
180
+
181
+
182
+ def _home_ids() -> Tuple[Optional[Tuple[int, int]], frozenset]:
183
+ """(the home folder's (st_dev, st_ino), those of each folder above it). Home is known by
184
+ identity, not by its spelling: `/home -> var/home`, macOS's case-insensitive names and
185
+ `/System/Volumes/Data` all lead to the same folder."""
186
+ key = ("home-ids",)
187
+ if _CACHE is not None and key in _CACHE:
188
+ return _CACHE[key] # type: ignore[return-value]
189
+ home = _home()
190
+ out: Tuple[Optional[Tuple[int, int]], frozenset] = (None, frozenset())
191
+ if home:
192
+ try:
193
+ st = os.stat(home)
194
+ above = set()
195
+ d = home
196
+ while os.path.dirname(d) != d:
197
+ d = os.path.dirname(d)
198
+ s = os.stat(d)
199
+ above.add((s.st_dev, s.st_ino))
200
+ out = ((st.st_dev, st.st_ino), frozenset(above))
201
+ except OSError:
202
+ pass
203
+ if _CACHE is not None:
204
+ _CACHE[key] = out # type: ignore[assignment]
205
+ return out
206
+
207
+
208
+ def _mine(st: Any) -> bool:
209
+ return st.st_uid in (os.getuid(), 0)
210
+
211
+
212
+ def _ids(st: Any) -> Tuple[int, int]:
213
+ return (st.st_dev, st.st_ino)
214
+
215
+
216
+ def _folder_on_way(stack: List[Tuple[str, Any]], child: Any, home_id: Any,
217
+ above: frozenset) -> Optional[str]:
218
+ """The rule for the folder at the top of `stack` (from `/` down: (name, lstat)), as the walk
219
+ steps into its entry `child` (an lstat): owned by the user or root, and no group or other
220
+ write (Homebrew's admin folders aside). A folder above the home folder is skipped when the
221
+ walk goes on towards home (a lab folder a PI owns, above `/data/lab/u`), and judged when it
222
+ leaves that way. A sticky folder outside home is fine for an entry that is the user's or
223
+ root's (the last entry never gets that: `_walk`)."""
224
+ here = stack[-1][1]
225
+ hid = _ids(here)
226
+ toward_home = hid in above and (_ids(child) == home_id or _ids(child) in above)
227
+ inside = _in_home(stack, home_id)
228
+ key = (hid, toward_home, _mine(child), inside)
229
+ if _CACHE is not None and key in _CACHE:
230
+ return _CACHE[key]
231
+ why: Optional[str] = None
232
+ if not toward_home:
233
+ folder = "/" + "/".join(n for n, _st in stack[1:])
234
+ bad = ""
235
+ if not _mine(here):
236
+ bad = NOT_MINE
237
+ elif foreign_writable(here) and not _homebrew_admin(folder, here) and \
238
+ not (not inside and here.st_mode & stat.S_ISVTX and _mine(child)):
239
+ bad = WRITABLE
240
+ if bad:
241
+ why = _where(stack, home_id, inside, bad, here)
242
+ if _CACHE is not None:
243
+ _CACHE[key] = why
244
+ return why
245
+
246
+
247
+ def _where(stack: List[Tuple[str, Any]], home_id: Any, inside: bool, bad: str,
248
+ here: Any, entry: str = "") -> str:
249
+ """A fault as the operator reads it, from the walk, which knows where it is: the folder at
250
+ the top of `stack` (`here` its lstat), or with `entry` that entry of it (`here` the entry's
251
+ lstat). The home folder: its own text; inside home: `~/REL/: why` for a folder, `~/REL: why`
252
+ for an entry; outside home: `PATH/: why MARKER` or `PATH: why MARKER`, the marker saying
253
+ whether the fault is yours (its step differs: `fix_text`)."""
254
+ if not entry and home_id is not None and _ids(here) == home_id:
255
+ return _home_text(bad)
256
+ names = [n for n, _st in stack[1:]] + ([os.path.basename(entry)] if entry else [])
257
+ names = [n for n in names if n]
258
+ # a folder is named with its `/`, whether it is the walk's last entry or a folder on the way
259
+ slash = "/" if (not entry or stat.S_ISDIR(here.st_mode)) and names else ""
260
+ if inside:
261
+ at = max(i for i, (_n, st) in enumerate(stack) if _ids(st) == home_id)
262
+ return "~/" + "/".join(names[at:]) + f"{slash}: {bad}"
263
+ tail = OUTSIDE_MINE if here.st_uid == os.getuid() else OUTSIDE
264
+ return "/" + "/".join(names) + f"{slash}: {bad} {tail}"
265
+
266
+
267
+ def _home_text(why: str) -> str:
268
+ """The fault of the home folder itself, as the operator reads it."""
269
+ return HOME_PROBLEM if why == WRITABLE else f"~/: {why}"
270
+
271
+
272
+ def _in_home(stack: List[Tuple[str, Any]], home_id: Any) -> bool:
273
+ return home_id is not None and any(_ids(st) == home_id for _n, st in stack)
274
+
275
+
276
+ def _last_problem(stack: List[Tuple[str, Any]], home_id: Any, entry: str,
277
+ st: Any) -> Optional[str]:
278
+ """The rule for the last entry of a walk: inside home the bare why (the caller names the
279
+ file; the steps there need no place), outside home the entry and its marker."""
280
+ why = _entry_problem(entry, st)
281
+ if why is None:
282
+ return None
283
+ if home_id is not None and _ids(st) == home_id:
284
+ return _home_text(why)
285
+ if _in_home(stack, home_id):
286
+ return why
287
+ return _where(stack, home_id, False, why, st, entry)
288
+
289
+
290
+ MAX_LINKS = 40
291
+
292
+
293
+ def _walk(path: str, collect: Optional[List[Tuple[str, str]]] = None) -> Optional[Tuple[str, str]]:
294
+ """`safe_path`: walk `path` from `/` as the kernel resolves it, one entry and one link at a
295
+ time (never `abspath` first: it would collapse `link/..` before the kernel does). Every
296
+ folder on the way is judged as the walk steps through it (`_folder_on_way`), so the folder
297
+ of every link in a chain is judged; a link's own mode never counts, its owner does; only
298
+ links count towards MAX_LINKS. The last entry: owned by the user or root, and no group or
299
+ other write (no sticky exception). The first problem as (text, place): `place` the folder or
300
+ entry judged, as the kernel resolved it (no link in it), "" when nothing is there. With
301
+ `collect`, a fault that is yours and outside the home folder (its step is a `chmod go-w`) is
302
+ added to it and the walk goes on, so one round names them all."""
303
+ p = path if path.startswith("/") else os.path.join(os.getcwd(), path)
304
+ home_id, above = _home_ids()
305
+ try:
306
+ stack: List[Tuple[str, Any]] = [("", os.lstat("/"))]
307
+ except OSError:
308
+ return "missing", ""
309
+
310
+ def at(names: List[str]) -> str:
311
+ return "/" + "/".join(names)
312
+
313
+ def fault(why: str, place: str) -> Optional[Tuple[str, str]]:
314
+ if collect is not None and why.endswith(OUTSIDE_MINE):
315
+ if (why, place) not in collect:
316
+ collect.append((why, place))
317
+ return None
318
+ return why, place
319
+
320
+ todo = [c for c in p.split("/") if c]
321
+ hops = 0
322
+ while todo:
323
+ c = todo.pop(0)
324
+ if c == ".":
325
+ continue
326
+ if c == "..":
327
+ if len(stack) > 1:
328
+ stack.pop()
329
+ continue
330
+ names = [n for n, _st in stack[1:]]
331
+ entry = at(names + [c])
332
+ try:
333
+ st = os.lstat(entry)
334
+ except OSError:
335
+ return "missing", ""
336
+ why = _folder_on_way(stack, st, home_id, above)
337
+ if why and fault(why, at(names)):
338
+ return why, at(names)
339
+ if stat.S_ISLNK(st.st_mode):
340
+ hops += 1
341
+ if hops > MAX_LINKS:
342
+ return "too many links", ""
343
+ if not _mine(st):
344
+ return _where(stack, home_id, _in_home(stack, home_id),
345
+ NOT_MINE, st, entry), entry
346
+ try:
347
+ target = os.readlink(entry)
348
+ except OSError:
349
+ return "missing", ""
350
+ if target.startswith("/"):
351
+ stack = stack[:1]
352
+ todo = [t for t in target.split("/") if t] + todo
353
+ continue
354
+ if todo:
355
+ if not stat.S_ISDIR(st.st_mode):
356
+ return "missing", "" # the kernel says ENOTDIR
357
+ stack.append((c, st))
358
+ continue
359
+ why = _last_problem(stack, home_id, entry, st)
360
+ return fault(why, entry) if why else None
361
+ # the path ends at a folder of the stack (`a/..`, or `/`)
362
+ here = stack[-1][1]
363
+ place = at([n for n, _st in stack[1:]])
364
+ why = _last_problem(stack[:-1] or stack, home_id, place, here)
365
+ return fault(why, place) if why else None
366
+
367
+
368
+ def safe_path(path: str) -> Optional[str]:
369
+ """The rule for "another account can change it", the one used by the self-check, the
370
+ broker's PATH and the launcher lookup: `path`, and each folder on the way to it, are owned
371
+ by the user or root and not writable by group or other (`_walk`). Folders above the home
372
+ folder are judged only where the way leaves the way home; a sticky folder outside home is
373
+ fine for the user's own entry; a link is judged by its folder and owner, then its target.
374
+ The first problem, or None."""
375
+ found = _walk(path)
376
+ return found[0] if found else None
377
+
378
+
379
+ def _faults(path: str) -> List[Tuple[str, str]]:
380
+ """Every fault of `path` that one step can fix together, as (text, place): those that are
381
+ yours outside the home folder (`_walk`'s `collect`), then the first other one."""
382
+ out: List[Tuple[str, str]] = []
383
+ last = _walk(path, out)
384
+ return out + ([last] if last else [])
385
+
386
+
387
+ class Places(NamedTuple):
388
+ """phiward's own Python, as the full check and `install` see it (`python_places`)."""
389
+ venv: str # the venv root, or ""
390
+ walk: List[str] # folders checked with everything in them
391
+ files: List[str] # single files: the interpreter and each link to it, pyvenv.cfg, libpython
392
+ cfg: str # the pyvenv.cfg Python reads (`_venv_cfg`), or "": the one source for the venv's
393
+ stdlib: str # the standard library, the one root that leaves out its own packages (`_below`)
394
+
395
+
396
+ def _link_chain(path: str) -> List[str]:
397
+ """`path` and each link on the way to what it leads to, the last one included."""
398
+ out: List[str] = []
399
+ p = os.path.abspath(path)
400
+ for _ in range(40):
401
+ out.append(p)
402
+ if not os.path.islink(p):
403
+ break
404
+ p = os.path.normpath(os.path.join(os.path.dirname(p), os.readlink(p)))
405
+ return out
406
+
407
+
408
+ def _libpython() -> str:
409
+ import sysconfig
410
+ ld = sysconfig.get_config_var("LDLIBRARY") or ""
411
+ for d in (sysconfig.get_config_var("PYTHONFRAMEWORKPREFIX"),
412
+ sysconfig.get_config_var("LIBDIR")):
413
+ if d and ld and os.path.isfile(os.path.join(d, ld)):
414
+ return os.path.join(d, ld)
415
+ return ""
416
+
417
+
418
+ def python_places(executable: Optional[str] = None, stdlib: Optional[str] = None,
419
+ dynload: Optional[str] = None,
420
+ libpython: Optional[str] = None) -> Places:
421
+ """What phiward's Python reads and runs at start, worked out without `site` (the checker runs
422
+ with `-I -S`): the interpreter and each link to it, the venv (with pyvenv.cfg), the standard
423
+ library and lib-dynload, libpython, and the folders that the venv's .pth path lines add (those
424
+ `_startup_files` accepts). Never a base Python's own site-packages or the rest of its prefix
425
+ (conda's pkgs/ and envs/). The arguments are for tests."""
426
+ import sysconfig
427
+ exe = os.path.abspath(executable or sys.executable)
428
+ cfg = _venv_cfg(exe)
429
+ venv = os.path.dirname(os.path.dirname(exe)) if cfg else ""
430
+ stdlib = sysconfig.get_path("stdlib") if stdlib is None else stdlib
431
+ dynload = (sysconfig.get_config_var("DESTSHARED") or "") if dynload is None else dynload
432
+ libpython = _libpython() if libpython is None else libpython
433
+ stdlib = os.path.normpath(stdlib) if stdlib else ""
434
+ # the roots: every folder Python reads is covered by one (`_covers`, by identity), however a
435
+ # .pth line spells it; no root is covered by another (whatever the order of the lines)
436
+ cands = ([venv] if venv else []) + [stdlib, os.path.normpath(dynload) if dynload else ""]
437
+ for site in _venv_sites(venv):
438
+ cands += _pth_targets(site)
439
+ walk: List[str] = []
440
+ for w in cands:
441
+ if w and os.path.isdir(w) and not any(_covers(x, w, stdlib) for x in walk):
442
+ walk.append(w)
443
+ # after the first pass no two roots are the same folder: drop a root another one covers
444
+ walk = [w for i, w in enumerate(walk)
445
+ if not any(j != i and _covers(x, w, stdlib) for j, x in enumerate(walk))]
446
+ files = _link_chain(exe)
447
+ if cfg:
448
+ files.append(cfg)
449
+ if libpython:
450
+ files += _link_chain(libpython) # libpython3.12.so is often a link to the .so.1.0
451
+ return Places(venv, walk, files, cfg, stdlib)
452
+
453
+
454
+ def _first_cfg(exe_dir: str) -> str:
455
+ """The pyvenv.cfg that site.py reads for an interpreter in `exe_dir`: the first of
456
+ `exe_dir/pyvenv.cfg` and the one in the folder above that is a file; "" when none is (not a
457
+ venv)."""
458
+ for d in (exe_dir, os.path.dirname(exe_dir)):
459
+ cfg = os.path.join(d, "pyvenv.cfg")
460
+ if os.path.isfile(cfg):
461
+ return cfg
462
+ return ""
463
+
464
+
465
+ def _venv_cfg(exe: str) -> str:
466
+ """`_first_cfg` for the interpreter `exe`, from its folder as spelled (site.py: `abspath`,
467
+ not `realpath`)."""
468
+ return _first_cfg(os.path.dirname(os.path.abspath(exe)))
469
+
470
+
471
+ def _venv_sites(venv: str) -> List[str]:
472
+ if not venv:
473
+ return []
474
+ out = []
475
+ for lib in ("lib", "lib64"):
476
+ try:
477
+ names = sorted(os.listdir(os.path.join(venv, lib)))
478
+ except OSError:
479
+ continue
480
+ for n in names:
481
+ site = os.path.join(venv, lib, n, "site-packages")
482
+ if n.startswith("python") and os.path.isdir(site) and \
483
+ os.path.realpath(site) not in [os.path.realpath(o) for o in out]:
484
+ out.append(site)
485
+ return out
486
+
487
+
488
+ def _pth_targets(site: str) -> List[str]:
489
+ """The folders that a site folder's accepted .pth path lines add, as Python makes them
490
+ (`_pth_dir`): `check_python` then judges each with `safe_path`, every link on the way."""
491
+ out: List[str] = []
492
+ bad = {n for n, _why in _startup_problems(site)}
493
+ try:
494
+ names = sorted(n for n in os.listdir(site) if n.endswith(".pth") and n not in bad)
495
+ except OSError:
496
+ return []
497
+ for n in names:
498
+ _problem, lines, _text = _pth_lines(os.path.join(site, n))
499
+ for kind, ln in lines:
500
+ d = _pth_dir(site, ln)
501
+ if kind == "path" and os.path.isdir(d) and d not in out:
502
+ out.append(d)
503
+ return out
504
+
505
+
506
+ MAX_PROBLEMS = 50
507
+ # names a walk of the standard library leaves out: a base Python's own packages, which phiward's
508
+ # venv does not put on its path
509
+ _NOT_WALKED = ("site-packages", "dist-packages")
510
+
511
+
512
+ def _inside_home(path: str, strict: bool = True) -> bool:
513
+ """Whether `path` (where it leads) is inside the home folder, by identity (`_home_ids`);
514
+ `strict`: not the home folder itself."""
515
+ home_id, _above = _home_ids()
516
+ if home_id is None:
517
+ return False
518
+ d = os.path.realpath(path)
519
+ first = True
520
+ while True:
521
+ try:
522
+ st = os.stat(d)
523
+ except OSError:
524
+ return False
525
+ if _ids(st) == home_id:
526
+ return not (strict and first)
527
+ parent = os.path.dirname(d)
528
+ if parent == d:
529
+ return False
530
+ d, first = parent, False
531
+
532
+
533
+ def _ident(path: str) -> Tuple[int, int]:
534
+ st = os.stat(path)
535
+ return (st.st_dev, st.st_ino)
536
+
537
+
538
+ def _is_stdlib(root: str, stdlib: str) -> bool:
539
+ """Whether `root` is the standard library, by identity (a root given through a link too)."""
540
+ try:
541
+ return bool(stdlib) and _ident(root) == _ident(stdlib)
542
+ except OSError:
543
+ return False
544
+
545
+
546
+ def _own_packages(root: str, stdlib: str) -> Dict[str, Optional[Tuple[int, int]]]:
547
+ """The one definition of what a walk leaves out: nothing, unless `root` is the standard
548
+ library; then its top-level entries named site-packages or dist-packages on disk (the base
549
+ Python's own packages, which a venv's Python does not read) that os.walk lists as folders
550
+ (`is_dir()`, a link too), each with its identity when it is a real folder (None for a link).
551
+ As os.walk reads the folder: a listing that fails gives nothing; an entry it cannot stat is
552
+ not a folder."""
553
+ if not _is_stdlib(root, stdlib):
554
+ return {}
555
+ out: Dict[str, Optional[Tuple[int, int]]] = {}
556
+ try:
557
+ entries = list(os.scandir(root))
558
+ except OSError:
559
+ return {}
560
+ for e in entries:
561
+ if e.name not in _NOT_WALKED:
562
+ continue
563
+ try:
564
+ if not e.is_dir():
565
+ continue
566
+ st = e.stat(follow_symlinks=False)
567
+ except OSError:
568
+ continue
569
+ out[e.name] = (st.st_dev, st.st_ino) if stat.S_ISDIR(st.st_mode) else None
570
+ return out
571
+
572
+
573
+ def _aside(root: str, stdlib: str) -> bool:
574
+ """Whether the walk of `root` leaves out a real folder (`_own_packages`): its tree line and
575
+ its step say so."""
576
+ return any(i is not None for i in _own_packages(root, stdlib).values())
577
+
578
+
579
+ def _covers(root: str, path: str, stdlib: str) -> bool:
580
+ """Whether the walk of `root` (`_below`) reaches `path`: climbing from where `path` really
581
+ is, by identity, `root` is reached, and not through one of the real folders it leaves out
582
+ (`_own_packages`, compared by identity: never by a spelled name). The one rule for what a
583
+ root covers, with `_below`."""
584
+ try:
585
+ rid = _ident(root)
586
+ except OSError:
587
+ return False
588
+ d, prev = os.path.realpath(path), None
589
+ while True:
590
+ try:
591
+ here = _ident(d)
592
+ except OSError:
593
+ return False
594
+ if here == rid:
595
+ # the root reached: through what it leaves out? (listed only now, and only below it)
596
+ return prev is None or prev not in {
597
+ i for i in _own_packages(root, stdlib).values() if i is not None}
598
+ parent = os.path.dirname(d)
599
+ if parent == d:
600
+ return False
601
+ d, prev = parent, here
602
+
603
+
604
+ def _below(root: str, stdlib: str) -> Any:
605
+ """Every folder and file below a walk root, as `check_python` judges them and `fix_modes`
606
+ changes them (links are not followed: a link is judged where it leads), but what
607
+ `_own_packages` leaves out (only for the standard library)."""
608
+ own = _own_packages(root, stdlib)
609
+ for here, dirs, names in os.walk(root):
610
+ if here == root and own:
611
+ dirs[:] = [d for d in dirs if d not in own]
612
+ for n in dirs + names:
613
+ yield os.path.join(here, n)
614
+
615
+
616
+ def check_python(places: Places) -> List[str]:
617
+ """The full check of phiward's own Python: every file in `places`, and every folder and file
618
+ in its folders (`_below`), with the folders above them, pass `safe_path`; a link is judged
619
+ where it leads; the venv reads no base site folder (`_system_site`); and its start-up files
620
+ pass `_startup_problems`, with no start-up module in a folder a .pth adds. One line per
621
+ fault, `FAULT: why`, the place said by the walk (`_where`, `_faults`: every fault of yours
622
+ outside the home folder in one round): outside the home folder with its marker, and the
623
+ entries of yours below a root there as one line for the tree (TREE_WHY). Kept by `_Lines`:
624
+ in the order the step reads them, at most MAX_PROBLEMS, then one line that there are
625
+ more."""
626
+ home = _home()
627
+ keep = _Lines()
628
+
629
+ def put(why: str, place: str, asked: str) -> None:
630
+ # a fault the walk placed names itself; a bare one (the last entry, inside home) is
631
+ # named by the place the walk judged (a link: where it leads; nothing there: the path
632
+ # asked), a folder with `/`. Its kind is the why's: a full kind words nothing more
633
+ key = (why, place or asked)
634
+ if why == HOME_PROBLEM or why.startswith(("/", "~/")):
635
+ keep.add(why)
636
+ elif key in keep.at:
637
+ pass # worded and kept already: a duplicate says nothing more
638
+ elif keep.full(_kind(why)):
639
+ keep.more = True
640
+ else:
641
+ keep.at.add(key)
642
+ if not place:
643
+ keep.add(f"{_shown(asked, home)}: {why}")
644
+ else:
645
+ slash = "/" if os.path.isdir(place) and not os.path.islink(place) else ""
646
+ keep.add(f"{_shown(place, home)}{slash}: {why}")
647
+
648
+ def judged(found: List[Tuple[str, str]], asked: str) -> None:
649
+ for why, place in found:
650
+ put(why, place, asked)
651
+
652
+ with _cached():
653
+ for f in places.files:
654
+ judged(_faults(f), f)
655
+ for root in places.walk:
656
+ # the root's own faults, and still everything below it: one round names them all
657
+ judged(_faults(root), root)
658
+ # os.walk does not follow links: every entry is where its root is
659
+ outside = not _inside_home(root, strict=False)
660
+ mine = 0
661
+ for full in _below(root, places.stdlib):
662
+ try:
663
+ st = os.lstat(full)
664
+ except OSError:
665
+ continue
666
+ if stat.S_ISLNK(st.st_mode):
667
+ # Python reads where a link leads: the way there and the target
668
+ judged(_link_faults(full), full)
669
+ continue
670
+ why = _entry_problem(full, st)
671
+ if why and outside and st.st_uid == os.getuid():
672
+ mine += 1 # yours, outside home: one line for the tree (`fix_text`)
673
+ elif why:
674
+ put(f"{full}: {why} {OUTSIDE}" if outside else why, full, full)
675
+ if mine:
676
+ keep.add(_tree_line(root, mine, _aside(root, places.stdlib)))
677
+ if _system_site(places.cfg):
678
+ keep.add(f"{_shown(places.cfg, home)}: {SYSTEM_SITE}")
679
+ for site in _venv_sites(places.venv):
680
+ for n, why in _startup_problems(site):
681
+ keep.add(f"{_shown(os.path.join(site, n), home)}: {why}")
682
+ # `import sitecustomize` searches the folders the .pth lines added too
683
+ for target in _pth_targets(site):
684
+ try:
685
+ names = sorted(os.listdir(target))
686
+ except OSError:
687
+ continue
688
+ for n in names:
689
+ if _is_startup(n):
690
+ keep.add(f"{_shown(os.path.join(target, n), home)}: {PTH_STARTUP}")
691
+ return keep.lines()
692
+
693
+
694
+ (K_HOME, K_HOME_OWNER, K_OUTSIDE, K_OUTSIDE_MINE, K_PTH, K_NO_ANSWER, K_REINSTALL,
695
+ K_MODES) = range(8)
696
+ KINDS = 8
697
+
698
+
699
+ def _kind(problem: str) -> int:
700
+ """A line's kind, in the order `fix_text` reads them (its step is the lowest kind's): the
701
+ home folder writable by the group (0) or owned by another account (1); a fault outside it
702
+ that another account owns or can write (2), or that is yours (3); a start-up file in a
703
+ folder a .pth adds (4); a check that gave no answer (5); anything a reinstall fixes (6);
704
+ a mode `install` fixes (7). Read from the end of the line only (a path may hold `: `), the
705
+ whole line where it has no place."""
706
+ if problem.endswith(HOME_PROBLEM):
707
+ return K_HOME
708
+ if problem == HOME_OWNER:
709
+ return K_HOME_OWNER
710
+ if problem.endswith(OUTSIDE):
711
+ return K_OUTSIDE
712
+ if problem.endswith(OUTSIDE_MINE):
713
+ return K_OUTSIDE_MINE
714
+ if problem.endswith(": " + PTH_STARTUP):
715
+ return K_PTH
716
+ if problem in (CHECK_FAILED, CHECK_SLOW):
717
+ return K_NO_ANSWER
718
+ if not problem.endswith(WRITABLE):
719
+ return K_REINSTALL
720
+ return K_MODES
721
+
722
+
723
+ MORE = "and more"
724
+
725
+
726
+ class _Lines:
727
+ """The lines of a check, as the step reads them: each once, at most MAX_PROBLEMS of each
728
+ kind (`_kind`), so a line of a lower kind is never pushed out by many of a higher one; a new
729
+ line of a full kind only says there are more. `lines()`: the kinds in order, at most
730
+ MAX_PROBLEMS, then MORE when there are more."""
731
+
732
+ def __init__(self) -> None:
733
+ self.kept: set = set()
734
+ self.at: set = set() # (why, place) of the lines `check_python` worded and kept
735
+ self.by: List[List[str]] = [[] for _ in range(KINDS)]
736
+ self.more = False
737
+
738
+ def full(self, kind: int) -> bool:
739
+ return len(self.by[kind]) >= MAX_PROBLEMS
740
+
741
+ def add(self, text: str) -> None:
742
+ if text == MORE:
743
+ self.more = True
744
+ return
745
+ if text in self.kept:
746
+ return
747
+ kind = _kind(text)
748
+ if self.full(kind):
749
+ self.more = True
750
+ return
751
+ self.kept.add(text)
752
+ self.by[kind].append(text)
753
+
754
+ def lines(self) -> List[str]:
755
+ out = [t for b in self.by for t in b]
756
+ if self.more or len(out) > MAX_PROBLEMS:
757
+ return out[:MAX_PROBLEMS] + [MORE]
758
+ return out
759
+
760
+
761
+ # the tree line of `check_python` and `_check`: entries of yours below a root outside the home
762
+ # folder, which one `find` fixes (`_tree_step`)
763
+ TREE_WHY = "in it " + WRITABLE
764
+
765
+
766
+ # the standard library's tree line, when it holds its own packages folder: the step leaves it out
767
+ TREE_ASIDE = TREE_WHY + ", its own packages folder aside"
768
+
769
+
770
+ def _tree_line(root: str, n: int, aside: bool = False) -> str:
771
+ """The one line for `n` entries of yours below `root`, outside the home folder; `aside`:
772
+ the standard library's own packages folder is left out (`_below`, `_tree_step`)."""
773
+ count = "1 entry" if n == 1 else f"{n} entries"
774
+ return f"{root.rstrip('/')}/: {count} {TREE_ASIDE if aside else TREE_WHY} {OUTSIDE_MINE}"
775
+ SYSTEM_SITE = "lets Python read the base Python's and your own site folders"
776
+
777
+
778
+ def _system_site(cfg: str) -> bool:
779
+ """Whether a venv's pyvenv.cfg (`_first_cfg`; "" for no venv) lets Python read the base
780
+ site folders, as site.venv reads it (3.9 to 3.14): line by line, `key.strip().lower()` and
781
+ `value.strip()`, the last line wins, and with no such line it does. A file that cannot be
782
+ read as utf-8 counts as reading them (Python would not start)."""
783
+ if not cfg:
784
+ return False
785
+ value = "true"
786
+ try:
787
+ # where a link leads (`places.files` judges the chain); never waiting on a FIFO; lines as
788
+ # `for line in open(cfg)` gives them (universal newlines)
789
+ text = _read_regular(os.path.realpath(cfg)).decode("utf-8")
790
+ for line in io.StringIO(text, newline=None):
791
+ if "=" in line:
792
+ key, _, v = line.partition("=")
793
+ if key.strip().lower() == "include-system-site-packages":
794
+ value = v.strip().lower()
795
+ except (OSError, ValueError):
796
+ return True
797
+ return value == "true"
798
+
799
+
800
+ PTH_STARTUP = "a start-up file in a folder a .pth adds"
801
+
802
+
803
+ def _link_faults(link: str) -> List[Tuple[str, str]]:
804
+ """A link inside phiward's Python, judged where it leads (`_faults`); a link that leads
805
+ nowhere yet, by the deepest folder that exists on its way (another account could make the
806
+ target there)."""
807
+ found = _faults(link)
808
+ if not found or found[-1][0] != "missing":
809
+ return found
810
+ d = os.path.dirname(os.path.realpath(link))
811
+ while d != "/" and not os.path.isdir(d):
812
+ d = os.path.dirname(d)
813
+ return found[:-1] + _faults(d)
814
+
815
+
816
+ def _clear(path: str) -> bool:
817
+ """Remove group and other write from one file or folder you own, never through a link and
818
+ never waiting on a FIFO: opened with O_NOFOLLOW and O_NONBLOCK, then fstat and fchmod (the
819
+ open file is what is changed, whatever happens to the name). Whether it was changed."""
820
+ try:
821
+ before = os.lstat(path)
822
+ except OSError:
823
+ return False
824
+ if stat.S_ISLNK(before.st_mode) or before.st_uid != os.getuid() or \
825
+ not before.st_mode & 0o022:
826
+ return False
827
+ try:
828
+ fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK |
829
+ getattr(os, "O_CLOEXEC", 0))
830
+ except OSError:
831
+ return False
832
+ try:
833
+ st = os.fstat(fd)
834
+ if st.st_uid != os.getuid() or (st.st_dev, st.st_ino) != (before.st_dev, before.st_ino):
835
+ return False
836
+ mode = stat.S_IMODE(st.st_mode)
837
+ if not mode & 0o022:
838
+ return False
839
+ os.fchmod(fd, mode & ~0o022)
840
+ return True
841
+ except OSError:
842
+ return False
843
+ finally:
844
+ os.close(fd)
845
+
846
+
847
+ def _launcher_link_folder(scripts: Any) -> str:
848
+ """The PATH folder of the first `phiward` that leads to one of the launcher `scripts`, when it
849
+ is inside the home folder (phiward never changes `/usr/local/bin`, nor the home folder)."""
850
+ want = {os.path.realpath(sc) for sc in scripts}
851
+ for e in os.environ.get("PATH", "").split(":"):
852
+ cand = os.path.join(e, "phiward")
853
+ if e.startswith("/") and os.path.lexists(cand) and os.path.realpath(cand) in want:
854
+ return e if _inside_home(e) else ""
855
+ return ""
856
+
857
+
858
+ def fix_modes(places: Optional[Places] = None, scripts: Optional[Any] = None,
859
+ package_dir: Optional[str] = None) -> List[str]:
860
+ """What `install` does for the full check, and only inside the home folder (never the home
861
+ folder itself): compile the folders of `places` there that you own (leaving out a base
862
+ Python's own site-packages, as the check does), so no other program on the same Python makes
863
+ a group-writable `__pycache__` there later; then remove group and other write from what you
864
+ own of them (`_below`), of the package, the launcher scripts and `places.files`, of the
865
+ folders above them up to the home folder, and of the PATH folder that holds the `phiward`
866
+ link. What is outside the home folder is left as it is: the check names it with its step.
867
+ The folders where something was changed."""
868
+ places = python_places() if places is None else places
869
+ scripts = (launcher_scripts() or ()) if scripts is None else scripts
870
+ package_dir = _running_package() if package_dir is None else package_dir
871
+ import compileall
872
+ roots = [r for r in places.walk if _inside_home(r)]
873
+ for root in roots:
874
+ try:
875
+ if os.lstat(root).st_uid != os.getuid():
876
+ continue
877
+ # what the check judges (`_below`: what `_own_packages` leaves out, no link), and
878
+ # only regular files: opening a FIFO named like a module would wait for ever
879
+ for full in _below(root, places.stdlib):
880
+ if full.endswith(".py") and stat.S_ISREG(os.lstat(full).st_mode):
881
+ compileall.compile_file(full, quiet=2)
882
+ except Exception: # noqa: BLE001 - a folder it cannot compile is checked as it is
883
+ pass
884
+ changed: List[str] = []
885
+
886
+ seen: set = set()
887
+
888
+ def note(path: str) -> None:
889
+ d = path if os.path.isdir(path) and not os.path.islink(path) else os.path.dirname(path)
890
+ if d not in seen:
891
+ seen.add(d)
892
+ changed.append(d)
893
+
894
+ tops = roots + ([package_dir] if _inside_home(package_dir) else [])
895
+ links: List[str] = []
896
+ for root in tops:
897
+ # inside the home folder, and os.walk does not follow links: everything below is too
898
+ for full in [root] + list(_below(root, places.stdlib)):
899
+ if os.path.islink(full):
900
+ links.append(full)
901
+ elif _clear(full):
902
+ note(full)
903
+ singles = [f for f in list(places.files) + list(scripts) if _inside_home(f)]
904
+ for f in singles:
905
+ if _clear(f):
906
+ note(f)
907
+ link_folder = _launcher_link_folder(scripts)
908
+ if link_folder and _clear(link_folder):
909
+ note(link_folder)
910
+ for p in tops + singles + ([link_folder] if link_folder else []):
911
+ d = os.path.dirname(os.path.realpath(p))
912
+ while _inside_home(d):
913
+ if _clear(d):
914
+ note(d)
915
+ d = os.path.dirname(d)
916
+ # a link: what the check names of it (`_link_faults`: every folder of the chain, the
917
+ # target, the deepest folder of a dangling one), judged again after each change, never
918
+ # with a cache (a folder just changed must be judged anew)
919
+ for link in links:
920
+ for _ in range(MAX_LINKS * 2):
921
+ found = _link_faults(link)
922
+ place = next((pl for _why, pl in found if pl and _inside_home(pl)), "")
923
+ if not place or not _clear(place):
924
+ break
925
+ note(place)
926
+ return changed
927
+
928
+
929
+ _WHYS = (WRITABLE, NOT_MINE)
930
+ _TREE = re.compile(r": \d+ entr(?:y|ies) (" + re.escape(TREE_ASIDE) + "|" + re.escape(TREE_WHY)
931
+ + ")$")
932
+
933
+
934
+ def _fault(problem: str) -> Tuple[str, str]:
935
+ """(the place a problem names as its fault, its tree kind: "" for no tree line, "all", or
936
+ "aside" for the standard library's line that leaves out its own packages folder): the
937
+ problem without its marker and its why, read from the end only (a path may hold `: `)."""
938
+ body = problem
939
+ for marker in (OUTSIDE_MINE, OUTSIDE):
940
+ if body.endswith(marker):
941
+ body = body[:-len(marker)].rstrip()
942
+ break
943
+ tree = _TREE.search(body)
944
+ if tree:
945
+ return body[:tree.start()], "aside" if tree.group(1) == TREE_ASIDE else "all"
946
+ for why in _WHYS:
947
+ if body.endswith(": " + why):
948
+ body = body[:-len(": " + why)]
949
+ break
950
+ return body, ""
951
+
952
+
953
+ def _tree_step(root: str, aside: bool) -> str:
954
+ """The one command for the entries of yours below a walk root outside the home folder, from
955
+ inside the root (a linked root is followed; the patterns hold no part of its name), with
956
+ umask 022: first what `_below` judges there (links skipped; with `aside`, what
957
+ `_own_packages` leaves out, by its names on disk, a folder only: a file of that name is
958
+ judged) loses group and other write, so nothing of the tree runs before its modes are fixed;
959
+ then phiward's Python compiles it, as `install` does inside the home folder, so no later
960
+ start writes a group-writable `__pycache__` there (`-I -S`: no folder of the tree on its path
961
+ beyond its own standard library, no .pth runs; with `aside`, `-x` leaves out the same
962
+ folder); then the same `find` again (a default ACL can make a new `__pycache__`
963
+ group-writable). The user id is written out (no `$(...)`: tcsh). A `cd` that fails runs
964
+ nothing."""
965
+ import shlex
966
+ prune = ("-path ./site-packages -type d -prune -o -path ./dist-packages -type d -prune -o "
967
+ if aside else "")
968
+ skip = "-x '^\\./(site|dist)-packages/' " if aside else ""
969
+ find = (f"find . {prune}! -type l -user {os.getuid()} "
970
+ "\\( -perm -020 -o -perm -002 \\) -exec chmod go-w {} +")
971
+ return (f"(cd {shlex.quote(root)} && (umask 022 ; {find} ; "
972
+ f"{shlex.quote(sys.executable)} -I -S -m compileall -qq {skip}. ; {find}))")
973
+
974
+
975
+ def _reinstall(package_dir: str) -> str:
976
+ """The reinstall step for the tool that installed phiward, read from the file that tool
977
+ keeps in its venv (pipx: pipx_metadata.json; uv: uv-receipt.toml), at the running version:
978
+ what restores a changed file and removes a planted one (uv: `--force --reinstall`; pipx:
979
+ `reinstall`, then `install --force`, which also restores a file edited in a cache that
980
+ uv hard-links)."""
981
+ from phiward import __version__
982
+ venv = _venv_of(os.path.dirname(package_dir)) if package_dir else ""
983
+ if venv and os.path.isfile(os.path.join(venv, "pipx_metadata.json")):
984
+ return f"`pipx reinstall phiward && pipx install --force phiward=={__version__}`"
985
+ if venv and os.path.isfile(os.path.join(venv, "uv-receipt.toml")):
986
+ return f"`uv tool install --force --reinstall phiward=={__version__}`"
987
+ return f"the way you installed it (phiward {__version__})"
988
+
989
+
990
+ def fix_text(problems: List[str], package_dir: str) -> str:
991
+ """The one step for the self-check's problems, the same in `doctor`, `launch` and every
992
+ wrapped server: the step of the lowest kind among them (`_kind`): the home folder first
993
+ (phiward never changes it), then a fault outside the home folder that another account owns
994
+ or can write (not phiward's to change), then the faults outside the home folder that are
995
+ yours (`chmod go-w` on exactly those, and one `find` per tree of yours), then a start-up
996
+ file a .pth folder holds, a check that gave no answer, anything a reinstall fixes (a changed
997
+ file, start-up code), else the modes, which `install` fixes."""
998
+ import shlex
999
+ kinds = [(_kind(p), p) for p in problems if p != MORE]
1000
+ kind = min((k for k, _p in kinds), default=K_MODES)
1001
+ of = [p for k, p in kinds if k == kind]
1002
+ if kind == K_HOME:
1003
+ return ("make your home folder writable by you alone: `chmod go-w ~`, then start again")
1004
+ if kind == K_HOME_OWNER:
1005
+ return ("your home folder belongs to another account: phiward cannot keep its own files "
1006
+ "safe there; ask your administrator to give it back to you")
1007
+ if kind == K_OUTSIDE:
1008
+ from phiward import __version__
1009
+ venv = _venv_of(os.path.dirname(package_dir)) if package_dir else ""
1010
+ pipx = bool(venv) and os.path.isfile(os.path.join(venv, "pipx_metadata.json"))
1011
+ cmd = (("pipx uninstall phiward && " if pipx else "")
1012
+ + "uv tool install --force --python-preference only-managed "
1013
+ f"phiward=={__version__}")
1014
+ return (f"install phiward on uv's own Python, inside your home folder (`{cmd}`): "
1015
+ f"another account can change {_fault(of[0])[0]}")
1016
+ if kind == K_OUTSIDE_MINE:
1017
+ faults = [_fault(p) for p in of]
1018
+ singles = list(dict.fromkeys(f.rstrip("/") or "/" for f, tree in faults if not tree))
1019
+ trees = list(dict.fromkeys((f.rstrip("/") or "/", tree == "aside")
1020
+ for f, tree in faults if tree))
1021
+ cmds = ([f"chmod go-w {' '.join(map(shlex.quote, singles))}"] if singles else []) + \
1022
+ [_tree_step(t, aside) for t, aside in trees]
1023
+ more = ", then run `phiward doctor` again" if MORE in problems else ""
1024
+ return ("make it writable by you alone (phiward does not change files outside your home "
1025
+ f"folder): {', then '.join(f'`{c}`' for c in cmds)}{more}, then start again")
1026
+ if kind == K_PTH:
1027
+ return (f"remove {of[0][:-len(': ' + PTH_STARTUP)]} (phiward did not install it, "
1028
+ "and Python runs it at every start), then start again")
1029
+ if kind == K_NO_ANSWER:
1030
+ return (f"start again; if it says this again, reinstall phiward {_reinstall(package_dir)}")
1031
+ if kind == K_REINSTALL:
1032
+ return f"reinstall phiward {_reinstall(package_dir)}, then start again"
1033
+ return ("run `(cd ~ && phiward install claude --user --write)` (it makes phiward's own files "
1034
+ "writable by you alone), then start again")
1035
+
1036
+
1037
+ def _owner_or_mode_faults(path: str) -> List[Tuple[str, str]]:
1038
+ """`_faults` as (why, place) (every fault of yours outside the home folder, then the first
1039
+ other one, as `check_python` finds them), and a link is a problem: a file phiward installed
1040
+ is never one."""
1041
+ try:
1042
+ st = os.lstat(path)
1043
+ except OSError:
1044
+ return [("missing", "")]
1045
+ if stat.S_ISLNK(st.st_mode):
1046
+ return [("a link", "")]
1047
+ return _faults(path)
1048
+
1049
+
1050
+ def _same_code(a: Any, b: Any) -> bool:
1051
+ """Two code objects do the same (the file name and line numbers aside)."""
1052
+ if type(a) is not type(b):
1053
+ return False
1054
+ if not hasattr(a, "co_code"):
1055
+ if isinstance(a, (tuple, frozenset)):
1056
+ if len(a) != len(b):
1057
+ return False
1058
+ sa = sorted(a, key=repr) if isinstance(a, frozenset) else a
1059
+ sb = sorted(b, key=repr) if isinstance(b, frozenset) else b
1060
+ return all(_same_code(x, y) for x, y in zip(sa, sb))
1061
+ if isinstance(a, (float, complex)):
1062
+ return repr(a) == repr(b) # -0.0 == 0.0, and a NaN is never == itself
1063
+ return a == b
1064
+ for attr in ("co_code", "co_names", "co_varnames", "co_freevars", "co_cellvars", "co_flags",
1065
+ "co_argcount", "co_posonlyargcount", "co_kwonlyargcount", "co_name",
1066
+ "co_nlocals", "co_stacksize", "co_exceptiontable"):
1067
+ if getattr(a, attr, None) != getattr(b, attr, None):
1068
+ return False
1069
+ return _same_code(a.co_consts, b.co_consts)
1070
+
1071
+
1072
+ def _opt_level(pyc: str) -> int:
1073
+ """The optimization level a compiled file's name says (`x.cpython-312.opt-2.pyc`)."""
1074
+ parts = os.path.basename(pyc).split(".")
1075
+ for p in parts:
1076
+ if p.startswith("opt-") and p[4:].isdigit():
1077
+ return int(p[4:])
1078
+ return 0
1079
+
1080
+
1081
+ def _pyc_problem(pyc: str, source: str) -> Optional[str]:
1082
+ """Why Python could run code from `pyc` other than `source`'s, or None."""
1083
+ try:
1084
+ data = _read_regular(pyc)
1085
+ src = _read_regular(source)
1086
+ except _NotRegular:
1087
+ return "not a regular file"
1088
+ except OSError:
1089
+ return "cannot be read"
1090
+ if len(data) < 16:
1091
+ return None # Python ignores it
1092
+ flags = int.from_bytes(data[4:8], "little")
1093
+ if flags == 0: # timestamp-based: used only when the header matches the source
1094
+ try:
1095
+ st = os.stat(source)
1096
+ except OSError:
1097
+ return None
1098
+ mtime = int.from_bytes(data[8:12], "little")
1099
+ size = int.from_bytes(data[12:16], "little")
1100
+ if mtime != (int(st.st_mtime) & 0xFFFFFFFF) or size != (st.st_size & 0xFFFFFFFF):
1101
+ return None # stale: Python compiles the source again
1102
+ try:
1103
+ code = marshal.loads(data[16:])
1104
+ want = compile(src, source, "exec", dont_inherit=True, optimize=_opt_level(pyc))
1105
+ except Exception: # noqa: BLE001 - anything unreadable is a problem
1106
+ return "cannot be read as code"
1107
+ return None if _same_code(code, want) else "does not match its source"
1108
+
1109
+
1110
+ def check(files: Optional[List[Tuple[str, str]]] = None,
1111
+ package_dir: str = "") -> Tuple[bool, List[str]]:
1112
+ """(installed, problems), in this process. `files` is a list of (path, "sha256=<b64>");
1113
+ with `package_dir`, files there that the list does not name are problems too."""
1114
+ if files is None:
1115
+ return _installed_files_check()
1116
+ with _cached():
1117
+ return _check(files, package_dir)
1118
+
1119
+
1120
+ def _lowest(problems: List[str]) -> List[str]:
1121
+ """The lines of the lowest kind, which the step (`fix_text`) fixes: a tree line first (it
1122
+ covers a whole folder: the package, a root of phiward's Python)."""
1123
+ kinds = [(_kind(p), p) for p in problems if p != MORE]
1124
+ low = min((k for k, _p in kinds), default=None)
1125
+ return sorted((p for k, p in kinds if k == low), key=lambda p: not _fault(p)[1])
1126
+
1127
+
1128
+ def shown(problems: List[str]) -> List[str]:
1129
+ """The lines a refusal shows: at most three of `_lowest`."""
1130
+ return _lowest(problems)[:3]
1131
+
1132
+
1133
+ def _listed(problems: List[str]) -> str:
1134
+ """`shown`, joined, and how many more lines of that kind there are (a full kind: more than
1135
+ it kept). MORE from another kind is not this kind's."""
1136
+ of = _lowest(problems)
1137
+ text = "; ".join(of[:3])
1138
+ if len(of) >= MAX_PROBLEMS and MORE in problems:
1139
+ return text + f"; and at least {len(of) - 3} more"
1140
+ if len(of) > 3:
1141
+ return text + f"; and {len(of) - 3} more"
1142
+ return text
1143
+
1144
+
1145
+ def refusal(problems: List[str]) -> str:
1146
+ """What failed, in the words every caller uses (`launch`, the session note, `doctor`): a
1147
+ check that gave no answer says so; else the lines its step fixes (`shown`)."""
1148
+ if problems and _kind(problems[0]) == K_NO_ANSWER:
1149
+ return f"phiward's self-check gave no answer ({problems[0]})"
1150
+ return f"phiward's own files fail its self-check ({_listed(problems)})"
1151
+
1152
+
1153
+ def _named(name: str, why: str) -> str:
1154
+ """A line of the package check: `NAME: why`, or the why alone when it names its own place
1155
+ (the walk's `_where`: the home folder, a path)."""
1156
+ return why if why == HOME_PROBLEM or why.startswith(("/", "~/")) else f"{name}: {why}"
1157
+
1158
+
1159
+ def _check(files: List[Tuple[str, str]], package_dir: str) -> Tuple[bool, List[str]]:
1160
+ problems = _Lines()
1161
+ dirs = set()
1162
+ listed = set()
1163
+ # the faults of yours outside the home folder inside the package folder: one tree line, as
1164
+ # `check_python` gives for a root there, so the step is one command (`_tree_step`)
1165
+ real_pkg = os.path.realpath(package_dir) if package_dir else ""
1166
+ folded: set = set()
1167
+
1168
+ def add(name: str, found: List[Tuple[str, str]]) -> None:
1169
+ for why, place in found:
1170
+ if real_pkg and place and why.endswith(OUTSIDE_MINE) and _inside(place, real_pkg):
1171
+ folded.add(place)
1172
+ else:
1173
+ problems.add(_named(name, why))
1174
+
1175
+ for path, want in files:
1176
+ listed.add(os.path.normpath(path))
1177
+ found = _owner_or_mode_faults(path)
1178
+ if found:
1179
+ add(os.path.basename(path), found)
1180
+ if any(why in ("missing", "a link", "too many links") for why, _p in found):
1181
+ continue # nothing there to read
1182
+ else:
1183
+ dirs.add(os.path.dirname(path))
1184
+ # read even with a mode fault: a changed file is named in the same round
1185
+ mode, _, value = want.partition("=")
1186
+ if mode == "sha256":
1187
+ try:
1188
+ if _sha256_b64(path) != value:
1189
+ problems.add(f"{os.path.basename(path)}: changed since install")
1190
+ except _NotRegular:
1191
+ problems.add(f"{os.path.basename(path)}: not a regular file")
1192
+ continue
1193
+ except OSError:
1194
+ problems.add(f"{os.path.basename(path)}: cannot be read")
1195
+ continue
1196
+ if path.endswith(".py"):
1197
+ cache = os.path.join(os.path.dirname(path), "__pycache__")
1198
+ stem = os.path.basename(path)[:-3] + "."
1199
+ try:
1200
+ names = [n for n in os.listdir(cache) if n.startswith(stem) and n.endswith(".pyc")]
1201
+ except OSError:
1202
+ names = []
1203
+ for n in names:
1204
+ why = _pyc_problem(os.path.join(cache, n), path)
1205
+ if why:
1206
+ problems.add(f"{n}: {why}")
1207
+ for d in sorted(dirs):
1208
+ add(f"{os.path.basename(d)}/", _owner_or_mode_faults(d))
1209
+ if folded:
1210
+ problems.add(_tree_line(real_pkg, len(folded)))
1211
+ if package_dir:
1212
+ for here, subdirs, names in os.walk(package_dir):
1213
+ for n in subdirs:
1214
+ # a linked folder is imported as a package before a module of the same name, and
1215
+ # os.walk does not enter it
1216
+ if os.path.islink(os.path.join(here, n)):
1217
+ problems.add(f"{n}/: a link in the package")
1218
+ for n in names:
1219
+ full = os.path.normpath(os.path.join(here, n))
1220
+ if full in listed:
1221
+ continue
1222
+ if os.path.basename(here) == "__pycache__" and n.endswith(".pyc"):
1223
+ continue # compared with their sources above; an orphan is never imported
1224
+ problems.add(f"{n}: not in the install record")
1225
+ return True, problems.lines()
1226
+
1227
+
1228
+ def _record_check(record: str) -> Tuple[bool, List[str]]:
1229
+ site = os.path.dirname(os.path.dirname(record))
1230
+ files: List[Tuple[str, str]] = []
1231
+ try:
1232
+ text = _read_regular(record).decode("utf-8")
1233
+ for row in csv.reader(io.StringIO(text, newline="")):
1234
+ if len(row) >= 2 and row[0].startswith(PACKAGE + "/") and row[1]:
1235
+ files.append((os.path.normpath(os.path.join(site, row[0])), row[1]))
1236
+ except (OSError, ValueError, csv.Error):
1237
+ return True, ["the install record cannot be read"]
1238
+ if not files:
1239
+ return False, [] # an editable install: the record lists no package files
1240
+ with _cached():
1241
+ installed, problems = check(files, os.path.join(site, PACKAGE))
1242
+ keep = _Lines()
1243
+ for p in problems + _startup_files(site):
1244
+ keep.add(p)
1245
+ return installed, keep.lines()
1246
+
1247
+
1248
+ # files the interpreter runs at start, before any check: a .pth line that starts with `import`
1249
+ # runs code; sitecustomize and usercustomize are imported
1250
+ STARTUP = ("sitecustomize", "usercustomize")
1251
+
1252
+
1253
+ def _is_startup(name: str) -> bool:
1254
+ """Whether `name` in a folder on Python's path could be imported as a start-up module: the
1255
+ module name alone (a package folder) or with any suffix (`.py`, `.pyc`, an extension
1256
+ module); a name that is not importable is refused too (simpler than the import system)."""
1257
+ return any(name == m or name.startswith(m + ".") for m in STARTUP)
1258
+ # what virtual environment tools write themselves (the whole file)
1259
+ KNOWN_STARTUP = {"_virtualenv.pth": "import _virtualenv"}
1260
+ # a .pth file Python reads whole; phiward reads it only when it is no larger than this
1261
+ PTH_LIMIT = 1 << 20
1262
+ # the only bytes a .pth may hold: then no Python version decodes or splits it differently from
1263
+ # phiward (3.12.16 and 3.13 decode utf-8-sig and split on \x0c and friends; 3.9 does not)
1264
+ _PTH_BYTES = frozenset(b"\t\n\r") | frozenset(range(0x20, 0x7F))
1265
+
1266
+
1267
+ def _venv_of(site: str) -> str:
1268
+ """The venv a site folder (`VENV/lib/pythonX.Y/site-packages`) belongs to (its pyvenv.cfg as
1269
+ site.py finds it: `_first_cfg`), or ""."""
1270
+ d = os.path.dirname(os.path.dirname(os.path.dirname(site)))
1271
+ return d if _first_cfg(os.path.join(d, "bin")) else ""
1272
+
1273
+
1274
+ def _allowed_places(site: str) -> List[str]:
1275
+ """Where a .pth path line may lead, as real paths: the venv, and for a pipx venv
1276
+ (`PIPX_HOME/venvs/NAME`) pipx's shared libraries (`PIPX_HOME/shared`), from the venv's own
1277
+ place; nothing else."""
1278
+ venv = _venv_of(site)
1279
+ if not venv:
1280
+ return []
1281
+ out = [os.path.realpath(venv)]
1282
+ if os.path.basename(os.path.dirname(venv)) == "venvs":
1283
+ out.append(os.path.realpath(os.path.join(os.path.dirname(os.path.dirname(venv)),
1284
+ "shared")))
1285
+ return out
1286
+
1287
+
1288
+ def _pth_lines(path: str) -> Tuple[str, List[Tuple[str, str]], str]:
1289
+ """(problem, [(kind, line)], text) of a .pth file, its lines taken as site.addpackage takes
1290
+ them: `#` at the start, skipped; blank, skipped; `import ` or `import\t` (after any leading
1291
+ whitespace: stricter than site), code; anything else, rstripped, a path. A file that is not
1292
+ plain ASCII, or larger than PTH_LIMIT, is a problem: phiward does not guess how Python
1293
+ reads it."""
1294
+ try:
1295
+ fd = _open_regular(path)
1296
+ try:
1297
+ data = os.read(fd, PTH_LIMIT + 1)
1298
+ finally:
1299
+ os.close(fd)
1300
+ except _NotRegular:
1301
+ return "not a regular file", [], ""
1302
+ except OSError:
1303
+ return "cannot be read", [], ""
1304
+ if len(data) > PTH_LIMIT:
1305
+ return "too large to be checked", [], ""
1306
+ if set(data) - _PTH_BYTES:
1307
+ return "not plain ASCII (Python may read it differently)", [], ""
1308
+ text = data.decode("ascii")
1309
+ out: List[Tuple[str, str]] = []
1310
+ for line in text.splitlines():
1311
+ if line.startswith("#") or not line.strip():
1312
+ continue
1313
+ if line.lstrip().startswith(("import ", "import\t")):
1314
+ out.append(("code", line))
1315
+ else:
1316
+ out.append(("path", line.rstrip()))
1317
+ return "", out, text
1318
+
1319
+
1320
+ def _pth_dir(site: str, line: str) -> str:
1321
+ """The folder Python adds for a .pth path line: site.makepath, abspath(join(site, line)),
1322
+ which is lexical (it does not follow a link before `..`)."""
1323
+ return os.path.abspath(os.path.join(site, line))
1324
+
1325
+
1326
+ def _startup_files(site: str, places: Optional[List[str]] = None) -> List[str]:
1327
+ """`_startup_problems` as `NAME: why` lines."""
1328
+ return [f"{n}: {why}" for n, why in _startup_problems(site, places)]
1329
+
1330
+
1331
+ def _startup_problems(site: str, places: Optional[List[str]] = None) -> List[Tuple[str, str]]:
1332
+ """The start-up files of a site folder that phiward does not accept, as (name, why): a
1333
+ sitecustomize or usercustomize; a .pth phiward cannot read as Python does (`_pth_lines`); one
1334
+ with a line that runs code, unless the whole file is a known one (an install record that lists
1335
+ it proves nothing); one with a path line whose folder (as Python makes it) leads outside the
1336
+ venv and pipx's shared libraries."""
1337
+ places = _allowed_places(site) if places is None else places
1338
+ try:
1339
+ names = os.listdir(site)
1340
+ except OSError:
1341
+ return []
1342
+ out: List[Tuple[str, str]] = []
1343
+ for n in sorted(names):
1344
+ if _is_startup(n):
1345
+ out.append((n, "a start-up file"))
1346
+ continue
1347
+ if not n.endswith(".pth"):
1348
+ continue
1349
+ problem, lines, text = _pth_lines(os.path.join(site, n))
1350
+ if problem:
1351
+ out.append((n, problem))
1352
+ continue
1353
+ if KNOWN_STARTUP.get(n) == text.strip():
1354
+ continue
1355
+ if any(kind == "code" for kind, _ln in lines):
1356
+ out.append((n, "runs code at start"))
1357
+ continue
1358
+ for _kind, ln in lines:
1359
+ d = _pth_dir(site, ln)
1360
+ real = os.path.realpath(d)
1361
+ if not any(_inside(real, p) for p in places):
1362
+ out.append((n, "adds a folder outside phiward's Python"))
1363
+ break
1364
+ if os.path.exists(d) and not os.path.isdir(d):
1365
+ # Python adds what exists: a zip on the path can hold start-up code
1366
+ out.append((n, "adds a file to Python's path"))
1367
+ break
1368
+ return out
1369
+
1370
+
1371
+ def _record_path() -> str:
1372
+ try:
1373
+ from importlib import metadata
1374
+ dist = metadata.distribution(DIST)
1375
+ except Exception: # noqa: BLE001
1376
+ return ""
1377
+ for f in dist.files or []:
1378
+ s = str(f)
1379
+ if s.endswith(".dist-info/RECORD"):
1380
+ return str(f.locate())
1381
+ return ""
1382
+
1383
+
1384
+ LAUNCHERS = ("phiward", "agent-guards")
1385
+
1386
+
1387
+ def launcher_scripts(record: Optional[str] = None,
1388
+ package_dir: Optional[str] = None) -> Optional[frozenset]:
1389
+ """The console scripts (`phiward`, `agent-guards`) that the install record of the running
1390
+ package lists, as real paths: the launcher Claude Code must start for a wrapped MCP server.
1391
+ None when there is no such record: a source checkout, an editable install (its record lists
1392
+ no package files), or a record of another copy than the running one."""
1393
+ record = _record_path() if record is None else record
1394
+ package_dir = _running_package() if package_dir is None else package_dir
1395
+ if not record:
1396
+ return None
1397
+ try:
1398
+ st = os.stat(record)
1399
+ key = (record, package_dir, st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns)
1400
+ except OSError:
1401
+ return None
1402
+ if key in _SCRIPTS_CACHE:
1403
+ return _SCRIPTS_CACHE[key]
1404
+ got = _launcher_scripts(record, package_dir)
1405
+ _SCRIPTS_CACHE.clear()
1406
+ _SCRIPTS_CACHE[key] = got
1407
+ return got
1408
+
1409
+
1410
+ _SCRIPTS_CACHE: Dict[tuple, Optional[frozenset]] = {}
1411
+
1412
+
1413
+ def _launcher_scripts(record: str, package_dir: str) -> Optional[frozenset]:
1414
+ site = os.path.dirname(os.path.dirname(record))
1415
+ if os.path.realpath(os.path.join(site, PACKAGE)) != os.path.realpath(package_dir):
1416
+ return None
1417
+ scripts, package_files = set(), False
1418
+ try:
1419
+ text = _read_regular(record).decode("utf-8")
1420
+ for row in csv.reader(io.StringIO(text, newline="")):
1421
+ if not row:
1422
+ continue
1423
+ if row[0].startswith(PACKAGE + "/"):
1424
+ package_files = True
1425
+ elif os.path.basename(row[0]) in LAUNCHERS:
1426
+ path = os.path.normpath(os.path.join(site, row[0]))
1427
+ if os.path.isfile(path):
1428
+ scripts.add(os.path.realpath(path))
1429
+ except (OSError, ValueError, csv.Error):
1430
+ return None
1431
+ return frozenset(scripts) if package_files else None
1432
+
1433
+
1434
+ def _installed_files_check() -> Tuple[bool, List[str]]:
1435
+ record = _record_path()
1436
+ return _record_check(record) if record else (False, [])
1437
+
1438
+
1439
+ def _running_package() -> str:
1440
+ return os.path.dirname(os.path.abspath(__file__))
1441
+
1442
+
1443
+ # the self-check child's bytecode prefix: below /dev/null, which is no folder, so Python finds no
1444
+ # compiled file there to read (and `-B` writes none)
1445
+ NO_PYCACHE = "/dev/null/phiward"
1446
+
1447
+
1448
+ def check_isolated(timeout: float = 60) -> Tuple[bool, List[str]]:
1449
+ """The check, in a separate interpreter that reads no site folder, no environment and no
1450
+ compiled file (`launch` uses this). An install whose package is not the one running (a
1451
+ source checkout on the path in front of it) counts as no install."""
1452
+ record = _record_path()
1453
+ if not record:
1454
+ return False, []
1455
+ site = os.path.dirname(os.path.dirname(record))
1456
+ if os.path.realpath(os.path.join(site, PACKAGE)) != os.path.realpath(_running_package()):
1457
+ return False, []
1458
+ cmd = [sys.executable, "-I", "-S", "-B", "-X", f"pycache_prefix={NO_PYCACHE}",
1459
+ os.path.abspath(__file__), record]
1460
+ try:
1461
+ r = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout,
1462
+ env={"PATH": "/usr/bin:/bin"})
1463
+ out: Dict[str, Any] = json.loads(r.stdout)
1464
+ return bool(out["installed"]), [str(p) for p in out["problems"]]
1465
+ except subprocess.TimeoutExpired:
1466
+ return True, [CHECK_SLOW]
1467
+ except (OSError, subprocess.SubprocessError, ValueError, KeyError, TypeError):
1468
+ return True, [CHECK_FAILED]
1469
+
1470
+
1471
+ def check_full_isolated(timeout: float = 120) -> Tuple[bool, List[str], List[str]]:
1472
+ """(installed, the package's problems as `check_isolated` finds them, the rest of the full
1473
+ check of phiward's own Python), in a separate interpreter (`-I -S -B`), for `doctor`."""
1474
+ record = _record_path()
1475
+ if not record:
1476
+ return False, [], []
1477
+ site = os.path.dirname(os.path.dirname(record))
1478
+ if os.path.realpath(os.path.join(site, PACKAGE)) != os.path.realpath(_running_package()):
1479
+ return False, [], []
1480
+ cmd = [sys.executable, "-I", "-S", "-B", "-X", f"pycache_prefix={NO_PYCACHE}",
1481
+ os.path.abspath(__file__), "--full", record, sys.executable]
1482
+ try:
1483
+ r = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout,
1484
+ env={"PATH": "/usr/bin:/bin"})
1485
+ out: Dict[str, Any] = json.loads(r.stdout)
1486
+ return (bool(out["installed"]), [str(p) for p in out["problems"]],
1487
+ [str(p) for p in out["python"]])
1488
+ except subprocess.TimeoutExpired:
1489
+ return True, [CHECK_SLOW], []
1490
+ except (OSError, subprocess.SubprocessError, ValueError, KeyError, TypeError):
1491
+ return True, [CHECK_FAILED], []
1492
+
1493
+
1494
+ def _main(argv: List[str]) -> Dict[str, Any]:
1495
+ if argv[:1] != ["--full"]:
1496
+ ok, found = _record_check(argv[0])
1497
+ return {"installed": ok, "problems": found}
1498
+ record, exe = (argv[1:] + ["", ""])[:2]
1499
+ ok, found = _record_check(record)
1500
+ places = python_places(exe or None)
1501
+ return {"installed": ok, "problems": found,
1502
+ "python": check_python(places)}
1503
+
1504
+
1505
+ if __name__ == "__main__":
1506
+ sys.stdout.write(json.dumps(_main(sys.argv[1:])))