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/carryover.py
ADDED
|
@@ -0,0 +1,1613 @@
|
|
|
1
|
+
"""Carry-over: what a session leaves behind for later.
|
|
2
|
+
|
|
3
|
+
Under `launch` the whole tool runs in the profile, so what a session writes matters only for
|
|
4
|
+
what reads it later. Each session therefore runs in a config folder of its own
|
|
5
|
+
(`runs/<id>/config`), built at start from a trusted copy that no session can read or write
|
|
6
|
+
(`~/.phiward/carryover/<tool>/`), and thrown away at exit. Nothing is shared between
|
|
7
|
+
sessions (stateless). No process is ever ended.
|
|
8
|
+
|
|
9
|
+
- Instructions: files the tool loads as instructions or settings (the adapter's list) that the
|
|
10
|
+
session changed, and the notable keys of `.claude.json`, go to quarantine; the operator reads
|
|
11
|
+
them and accepts them (`phiward carryover show | accept ID`), or adds files of their own
|
|
12
|
+
(`carryover add PATH`). Links are never trusted. Everything else the session made is thrown
|
|
13
|
+
away with its folder.
|
|
14
|
+
- The project: every changed, new or removed file is reported, instructions for models first.
|
|
15
|
+
|
|
16
|
+
The launcher writes into a folder a session can write only by descriptor, and reads or removes
|
|
17
|
+
what a session wrote only after renaming it into `trash/`. Anything kept may be deleted at any
|
|
18
|
+
time; a start rebuilds from
|
|
19
|
+
what is left and never adopts anything from a folder a session can write. Sessions may run in
|
|
20
|
+
parallel: each holds a lock on its own run folder, which cleaners respect."""
|
|
21
|
+
|
|
22
|
+
import errno
|
|
23
|
+
import fcntl
|
|
24
|
+
import fnmatch
|
|
25
|
+
import hashlib
|
|
26
|
+
import json
|
|
27
|
+
import os
|
|
28
|
+
import secrets
|
|
29
|
+
import stat
|
|
30
|
+
import sys
|
|
31
|
+
import time
|
|
32
|
+
from dataclasses import dataclass, field
|
|
33
|
+
from typing import Dict, List, NamedTuple, Optional, Sequence, Tuple
|
|
34
|
+
|
|
35
|
+
from phiward import claude_settings, safeio
|
|
36
|
+
|
|
37
|
+
MAX_ENTRIES = 20_000
|
|
38
|
+
MAX_BYTES = 500 * 1024 * 1024
|
|
39
|
+
QUARANTINE_MAX = 200
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class CarryoverError(Exception):
|
|
43
|
+
pass
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclass
|
|
47
|
+
class Spec:
|
|
48
|
+
"""An adapter's carry-over data (stateless). `instructions`: top-level names in the
|
|
49
|
+
config folder that the tool loads as instructions or settings; they come from the trusted
|
|
50
|
+
copy, and the session's changes go to quarantine. `json_main`: a JSON file the tool keeps
|
|
51
|
+
its own state in (it comes from the trusted copy too); only changes to the `json_notable`
|
|
52
|
+
keys go to quarantine. Everything else a session writes is thrown away with its folder.
|
|
53
|
+
`memory_setting`, `memory_rel`: the setting that moves auto memory into the session's
|
|
54
|
+
folder, and that folder's name (an instruction)."""
|
|
55
|
+
instructions: List[str] = field(default_factory=list)
|
|
56
|
+
json_main: str = ""
|
|
57
|
+
json_notable: List[List[str]] = field(default_factory=list)
|
|
58
|
+
memory_setting: str = ""
|
|
59
|
+
memory_rel: str = ""
|
|
60
|
+
# inside the instruction folders: downloads the tool makes in every fresh folder, never
|
|
61
|
+
# loaded as instructions by themselves; dropped without a quarantine entry
|
|
62
|
+
downloads: List[str] = field(default_factory=list)
|
|
63
|
+
# keys of json_main set in every session unless the trusted copy says otherwise: UI state
|
|
64
|
+
# only, never instructions (a fresh folder otherwise shows the first-run screens)
|
|
65
|
+
json_defaults: Dict[str, object] = field(default_factory=dict)
|
|
66
|
+
|
|
67
|
+
@property
|
|
68
|
+
def enabled(self) -> bool:
|
|
69
|
+
return bool(self.instructions or self.json_main)
|
|
70
|
+
|
|
71
|
+
def trusted_names(self) -> List[str]:
|
|
72
|
+
return self.instructions + ([self.json_main] if self.json_main else [])
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
_MCP_KEYS = ["mcpServers", "enableAllProjectMcpServers", "enabledMcpjsonServers",
|
|
76
|
+
"disabledMcpjsonServers"]
|
|
77
|
+
SPECS: Dict[str, Spec] = {
|
|
78
|
+
"claude": Spec(
|
|
79
|
+
# what Claude Code loads as instructions or settings (memory and claude-directory docs):
|
|
80
|
+
# what it runs as code (the one list, claude_settings), and its instruction files
|
|
81
|
+
instructions=list(dict.fromkeys(
|
|
82
|
+
list(claude_settings.CODE_DIRS) + list(claude_settings.CODE_FILES)
|
|
83
|
+
+ list(claude_settings.SETTINGS_NAMES)
|
|
84
|
+
+ ["CLAUDE.md", "rules", "output-styles", "agent-memory", "keybindings.json",
|
|
85
|
+
"auto-memory"])),
|
|
86
|
+
json_main=".claude.json",
|
|
87
|
+
json_notable=[[k] for k in _MCP_KEYS + ["autoConnectIde", "claudeInChromeDefaultEnabled",
|
|
88
|
+
"customApiKeyResponses", "primaryApiKey"]] +
|
|
89
|
+
[["projects", "*", k] for k in _MCP_KEYS + ["allowedTools", "hasTrustDialogAccepted",
|
|
90
|
+
"hasClaudeMdExternalIncludesApproved",
|
|
91
|
+
"hasClaudeMdExternalIncludesWarningShown"]],
|
|
92
|
+
memory_setting="autoMemoryDirectory",
|
|
93
|
+
memory_rel="auto-memory",
|
|
94
|
+
# the plugin catalog Claude Code fetches into a fresh folder (~14 MB); a plugin becomes
|
|
95
|
+
# active only when installed or enabled (installed_plugins.json, plugins/cache,
|
|
96
|
+
# enabledPlugins in settings.json), and those still go to quarantine
|
|
97
|
+
# also the records of built-in plugins; remote-settings.json and
|
|
98
|
+
# policy-limits.json are fetched from the server at each start, so they are not
|
|
99
|
+
# instruction names at all: a session's copy is thrown away with its folder
|
|
100
|
+
downloads=["plugins/marketplaces", "plugins/known_marketplaces.json",
|
|
101
|
+
"plugins/store/*_builtin-*.json"],
|
|
102
|
+
json_defaults={"hasCompletedOnboarding": True}),
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
# -- signatures -----------------------------------------------------------------------------------
|
|
107
|
+
|
|
108
|
+
def _hash_file(path: str) -> str:
|
|
109
|
+
fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
|
|
110
|
+
try:
|
|
111
|
+
h = hashlib.sha256()
|
|
112
|
+
while True:
|
|
113
|
+
b = os.read(fd, 1 << 20)
|
|
114
|
+
if not b:
|
|
115
|
+
return h.hexdigest()
|
|
116
|
+
h.update(b)
|
|
117
|
+
finally:
|
|
118
|
+
os.close(fd)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
class _Budget:
|
|
122
|
+
def __init__(self) -> None:
|
|
123
|
+
self.entries = 0
|
|
124
|
+
self.bytes = 0
|
|
125
|
+
|
|
126
|
+
def take(self, size: int) -> bool:
|
|
127
|
+
self.entries += 1
|
|
128
|
+
self.bytes += size
|
|
129
|
+
return self.entries <= MAX_ENTRIES and self.bytes <= MAX_BYTES
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
TOO_LARGE = "\0too large"
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def signature(path: str, budget: Optional[_Budget] = None) -> Optional[Dict[str, str]]:
|
|
136
|
+
"""The content of a file, link or folder tree, by relative name; None when missing; links
|
|
137
|
+
recorded, never followed. Past the budget the result is marked, so it never equals a
|
|
138
|
+
recorded one. Walks without recursion, so a deep tree cannot stop it."""
|
|
139
|
+
budget = budget or _Budget()
|
|
140
|
+
try:
|
|
141
|
+
st0 = os.lstat(path)
|
|
142
|
+
except FileNotFoundError:
|
|
143
|
+
return None
|
|
144
|
+
out: Dict[str, str] = {}
|
|
145
|
+
stack: List[Tuple[str, str, os.stat_result]] = [(path, ".", st0)]
|
|
146
|
+
while stack:
|
|
147
|
+
p, rel, st = stack.pop()
|
|
148
|
+
if not budget.take(st.st_size if stat.S_ISREG(st.st_mode) else 0):
|
|
149
|
+
out[TOO_LARGE] = "x"
|
|
150
|
+
return out
|
|
151
|
+
mode = f"{stat.S_IMODE(st.st_mode):o}"
|
|
152
|
+
if stat.S_ISLNK(st.st_mode):
|
|
153
|
+
out[rel] = "l:" + os.readlink(p)
|
|
154
|
+
elif stat.S_ISREG(st.st_mode):
|
|
155
|
+
try:
|
|
156
|
+
out[rel] = f"f:{mode}:" + _hash_file(p)
|
|
157
|
+
except OSError:
|
|
158
|
+
out[rel] = "f:?"
|
|
159
|
+
elif stat.S_ISDIR(st.st_mode):
|
|
160
|
+
out[rel] = f"d:{mode}"
|
|
161
|
+
try:
|
|
162
|
+
entries = sorted(os.scandir(p), key=lambda e: e.name)
|
|
163
|
+
except OSError:
|
|
164
|
+
out[rel] = "d:?"
|
|
165
|
+
continue
|
|
166
|
+
for e in reversed(entries):
|
|
167
|
+
r = f"{rel}/{e.name}" if rel != "." else e.name
|
|
168
|
+
try:
|
|
169
|
+
stack.append((e.path, r, e.stat(follow_symlinks=False)))
|
|
170
|
+
except OSError:
|
|
171
|
+
out[r] = "?"
|
|
172
|
+
else:
|
|
173
|
+
out[rel] = "s:special"
|
|
174
|
+
return out
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def _has_link(sig: Optional[Dict[str, str]]) -> bool:
|
|
178
|
+
return bool(sig) and any(v.startswith("l:") for v in sig.values())
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
# -- moving and copying (rules P1) ------------------------------
|
|
182
|
+
#
|
|
183
|
+
# These run in the unconfined launcher. They are used only on things that no session can change
|
|
184
|
+
# any more: the trusted copy, quarantine, `state/files/`, and a run folder after it has been
|
|
185
|
+
# renamed into `trash/`. Folders a session can still write are touched only through descriptors
|
|
186
|
+
# (`_opendir`, renames with dir_fd), never by path.
|
|
187
|
+
|
|
188
|
+
MAX_FILE = 64 * 1024 * 1024 # a kept file or a JSON file larger than this is not read
|
|
189
|
+
QUARANTINE_ENTRY_BYTES = 50 * 1024 * 1024
|
|
190
|
+
_UF = getattr(stat, "UF_IMMUTABLE", 0) | getattr(stat, "UF_APPEND", 0)
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
def _opendir(name: str, dir_fd: Optional[int] = None) -> int:
|
|
194
|
+
"""A folder opened without following a link, owned by the operator."""
|
|
195
|
+
fd = os.open(name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=dir_fd)
|
|
196
|
+
if os.fstat(fd).st_uid != os.getuid():
|
|
197
|
+
os.close(fd)
|
|
198
|
+
raise CarryoverError("a folder is not owned by you")
|
|
199
|
+
return fd
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def _movable(parent_fd: int, name: str) -> None:
|
|
203
|
+
"""A folder a session made unreadable (chmod 000) cannot move to another parent: its owner
|
|
204
|
+
bits are given back first, by descriptor, never through a link. On Linux the session's
|
|
205
|
+
processes have ended, so the entry checked is the entry changed."""
|
|
206
|
+
try:
|
|
207
|
+
st = os.lstat(name, dir_fd=parent_fd)
|
|
208
|
+
if not stat.S_ISDIR(st.st_mode) or st.st_uid != os.getuid():
|
|
209
|
+
return
|
|
210
|
+
mode = stat.S_IMODE(st.st_mode) | 0o700
|
|
211
|
+
try:
|
|
212
|
+
os.chmod(name, mode, dir_fd=parent_fd, follow_symlinks=False)
|
|
213
|
+
except NotImplementedError:
|
|
214
|
+
os.chmod(name, mode, dir_fd=parent_fd)
|
|
215
|
+
except OSError:
|
|
216
|
+
pass
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def _unlock_at(dir_fd: int, name: str) -> None:
|
|
220
|
+
"""`_unlock` for an entry named relative to a folder descriptor: the process changes into the
|
|
221
|
+
folder for the one call (the tree no longer changes: trash), so no path length limits it."""
|
|
222
|
+
if not _UF or not hasattr(os, "chflags"):
|
|
223
|
+
return
|
|
224
|
+
here = os.open(".", os.O_RDONLY)
|
|
225
|
+
try:
|
|
226
|
+
os.fchdir(dir_fd)
|
|
227
|
+
_unlock(name)
|
|
228
|
+
except OSError:
|
|
229
|
+
pass
|
|
230
|
+
finally:
|
|
231
|
+
os.fchdir(here)
|
|
232
|
+
os.close(here)
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def _unlock(p: str) -> None:
|
|
236
|
+
"""Only the immutable and append flags (a session can set them to stop removal), only on an
|
|
237
|
+
entry that no longer changes, never on a hard-linked file."""
|
|
238
|
+
if not _UF or not hasattr(os, "chflags"):
|
|
239
|
+
return
|
|
240
|
+
try:
|
|
241
|
+
st = os.lstat(p)
|
|
242
|
+
if stat.S_ISREG(st.st_mode) and st.st_nlink > 1:
|
|
243
|
+
return # a hard link: the file is not only ours
|
|
244
|
+
if st.st_flags & _UF:
|
|
245
|
+
os.chflags(p, st.st_flags & ~_UF, follow_symlinks=False)
|
|
246
|
+
except (OSError, AttributeError):
|
|
247
|
+
pass
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def _copy(src: str, dst: str, budget: Optional[_Budget] = None,
|
|
251
|
+
skip: Sequence[str] = ()) -> None:
|
|
252
|
+
"""Copy a file, link or folder tree into `dst` (which must not exist, in a folder only the
|
|
253
|
+
launcher writes). The source is read through descriptors only, never following a link, so a
|
|
254
|
+
folder swapped for a link while it is copied is never entered. Links
|
|
255
|
+
are copied as links; a hard-linked file, a special file, or a tree past the budget is
|
|
256
|
+
refused."""
|
|
257
|
+
budget = budget or _Budget()
|
|
258
|
+
st = os.lstat(src)
|
|
259
|
+
|
|
260
|
+
def take(st: os.stat_result) -> None:
|
|
261
|
+
if not budget.take(st.st_size if stat.S_ISREG(st.st_mode) else 0):
|
|
262
|
+
raise CarryoverError("too large to copy")
|
|
263
|
+
|
|
264
|
+
def file_at(dir_fd: Optional[int], name: str, out: str) -> None:
|
|
265
|
+
fi = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=dir_fd)
|
|
266
|
+
try:
|
|
267
|
+
fst = os.fstat(fi)
|
|
268
|
+
if not stat.S_ISREG(fst.st_mode):
|
|
269
|
+
raise CarryoverError(f"{_esc(name)} is not a regular file")
|
|
270
|
+
if fst.st_nlink > 1:
|
|
271
|
+
raise CarryoverError(f"{_esc(name)} is a hard link")
|
|
272
|
+
fo = os.open(out, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
|
|
273
|
+
try:
|
|
274
|
+
while True:
|
|
275
|
+
b = os.read(fi, 1 << 20)
|
|
276
|
+
if not b:
|
|
277
|
+
break
|
|
278
|
+
_write_all(fo, b)
|
|
279
|
+
finally:
|
|
280
|
+
os.close(fo)
|
|
281
|
+
os.chmod(out, stat.S_IMODE(fst.st_mode) | 0o600)
|
|
282
|
+
finally:
|
|
283
|
+
os.close(fi)
|
|
284
|
+
|
|
285
|
+
take(st)
|
|
286
|
+
if stat.S_ISLNK(st.st_mode):
|
|
287
|
+
os.symlink(os.readlink(src), dst)
|
|
288
|
+
return
|
|
289
|
+
if stat.S_ISREG(st.st_mode):
|
|
290
|
+
file_at(None, src, dst)
|
|
291
|
+
return
|
|
292
|
+
if not stat.S_ISDIR(st.st_mode):
|
|
293
|
+
raise CarryoverError(f"{_esc(src)} is not a regular file or folder")
|
|
294
|
+
top = os.open(src, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
|
|
295
|
+
skipped = set(skip)
|
|
296
|
+
stack: List[Tuple[int, str, int, str]] = [(top, dst, stat.S_IMODE(st.st_mode), "")]
|
|
297
|
+
opened = [top]
|
|
298
|
+
try:
|
|
299
|
+
while stack:
|
|
300
|
+
dfd, out, mode, rel = stack.pop()
|
|
301
|
+
os.mkdir(out, 0o700)
|
|
302
|
+
for e in sorted(os.scandir(dfd), key=lambda x: x.name):
|
|
303
|
+
erel = f"{rel}/{e.name}" if rel else e.name
|
|
304
|
+
if erel in skipped or (e.is_file(follow_symlinks=False) and any(
|
|
305
|
+
any(c in g for c in "*?[") and len(g.split("/")) == len(erel.split("/")) and
|
|
306
|
+
all(fnmatch.fnmatchcase(a, b) for a, b in zip(erel.split("/"), g.split("/")))
|
|
307
|
+
for g in skipped)):
|
|
308
|
+
continue
|
|
309
|
+
est = e.stat(follow_symlinks=False)
|
|
310
|
+
take(est)
|
|
311
|
+
target = os.path.join(out, e.name)
|
|
312
|
+
if stat.S_ISLNK(est.st_mode):
|
|
313
|
+
os.symlink(os.readlink(e.name, dir_fd=dfd), target)
|
|
314
|
+
elif stat.S_ISREG(est.st_mode):
|
|
315
|
+
file_at(dfd, e.name, target)
|
|
316
|
+
elif stat.S_ISDIR(est.st_mode):
|
|
317
|
+
cfd = os.open(e.name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=dfd)
|
|
318
|
+
opened.append(cfd)
|
|
319
|
+
stack.append((cfd, target, stat.S_IMODE(est.st_mode), erel))
|
|
320
|
+
else:
|
|
321
|
+
raise CarryoverError(f"{_esc(e.name)} is not a regular file or folder")
|
|
322
|
+
os.chmod(out, mode | 0o700)
|
|
323
|
+
finally:
|
|
324
|
+
for fd in opened:
|
|
325
|
+
try:
|
|
326
|
+
os.close(fd)
|
|
327
|
+
except OSError:
|
|
328
|
+
pass
|
|
329
|
+
|
|
330
|
+
|
|
331
|
+
def _remove(p: str) -> None:
|
|
332
|
+
"""Remove an entry that no longer changes (trash, trusted, quarantine). It works through
|
|
333
|
+
folder descriptors only, one open at a time, going down by name and back up by "..": no
|
|
334
|
+
recursion, no path-length limit, no open-file limit, and never through a link (a link is
|
|
335
|
+
unlinked as a link). Folders get u+rwx first; the two blocking flags are cleared where the
|
|
336
|
+
path is short enough to name, never on a hard-linked file."""
|
|
337
|
+
if not os.path.lexists(p):
|
|
338
|
+
return
|
|
339
|
+
_unlock(p)
|
|
340
|
+
if not _is_real_dir(p):
|
|
341
|
+
os.unlink(p)
|
|
342
|
+
return
|
|
343
|
+
me = os.getuid()
|
|
344
|
+
flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
|
|
345
|
+
|
|
346
|
+
def writable(name: str, dir_fd: int) -> None:
|
|
347
|
+
try:
|
|
348
|
+
st = os.lstat(name, dir_fd=dir_fd)
|
|
349
|
+
if stat.S_ISDIR(st.st_mode) and st.st_uid == me:
|
|
350
|
+
try:
|
|
351
|
+
os.chmod(name, stat.S_IMODE(st.st_mode) | 0o700, dir_fd=dir_fd,
|
|
352
|
+
follow_symlinks=False)
|
|
353
|
+
except NotImplementedError: # Linux: the entry no longer changes (trash)
|
|
354
|
+
os.chmod(name, stat.S_IMODE(st.st_mode) | 0o700, dir_fd=dir_fd)
|
|
355
|
+
except OSError:
|
|
356
|
+
pass
|
|
357
|
+
|
|
358
|
+
parent = os.open(os.path.dirname(p) or ".", flags)
|
|
359
|
+
try:
|
|
360
|
+
writable(os.path.basename(p), parent)
|
|
361
|
+
finally:
|
|
362
|
+
os.close(parent)
|
|
363
|
+
fd = os.open(p, flags)
|
|
364
|
+
names: List[str] = []
|
|
365
|
+
ids: List[Tuple[int, int]] = [] # (device, inode) of each folder on the way down
|
|
366
|
+
path = p # only used while short enough to name
|
|
367
|
+
try:
|
|
368
|
+
while True:
|
|
369
|
+
down = None
|
|
370
|
+
here = os.fstat(fd)
|
|
371
|
+
try:
|
|
372
|
+
named = len(path) < 900 and os.lstat(path)[1:3] == (here.st_ino, here.st_dev)
|
|
373
|
+
except OSError:
|
|
374
|
+
named = False # the path no longer names this folder: flags are left alone
|
|
375
|
+
for e in list(os.scandir(fd)):
|
|
376
|
+
if e.is_dir(follow_symlinks=False):
|
|
377
|
+
if e.stat(follow_symlinks=False).st_dev != here.st_dev:
|
|
378
|
+
raise CarryoverError(f"{_esc(p)} holds a mount point; it is left as it is")
|
|
379
|
+
down = e.name
|
|
380
|
+
break
|
|
381
|
+
if named:
|
|
382
|
+
_unlock(os.path.join(path, e.name))
|
|
383
|
+
else:
|
|
384
|
+
_unlock_at(fd, e.name) # deep: by descriptor
|
|
385
|
+
os.unlink(e.name, dir_fd=fd)
|
|
386
|
+
if down is not None:
|
|
387
|
+
if named:
|
|
388
|
+
_unlock(os.path.join(path, down)) # a folder's own flags
|
|
389
|
+
else:
|
|
390
|
+
_unlock_at(fd, down)
|
|
391
|
+
writable(down, fd)
|
|
392
|
+
st = os.fstat(fd)
|
|
393
|
+
nfd = os.open(down, flags, dir_fd=fd)
|
|
394
|
+
os.close(fd)
|
|
395
|
+
fd = nfd
|
|
396
|
+
ids.append((st.st_dev, st.st_ino))
|
|
397
|
+
names.append(down)
|
|
398
|
+
path = os.path.join(path, down)
|
|
399
|
+
continue
|
|
400
|
+
if not names:
|
|
401
|
+
break
|
|
402
|
+
up = os.open("..", flags, dir_fd=fd)
|
|
403
|
+
ust = os.fstat(up)
|
|
404
|
+
if (ust.st_dev, ust.st_ino) != ids[-1]: # moved while removed: stop
|
|
405
|
+
os.close(up)
|
|
406
|
+
raise CarryoverError(f"{_esc(p)} changed while it was removed; it is left as it is")
|
|
407
|
+
os.close(fd)
|
|
408
|
+
fd = up
|
|
409
|
+
ids.pop()
|
|
410
|
+
os.rmdir(names.pop(), dir_fd=fd)
|
|
411
|
+
path = os.path.dirname(path)
|
|
412
|
+
finally:
|
|
413
|
+
os.close(fd)
|
|
414
|
+
os.rmdir(p)
|
|
415
|
+
|
|
416
|
+
|
|
417
|
+
def _move(src: str, dst: str) -> None:
|
|
418
|
+
"""Rename an entry; a rename takes a link, not its target. Never copy-then-delete: a rename
|
|
419
|
+
that fails stops with a message."""
|
|
420
|
+
os.makedirs(os.path.dirname(dst), mode=0o700, exist_ok=True)
|
|
421
|
+
_unlock(src)
|
|
422
|
+
try:
|
|
423
|
+
os.rename(src, dst)
|
|
424
|
+
except OSError as exc:
|
|
425
|
+
raise CarryoverError(f"{_esc(src)} could not be moved aside ({exc.strerror}); fix it by "
|
|
426
|
+
"hand, then start again")
|
|
427
|
+
|
|
428
|
+
|
|
429
|
+
def _write_all(fd: int, data: bytes) -> None:
|
|
430
|
+
"""Every byte or an error: a short write (a full disk) never truncates silently (rule D)."""
|
|
431
|
+
view = memoryview(data)
|
|
432
|
+
while view:
|
|
433
|
+
n = os.write(fd, view)
|
|
434
|
+
if n <= 0:
|
|
435
|
+
raise OSError(errno.ENOSPC, "short write")
|
|
436
|
+
view = view[n:]
|
|
437
|
+
|
|
438
|
+
|
|
439
|
+
def _is_real_dir(p: str) -> bool:
|
|
440
|
+
try:
|
|
441
|
+
return stat.S_ISDIR(os.lstat(p).st_mode)
|
|
442
|
+
except OSError:
|
|
443
|
+
return False
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
def _expand(folder: str, pattern: str) -> List[str]:
|
|
447
|
+
"""The concrete relative paths of a pattern that exist now; only real folders are entered."""
|
|
448
|
+
rels = [""]
|
|
449
|
+
for part in pattern.split("/"):
|
|
450
|
+
nxt = []
|
|
451
|
+
for r in rels:
|
|
452
|
+
base = os.path.join(folder, r) if r else folder
|
|
453
|
+
if part == "*":
|
|
454
|
+
if _is_real_dir(base):
|
|
455
|
+
nxt += [os.path.join(r, n) if r else n for n in sorted(os.listdir(base))]
|
|
456
|
+
else:
|
|
457
|
+
nxt.append(os.path.join(r, part) if r else part)
|
|
458
|
+
rels = nxt
|
|
459
|
+
return [r for r in rels if os.path.lexists(os.path.join(folder, r))]
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
# -- JSON ---------------------------------------------------------------------------------------------
|
|
463
|
+
|
|
464
|
+
def _json_paths(data: object, keypath: Sequence[str], pre: Tuple[str, ...] = ()) -> List[Tuple[str, ...]]:
|
|
465
|
+
if not keypath:
|
|
466
|
+
return [pre]
|
|
467
|
+
if not isinstance(data, dict):
|
|
468
|
+
return []
|
|
469
|
+
k = keypath[0]
|
|
470
|
+
keys = sorted(data) if k == "*" else ([k] if k in data else [])
|
|
471
|
+
out: List[Tuple[str, ...]] = []
|
|
472
|
+
for key in keys:
|
|
473
|
+
out += _json_paths(data[key], keypath[1:], pre + (key,))
|
|
474
|
+
return out
|
|
475
|
+
|
|
476
|
+
|
|
477
|
+
# keys of the tool's JSON file that `add` never takes, though a session's change to them is
|
|
478
|
+
# quarantined: login secrets
|
|
479
|
+
JSON_NOT_ADDED = ("primaryApiKey", "customApiKeyResponses")
|
|
480
|
+
SHOW_VALUE = 2000
|
|
481
|
+
|
|
482
|
+
|
|
483
|
+
def _shown_value(v: object, whole: bool = False) -> str:
|
|
484
|
+
text = json.dumps(v, sort_keys=True, ensure_ascii=True)
|
|
485
|
+
return _esc(text if whole or len(text) <= SHOW_VALUE else text[:SHOW_VALUE] + " ...(cut)")
|
|
486
|
+
|
|
487
|
+
|
|
488
|
+
def _get(data: object, path: Sequence[str]) -> object:
|
|
489
|
+
for k in path:
|
|
490
|
+
if not isinstance(data, dict) or k not in data:
|
|
491
|
+
return None
|
|
492
|
+
data = data[k]
|
|
493
|
+
return data
|
|
494
|
+
|
|
495
|
+
|
|
496
|
+
def _set(data: dict, path: Sequence[str], value: object) -> None:
|
|
497
|
+
for k in path[:-1]:
|
|
498
|
+
nxt = data.get(k)
|
|
499
|
+
if not isinstance(nxt, dict):
|
|
500
|
+
if value is None:
|
|
501
|
+
return
|
|
502
|
+
nxt = data[k] = {}
|
|
503
|
+
data = nxt
|
|
504
|
+
if value is None:
|
|
505
|
+
data.pop(path[-1], None)
|
|
506
|
+
else:
|
|
507
|
+
data[path[-1]] = value
|
|
508
|
+
|
|
509
|
+
|
|
510
|
+
_MISSING = object()
|
|
511
|
+
|
|
512
|
+
|
|
513
|
+
def _read_json(path: str) -> object:
|
|
514
|
+
"""A JSON object; None when the file is missing; _MISSING when it cannot be read as one (a
|
|
515
|
+
file the tool may still read)."""
|
|
516
|
+
try:
|
|
517
|
+
fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
|
|
518
|
+
except FileNotFoundError:
|
|
519
|
+
return None
|
|
520
|
+
except OSError:
|
|
521
|
+
return _MISSING
|
|
522
|
+
try:
|
|
523
|
+
st = os.fstat(fd)
|
|
524
|
+
if not stat.S_ISREG(st.st_mode) or st.st_nlink > 1 or st.st_size > MAX_FILE:
|
|
525
|
+
os.close(fd)
|
|
526
|
+
return _MISSING
|
|
527
|
+
with os.fdopen(fd, "rb") as fh:
|
|
528
|
+
raw = fh.read(MAX_FILE + 1)
|
|
529
|
+
if len(raw) > MAX_FILE:
|
|
530
|
+
return _MISSING
|
|
531
|
+
d = json.loads(raw.decode("utf-8")) # strict: what Python cannot read is not trusted
|
|
532
|
+
except (OSError, ValueError, RecursionError):
|
|
533
|
+
return _MISSING
|
|
534
|
+
return d if isinstance(d, dict) else _MISSING
|
|
535
|
+
|
|
536
|
+
|
|
537
|
+
def _write_json(path: str, data: object) -> None:
|
|
538
|
+
safeio.write_new(path, json.dumps(data, indent=2) + "\n")
|
|
539
|
+
|
|
540
|
+
|
|
541
|
+
def _esc(s: str) -> str:
|
|
542
|
+
return s.encode("unicode_escape").decode("ascii")
|
|
543
|
+
|
|
544
|
+
|
|
545
|
+
# -- the trusted state ------------------------------------------------------------------------------
|
|
546
|
+
|
|
547
|
+
RUNS, TRASH = "runs", "trash"
|
|
548
|
+
OURS = {RUNS, TRASH} # the tool folder's own entries; anything else is from an older layout
|
|
549
|
+
|
|
550
|
+
|
|
551
|
+
class Store:
|
|
552
|
+
"""The trusted copy of one tool's instructions and settings, in
|
|
553
|
+
`~/.phiward/carryover/<tool>/` (no session can read or write it), and the session
|
|
554
|
+
folders built from it. The tool folder `<base>` holds `runs/<id>/` (one session's
|
|
555
|
+
config, temp and caches, each locked by its launcher while it runs) and `trash/` (run folders
|
|
556
|
+
being read or removed). Nothing else is kept. Rule D: any of it may be deleted at any time."""
|
|
557
|
+
|
|
558
|
+
VERSION = 5
|
|
559
|
+
|
|
560
|
+
def __init__(self, tool: str, home: str, spec: Optional[Spec] = None) -> None:
|
|
561
|
+
self.tool = tool
|
|
562
|
+
self.spec = spec if spec is not None else SPECS.get(tool, Spec())
|
|
563
|
+
self.dir = os.path.join(home, ".phiward", "carryover", tool)
|
|
564
|
+
self.trusted = os.path.join(self.dir, "trusted")
|
|
565
|
+
self.qroot = os.path.join(self.dir, "quarantine")
|
|
566
|
+
self.sessions = os.path.join(self.dir, "sessions") # what each session was built with
|
|
567
|
+
self.manifest_path = os.path.join(self.dir, "manifest.json")
|
|
568
|
+
self._run_fd: Optional[int] = None
|
|
569
|
+
self.run = ""
|
|
570
|
+
|
|
571
|
+
# the record: {"version": 5, "paths": {name: sig|None}}; a session's record, in sessions/<id>:
|
|
572
|
+
# {"config": path, "built": {name: sig}, "json_built": object}
|
|
573
|
+
def _load(self) -> Tuple[Optional[dict], str]:
|
|
574
|
+
m = _read_json(self.manifest_path)
|
|
575
|
+
if m is None:
|
|
576
|
+
return None, "missing"
|
|
577
|
+
if isinstance(m, dict) and isinstance(m.get("paths"), dict):
|
|
578
|
+
return m, ("ok" if m.get("version") == self.VERSION else "old")
|
|
579
|
+
raise CarryoverError(f"the carry-over record ({_esc(self.manifest_path)}) cannot be read; "
|
|
580
|
+
f"run: phiward carryover reset --tool {self.tool}")
|
|
581
|
+
|
|
582
|
+
def _save(self, m: dict) -> None:
|
|
583
|
+
m["version"] = self.VERSION
|
|
584
|
+
_write_json(self.manifest_path, m)
|
|
585
|
+
|
|
586
|
+
def _prepare(self) -> None:
|
|
587
|
+
for d in (self.dir, self.sessions):
|
|
588
|
+
os.makedirs(d, mode=0o700, exist_ok=True)
|
|
589
|
+
if os.path.realpath(self.dir) != os.path.normpath(self.dir):
|
|
590
|
+
raise CarryoverError("the carry-over folder has a link on its path")
|
|
591
|
+
|
|
592
|
+
def _locked(self):
|
|
593
|
+
"""The trusted copy is locked only while it is read and changed, so sessions can run in
|
|
594
|
+
parallel."""
|
|
595
|
+
store = self
|
|
596
|
+
|
|
597
|
+
class _L:
|
|
598
|
+
def __enter__(self):
|
|
599
|
+
store._prepare()
|
|
600
|
+
self.fd = _opendir(store.dir)
|
|
601
|
+
fcntl.flock(self.fd, fcntl.LOCK_EX)
|
|
602
|
+
return self
|
|
603
|
+
|
|
604
|
+
def __exit__(self, *a):
|
|
605
|
+
os.close(self.fd)
|
|
606
|
+
return _L()
|
|
607
|
+
|
|
608
|
+
def _resign(self) -> dict:
|
|
609
|
+
"""A record made from the trusted copy, which no session can write (rule D)."""
|
|
610
|
+
m: dict = {"paths": {}}
|
|
611
|
+
if _is_real_dir(self.trusted):
|
|
612
|
+
for n in sorted(os.listdir(self.trusted)):
|
|
613
|
+
if n in self.spec.trusted_names():
|
|
614
|
+
m["paths"][n] = signature(os.path.join(self.trusted, n))
|
|
615
|
+
return m
|
|
616
|
+
|
|
617
|
+
def _record(self) -> Tuple[dict, List[str]]:
|
|
618
|
+
"""The trusted record, checked against the trusted copy: an item missing or changed on
|
|
619
|
+
disk is not used, and is reported (rule D)."""
|
|
620
|
+
msgs: List[str] = []
|
|
621
|
+
m, kind = self._load()
|
|
622
|
+
if kind != "ok" or m is None:
|
|
623
|
+
m = self._resign()
|
|
624
|
+
if kind == "missing" and m["paths"]:
|
|
625
|
+
msgs.append("phiward launch: the carry-over record was missing; it was made "
|
|
626
|
+
"again from the trusted copy")
|
|
627
|
+
self._save(m)
|
|
628
|
+
return m, msgs
|
|
629
|
+
bad = []
|
|
630
|
+
for rel, sig in list(m["paths"].items()):
|
|
631
|
+
if rel not in self.spec.trusted_names():
|
|
632
|
+
m["paths"].pop(rel)
|
|
633
|
+
elif sig is not None and signature(os.path.join(self.trusted, rel)) != sig:
|
|
634
|
+
m["paths"][rel] = None
|
|
635
|
+
bad.append(rel)
|
|
636
|
+
if bad:
|
|
637
|
+
msgs.append(f"phiward launch: the trusted copy of {', '.join(_esc(b) for b in bad)} "
|
|
638
|
+
"is missing or damaged; it is not used (add or accept it again)")
|
|
639
|
+
return m, msgs
|
|
640
|
+
|
|
641
|
+
# -- start ----------------------------------------------------------------------------------------
|
|
642
|
+
|
|
643
|
+
def start(self, base: str, run: str, memory: bool = False, edit=None) -> List[str]:
|
|
644
|
+
"""Make and lock this session's run folder, finish any session whose launcher is gone,
|
|
645
|
+
and build `<run>/config` from the trusted copy."""
|
|
646
|
+
msgs = _layout(base)
|
|
647
|
+
# made and locked under the lock of runs/, which every cleaner takes too, so no other
|
|
648
|
+
# launcher can finish a folder between its making and its lock
|
|
649
|
+
with _runs_lock(base) as rfd:
|
|
650
|
+
os.mkdir(os.path.basename(run), 0o700, dir_fd=rfd)
|
|
651
|
+
self._run_fd = _opendir(os.path.basename(run), rfd)
|
|
652
|
+
fcntl.flock(self._run_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
|
653
|
+
self.run = run
|
|
654
|
+
config = os.path.join(run, "config")
|
|
655
|
+
if not self.spec.enabled:
|
|
656
|
+
msgs += _clean_runs(base, run, lambda _n: [])
|
|
657
|
+
os.makedirs(config, mode=0o700)
|
|
658
|
+
return msgs
|
|
659
|
+
self._prepare()
|
|
660
|
+
msgs += self._move_legacy(base)
|
|
661
|
+
msgs += _clean_runs(base, run, lambda n: self._finish(base, n, "the last session did not "
|
|
662
|
+
"finish"))
|
|
663
|
+
with self._locked():
|
|
664
|
+
m, warn = self._record()
|
|
665
|
+
msgs += warn
|
|
666
|
+
if edit is not None:
|
|
667
|
+
bad = os.path.join(self.trusted, "settings.json")
|
|
668
|
+
if m["paths"].get("settings.json") is None and os.path.lexists(bad):
|
|
669
|
+
qid, qdir = self._new_qid() # damaged: kept for the operator, made again
|
|
670
|
+
_move(bad, os.path.join(qdir, "files", "settings.json"))
|
|
671
|
+
msgs += self._finish_entry(qid, qdir, "the trusted settings.json was changed on "
|
|
672
|
+
"disk; a new one was made with only the launcher's "
|
|
673
|
+
"hook", ["settings.json"], [], [], copied=["settings.json"])
|
|
674
|
+
os.makedirs(self.trusted, mode=0o700, exist_ok=True)
|
|
675
|
+
dfd = _opendir(self.trusted)
|
|
676
|
+
try:
|
|
677
|
+
edit(dfd) # the launcher's own hook entry, made on the trusted copy
|
|
678
|
+
finally:
|
|
679
|
+
os.close(dfd)
|
|
680
|
+
m["paths"]["settings.json"] = signature(os.path.join(self.trusted, "settings.json"))
|
|
681
|
+
self._save(m)
|
|
682
|
+
try:
|
|
683
|
+
rec = self._build(config, m, memory)
|
|
684
|
+
except OSError as exc:
|
|
685
|
+
if _nospace(exc):
|
|
686
|
+
raise CarryoverError("not enough disk space to start; see `phiward "
|
|
687
|
+
f"carryover status --tool {self.tool}`")
|
|
688
|
+
raise
|
|
689
|
+
_write_json(os.path.join(self.sessions, os.path.basename(run) + ".json"), rec)
|
|
690
|
+
return msgs
|
|
691
|
+
|
|
692
|
+
def _move_legacy(self, base: str) -> List[str]:
|
|
693
|
+
"""Entries of an older layout (state, caches, a shared temp folder, the old config
|
|
694
|
+
files) are never trusted: they move, as they are, into `legacy-<time>` once (rule D)."""
|
|
695
|
+
legacy = [n for n in sorted(os.listdir(base)) if n not in OURS and not n.startswith("legacy-")
|
|
696
|
+
and n != ".DS_Store"]
|
|
697
|
+
if not legacy:
|
|
698
|
+
return []
|
|
699
|
+
aside = os.path.join(base, "legacy-" + time.strftime("%Y%m%d-%H%M%S-") + secrets.token_hex(3))
|
|
700
|
+
for n in legacy:
|
|
701
|
+
_move(os.path.join(base, n), os.path.join(aside, n))
|
|
702
|
+
return [f"phiward launch: the tool folder had entries from an older layout; they were "
|
|
703
|
+
f"moved to {_esc(aside)} and are not used. To keep an instruction file from there, "
|
|
704
|
+
f"read it, then: phiward carryover add PATH --tool {self.tool}. If a session of an "
|
|
705
|
+
"older phiward is still running, quit it."]
|
|
706
|
+
|
|
707
|
+
def _build(self, config: str, m: dict, memory: bool) -> dict:
|
|
708
|
+
"""The run folder is new and no session runs in it yet: built by path."""
|
|
709
|
+
os.makedirs(config, mode=0o700)
|
|
710
|
+
for rel, sig in sorted(m["paths"].items()):
|
|
711
|
+
if sig is not None:
|
|
712
|
+
_copy(os.path.join(self.trusted, rel), os.path.join(config, rel))
|
|
713
|
+
if self.spec.json_main and self.spec.json_defaults:
|
|
714
|
+
jp = os.path.join(config, self.spec.json_main)
|
|
715
|
+
data = _read_json(jp)
|
|
716
|
+
data = data if isinstance(data, dict) else {}
|
|
717
|
+
for k, v in self.spec.json_defaults.items():
|
|
718
|
+
data.setdefault(k, v)
|
|
719
|
+
_write_json(jp, data)
|
|
720
|
+
if self.spec.memory_setting:
|
|
721
|
+
s = os.path.join(config, "settings.json")
|
|
722
|
+
data = _read_json(s)
|
|
723
|
+
data = data if isinstance(data, dict) else {}
|
|
724
|
+
if memory:
|
|
725
|
+
data[self.spec.memory_setting] = os.path.join(config, self.spec.memory_rel)
|
|
726
|
+
os.makedirs(os.path.join(config, self.spec.memory_rel), mode=0o700, exist_ok=True)
|
|
727
|
+
else:
|
|
728
|
+
data.pop(self.spec.memory_setting, None)
|
|
729
|
+
_write_json(s, data)
|
|
730
|
+
main_json = _read_json(os.path.join(config, self.spec.json_main)) if self.spec.json_main else None
|
|
731
|
+
built_json = {}
|
|
732
|
+
for n in os.listdir(config):
|
|
733
|
+
if n in self.spec.instructions and n.endswith(".json"):
|
|
734
|
+
d = _read_json(os.path.join(config, n))
|
|
735
|
+
if isinstance(d, dict):
|
|
736
|
+
built_json[n] = d
|
|
737
|
+
return {"config": config,
|
|
738
|
+
"built_json": built_json,
|
|
739
|
+
"built": {n: signature(os.path.join(config, n)) for n in os.listdir(config)
|
|
740
|
+
if n in self.spec.instructions},
|
|
741
|
+
"json_built": main_json if isinstance(main_json, dict) else {}}
|
|
742
|
+
|
|
743
|
+
# -- end ------------------------------------------------------------------------------------------
|
|
744
|
+
|
|
745
|
+
def end(self, base: str, run: str = "") -> List[str]:
|
|
746
|
+
"""At exit: the run folder is renamed into `trash/` first; then what the session
|
|
747
|
+
changed in its instructions is copied to quarantine, and the folder is removed."""
|
|
748
|
+
if not self.spec.enabled:
|
|
749
|
+
return []
|
|
750
|
+
run = run or self.run
|
|
751
|
+
if not run:
|
|
752
|
+
return []
|
|
753
|
+
try:
|
|
754
|
+
return self._finish(base, os.path.basename(run), "changed by the session")
|
|
755
|
+
finally:
|
|
756
|
+
if self._run_fd is not None: # released only after the move
|
|
757
|
+
os.close(self._run_fd)
|
|
758
|
+
self._run_fd = None
|
|
759
|
+
|
|
760
|
+
def _finish(self, base: str, name: str, why: str) -> List[str]:
|
|
761
|
+
rec_path = os.path.join(self.sessions, name + ".json")
|
|
762
|
+
rec = _read_json(rec_path)
|
|
763
|
+
t = _to_trash(base, name)
|
|
764
|
+
msgs: List[str] = []
|
|
765
|
+
if not t:
|
|
766
|
+
return msgs # another launcher finished it, or it could not be moved (it stays)
|
|
767
|
+
if isinstance(rec, dict):
|
|
768
|
+
msgs += self._compare(t, rec, why)
|
|
769
|
+
else: # rule D: never lost without a word
|
|
770
|
+
msgs.append("phiward launch: a session's record was missing or could not be read "
|
|
771
|
+
"(the carry-over folder may have been deleted); its changes were not kept")
|
|
772
|
+
try:
|
|
773
|
+
os.unlink(rec_path)
|
|
774
|
+
except FileNotFoundError:
|
|
775
|
+
pass
|
|
776
|
+
if t:
|
|
777
|
+
try:
|
|
778
|
+
_remove(t)
|
|
779
|
+
except (OSError, RecursionError, CarryoverError):
|
|
780
|
+
msgs.append(f"phiward launch: {_esc(t)} could not be removed; it stays in trash "
|
|
781
|
+
"and is tried again at the next start")
|
|
782
|
+
return msgs
|
|
783
|
+
|
|
784
|
+
def _compare(self, t: str, rec: dict, why: str) -> List[str]:
|
|
785
|
+
qid, qdir = self._new_qid()
|
|
786
|
+
moved: List[str] = []
|
|
787
|
+
copied: List[str] = []
|
|
788
|
+
details: List[str] = []
|
|
789
|
+
json_changes: List[dict] = []
|
|
790
|
+
tc = os.path.join(t, "config") if t else ""
|
|
791
|
+
if not (t and _is_real_dir(t) and _is_real_dir(tc)):
|
|
792
|
+
return ["phiward launch: the session's folder was missing or replaced by a link; "
|
|
793
|
+
"nothing was read from it"]
|
|
794
|
+
built = rec.get("built", {})
|
|
795
|
+
budget = _Budget()
|
|
796
|
+
names = {n for n in set(built) | set(os.listdir(tc)) if n in self.spec.instructions}
|
|
797
|
+
for rel in sorted(names):
|
|
798
|
+
p = os.path.join(tc, rel)
|
|
799
|
+
skip = [d[len(rel) + 1:] for d in self.spec.downloads if d.startswith(rel + "/")]
|
|
800
|
+
cur = _without(signature(p), skip)
|
|
801
|
+
if cur == _without(built.get(rel), skip):
|
|
802
|
+
continue
|
|
803
|
+
old = _without(built.get(rel), skip) or {}
|
|
804
|
+
for k in sorted(set(cur or {}) | set(old)):
|
|
805
|
+
v = (cur or {}).get(k)
|
|
806
|
+
if v != old.get(k) and k != TOO_LARGE:
|
|
807
|
+
how = "new" if k not in old else "removed" if v is None else "changed"
|
|
808
|
+
if v and v.startswith("l:"):
|
|
809
|
+
how += f", a link to {v[2:]}"
|
|
810
|
+
details.append(f"{rel if k == '.' else rel + '/' + k} ({how})")
|
|
811
|
+
if rel.endswith(".json") and cur and built.get(rel):
|
|
812
|
+
keys = _json_key_diff(os.path.join(tc, rel), rec.get("built_json", {}).get(rel))
|
|
813
|
+
if keys:
|
|
814
|
+
details.append(f"{rel}: {', '.join(keys)} (changed)")
|
|
815
|
+
moved.append(rel)
|
|
816
|
+
if cur is None:
|
|
817
|
+
continue
|
|
818
|
+
if budget.bytes > QUARANTINE_ENTRY_BYTES or not self._room():
|
|
819
|
+
details.append(f"{rel} (not copied: quarantine is full or the entry too large)")
|
|
820
|
+
continue
|
|
821
|
+
qf = os.path.join(qdir, "files")
|
|
822
|
+
tmp = os.path.join(qf, f".phiward-{secrets.token_hex(6)}")
|
|
823
|
+
try:
|
|
824
|
+
os.makedirs(qf, mode=0o700, exist_ok=True)
|
|
825
|
+
_copy(p, tmp, budget, skip) # whole or nothing
|
|
826
|
+
os.rename(tmp, os.path.join(qf, rel))
|
|
827
|
+
copied.append(rel)
|
|
828
|
+
except (OSError, CarryoverError, RecursionError) as exc:
|
|
829
|
+
details.append(f"{rel} (not copied: {exc})")
|
|
830
|
+
if os.path.lexists(tmp):
|
|
831
|
+
_remove(tmp)
|
|
832
|
+
if self.spec.json_main:
|
|
833
|
+
data = _read_json(os.path.join(tc, self.spec.json_main))
|
|
834
|
+
want = rec.get("json_built", {})
|
|
835
|
+
if isinstance(data, dict):
|
|
836
|
+
for kp in self.spec.json_notable:
|
|
837
|
+
for p in sorted(set(_json_paths(data, kp)) | set(_json_paths(want, kp))):
|
|
838
|
+
cur = _get(data, p)
|
|
839
|
+
if cur != _get(want, p) and (cur or _get(want, p)): # not empty defaults
|
|
840
|
+
details.append(f"{self.spec.json_main}: {'.'.join(p)} (changed)")
|
|
841
|
+
json_changes.append({"file": self.spec.json_main, "key": list(p),
|
|
842
|
+
"value": cur})
|
|
843
|
+
return self._finish_entry(qid, qdir, why, moved, details, json_changes, copied=copied)
|
|
844
|
+
|
|
845
|
+
def _room(self) -> bool:
|
|
846
|
+
return not os.path.isdir(self.qroot) or len(os.listdir(self.qroot)) < QUARANTINE_MAX
|
|
847
|
+
|
|
848
|
+
def _new_qid(self) -> Tuple[str, str]:
|
|
849
|
+
qid = time.strftime("%Y%m%d-%H%M%S") + f"-{time.time_ns() % 10**9:09d}-" + secrets.token_hex(2)
|
|
850
|
+
return qid, os.path.join(self.qroot, qid)
|
|
851
|
+
|
|
852
|
+
def _finish_entry(self, qid: str, qdir: str, why: str, moved: List[str], details: List[str],
|
|
853
|
+
json_changes: List[dict], copied: Sequence[str] = ()) -> List[str]:
|
|
854
|
+
if not moved and not json_changes:
|
|
855
|
+
if _is_real_dir(qdir):
|
|
856
|
+
_remove(qdir)
|
|
857
|
+
return []
|
|
858
|
+
self._bound_quarantine()
|
|
859
|
+
if not _is_real_dir(qdir) and not self._room():
|
|
860
|
+
return [f"phiward launch: {len(moved) + len(json_changes)} item(s) a later session "
|
|
861
|
+
f"would read as instructions were not kept ({why}); quarantine is full, so no "
|
|
862
|
+
f"copy was made (phiward carryover status --tool {self.tool})"]
|
|
863
|
+
os.makedirs(qdir, mode=0o700, exist_ok=True)
|
|
864
|
+
_write_json(os.path.join(qdir, "changes.json"),
|
|
865
|
+
{"why": why, "paths": moved[:5000], "copied": list(copied)[:5000],
|
|
866
|
+
"truncated": len(moved) > 5000,
|
|
867
|
+
"json": json_changes[:1000], "details": details[:1000]})
|
|
868
|
+
items = details or moved
|
|
869
|
+
lines = [f"phiward launch: {len(items)} item(s) that a later session would read as "
|
|
870
|
+
f"instructions were not kept ({why}); in quarantine as {qid}:"]
|
|
871
|
+
lines += [" " + _esc(i) for i in items[:30]]
|
|
872
|
+
if len(items) > 30:
|
|
873
|
+
lines.append(f" ... and {len(items) - 30} more")
|
|
874
|
+
lines.append(f" read them: phiward carryover show --tool {self.tool}; keep them: "
|
|
875
|
+
f"phiward carryover accept {qid} --tool {self.tool}")
|
|
876
|
+
return lines
|
|
877
|
+
|
|
878
|
+
def _bound_quarantine(self) -> None:
|
|
879
|
+
"""Only entries the operator has dealt with (accepted) are removed automatically, the
|
|
880
|
+
oldest first; unread ones stay, and a full quarantine stops new copies (_room)."""
|
|
881
|
+
if not os.path.isdir(self.qroot):
|
|
882
|
+
return
|
|
883
|
+
done = sorted(q for q in os.listdir(self.qroot) if q.endswith(".accepted"))
|
|
884
|
+
while done and len(os.listdir(self.qroot)) >= QUARANTINE_MAX:
|
|
885
|
+
try:
|
|
886
|
+
_remove(os.path.join(self.qroot, done.pop(0)))
|
|
887
|
+
except FileNotFoundError:
|
|
888
|
+
pass
|
|
889
|
+
|
|
890
|
+
# -- the operator's commands ----------------------------------------------------------------------
|
|
891
|
+
|
|
892
|
+
def entries(self) -> List[Tuple[str, dict]]:
|
|
893
|
+
if not os.path.isdir(self.qroot):
|
|
894
|
+
return []
|
|
895
|
+
out = []
|
|
896
|
+
for q in sorted(os.listdir(self.qroot), reverse=True):
|
|
897
|
+
c = _read_json(os.path.join(self.qroot, q, "changes.json"))
|
|
898
|
+
if isinstance(c, dict):
|
|
899
|
+
out.append((q, c))
|
|
900
|
+
return out
|
|
901
|
+
|
|
902
|
+
def _put_trusted(self, items: List[Tuple[str, str]], m: dict) -> None:
|
|
903
|
+
"""Copy each (name, source) into the trusted copy, all or nothing; links and hard links
|
|
904
|
+
are never trusted. A source of "" removes the name."""
|
|
905
|
+
for name, _src in items:
|
|
906
|
+
if name not in self.spec.trusted_names():
|
|
907
|
+
raise CarryoverError(f"{_esc(name)} is not an instruction or settings name of "
|
|
908
|
+
f"{self.tool} ({', '.join(self.spec.trusted_names())})")
|
|
909
|
+
os.makedirs(self.trusted, mode=0o700, exist_ok=True)
|
|
910
|
+
staged: List[Tuple[str, str]] = []
|
|
911
|
+
try:
|
|
912
|
+
for name, src in items:
|
|
913
|
+
tmp = ""
|
|
914
|
+
if src:
|
|
915
|
+
tmp = os.path.join(self.trusted, f".phiward-{secrets.token_hex(6)}")
|
|
916
|
+
staged.append((name, tmp))
|
|
917
|
+
_copy(src, tmp) # by descriptor; refuses hard links, special files, huge trees
|
|
918
|
+
sig = signature(tmp)
|
|
919
|
+
if _has_link(sig) or (sig and TOO_LARGE in sig):
|
|
920
|
+
raise CarryoverError(f"{_esc(name)} is or holds a link, or is too large; it "
|
|
921
|
+
"is never trusted")
|
|
922
|
+
else:
|
|
923
|
+
staged.append((name, ""))
|
|
924
|
+
except (OSError, CarryoverError, RecursionError):
|
|
925
|
+
for _, tmp in staged:
|
|
926
|
+
if tmp and os.path.lexists(tmp):
|
|
927
|
+
_remove(tmp)
|
|
928
|
+
raise
|
|
929
|
+
for name, tmp in staged:
|
|
930
|
+
dst = os.path.join(self.trusted, name)
|
|
931
|
+
# download paths are not copied to quarantine: what the trusted copy holds there
|
|
932
|
+
# stays
|
|
933
|
+
for d in self.spec.downloads:
|
|
934
|
+
if tmp and d.startswith(name + "/") and not any(c in d for c in "*?["):
|
|
935
|
+
old, new = os.path.join(self.trusted, d), os.path.join(tmp, d[len(name) + 1:])
|
|
936
|
+
if os.path.lexists(old) and not os.path.lexists(new):
|
|
937
|
+
os.makedirs(os.path.dirname(new), mode=0o700, exist_ok=True)
|
|
938
|
+
_copy(old, new)
|
|
939
|
+
if os.path.lexists(dst):
|
|
940
|
+
_remove(dst)
|
|
941
|
+
if tmp:
|
|
942
|
+
os.rename(tmp, dst)
|
|
943
|
+
m["paths"][name] = signature(dst) if tmp else None
|
|
944
|
+
|
|
945
|
+
def accept(self, qid: str, only: Sequence[str] = ()) -> List[str]:
|
|
946
|
+
"""The operator keeps a quarantined change: it is written into the trusted copy (all or
|
|
947
|
+
nothing), and every later session is built with it. `only` limits it to the named items
|
|
948
|
+
(instruction names such as `settings.json`, or `.claude.json` keys such as
|
|
949
|
+
`projects./path.hasTrustDialogAccepted`)."""
|
|
950
|
+
if os.path.basename(qid) != qid or qid in ("", ".", "..") or qid.endswith(".accepted"):
|
|
951
|
+
raise CarryoverError("not a quarantine id")
|
|
952
|
+
qdir = os.path.join(self.qroot, qid)
|
|
953
|
+
c = _read_json(os.path.join(qdir, "changes.json"))
|
|
954
|
+
if not isinstance(c, dict):
|
|
955
|
+
raise CarryoverError(f"no quarantine entry {qid}")
|
|
956
|
+
if c.get("truncated"):
|
|
957
|
+
raise CarryoverError("this entry has too many items to accept; read it and add what you "
|
|
958
|
+
"need with: phiward carryover add PATH")
|
|
959
|
+
with self._locked():
|
|
960
|
+
m, _ = self._record()
|
|
961
|
+
rels = [r for r in c.get("paths", []) if isinstance(r, str) and r in self.spec.instructions
|
|
962
|
+
and (not only or r in only)]
|
|
963
|
+
copied = set(c.get("copied", []))
|
|
964
|
+
items = []
|
|
965
|
+
for r in rels:
|
|
966
|
+
f = os.path.join(qdir, "files", r)
|
|
967
|
+
if r in copied and os.path.lexists(f):
|
|
968
|
+
items.append((r, f))
|
|
969
|
+
elif not os.path.lexists(f) and any(d.startswith(f"{r} (removed") for d in c.get("details", [])):
|
|
970
|
+
items.append((r, "")) # the session removed it: accepting removes it
|
|
971
|
+
else:
|
|
972
|
+
raise CarryoverError(f"{_esc(r)} was not copied to quarantine whole; it cannot be "
|
|
973
|
+
"accepted (read the details; add what you need by hand)")
|
|
974
|
+
changes = [ch for ch in c.get("json", []) if isinstance(ch, dict) and
|
|
975
|
+
ch.get("file") == self.spec.json_main and isinstance(ch.get("key"), list)
|
|
976
|
+
and (not only or ".".join(ch["key"]) in only)]
|
|
977
|
+
known = set(c.get("paths", [])) | {".".join(ch["key"]) for ch in c.get("json", [])
|
|
978
|
+
if isinstance(ch, dict) and isinstance(ch.get("key"), list)}
|
|
979
|
+
unknown = [o for o in only if o not in known]
|
|
980
|
+
if unknown:
|
|
981
|
+
raise CarryoverError(f"not in this entry: {', '.join(_esc(u) for u in unknown)}")
|
|
982
|
+
if changes:
|
|
983
|
+
obj = _read_json(os.path.join(self.trusted, self.spec.json_main))
|
|
984
|
+
obj = obj if isinstance(obj, dict) else {}
|
|
985
|
+
for ch in changes:
|
|
986
|
+
_set(obj, ch["key"], ch.get("value"))
|
|
987
|
+
tmpj = os.path.join(self.dir, f".phiward-{secrets.token_hex(6)}.json")
|
|
988
|
+
_write_json(tmpj, obj)
|
|
989
|
+
items.append((self.spec.json_main, tmpj))
|
|
990
|
+
try:
|
|
991
|
+
self._put_trusted(items, m)
|
|
992
|
+
finally:
|
|
993
|
+
if changes and os.path.lexists(tmpj):
|
|
994
|
+
os.unlink(tmpj)
|
|
995
|
+
self._save(m)
|
|
996
|
+
if only: # what was not named stays in quarantine
|
|
997
|
+
rest_paths = [r for r in c.get("paths", []) if r not in only]
|
|
998
|
+
rest_json = [ch for ch in c.get("json", []) if ".".join(ch.get("key", [])) not in only]
|
|
999
|
+
if rest_paths or rest_json:
|
|
1000
|
+
c["paths"], c["json"] = rest_paths, rest_json
|
|
1001
|
+
c["copied"] = [r for r in c.get("copied", []) if r in rest_paths]
|
|
1002
|
+
c["details"] = [d for d in c.get("details", [])
|
|
1003
|
+
if not any(d == o or d.startswith(o + "/") or d.startswith(o + " ")
|
|
1004
|
+
or d.startswith(o + ":") for o in only)]
|
|
1005
|
+
_write_json(os.path.join(qdir, "changes.json"), c)
|
|
1006
|
+
return [n for n, _ in items]
|
|
1007
|
+
os.rename(qdir, qdir + ".accepted")
|
|
1008
|
+
return [n for n, _ in items if n != self.spec.json_main] + [
|
|
1009
|
+
".".join(ch["key"]) for ch in changes]
|
|
1010
|
+
|
|
1011
|
+
def add(self, src: str, name: str = "") -> str:
|
|
1012
|
+
"""The operator puts an instruction file or folder of their own into the trusted copy.
|
|
1013
|
+
The tool's own JSON file (`json_main`, Claude Code's `.claude.json`) is never copied
|
|
1014
|
+
whole: only its JSON_ADD keys (MCP servers, trust and allowed tools), merged into the
|
|
1015
|
+
trusted copy's; the return value then names the keys taken."""
|
|
1016
|
+
name = name or os.path.basename(os.path.normpath(src))
|
|
1017
|
+
if self.spec.json_main and name == self.spec.json_main:
|
|
1018
|
+
return self._add_json(src)
|
|
1019
|
+
if not os.path.lexists(src):
|
|
1020
|
+
raise CarryoverError(f"{_esc(src)} does not exist")
|
|
1021
|
+
ag_home = os.path.realpath(os.path.dirname(os.path.dirname(self.dir)))
|
|
1022
|
+
real = os.path.realpath(src)
|
|
1023
|
+
if real == ag_home or real.startswith(ag_home + os.sep) or ag_home.startswith(real + os.sep):
|
|
1024
|
+
raise CarryoverError("a source inside or above ~/.phiward cannot be added")
|
|
1025
|
+
with self._locked():
|
|
1026
|
+
m, _ = self._record()
|
|
1027
|
+
self._put_trusted([(name, src)], m)
|
|
1028
|
+
self._save(m)
|
|
1029
|
+
return name
|
|
1030
|
+
|
|
1031
|
+
def _add_json(self, src: str) -> str:
|
|
1032
|
+
data = _read_json(src)
|
|
1033
|
+
if not isinstance(data, dict):
|
|
1034
|
+
raise CarryoverError(f"{_esc(src)} cannot be read as a JSON object")
|
|
1035
|
+
with self._locked():
|
|
1036
|
+
m, _ = self._record()
|
|
1037
|
+
obj = _read_json(os.path.join(self.trusted, self.spec.json_main))
|
|
1038
|
+
obj = obj if isinstance(obj, dict) else {}
|
|
1039
|
+
taken: List[str] = []
|
|
1040
|
+
for kp in self.spec.json_notable:
|
|
1041
|
+
if kp[-1] in JSON_NOT_ADDED:
|
|
1042
|
+
continue
|
|
1043
|
+
for p in _json_paths(data, kp):
|
|
1044
|
+
v = _get(data, p)
|
|
1045
|
+
if v is not None:
|
|
1046
|
+
_set(obj, list(p), v)
|
|
1047
|
+
taken.append(".".join(p))
|
|
1048
|
+
tmpj = os.path.join(self.dir, f".phiward-{secrets.token_hex(6)}.json")
|
|
1049
|
+
_write_json(tmpj, obj)
|
|
1050
|
+
try:
|
|
1051
|
+
self._put_trusted([(self.spec.json_main, tmpj)], m)
|
|
1052
|
+
finally:
|
|
1053
|
+
if os.path.lexists(tmpj):
|
|
1054
|
+
os.unlink(tmpj)
|
|
1055
|
+
self._save(m)
|
|
1056
|
+
return ", ".join(taken) or "nothing"
|
|
1057
|
+
|
|
1058
|
+
def show_lines(self) -> List[str]:
|
|
1059
|
+
"""What `carryover show` prints: each quarantine entry, its items, and for a change to
|
|
1060
|
+
the tool's JSON file the value `accept` would write (escaped, cut at SHOW_VALUE)."""
|
|
1061
|
+
out: List[str] = []
|
|
1062
|
+
trusted = _read_json(os.path.join(self.trusted, self.spec.json_main)) \
|
|
1063
|
+
if self.spec.json_main else None
|
|
1064
|
+
for qid, c in self.entries():
|
|
1065
|
+
if qid.endswith(".accepted"):
|
|
1066
|
+
continue
|
|
1067
|
+
items = c.get("details") or list(c.get("paths", []))
|
|
1068
|
+
out.append(f"{qid} {_esc(str(c.get('why', '')))} {len(items)} item(s)")
|
|
1069
|
+
out += [f" {_esc(str(i))}" for i in items]
|
|
1070
|
+
for ch in c.get("json", []):
|
|
1071
|
+
if not isinstance(ch, dict) or not isinstance(ch.get("key"), list):
|
|
1072
|
+
continue
|
|
1073
|
+
key = ".".join(str(k) for k in ch["key"])
|
|
1074
|
+
old = _get(trusted, ch["key"]) if isinstance(trusted, dict) else None
|
|
1075
|
+
new = ch.get("value")
|
|
1076
|
+
if isinstance(old, dict) and isinstance(new, dict) or \
|
|
1077
|
+
old is None and isinstance(new, dict):
|
|
1078
|
+
# entry by entry (a server added last is never cut away)
|
|
1079
|
+
before = old if isinstance(old, dict) else {}
|
|
1080
|
+
for k in sorted(set(before) | set(new), key=str):
|
|
1081
|
+
if before.get(k) == new.get(k):
|
|
1082
|
+
continue
|
|
1083
|
+
what = ("removed" if k not in new else "added" if k not in before
|
|
1084
|
+
else "changed to")
|
|
1085
|
+
if k in new and isinstance(new[k], dict):
|
|
1086
|
+
# a server: each of its keys on a line of its own (`command` and
|
|
1087
|
+
# `env` are never cut away behind a long `args`)
|
|
1088
|
+
out.append(f" {_esc(key)}.{_esc(str(k))}: {what}")
|
|
1089
|
+
for sk in sorted(new[k], key=str):
|
|
1090
|
+
sv = new[k][sk]
|
|
1091
|
+
if isinstance(sv, dict): # `env`: each variable whole
|
|
1092
|
+
out.append(f" {_esc(str(sk))}:")
|
|
1093
|
+
out += [f" {_esc(str(a))}={_shown_value(b, True)}"
|
|
1094
|
+
for a, b in sorted(sv.items(), key=lambda x: str(x[0]))]
|
|
1095
|
+
elif isinstance(sv, list): # `args`: each word whole
|
|
1096
|
+
out.append(f" {_esc(str(sk))}:")
|
|
1097
|
+
out += [f" {_shown_value(b, True)}" for b in sv]
|
|
1098
|
+
else:
|
|
1099
|
+
out.append(f" {_esc(str(sk))}: {_shown_value(sv, True)}")
|
|
1100
|
+
continue
|
|
1101
|
+
shown = "" if k not in new else " " + _shown_value(new[k])
|
|
1102
|
+
out.append(f" {_esc(key)}.{_esc(str(k))}: {what}{shown}")
|
|
1103
|
+
else:
|
|
1104
|
+
out.append(f" {_esc(key)}: now {_shown_value(old)}")
|
|
1105
|
+
out.append(f" {_esc(key)}: accept writes {_shown_value(new)}")
|
|
1106
|
+
out.append(f" files: {_esc(os.path.join(self.qroot, qid, 'files'))}")
|
|
1107
|
+
return out or ["nothing in quarantine"]
|
|
1108
|
+
|
|
1109
|
+
def reset(self) -> None:
|
|
1110
|
+
"""The record cannot be read: it is made again from the trusted copy."""
|
|
1111
|
+
with self._locked():
|
|
1112
|
+
self._save(self._resign())
|
|
1113
|
+
|
|
1114
|
+
def status(self, base: str) -> List[str]:
|
|
1115
|
+
"""Sizes, and what each deletion costs (rule D): everything here may be deleted."""
|
|
1116
|
+
def size(p: str) -> Tuple[int, int]:
|
|
1117
|
+
n = b = 0
|
|
1118
|
+
if _is_real_dir(p): # never a link at the top; bounded
|
|
1119
|
+
stack = [p]
|
|
1120
|
+
while stack and n < 1_000_000:
|
|
1121
|
+
try:
|
|
1122
|
+
it = list(os.scandir(stack.pop()))
|
|
1123
|
+
except OSError:
|
|
1124
|
+
continue
|
|
1125
|
+
for e in it:
|
|
1126
|
+
try:
|
|
1127
|
+
st = e.stat(follow_symlinks=False)
|
|
1128
|
+
except OSError:
|
|
1129
|
+
continue
|
|
1130
|
+
n += 1
|
|
1131
|
+
b += st.st_size if stat.S_ISREG(st.st_mode) else 0
|
|
1132
|
+
if stat.S_ISDIR(st.st_mode):
|
|
1133
|
+
stack.append(e.path)
|
|
1134
|
+
return n, b
|
|
1135
|
+
rows = [
|
|
1136
|
+
(os.path.join(base, RUNS), "session folders; delete when no session runs: costs nothing"),
|
|
1137
|
+
(os.path.join(base, TRASH), "being removed; delete when no session runs: costs nothing"),
|
|
1138
|
+
(self.qroot, "quarantine; delete: you lose copies you have not read"),
|
|
1139
|
+
(self.trusted, "the trusted copy; delete: sessions start with no instructions or settings "
|
|
1140
|
+
"of yours, and you add or accept them again"),
|
|
1141
|
+
]
|
|
1142
|
+
out = []
|
|
1143
|
+
for p, what in rows:
|
|
1144
|
+
n, b = size(p)
|
|
1145
|
+
out.append(f"{b / (1 << 20):10.1f} MB {n:7d} entries {_esc(p)}\n {what}")
|
|
1146
|
+
legacy = [x for x in (os.listdir(base) if _is_real_dir(base) else []) if x.startswith("legacy-")]
|
|
1147
|
+
if legacy:
|
|
1148
|
+
out.append(f" {len(legacy)} legacy folder(s) in {_esc(base)}: entries of an older layout, "
|
|
1149
|
+
"not used; delete them when you have kept what you need")
|
|
1150
|
+
return out
|
|
1151
|
+
|
|
1152
|
+
|
|
1153
|
+
def _without(sig: Optional[Dict[str, str]], skip: Sequence[str]) -> Optional[Dict[str, str]]:
|
|
1154
|
+
"""A signature without the entries under the skipped relative paths."""
|
|
1155
|
+
if sig is None or not skip:
|
|
1156
|
+
return sig
|
|
1157
|
+
gone = {k for k in sig if any(_skip_match(k, s, sig.get(k, "")) for s in skip)}
|
|
1158
|
+
if not gone:
|
|
1159
|
+
return sig
|
|
1160
|
+
out = {k: v for k, v in sig.items() if k not in gone}
|
|
1161
|
+
# a folder left empty by dropped downloads counts as no folder, at any depth
|
|
1162
|
+
for k in sorted((k for k, v in out.items() if v.startswith("d:") and k != "."),
|
|
1163
|
+
key=lambda x: -x.count("/")):
|
|
1164
|
+
if not any(o.startswith(k + "/") for o in out) and any(g.startswith(k + "/") for g in gone):
|
|
1165
|
+
out.pop(k)
|
|
1166
|
+
if list(out) == ["."] and out["."].startswith("d:"):
|
|
1167
|
+
return None
|
|
1168
|
+
return out
|
|
1169
|
+
|
|
1170
|
+
|
|
1171
|
+
def _skip_match(k: str, s: str, v: str) -> bool:
|
|
1172
|
+
"""A literal skip covers its subtree; a glob matches one path segment per part, and a file
|
|
1173
|
+
only (`*` must not cross "/", and a glob never hides a folder's contents)."""
|
|
1174
|
+
if not any(c in s for c in "*?["):
|
|
1175
|
+
return k == s or k.startswith(s + "/")
|
|
1176
|
+
kp, sp = k.split("/"), s.split("/")
|
|
1177
|
+
return len(kp) == len(sp) and v.startswith("f:") and \
|
|
1178
|
+
all(fnmatch.fnmatchcase(a, b) for a, b in zip(kp, sp))
|
|
1179
|
+
|
|
1180
|
+
|
|
1181
|
+
def _json_key_diff(path: str, before: object) -> List[str]:
|
|
1182
|
+
"""The top-level keys that differ between a JSON file and what it was built with."""
|
|
1183
|
+
now = _read_json(path)
|
|
1184
|
+
if not isinstance(now, dict):
|
|
1185
|
+
return []
|
|
1186
|
+
was = before if isinstance(before, dict) else {}
|
|
1187
|
+
return sorted(k for k in set(now) | set(was) if now.get(k) != was.get(k))
|
|
1188
|
+
|
|
1189
|
+
|
|
1190
|
+
def _nospace(exc: OSError) -> bool:
|
|
1191
|
+
return exc.errno in (errno.ENOSPC, errno.EDQUOT)
|
|
1192
|
+
|
|
1193
|
+
|
|
1194
|
+
def _layout(base: str) -> List[str]:
|
|
1195
|
+
"""The tool folder's own folders, made again when missing (rule D); only the launcher
|
|
1196
|
+
writes them (a session writes only inside its own run folder)."""
|
|
1197
|
+
for sub in (RUNS, TRASH):
|
|
1198
|
+
p = os.path.join(base, sub)
|
|
1199
|
+
os.makedirs(p, mode=0o700, exist_ok=True)
|
|
1200
|
+
if not _is_real_dir(p) or os.path.realpath(p) != os.path.normpath(p):
|
|
1201
|
+
raise CarryoverError(f"{_esc(p)} is not a real folder")
|
|
1202
|
+
return []
|
|
1203
|
+
|
|
1204
|
+
|
|
1205
|
+
def _to_trash(base: str, name: str) -> str:
|
|
1206
|
+
"""P2: rename `runs/<name>` into `trash/` in one step, by descriptor; the rename takes a link
|
|
1207
|
+
as a link. Returns the new path, or "" when it could not be moved (it stays in runs/, where
|
|
1208
|
+
nothing reads it)."""
|
|
1209
|
+
rfd = _opendir(os.path.join(base, RUNS))
|
|
1210
|
+
tfd = _opendir(os.path.join(base, TRASH))
|
|
1211
|
+
target = f"{name}-{secrets.token_hex(4)}"
|
|
1212
|
+
try:
|
|
1213
|
+
# a flag or mode a session set on its own run folder would stop the rename; runs/ is
|
|
1214
|
+
# written only by the launcher, so the entry is changed by name there without following
|
|
1215
|
+
# a link (on Linux the session's processes have ended, so the entry checked is the one
|
|
1216
|
+
# changed)
|
|
1217
|
+
try:
|
|
1218
|
+
st = os.lstat(name, dir_fd=rfd)
|
|
1219
|
+
if stat.S_ISDIR(st.st_mode) and st.st_uid == os.getuid():
|
|
1220
|
+
if _UF and getattr(st, "st_flags", 0) & _UF:
|
|
1221
|
+
os.chflags(os.path.join(base, RUNS, name), st.st_flags & ~_UF, follow_symlinks=False)
|
|
1222
|
+
_movable(rfd, name)
|
|
1223
|
+
except (OSError, NotImplementedError):
|
|
1224
|
+
pass
|
|
1225
|
+
os.rename(name, target, src_dir_fd=rfd, dst_dir_fd=tfd)
|
|
1226
|
+
except OSError:
|
|
1227
|
+
return ""
|
|
1228
|
+
finally:
|
|
1229
|
+
os.close(rfd)
|
|
1230
|
+
os.close(tfd)
|
|
1231
|
+
return os.path.join(base, TRASH, target)
|
|
1232
|
+
|
|
1233
|
+
|
|
1234
|
+
def _plain_finish(base: str, name: str) -> List[str]:
|
|
1235
|
+
t = _to_trash(base, name)
|
|
1236
|
+
if t:
|
|
1237
|
+
try:
|
|
1238
|
+
_remove(t)
|
|
1239
|
+
except (OSError, RecursionError, CarryoverError):
|
|
1240
|
+
return [f"phiward launch: {_esc(t)} could not be removed; it is tried again at the "
|
|
1241
|
+
"next start"]
|
|
1242
|
+
return []
|
|
1243
|
+
|
|
1244
|
+
|
|
1245
|
+
class _runs_lock:
|
|
1246
|
+
"""The lock of runs/: held while a run folder is made and locked, and while a cleaner tests a
|
|
1247
|
+
run folder's lock and moves it."""
|
|
1248
|
+
|
|
1249
|
+
def __init__(self, base: str) -> None:
|
|
1250
|
+
self.base = base
|
|
1251
|
+
|
|
1252
|
+
def __enter__(self) -> int:
|
|
1253
|
+
self.fd = _opendir(os.path.join(self.base, RUNS))
|
|
1254
|
+
fcntl.flock(self.fd, fcntl.LOCK_EX)
|
|
1255
|
+
return self.fd
|
|
1256
|
+
|
|
1257
|
+
def __exit__(self, *a) -> None:
|
|
1258
|
+
os.close(self.fd)
|
|
1259
|
+
|
|
1260
|
+
|
|
1261
|
+
def _clean_runs(base: str, current: str, finish) -> List[str]:
|
|
1262
|
+
"""Every run folder but the current one whose launcher no longer holds its lock is finished
|
|
1263
|
+
(`finish(name)`: read, then moved to trash and removed). A locked one is a live session and
|
|
1264
|
+
is left alone (parallel sessions). Trash is emptied; what cannot be removed stays and is
|
|
1265
|
+
reported."""
|
|
1266
|
+
msgs: List[str] = []
|
|
1267
|
+
runs = os.path.join(base, RUNS)
|
|
1268
|
+
with _runs_lock(base) as rfd:
|
|
1269
|
+
for n in sorted(os.listdir(rfd)):
|
|
1270
|
+
if os.path.join(runs, n) == current:
|
|
1271
|
+
continue
|
|
1272
|
+
try:
|
|
1273
|
+
st = os.lstat(n, dir_fd=rfd)
|
|
1274
|
+
except OSError:
|
|
1275
|
+
continue
|
|
1276
|
+
if not stat.S_ISDIR(st.st_mode): # a link or a file: nothing to read, only moved away
|
|
1277
|
+
msgs += _plain_finish(base, n)
|
|
1278
|
+
continue
|
|
1279
|
+
_movable(rfd, n) # a session may have made its own folder unreadable
|
|
1280
|
+
try:
|
|
1281
|
+
fd: Optional[int] = _opendir(n, rfd)
|
|
1282
|
+
except (OSError, CarryoverError):
|
|
1283
|
+
continue # still not openable: its lock cannot be tested, so it counts as live
|
|
1284
|
+
try:
|
|
1285
|
+
fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
|
1286
|
+
except OSError:
|
|
1287
|
+
os.close(fd)
|
|
1288
|
+
continue # a live session
|
|
1289
|
+
try:
|
|
1290
|
+
msgs += finish(n) # the lock is held through the move
|
|
1291
|
+
finally:
|
|
1292
|
+
os.close(fd)
|
|
1293
|
+
trash = os.path.join(base, TRASH)
|
|
1294
|
+
left = 0
|
|
1295
|
+
tfd = _opendir(trash)
|
|
1296
|
+
try:
|
|
1297
|
+
for n in sorted(os.listdir(tfd)):
|
|
1298
|
+
try:
|
|
1299
|
+
fd: Optional[int] = _opendir(n, tfd)
|
|
1300
|
+
except (OSError, CarryoverError):
|
|
1301
|
+
fd = None # a link or a file
|
|
1302
|
+
if fd is not None:
|
|
1303
|
+
try:
|
|
1304
|
+
fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
|
1305
|
+
except OSError:
|
|
1306
|
+
os.close(fd)
|
|
1307
|
+
continue # its launcher is still reading it
|
|
1308
|
+
try:
|
|
1309
|
+
_remove(os.path.join(trash, n)) # the lock is held until it is gone
|
|
1310
|
+
except (OSError, RecursionError, CarryoverError):
|
|
1311
|
+
left += 1
|
|
1312
|
+
finally:
|
|
1313
|
+
if fd is not None:
|
|
1314
|
+
os.close(fd)
|
|
1315
|
+
finally:
|
|
1316
|
+
os.close(tfd)
|
|
1317
|
+
if left:
|
|
1318
|
+
msgs.append(f"phiward launch: {left} old session folder(s) in {_esc(trash)} could not be "
|
|
1319
|
+
"removed (a file may be locked); remove them by hand")
|
|
1320
|
+
return msgs
|
|
1321
|
+
|
|
1322
|
+
|
|
1323
|
+
# -- the project report -----------------------------------------------------------------------------
|
|
1324
|
+
|
|
1325
|
+
SKIP = {".git"} # objects are not walked; its control entries are (GIT_CONTROL_REPORT)
|
|
1326
|
+
# the git control entries that run code or point git elsewhere: walked inside every `.git`, so a
|
|
1327
|
+
# repository the session made, or changed, is reported (a new
|
|
1328
|
+
# .git/config with core.fsmonitor runs when the operator's prompt calls `git status`)
|
|
1329
|
+
GIT_CONTROL_REPORT = ("config", "HEAD", "commondir", "gitdir", "hooks", "info", "modules",
|
|
1330
|
+
"worktrees")
|
|
1331
|
+
INSTRUCTION_NAMES = {"CLAUDE.md", "CLAUDE.local.md", "AGENTS.md", "GEMINI.md", ".cursorrules",
|
|
1332
|
+
".windsurfrules", "copilot-instructions.md"}
|
|
1333
|
+
RUNS_LATER_NAMES = {"Makefile", "makefile", "GNUmakefile", "package.json", "pyproject.toml",
|
|
1334
|
+
"setup.py", "setup.cfg", "tox.ini", "noxfile.py", "conftest.py",
|
|
1335
|
+
".pre-commit-config.yaml", "lefthook.yml", ".envrc", "Justfile", "justfile",
|
|
1336
|
+
"Rakefile", "build.gradle", "pom.xml", "Cargo.toml", "CMakeLists.txt",
|
|
1337
|
+
"Dockerfile", "docker-compose.yml", ".gitattributes", ".gitmodules",
|
|
1338
|
+
".gitlab-ci.yml", "Snakefile", "nextflow.config", "sitecustomize.py",
|
|
1339
|
+
"usercustomize.py", ".npmrc", ".yarnrc", ".yarnrc.yml", ".pnpmfile.cjs",
|
|
1340
|
+
# read from the current folder by R, IPython, pdb, pytest and task runners
|
|
1341
|
+
".Rprofile", ".Renviron", "activate.R", ".pdbrc", "ipython_config.py",
|
|
1342
|
+
"jupyter_notebook_config.py", "jupyter_server_config.py",
|
|
1343
|
+
"jupyter_lab_config.py", "pytest.ini", "mise.toml", ".mise.toml",
|
|
1344
|
+
"Taskfile.yml", "Taskfile.yaml"}
|
|
1345
|
+
RUNS_LATER_SUFFIXES = (".sh", ".bash", ".pth")
|
|
1346
|
+
SETTINGS_PREFIXES = (".vscode/", ".idea/", ".mcp.json", ".claude/settings")
|
|
1347
|
+
TRUNCATED = "\0truncated"
|
|
1348
|
+
|
|
1349
|
+
|
|
1350
|
+
def project_state(project: str, limit: int = 200_000, scan_limit: int = 2_000_000) -> Dict[str, tuple]:
|
|
1351
|
+
"""Metadata of every entry in the project (inode, size, times, mode, link target), bounded;
|
|
1352
|
+
the change time cannot be set by a program, so a reset modification time is still seen.
|
|
1353
|
+
Past the bound the result says so, and nothing is reported as removed."""
|
|
1354
|
+
import collections
|
|
1355
|
+
out: Dict[str, tuple] = {}
|
|
1356
|
+
# breadth first, dot-folders first: instructions and settings live near the top and in dot
|
|
1357
|
+
# folders, so a flood of files deep in the tree is visited last
|
|
1358
|
+
stack: "collections.deque[str]" = collections.deque([""])
|
|
1359
|
+
seen = 0
|
|
1360
|
+
while stack:
|
|
1361
|
+
rel = stack.popleft()
|
|
1362
|
+
try:
|
|
1363
|
+
it = sorted(os.scandir(os.path.join(project, rel) if rel else project),
|
|
1364
|
+
key=lambda e: (not e.name.startswith("."), e.name))
|
|
1365
|
+
except OSError:
|
|
1366
|
+
continue
|
|
1367
|
+
for e in it:
|
|
1368
|
+
seen += 1
|
|
1369
|
+
if seen > scan_limit:
|
|
1370
|
+
out[TRUNCATED] = ("t", len(stack) + 1)
|
|
1371
|
+
return out
|
|
1372
|
+
r = f"{rel}/{e.name}" if rel else e.name
|
|
1373
|
+
full = len(out) >= limit
|
|
1374
|
+
if full and TRUNCATED not in out:
|
|
1375
|
+
out[TRUNCATED] = ("t", 0)
|
|
1376
|
+
try:
|
|
1377
|
+
st = e.stat(follow_symlinks=False)
|
|
1378
|
+
except OSError:
|
|
1379
|
+
continue
|
|
1380
|
+
link = os.readlink(e.path) if stat.S_ISLNK(st.st_mode) else ""
|
|
1381
|
+
if stat.S_ISDIR(st.st_mode):
|
|
1382
|
+
out[r] = ("d", st.st_ino, st.st_mode)
|
|
1383
|
+
if e.name not in SKIP:
|
|
1384
|
+
# dot-folder trees (.claude, .vscode, .github, .husky) first and whole:
|
|
1385
|
+
# they hold instructions and settings, and a flood elsewhere waits
|
|
1386
|
+
if any(part.startswith(".") for part in r.split("/")):
|
|
1387
|
+
stack.appendleft(r)
|
|
1388
|
+
else:
|
|
1389
|
+
stack.append(r)
|
|
1390
|
+
else:
|
|
1391
|
+
stack += [f"{r}/{c}" for c in GIT_CONTROL_REPORT
|
|
1392
|
+
if os.path.isdir(os.path.join(project, r, c)) and
|
|
1393
|
+
not os.path.islink(os.path.join(project, r, c))]
|
|
1394
|
+
for c in GIT_CONTROL_REPORT:
|
|
1395
|
+
q = os.path.join(project, r, c)
|
|
1396
|
+
try:
|
|
1397
|
+
cst = os.lstat(q)
|
|
1398
|
+
except OSError:
|
|
1399
|
+
continue
|
|
1400
|
+
if not stat.S_ISDIR(cst.st_mode):
|
|
1401
|
+
ln = os.readlink(q) if stat.S_ISLNK(cst.st_mode) else ""
|
|
1402
|
+
out[f"{r}/{c}"] = ("f", cst.st_ino, cst.st_size, cst.st_mtime_ns,
|
|
1403
|
+
cst.st_ctime_ns, cst.st_mode, ln)
|
|
1404
|
+
else:
|
|
1405
|
+
ent = ("f", st.st_ino, st.st_size, st.st_mtime_ns, st.st_ctime_ns, st.st_mode, link)
|
|
1406
|
+
# past the bound, the walk goes on and keeps what matters most: instructions,
|
|
1407
|
+
# files that run later, settings (a flood of files must not hide
|
|
1408
|
+
# them)
|
|
1409
|
+
if not full or _rank(r, ent, project) < 3:
|
|
1410
|
+
out[r] = ent
|
|
1411
|
+
return out
|
|
1412
|
+
|
|
1413
|
+
|
|
1414
|
+
def _rank(rel: str, entry: Optional[tuple] = None, project: str = "") -> int:
|
|
1415
|
+
name = os.path.basename(rel)
|
|
1416
|
+
if rel.startswith(".git/") or "/.git/" in rel or name == ".git":
|
|
1417
|
+
return 1 # git control files run code (hooks, fsmonitor) or point git elsewhere; a `.git`
|
|
1418
|
+
# file (`gitdir: ...`) points git at a folder the session chose
|
|
1419
|
+
if project and (name in ("config", "HEAD", "packed-refs", "commondir") or
|
|
1420
|
+
rel.startswith("hooks/") or "/hooks/" in rel):
|
|
1421
|
+
if rel.startswith("hooks/"):
|
|
1422
|
+
repo_rel = ""
|
|
1423
|
+
elif "/hooks/" in rel:
|
|
1424
|
+
repo_rel = rel.split("/hooks/")[0]
|
|
1425
|
+
else:
|
|
1426
|
+
repo_rel = os.path.dirname(rel)
|
|
1427
|
+
repo = os.path.join(project, repo_rel) if repo_rel else project
|
|
1428
|
+
if os.path.isdir(os.path.join(repo, "objects")) and (
|
|
1429
|
+
os.path.isfile(os.path.join(repo, "HEAD")) or os.path.isdir(os.path.join(repo, "refs"))):
|
|
1430
|
+
return 1 # a folder laid out as a git repository (a bare one, or a gitdir target)
|
|
1431
|
+
if rel.startswith(SETTINGS_PREFIXES) or "/.vscode/" in rel:
|
|
1432
|
+
return 2
|
|
1433
|
+
if name in INSTRUCTION_NAMES or rel.startswith((".claude/", ".cursor/rules/", ".github/instructions/")) \
|
|
1434
|
+
or "/.claude/" in rel:
|
|
1435
|
+
return 0
|
|
1436
|
+
if name in RUNS_LATER_NAMES or name.endswith(RUNS_LATER_SUFFIXES) or \
|
|
1437
|
+
rel.startswith((".github/workflows/", ".husky/", ".githooks/", ".devcontainer/",
|
|
1438
|
+
".cargo/")) or "/.husky/" in rel:
|
|
1439
|
+
return 1
|
|
1440
|
+
if entry is not None and entry[0] == "f" and entry[5] & 0o111:
|
|
1441
|
+
return 1 # an executable file: a program on a PATH, a script run by name
|
|
1442
|
+
return 3
|
|
1443
|
+
|
|
1444
|
+
|
|
1445
|
+
# the kinds of changed project files, by `_rank`: the first three are for a person to read
|
|
1446
|
+
KINDS = ("instructions", "runs_later", "settings", "other")
|
|
1447
|
+
|
|
1448
|
+
|
|
1449
|
+
class Changes(NamedTuple):
|
|
1450
|
+
"""The project files a session changed, as (path, how) grouped by `_rank`, and whether the
|
|
1451
|
+
scan was cut short (the project has more entries than it compares)."""
|
|
1452
|
+
groups: Dict[int, List[Tuple[str, str]]]
|
|
1453
|
+
truncated: bool
|
|
1454
|
+
|
|
1455
|
+
|
|
1456
|
+
def project_changes(before: Dict[str, tuple], after: Dict[str, tuple],
|
|
1457
|
+
project: str = "") -> Changes:
|
|
1458
|
+
"""`Changes` between two `project_state`s."""
|
|
1459
|
+
truncated = TRUNCATED in before or TRUNCATED in after
|
|
1460
|
+
changed = []
|
|
1461
|
+
for r in set(before) | set(after):
|
|
1462
|
+
if r == TRUNCATED:
|
|
1463
|
+
continue
|
|
1464
|
+
b, a = before.get(r), after.get(r)
|
|
1465
|
+
if b == a or (b and a and b[0] == a[0] == "d"):
|
|
1466
|
+
continue
|
|
1467
|
+
if a is None and truncated:
|
|
1468
|
+
continue # past the bound, an entry not seen is not known to be removed
|
|
1469
|
+
if (a or b)[0] == "d" and (b is None or a is None):
|
|
1470
|
+
continue # a folder made or removed: its files are listed
|
|
1471
|
+
changed.append((r, "new" if b is None else "removed" if a is None else "changed"))
|
|
1472
|
+
groups: Dict[int, List[Tuple[str, str]]] = {0: [], 1: [], 2: [], 3: []}
|
|
1473
|
+
for r, how in sorted(changed):
|
|
1474
|
+
groups[_rank(r, after.get(r) or before.get(r), project)].append((r, how))
|
|
1475
|
+
return Changes(groups, truncated)
|
|
1476
|
+
|
|
1477
|
+
|
|
1478
|
+
def project_report(changes: Changes) -> List[str]:
|
|
1479
|
+
"""The lines `launch` prints about the project files a session changed
|
|
1480
|
+
(`project_changes`)."""
|
|
1481
|
+
groups, truncated = changes
|
|
1482
|
+
changed = [c for k in sorted(groups) for c in groups[k]]
|
|
1483
|
+
lines: List[str] = []
|
|
1484
|
+
if changed:
|
|
1485
|
+
lines.append(f"phiward launch: the session changed {len(changed)} file(s) in the "
|
|
1486
|
+
"project; read them before you run anything outside launch:")
|
|
1487
|
+
# instructions for models in full (up to 500), so other files cannot push them out of
|
|
1488
|
+
# sight
|
|
1489
|
+
# instructions, files that run later and settings are never folded into a count
|
|
1490
|
+
for k, title, show in ((0, "instructions for models", 500), (1, "files that run later", 500),
|
|
1491
|
+
(2, "settings", 500)):
|
|
1492
|
+
if groups[k]:
|
|
1493
|
+
lines.append(f" {title} ({len(groups[k])}):")
|
|
1494
|
+
lines += [f" {_esc(r)} ({how})" for r, how in groups[k][:show]]
|
|
1495
|
+
if len(groups[k]) > show:
|
|
1496
|
+
lines.append(f" ... and {len(groups[k]) - show} more")
|
|
1497
|
+
rest = groups[3]
|
|
1498
|
+
if rest:
|
|
1499
|
+
if len(rest) <= 10:
|
|
1500
|
+
lines.append(" other: " + "; ".join(_esc(r) for r, _ in rest))
|
|
1501
|
+
else:
|
|
1502
|
+
lines.append(f" and {len(rest)} other file(s)")
|
|
1503
|
+
if truncated:
|
|
1504
|
+
lines.append("phiward launch: WARNING: the project has more entries than the report "
|
|
1505
|
+
"compares; past that point only instructions, files that run later and "
|
|
1506
|
+
"settings were checked, and other files are not listed. Read the project "
|
|
1507
|
+
"before you run anything outside launch.")
|
|
1508
|
+
return lines
|
|
1509
|
+
|
|
1510
|
+
|
|
1511
|
+
# -- the command ---------------------------------------------------------------------------------------
|
|
1512
|
+
|
|
1513
|
+
USAGE = ("usage: phiward carryover status [--tool NAME]\n"
|
|
1514
|
+
" phiward carryover add PATH [--as NAME] [--tool NAME]\n"
|
|
1515
|
+
" phiward carryover show [--tool NAME]\n"
|
|
1516
|
+
" phiward carryover accept ID [ITEM...] [--tool NAME]\n"
|
|
1517
|
+
" phiward carryover reset [--tool NAME]\n")
|
|
1518
|
+
HELP = USAGE + """
|
|
1519
|
+
Commands:
|
|
1520
|
+
status show the size of each carry-over folder (sessions, trash, quarantine,
|
|
1521
|
+
the trusted copy) and what it costs to delete it
|
|
1522
|
+
add PATH put an instruction file or folder of your own into the trusted copy
|
|
1523
|
+
(--as NAME: the name it gets there)
|
|
1524
|
+
show list the changes in quarantine, each with its ID and items
|
|
1525
|
+
accept ID [ITEM...] keep a change from quarantine (all of it, or only the named items);
|
|
1526
|
+
every later session starts with it
|
|
1527
|
+
reset make the record again from the trusted copy, when it cannot be read
|
|
1528
|
+
|
|
1529
|
+
Options:
|
|
1530
|
+
--tool NAME the agent tool (default: claude)
|
|
1531
|
+
-h, --help show this help
|
|
1532
|
+
|
|
1533
|
+
Each `phiward launch` session runs in a config folder of its own. It is built from a trusted
|
|
1534
|
+
copy that no session can read or write, and it is thrown away at exit. When a session changes
|
|
1535
|
+
the tool's instructions or settings, the change goes to quarantine. Read it with `show`, and
|
|
1536
|
+
keep it with `accept`. These commands are yours: run them in your own terminal, not through
|
|
1537
|
+
an agent tool.
|
|
1538
|
+
"""
|
|
1539
|
+
|
|
1540
|
+
|
|
1541
|
+
def main(argv: List[str]) -> int:
|
|
1542
|
+
from phiward import wholetool
|
|
1543
|
+
args = list(argv)
|
|
1544
|
+
if args[:1] in (["-h"], ["--help"]):
|
|
1545
|
+
sys.stdout.write(HELP)
|
|
1546
|
+
return 0
|
|
1547
|
+
tool = "claude"
|
|
1548
|
+
if "--tool" in args:
|
|
1549
|
+
i = args.index("--tool")
|
|
1550
|
+
if i + 1 >= len(args):
|
|
1551
|
+
sys.stderr.write(USAGE)
|
|
1552
|
+
return 2
|
|
1553
|
+
tool = args[i + 1]
|
|
1554
|
+
del args[i:i + 2]
|
|
1555
|
+
if tool not in wholetool.ADAPTERS:
|
|
1556
|
+
sys.stderr.write(f"phiward carryover: no adapter for '{tool}'\n")
|
|
1557
|
+
return 2
|
|
1558
|
+
env = dict(os.environ)
|
|
1559
|
+
store = Store(tool, wholetool._real_home(env))
|
|
1560
|
+
if args == ["status"]:
|
|
1561
|
+
base = wholetool.tool_folder(wholetool.ADAPTERS[tool], env)
|
|
1562
|
+
sys.stdout.write("\n".join(store.status(base)) + "\n")
|
|
1563
|
+
return 0
|
|
1564
|
+
if args == ["show"]:
|
|
1565
|
+
sys.stdout.write("\n".join(store.show_lines()) + "\n")
|
|
1566
|
+
return 0
|
|
1567
|
+
if args[:1] in (["accept"], ["add"], ["reset"]):
|
|
1568
|
+
# these change what every later `launch` session trusts: the operator's, in a terminal
|
|
1569
|
+
# (an agent could otherwise reach them through another spelling of the command)
|
|
1570
|
+
try:
|
|
1571
|
+
tty = sys.stdin.isatty()
|
|
1572
|
+
except (AttributeError, ValueError):
|
|
1573
|
+
tty = False
|
|
1574
|
+
if not tty:
|
|
1575
|
+
sys.stderr.write("phiward carryover: `add`, `accept` and `reset` change what every "
|
|
1576
|
+
"later session trusts; run them in your own terminal, not through "
|
|
1577
|
+
"an agent tool. Nothing was changed.\n")
|
|
1578
|
+
return 2
|
|
1579
|
+
try:
|
|
1580
|
+
if args[:1] == ["accept"] and len(args) >= 2:
|
|
1581
|
+
done = store.accept(args[1], args[2:])
|
|
1582
|
+
sys.stdout.write(f"accepted {len(done)} item(s); they are now the trusted state\n")
|
|
1583
|
+
return 0
|
|
1584
|
+
if args[:1] == ["add"] and len(args) in (2, 4) and (len(args) == 2 or args[2] == "--as"):
|
|
1585
|
+
from phiward import config, paths
|
|
1586
|
+
cfg = config.load(os.getcwd(), env=env)
|
|
1587
|
+
src = os.path.abspath(args[1])
|
|
1588
|
+
if cfg.problem:
|
|
1589
|
+
raise CarryoverError("the phiward config cannot be used (run phiward doctor)")
|
|
1590
|
+
rel = paths.ProtectedSet(cfg.all_roots, cfg.patterns).relation(os.path.realpath(src))
|
|
1591
|
+
if rel in (paths.INSIDE, paths.ABOVE): # priority 1: the model reads this copy
|
|
1592
|
+
raise CarryoverError("that path is inside or above protected data; it is never put "
|
|
1593
|
+
"into the trusted copy, which every session's model reads")
|
|
1594
|
+
# copied from the resolved path that was checked
|
|
1595
|
+
as_name = args[3] if len(args) == 4 else os.path.basename(src)
|
|
1596
|
+
name = store.add(os.path.realpath(src), as_name)
|
|
1597
|
+
if store.spec.json_main and as_name == store.spec.json_main:
|
|
1598
|
+
sys.stdout.write(f"added these keys of {as_name} to the trusted copy: {name}. "
|
|
1599
|
+
"Every later session starts with them; the `env` and header "
|
|
1600
|
+
"values of an MCP server there are readable by the agent.\n")
|
|
1601
|
+
else:
|
|
1602
|
+
sys.stdout.write(f"added {name} to the trusted copy; every later session starts "
|
|
1603
|
+
"with it\n")
|
|
1604
|
+
return 0
|
|
1605
|
+
if args == ["reset"]:
|
|
1606
|
+
store.reset()
|
|
1607
|
+
sys.stdout.write("the record was made again from the trusted copy\n")
|
|
1608
|
+
return 0
|
|
1609
|
+
except (CarryoverError, OSError) as exc:
|
|
1610
|
+
sys.stderr.write(f"phiward carryover: {exc}\n")
|
|
1611
|
+
return 1
|
|
1612
|
+
sys.stderr.write(USAGE)
|
|
1613
|
+
return 2
|