phiward 0.2.0b1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. phiward/__init__.py +8 -0
  2. phiward/__main__.py +5 -0
  3. phiward/_toml.py +211 -0
  4. phiward/adapters/__init__.py +105 -0
  5. phiward/adapters/claude.py +429 -0
  6. phiward/broker.py +831 -0
  7. phiward/carryover.py +1613 -0
  8. phiward/claude_settings.py +1307 -0
  9. phiward/cli.py +110 -0
  10. phiward/config.py +936 -0
  11. phiward/confine.py +476 -0
  12. phiward/copying.py +533 -0
  13. phiward/core.py +105 -0
  14. phiward/data/agents-section.md +43 -0
  15. phiward/doctor.py +1132 -0
  16. phiward/fasthook.py +70 -0
  17. phiward/fsinfo.py +241 -0
  18. phiward/gateway.py +159 -0
  19. phiward/githooks.py +248 -0
  20. phiward/guards/__init__.py +0 -0
  21. phiward/guards/protected_paths.py +1138 -0
  22. phiward/hidden.py +281 -0
  23. phiward/init.py +155 -0
  24. phiward/install.py +828 -0
  25. phiward/inventory.py +173 -0
  26. phiward/mcp.py +186 -0
  27. phiward/mcp_config.py +1736 -0
  28. phiward/names.py +5 -0
  29. phiward/packs/dates.toml +17 -0
  30. phiward/packs/genomics.toml +51 -0
  31. phiward/packs/msk.toml +32 -0
  32. phiward/pathid.py +403 -0
  33. phiward/pathmatch.py +98 -0
  34. phiward/paths.py +942 -0
  35. phiward/pin.py +214 -0
  36. phiward/procinfo.py +73 -0
  37. phiward/remote.py +448 -0
  38. phiward/run.py +788 -0
  39. phiward/safeio.py +84 -0
  40. phiward/sanitize.py +691 -0
  41. phiward/selfcheck.py +1506 -0
  42. phiward/service.py +321 -0
  43. phiward/session_note.py +86 -0
  44. phiward/setup_cmd.py +886 -0
  45. phiward/shell.py +504 -0
  46. phiward/wholetool.py +1463 -0
  47. phiward-0.2.0b1.dist-info/METADATA +147 -0
  48. phiward-0.2.0b1.dist-info/RECORD +53 -0
  49. phiward-0.2.0b1.dist-info/WHEEL +5 -0
  50. phiward-0.2.0b1.dist-info/entry_points.txt +3 -0
  51. phiward-0.2.0b1.dist-info/licenses/LICENSE +662 -0
  52. phiward-0.2.0b1.dist-info/licenses/NOTICE +16 -0
  53. phiward-0.2.0b1.dist-info/top_level.txt +1 -0
