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.
- phiward/__init__.py +8 -0
- phiward/__main__.py +5 -0
- phiward/_toml.py +211 -0
- phiward/adapters/__init__.py +105 -0
- phiward/adapters/claude.py +429 -0
- phiward/broker.py +831 -0
- phiward/carryover.py +1613 -0
- phiward/claude_settings.py +1307 -0
- phiward/cli.py +110 -0
- phiward/config.py +936 -0
- phiward/confine.py +476 -0
- phiward/copying.py +533 -0
- phiward/core.py +105 -0
- phiward/data/agents-section.md +43 -0
- phiward/doctor.py +1132 -0
- phiward/fasthook.py +70 -0
- phiward/fsinfo.py +241 -0
- phiward/gateway.py +159 -0
- phiward/githooks.py +248 -0
- phiward/guards/__init__.py +0 -0
- phiward/guards/protected_paths.py +1138 -0
- phiward/hidden.py +281 -0
- phiward/init.py +155 -0
- phiward/install.py +828 -0
- phiward/inventory.py +173 -0
- phiward/mcp.py +186 -0
- phiward/mcp_config.py +1736 -0
- phiward/names.py +5 -0
- phiward/packs/dates.toml +17 -0
- phiward/packs/genomics.toml +51 -0
- phiward/packs/msk.toml +32 -0
- phiward/pathid.py +403 -0
- phiward/pathmatch.py +98 -0
- phiward/paths.py +942 -0
- phiward/pin.py +214 -0
- phiward/procinfo.py +73 -0
- phiward/remote.py +448 -0
- phiward/run.py +788 -0
- phiward/safeio.py +84 -0
- phiward/sanitize.py +691 -0
- phiward/selfcheck.py +1506 -0
- phiward/service.py +321 -0
- phiward/session_note.py +86 -0
- phiward/setup_cmd.py +886 -0
- phiward/shell.py +504 -0
- phiward/wholetool.py +1463 -0
- phiward-0.2.0b1.dist-info/METADATA +147 -0
- phiward-0.2.0b1.dist-info/RECORD +53 -0
- phiward-0.2.0b1.dist-info/WHEEL +5 -0
- phiward-0.2.0b1.dist-info/entry_points.txt +3 -0
- phiward-0.2.0b1.dist-info/licenses/LICENSE +662 -0
- phiward-0.2.0b1.dist-info/licenses/NOTICE +16 -0
- 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:])))
|