phiward/shell.py ADDED
@@ -0,0 +1,504 @@
1
+ """Split a shell command into words and operators, the way a POSIX shell (bash, zsh) would.
2
+
3
+ This is not a full shell parser and does not try to be. It does what the guard needs:
4
+ - every word, with its quotes removed and its variables expanded where the value is known;
5
+ - every operator (`|`, `&&`, `;`, redirections), so the guard can match its two allowed forms;
6
+ - the text of every command substitution, process substitution and unquoted heredoc, so the
7
+ guard can check those commands too;
8
+ - whether some word holds a variable whose value the guard cannot know (`unresolved`).
9
+
10
+ It over-approximates on purpose: when in doubt it gives more candidate paths, never fewer.
11
+ """
12
+
13
+ import os
14
+ import re
15
+ from dataclasses import dataclass, field
16
+ from typing import List, Mapping, Optional, Set, Tuple, Union
17
+
18
+ NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
19
+ ASSIGNMENT = re.compile(r"([A-Za-z_][A-Za-z0-9_]*)(\[[^\]]*\])?\+?=")
20
+ _SPECIAL = set("?#$!@*-_0123456789")
21
+ _REDIR = re.compile(r"(\d*|&)(>>|>&|>\||<<<|<<-|<<|<&|<>|>|<)")
22
+ _CONTROL = ("&&", "||", ";;", "|&", "|", "&", ";", "(", ")")
23
+
24
+
25
+ class ShellSyntaxError(ValueError):
26
+ pass
27
+
28
+
29
+ @dataclass
30
+ class Word:
31
+ raw: str = ""
32
+ # segments: (kind, text, quoted) with kind in lit, ansi ($'...', escapes kept as written),
33
+ # var, varx (${NAME} with a modifier, as in ${NAME:-x}: its value is not known), special,
34
+ # sub, tilde; `text()` keeps only lit and tilde
35
+ segs: List[Tuple[str, str, bool]] = field(default_factory=list)
36
+ has_glob: bool = False # an unquoted * ? [
37
+ has_brace: bool = False # an unquoted { with , or ..
38
+ has_sub: bool = False # $( ), backticks, <( ), >( )
39
+ has_dollar: bool = False # any $ expansion
40
+ redirect_target: bool = False
41
+
42
+ def text(self) -> str:
43
+ """The literal text, quotes removed, expansions dropped."""
44
+ return "".join(t for k, t, _ in self.segs if k in ("lit", "tilde"))
45
+
46
+
47
+ @dataclass
48
+ class Op:
49
+ text: str # "|", "&&", ";", "\n", "(", or a redirection such as "2>&", ">", "<<"
50
+ target: Optional[Word] = None # the word after a redirection
51
+
52
+ @property
53
+ def is_redirect(self) -> bool:
54
+ return self.target is not None or self.text in ("<<", "<<-")
55
+
56
+
57
+ Item = Union[Word, Op]
58
+
59
+
60
+ @dataclass
61
+ class Parsed:
62
+ items: List[Item] = field(default_factory=list)
63
+ subs: List[str] = field(default_factory=list) # inner command texts to check as commands
64
+ vars: Set[str] = field(default_factory=set) # names of $NAME / ${NAME...} used
65
+ heredocs: List[str] = field(default_factory=list) # bodies (data, not words)
66
+ # a parenthesis glued to a word outside quotes, comments and heredocs: a zsh or extglob
67
+ # group (`d/(a|b)/x`, `@(a)`), which this lexer reads as syntax
68
+ groups: bool = False
69
+
70
+ def words(self) -> List[Word]:
71
+ out: List[Word] = []
72
+ for it in self.items:
73
+ if isinstance(it, Word):
74
+ out.append(it)
75
+ elif it.target is not None:
76
+ out.append(it.target)
77
+ return out
78
+
79
+
80
+ def parse(s: str) -> Parsed:
81
+ p = _Lexer(s)
82
+ p.run()
83
+ return p.out
84
+
85
+
86
+ def bound_names(parsed: Parsed) -> Set[str]:
87
+ """Names the command itself gives a value: assignments, and bare words such as the NAME of
88
+ `for NAME in`, `read NAME`, `export NAME`. Their values come from the command's own (checked)
89
+ sources at run time."""
90
+ names: Set[str] = set()
91
+ for w in parsed.words():
92
+ t = w.text()
93
+ m = ASSIGNMENT.match(t)
94
+ if m:
95
+ names.add(m.group(1))
96
+ if not w.has_dollar and NAME.fullmatch(t):
97
+ names.add(t)
98
+ return names
99
+
100
+
101
+ def expand(word: Word, env: Mapping[str, str], bound: Set[str], home: str) -> Tuple[List[str], bool]:
102
+ """The possible values of a word, and whether a variable in it is unknown.
103
+
104
+ Known variables take their value from `env`; variables the command binds and special
105
+ parameters expand to nothing (their sources are checked separately); command substitutions
106
+ expand to nothing (their commands are checked separately).
107
+ """
108
+ unknown = False
109
+ parts: List[str] = []
110
+ for kind, text, quoted in word.segs:
111
+ if kind in ("lit", "ansi"): # $'...' keeps its escapes as written
112
+ parts.append(text)
113
+ elif kind == "tilde":
114
+ if text == "~+":
115
+ parts.append(".") # the working folder: resolved against each base
116
+ elif text == "~-":
117
+ unknown = True # the previous working folder: not known here
118
+ else:
119
+ parts.append(home if text == "~" else os.path.expanduser(text))
120
+ elif kind == "varx":
121
+ unknown = True
122
+ elif kind == "var":
123
+ if text in env:
124
+ parts.append(env[text])
125
+ elif text not in bound:
126
+ unknown = True
127
+ # special, sub: nothing
128
+ value = "".join(parts)
129
+ return [value], unknown
130
+
131
+
132
+ class _Lexer:
133
+ def __init__(self, s: str):
134
+ self.s = s
135
+ self.i = 0
136
+ self.out = Parsed()
137
+ self.pending_heredocs: List[Tuple[str, bool, bool]] = [] # (delimiter, quoted, strip)
138
+
139
+ # -- helpers ---------------------------------------------------------------------------
140
+ def peek(self, n: int = 0) -> str:
141
+ j = self.i + n
142
+ return self.s[j] if j < len(self.s) else ""
143
+
144
+ def run(self) -> None:
145
+ s = self.s
146
+ while self.i < len(s):
147
+ ch = s[self.i]
148
+ if ch in " \t":
149
+ self.i += 1
150
+ continue
151
+ if ch == "\\" and self.peek(1) == "\n":
152
+ self.i += 2
153
+ continue
154
+ if ch == "\n":
155
+ self.i += 1
156
+ self.out.items.append(Op("\n"))
157
+ self._read_heredocs()
158
+ continue
159
+ if ch == "#":
160
+ while self.i < len(s) and s[self.i] != "\n":
161
+ self.i += 1
162
+ continue
163
+ if ch in "<>" and self.peek(1) == "(":
164
+ self.out.items.append(self._word())
165
+ continue
166
+ m = _REDIR.match(s, self.i)
167
+ if m and (m.group(1) == "" or m.group(1) == "&" or self._redir_number_ok()):
168
+ self._redirect(m)
169
+ continue
170
+ op = next((o for o in _CONTROL if s.startswith(o, self.i)), None)
171
+ if op:
172
+ if self._glued(op):
173
+ self.out.groups = True
174
+ self.i += len(op)
175
+ self.out.items.append(Op(op))
176
+ continue
177
+ self.out.items.append(self._word())
178
+ if self.pending_heredocs:
179
+ raise ShellSyntaxError("a heredoc has no end line")
180
+
181
+ def _glued(self, op: str) -> bool:
182
+ """Whether the `(` or `)` at self.i is glued to a word: not `name()`, `a=(...)`, a
183
+ subshell or the end of one."""
184
+ s, i = self.s, self.i
185
+ if op == "(":
186
+ before = s[i - 1] if i else ""
187
+ return bool(before) and before not in " \t\n;|&$<>(=" and self.peek(1) != ")"
188
+ if op == ")":
189
+ if i and s[i - 1] == "(":
190
+ return False # `name()` before a body: `f(){ ...; }`
191
+ after = self.peek(1)
192
+ return bool(after) and after not in " \t\n;|&)<>"
193
+ return False
194
+
195
+ def _redir_number_ok(self) -> bool:
196
+ # "2>" is a redirection only when the digits start a word
197
+ return self.i == 0 or self.s[self.i - 1] in " \t\n;&|()"
198
+
199
+ def _redirect(self, m: "re.Match[str]") -> None:
200
+ fd, op = m.group(1), m.group(2)
201
+ self.i = m.end()
202
+ while self.peek() in (" ", "\t"):
203
+ self.i += 1
204
+ if op in ("<<", "<<-"):
205
+ target = self._word()
206
+ delim = target.text()
207
+ quoted = any(q for _, _, q in target.segs) or "\\" in target.raw
208
+ self.pending_heredocs.append((delim, quoted, op == "<<-"))
209
+ self.out.items.append(Op(fd + op, target))
210
+ return
211
+ if self.i >= len(self.s) or self.s[self.i] in "\n;&|()":
212
+ raise ShellSyntaxError("a redirection has no target")
213
+ target = self._word()
214
+ target.redirect_target = True
215
+ self.out.items.append(Op(fd + op, target))
216
+
217
+ def _read_heredocs(self) -> None:
218
+ for delim, quoted, strip in self.pending_heredocs:
219
+ body: List[str] = []
220
+ while True:
221
+ if self.i >= len(self.s):
222
+ raise ShellSyntaxError("a heredoc has no end line")
223
+ end = self.s.find("\n", self.i)
224
+ end = len(self.s) if end < 0 else end
225
+ line = self.s[self.i:end]
226
+ self.i = min(end + 1, len(self.s))
227
+ if (line.lstrip("\t") if strip else line) == delim:
228
+ break
229
+ body.append(line)
230
+ text = "\n".join(body)
231
+ self.out.heredocs.append(text)
232
+ if not quoted:
233
+ # an unquoted heredoc expands $VAR, $( ) and backticks
234
+ inner = _Lexer(text)
235
+ inner._scan_expansions_only()
236
+ self.out.subs.extend(inner.out.subs)
237
+ self.out.vars |= inner.out.vars
238
+ self.pending_heredocs = []
239
+
240
+ def _scan_expansions_only(self) -> None:
241
+ w = Word()
242
+ while self.i < len(self.s):
243
+ if self.s[self.i] == "$":
244
+ self._dollar(w, quoted=True)
245
+ elif self.s[self.i] == "`":
246
+ self._backtick(w)
247
+ elif self.s[self.i] == "\\":
248
+ self.i += 2
249
+ else:
250
+ self.i += 1
251
+
252
+ # -- words -----------------------------------------------------------------------------
253
+ def _word(self) -> Word:
254
+ s = self.s
255
+ w = Word()
256
+ start = self.i
257
+ if self.i >= len(s): # `<<` or `>` at the very end: no word where one must be (fuzz)
258
+ raise ShellSyntaxError("a word is missing")
259
+ if s[self.i] in "<>" and self.peek(1) == "(":
260
+ inner = self._balanced(self.i + 2, "(", ")")
261
+ self.out.subs.append(inner)
262
+ w.has_sub = True
263
+ w.segs.append(("sub", inner, False))
264
+ first = True
265
+ while self.i < len(s):
266
+ ch = s[self.i]
267
+ if ch in " \t\n;&|()<>":
268
+ if ch in "<>" and self.peek(1) == "(" and not first:
269
+ break
270
+ break
271
+ if ch == "'":
272
+ end = s.find("'", self.i + 1)
273
+ if end < 0:
274
+ raise ShellSyntaxError("a single quote is not closed")
275
+ w.segs.append(("lit", s[self.i + 1:end], True))
276
+ self.i = end + 1
277
+ elif ch == '"':
278
+ self._double(w)
279
+ elif ch == "\\":
280
+ if self.i + 1 < len(s):
281
+ if s[self.i + 1] != "\n":
282
+ w.segs.append(("lit", s[self.i + 1], True))
283
+ self.i += 2
284
+ else:
285
+ self.i += 1
286
+ elif ch == "$":
287
+ self._dollar(w, quoted=False)
288
+ elif ch == "`":
289
+ self._backtick(w)
290
+ elif ch == "~" and first:
291
+ m = re.match(r"~[+-](?=$|[/\s:;&|)])|~[A-Za-z0-9_.-]*", s[self.i:])
292
+ tilde = m.group(0)
293
+ nxt = s[self.i + len(tilde):self.i + len(tilde) + 1]
294
+ if nxt in ("", "/", " ", "\t", "\n", ":", ";", "&", "|", ")"):
295
+ w.segs.append(("tilde", tilde, False))
296
+ else:
297
+ w.segs.append(("lit", tilde, False))
298
+ self.i += len(tilde)
299
+ else:
300
+ if ch in "*?[":
301
+ w.has_glob = True
302
+ if ch == "{":
303
+ w.has_brace = True
304
+ w.segs.append(("lit", ch, False))
305
+ self.i += 1
306
+ first = False
307
+ w.raw = s[start:self.i]
308
+ if w.has_brace and not re.search(r"\{[^{}]*(,|\.\.)[^{}]*\}", w.text()):
309
+ w.has_brace = False
310
+ return w
311
+
312
+ def _double(self, w: Word) -> None:
313
+ s = self.s
314
+ self.i += 1
315
+ buf = ""
316
+ while True:
317
+ if self.i >= len(s):
318
+ raise ShellSyntaxError("a double quote is not closed")
319
+ ch = s[self.i]
320
+ if ch == '"':
321
+ self.i += 1
322
+ break
323
+ if ch == "\\" and self.peek(1) in ('"', "\\", "$", "`", "\n"):
324
+ if self.peek(1) != "\n":
325
+ buf += self.peek(1)
326
+ self.i += 2
327
+ continue
328
+ if ch in "$`":
329
+ if buf:
330
+ w.segs.append(("lit", buf, True))
331
+ buf = ""
332
+ if ch == "$":
333
+ self._dollar(w, quoted=True)
334
+ else:
335
+ self._backtick(w)
336
+ continue
337
+ buf += ch
338
+ self.i += 1
339
+ w.segs.append(("lit", buf, True))
340
+
341
+ def _backtick(self, w: Word) -> None:
342
+ s = self.s
343
+ j = self.i + 1
344
+ inner = ""
345
+ while True:
346
+ if j >= len(s):
347
+ raise ShellSyntaxError("a backtick is not closed")
348
+ if s[j] == "\\" and j + 1 < len(s):
349
+ inner += s[j + 1]
350
+ j += 2
351
+ continue
352
+ if s[j] == "`":
353
+ break
354
+ inner += s[j]
355
+ j += 1
356
+ self.i = j + 1
357
+ self.out.subs.append(inner)
358
+ w.has_sub = True
359
+ w.segs.append(("sub", inner, False))
360
+
361
+ def _dollar(self, w: Word, quoted: bool) -> None:
362
+ s = self.s
363
+ nxt = self.peek(1)
364
+ w.has_dollar = True
365
+ if nxt == "(" and self.peek(2) == "(":
366
+ inner = self._balanced(self.i + 3, "(", ")")
367
+ # arithmetic: $(( ... )); the extra ")" closes it
368
+ if self.peek() == ")":
369
+ self.i += 1
370
+ for name in NAME.findall(inner):
371
+ self.out.vars.add(name)
372
+ w.segs.append(("special", "", quoted))
373
+ return
374
+ if nxt == "[":
375
+ # $[ ... ]: old bash arithmetic, a number like $(( ... ))
376
+ inner = self._balanced(self.i + 2, "[", "]")
377
+ for name in NAME.findall(inner):
378
+ self.out.vars.add(name)
379
+ w.segs.append(("special", "", quoted))
380
+ return
381
+ if nxt == "(":
382
+ inner = self._balanced(self.i + 2, "(", ")")
383
+ self.out.subs.append(inner)
384
+ w.has_sub = True
385
+ w.segs.append(("sub", inner, quoted))
386
+ return
387
+ if nxt == "{":
388
+ inner = self._balanced(self.i + 2, "{", "}")
389
+ m = re.match(r"([#!]?)([A-Za-z_][A-Za-z0-9_]*|[?#$!@*\-_0-9])(.*)", inner, re.S)
390
+ if not m:
391
+ raise ShellSyntaxError("a ${...} expansion is not understood")
392
+ mod, name, rest = m.group(1), m.group(2), m.group(3)
393
+ if name[0] in _SPECIAL or mod == "#":
394
+ # a special parameter, or a length (${#X}, ${#arr[@]}): text the guard does not
395
+ # know (special), never a variable's value
396
+ if name[0] not in _SPECIAL:
397
+ self.out.vars.add(name)
398
+ w.segs.append(("special", "", quoted))
399
+ if mod == "#":
400
+ return # a length: `[@]` and the like are part of it, not text
401
+ else:
402
+ self.out.vars.add(name)
403
+ # ${#X}, ${!X}, ${X:-y}, ${X%/}: a value the guard does not compute
404
+ w.segs.append(("varx" if mod or rest else "var", name, quoted))
405
+ if rest:
406
+ # ${VAR:-word} and the like: the word part may hold paths and expansions
407
+ sub = _Lexer(rest.lstrip(":-=?+#%/^,"))
408
+ try:
409
+ sub._scan_expansions_only()
410
+ except ShellSyntaxError:
411
+ pass
412
+ self.out.subs.extend(sub.out.subs)
413
+ self.out.vars |= sub.out.vars
414
+ w.segs.append(("lit", rest, True))
415
+ return
416
+ if nxt == "'" and not quoted:
417
+ # $'...' ANSI-C quoting: keep the text literally (escapes stay as written); a
418
+ # backslash escapes the next character, `\'` included
419
+ end = self.i + 2
420
+ while end < len(s) and s[end] != "'":
421
+ end += 2 if s[end] == "\\" else 1
422
+ if end >= len(s):
423
+ raise ShellSyntaxError("a $'...' quote is not closed")
424
+ w.segs.append(("ansi", s[self.i + 2:end], True))
425
+ self.i = end + 1
426
+ return
427
+ if nxt == '"' and not quoted:
428
+ self.i += 1
429
+ self._double(w)
430
+ return
431
+ m = NAME.match(s, self.i + 1)
432
+ if m and m.group(0) == "_":
433
+ w.segs.append(("special", "_", quoted)) # $_: the last word of the last command
434
+ self.i += 2
435
+ return
436
+ if m:
437
+ self.out.vars.add(m.group(0))
438
+ w.segs.append(("var", m.group(0), quoted))
439
+ self.i = m.end()
440
+ return
441
+ if nxt and nxt in _SPECIAL:
442
+ w.segs.append(("special", nxt, quoted))
443
+ self.i += 2
444
+ return
445
+ # a lone "$"
446
+ w.has_dollar = False
447
+ w.segs.append(("lit", "$", quoted))
448
+ self.i += 1
449
+
450
+ def _balanced(self, start: int, open_ch: str, close_ch: str) -> str:
451
+ """The text from `start` to the matching close character (quotes respected)."""
452
+ s = self.s
453
+ depth = 1
454
+ j = start
455
+ heredocs: List[Tuple[str, bool]] = []
456
+ while j < len(s):
457
+ ch = s[j]
458
+ if ch == "\\":
459
+ j += 2
460
+ continue
461
+ if ch == "<" and s.startswith("<<", j) and not s.startswith("<<<", j):
462
+ m = re.match(r"<<(-?)\s*(['\"]?)([A-Za-z0-9_.-]+)\2", s[j:])
463
+ if m:
464
+ heredocs.append((m.group(3), m.group(1) == "-"))
465
+ j += m.end()
466
+ continue
467
+ if ch == "\n" and heredocs:
468
+ # skip heredoc bodies: they are data, and may hold quotes and parentheses
469
+ j += 1
470
+ for delim, strip in heredocs:
471
+ while j < len(s):
472
+ end = s.find("\n", j)
473
+ end = len(s) if end < 0 else end
474
+ line = s[j:end]
475
+ j = end + 1
476
+ if (line.lstrip("\t") if strip else line) == delim:
477
+ break
478
+ heredocs = []
479
+ continue
480
+ if ch == "'" and open_ch == "(":
481
+ end = s.find("'", j + 1)
482
+ if end < 0:
483
+ raise ShellSyntaxError("a single quote is not closed")
484
+ j = end + 1
485
+ continue
486
+ if ch == '"':
487
+ k = j + 1
488
+ while k < len(s) and s[k] != '"':
489
+ k += 2 if s[k] == "\\" else 1
490
+ if k >= len(s):
491
+ raise ShellSyntaxError("a double quote is not closed")
492
+ j = k + 1
493
+ continue
494
+ if ch == open_ch:
495
+ depth += 1
496
+ elif ch == close_ch:
497
+ depth -= 1
498
+ if depth == 0:
499
+ self.i = j + 1
500
+ return s[start:j]
501
+ j += 1
502
+ raise ShellSyntaxError(f"a '{open_ch}' is not closed")
503
+
504
+