knarr 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- knarr/__init__.py +7 -0
- knarr/doctor.py +656 -0
- knarr/explorer/__init__.py +4 -0
- knarr/explorer/borrow.py +403 -0
- knarr/explorer/caps.py +379 -0
- knarr/explorer/explorer_tools.py +2509 -0
- knarr/explorer/files.py +24 -0
- knarr/explorer/human_demo.py +705 -0
- knarr/explorer/learned_controls.py +456 -0
- knarr/explorer/origin.py +63 -0
- knarr/explorer/profiles.py +404 -0
- knarr/explorer/redact.py +107 -0
- knarr/explorer/session.py +432 -0
- knarr/explorer/trace.py +240 -0
- knarr/explorer/write_block.py +872 -0
- knarr/mcp/__init__.py +4 -0
- knarr/mcp/__main__.py +6 -0
- knarr/mcp/limits.py +74 -0
- knarr/mcp/server.py +368 -0
- knarr/mcp/session.py +818 -0
- knarr/mcp/worker.py +128 -0
- knarr-0.1.0.dist-info/METADATA +296 -0
- knarr-0.1.0.dist-info/RECORD +28 -0
- knarr-0.1.0.dist-info/WHEEL +5 -0
- knarr-0.1.0.dist-info/entry_points.txt +3 -0
- knarr-0.1.0.dist-info/licenses/LICENSE +202 -0
- knarr-0.1.0.dist-info/licenses/NOTICE +4 -0
- knarr-0.1.0.dist-info/top_level.txt +1 -0
knarr/__init__.py
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
"""Knarr: an AI agent explores a website toward a goal with guarded browser tools.
|
|
2
|
+
|
|
3
|
+
``knarr.explorer`` is the core: the tool palette, the guards (URL boundary,
|
|
4
|
+
forbidden actions, write block), limits, trace, login borrowing and site profiles.
|
|
5
|
+
``knarr.mcp`` serves those tools to an MCP client such as Claude Code.
|
|
6
|
+
``knarr.doctor`` checks that everything can run on this machine.
|
|
7
|
+
"""
|
knarr/doctor.py
ADDED
|
@@ -0,0 +1,656 @@
|
|
|
1
|
+
"""``knarr-doctor``: check that Knarr can run here, and say how to fix what can't.
|
|
2
|
+
|
|
3
|
+
It checks, in order: the Python that runs it, the installed packages, your
|
|
4
|
+
``KNARR_*`` settings, your site profiles, the browser (it starts one, loads a
|
|
5
|
+
local test page that tries to write, and checks that the write block held the
|
|
6
|
+
write back), the Chrome you borrow a login from, and that the MCP server starts
|
|
7
|
+
and lists its tools. Nothing here opens a site, and no cookie value is read or printed.
|
|
8
|
+
|
|
9
|
+
uvx --from knarr knarr-doctor everything
|
|
10
|
+
uvx --from knarr knarr-doctor --quick settings, packages and Chrome only (no browser, no server)
|
|
11
|
+
|
|
12
|
+
Installed with pip, run it as ``knarr-doctor`` or ``python3 -m knarr.doctor``.
|
|
13
|
+
|
|
14
|
+
Exit status 1 if anything failed; warnings don't change it.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import asyncio
|
|
20
|
+
import difflib
|
|
21
|
+
import importlib.metadata
|
|
22
|
+
import json
|
|
23
|
+
import os
|
|
24
|
+
import platform
|
|
25
|
+
import re
|
|
26
|
+
import shutil
|
|
27
|
+
import signal
|
|
28
|
+
import sys
|
|
29
|
+
import tempfile
|
|
30
|
+
import threading
|
|
31
|
+
import time
|
|
32
|
+
from dataclasses import dataclass
|
|
33
|
+
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
|
34
|
+
from pathlib import Path
|
|
35
|
+
from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, TextIO, Tuple
|
|
36
|
+
|
|
37
|
+
MIN_PYTHON = (3, 12)
|
|
38
|
+
|
|
39
|
+
# Minimum versions of what the package needs (pyproject.toml is the source; a test keeps these equal).
|
|
40
|
+
REQUIRED: Dict[str, Tuple[Tuple[int, ...], Optional[Tuple[int, ...]]]] = {
|
|
41
|
+
"mcp": ((1, 13), (2,)), # (minimum, first version that is too new)
|
|
42
|
+
"playwright": ((1, 48), (2,)),
|
|
43
|
+
"pyyaml": ((6, 0), (7,)),
|
|
44
|
+
"websockets": ((12,), (16,)),
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
DIST_NAME = "knarr"
|
|
48
|
+
# The plugin starts the server with uvx, which fetches the package from PyPI on first use.
|
|
49
|
+
SERVER_COMMAND = f"uvx {DIST_NAME}"
|
|
50
|
+
DOCTOR_COMMAND = f"uvx --from {DIST_NAME} knarr-doctor"
|
|
51
|
+
# What fixes a missing or mismatched package: a fresh copy through uvx, or pip for a pip install.
|
|
52
|
+
INSTALL_COMMAND = f"uvx --refresh --from {DIST_NAME} knarr-doctor"
|
|
53
|
+
PIP_INSTALL_COMMAND = f"python3 -m pip install --upgrade {DIST_NAME}"
|
|
54
|
+
PACKAGE_FIX = f"{INSTALL_COMMAND}\n(installed with pip instead: {PIP_INSTALL_COMMAND})"
|
|
55
|
+
BROWSER_COMMAND = f"uvx --from {DIST_NAME} playwright install chromium"
|
|
56
|
+
|
|
57
|
+
RUNS_DIR_ENV = "KNARR_RUNS_DIR"
|
|
58
|
+
PROFILES_DIR_ENV = "KNARR_PROFILES_DIR" # the profiles module owns it; imported lazily, a test keeps them equal
|
|
59
|
+
KNOWN_SETTINGS = (
|
|
60
|
+
"KNARR_ALLOW_WRITES", "KNARR_BLOCK_WRITES", "KNARR_WRITE_ALLOW", "KNARR_RECORD_FIELDS",
|
|
61
|
+
"KNARR_CDP_URL", "KNARR_STORAGE_STATE", "KNARR_BROWSER_CHANNEL", "KNARR_NO_SANDBOX",
|
|
62
|
+
"KNARR_TRACE", RUNS_DIR_ENV, "KNARR_MAX_TURNS", "KNARR_MAX_WALL_CLOCK_SEC",
|
|
63
|
+
"KNARR_IDLE_TIMEOUT_SEC", PROFILES_DIR_ENV,
|
|
64
|
+
)
|
|
65
|
+
# Set by the tests that drive real browsers; not a setting for users.
|
|
66
|
+
TEST_ONLY_SETTINGS = ("KNARR_BROWSER_TESTS",)
|
|
67
|
+
|
|
68
|
+
BROWSER_TEST_SECONDS = 90
|
|
69
|
+
SERVER_TEST_SECONDS = 30
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
@dataclass
|
|
73
|
+
class Result:
|
|
74
|
+
status: str # "ok", "warn", "fail" or "info"
|
|
75
|
+
title: str
|
|
76
|
+
detail: str = ""
|
|
77
|
+
fix: str = ""
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def ok(title: str, detail: str = "") -> Result:
|
|
81
|
+
return Result("ok", title, detail)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def warn(title: str, detail: str = "", fix: str = "") -> Result:
|
|
85
|
+
return Result("warn", title, detail, fix)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def fail(title: str, detail: str = "", fix: str = "") -> Result:
|
|
89
|
+
return Result("fail", title, detail, fix)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def info(title: str, detail: str = "", fix: str = "") -> Result:
|
|
93
|
+
return Result("info", title, detail, fix)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def _version_tuple(text: str) -> Tuple[int, ...]:
|
|
97
|
+
parts: List[int] = []
|
|
98
|
+
for piece in text.split("."):
|
|
99
|
+
digits = ""
|
|
100
|
+
for ch in piece:
|
|
101
|
+
if not ch.isdigit():
|
|
102
|
+
break
|
|
103
|
+
digits += ch
|
|
104
|
+
if not digits:
|
|
105
|
+
break
|
|
106
|
+
parts.append(int(digits))
|
|
107
|
+
if digits != piece:
|
|
108
|
+
break
|
|
109
|
+
return tuple(parts)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
# -- python and packages ------------------------------------------------------------------------
|
|
113
|
+
|
|
114
|
+
def check_python(version: Sequence[int] = tuple(sys.version_info[:3]), executable: str = sys.executable,
|
|
115
|
+
uvx_path: Optional[str] = None) -> List[Result]:
|
|
116
|
+
results: List[Result] = []
|
|
117
|
+
shown = ".".join(str(v) for v in version[:3])
|
|
118
|
+
if tuple(version[:2]) < MIN_PYTHON:
|
|
119
|
+
results.append(fail(f"Python {shown} is too old", f"Knarr needs Python {'.'.join(map(str, MIN_PYTHON))} or newer.",
|
|
120
|
+
"Install a newer Python and install Knarr for it."))
|
|
121
|
+
else:
|
|
122
|
+
results.append(ok(f"Python {shown}", executable))
|
|
123
|
+
if uvx_path is None:
|
|
124
|
+
uvx_path = shutil.which("uvx")
|
|
125
|
+
if uvx_path:
|
|
126
|
+
results.append(ok("uvx", uvx_path))
|
|
127
|
+
else:
|
|
128
|
+
results.append(warn("No uvx on your PATH", f"The Claude Code plugin starts the server with `{SERVER_COMMAND}`.",
|
|
129
|
+
"Install uv (https://docs.astral.sh/uv/), or skip the plugin and add the server "
|
|
130
|
+
"for the Python that has Knarr: claude mcp add knarr -- python3 -m knarr.mcp"))
|
|
131
|
+
return results
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def _installed_versions() -> Dict[str, Optional[str]]:
|
|
135
|
+
found: Dict[str, Optional[str]] = {}
|
|
136
|
+
for name in REQUIRED:
|
|
137
|
+
try:
|
|
138
|
+
found[name] = importlib.metadata.version(name)
|
|
139
|
+
except importlib.metadata.PackageNotFoundError:
|
|
140
|
+
found[name] = None
|
|
141
|
+
return found
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def check_packages(versions: Optional[Mapping[str, Optional[str]]] = None) -> List[Result]:
|
|
145
|
+
versions = _installed_versions() if versions is None else versions
|
|
146
|
+
results: List[Result] = []
|
|
147
|
+
try:
|
|
148
|
+
own = importlib.metadata.version(DIST_NAME)
|
|
149
|
+
results.append(ok(f"{DIST_NAME} {own}"))
|
|
150
|
+
except importlib.metadata.PackageNotFoundError:
|
|
151
|
+
results.append(info(f"{DIST_NAME} is run from source, not installed",
|
|
152
|
+
"That is fine for development; the plugin runs the released package with uvx."))
|
|
153
|
+
for name, (minimum, too_new) in REQUIRED.items():
|
|
154
|
+
have = versions.get(name)
|
|
155
|
+
wanted = ".".join(map(str, minimum)) + (f" up to but not including {'.'.join(map(str, too_new))}" if too_new else " or newer")
|
|
156
|
+
if have is None:
|
|
157
|
+
results.append(fail(f"{name} is not installed", f"Needs {wanted}.", PACKAGE_FIX))
|
|
158
|
+
continue
|
|
159
|
+
parsed = _version_tuple(have)
|
|
160
|
+
if parsed < minimum or (too_new is not None and parsed >= too_new):
|
|
161
|
+
results.append(fail(f"{name} {have} doesn't fit", f"Needs {wanted}.", PACKAGE_FIX))
|
|
162
|
+
else:
|
|
163
|
+
results.append(ok(f"{name} {have}"))
|
|
164
|
+
return results
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
# -- settings -------------------------------------------------------------------------------------
|
|
168
|
+
|
|
169
|
+
def check_settings(env: Mapping[str, str]) -> List[Result]:
|
|
170
|
+
from knarr.explorer.write_block import WriteBlock, WritePolicy, parse_switch
|
|
171
|
+
|
|
172
|
+
results: List[Result] = []
|
|
173
|
+
known = set(KNOWN_SETTINGS) | set(TEST_ONLY_SETTINGS)
|
|
174
|
+
for name in sorted(k for k in env if k.startswith("KNARR_") and k not in known):
|
|
175
|
+
close = difflib.get_close_matches(name, KNOWN_SETTINGS, n=1, cutoff=0.7)
|
|
176
|
+
results.append(warn(f"{name} is not a Knarr setting", "It has no effect.",
|
|
177
|
+
f"Did you mean {close[0]}?" if close else "See the environment variables table in the README."))
|
|
178
|
+
|
|
179
|
+
def flag(name: str) -> bool:
|
|
180
|
+
return parse_switch(env.get(name)) is True
|
|
181
|
+
|
|
182
|
+
# A switch that nobody can read is off, except KNARR_BLOCK_WRITES, where it counts as on. Say so.
|
|
183
|
+
for name in ("KNARR_ALLOW_WRITES", "KNARR_BLOCK_WRITES", "KNARR_TRACE", "KNARR_NO_SANDBOX"):
|
|
184
|
+
raw = (env.get(name) or "").strip()
|
|
185
|
+
if parse_switch(raw) is None:
|
|
186
|
+
safe = name == "KNARR_BLOCK_WRITES"
|
|
187
|
+
results.append(warn(f"{name}={raw!r} is not understood, so " + ("writes are blocked" if safe else "it is off"),
|
|
188
|
+
"Say 1 or 0 (also true/false, yes/no, on/off).",
|
|
189
|
+
f"Set {name}=1" if safe else f"Set {name}=1 to turn it on."))
|
|
190
|
+
# The write policy, built the way the server builds it.
|
|
191
|
+
block = parse_switch(env.get("KNARR_BLOCK_WRITES")) is not False
|
|
192
|
+
allow = flag("KNARR_ALLOW_WRITES")
|
|
193
|
+
patterns = tuple(p.strip() for p in (env.get("KNARR_WRITE_ALLOW") or "").split(",") if p.strip())
|
|
194
|
+
try:
|
|
195
|
+
WriteBlock(WritePolicy(block=block or not allow, allow_patterns=patterns))
|
|
196
|
+
except ValueError as exc:
|
|
197
|
+
results.append(fail("KNARR_WRITE_ALLOW is not valid", str(exc), "Fix or unset KNARR_WRITE_ALLOW."))
|
|
198
|
+
patterns = ()
|
|
199
|
+
if allow and not block:
|
|
200
|
+
results.append(warn("Writes are ALLOWED (KNARR_ALLOW_WRITES)",
|
|
201
|
+
"Clicks act with your real permissions and can change data.",
|
|
202
|
+
"Unset KNARR_ALLOW_WRITES to block writes again."))
|
|
203
|
+
else:
|
|
204
|
+
note = f"; {len(patterns)} request pattern(s) in KNARR_WRITE_ALLOW are let through" if patterns else ""
|
|
205
|
+
results.append(ok("Writes are blocked" + (" (KNARR_BLOCK_WRITES wins over KNARR_ALLOW_WRITES)" if allow else ""), note.lstrip("; ")))
|
|
206
|
+
if flag("KNARR_TRACE"):
|
|
207
|
+
results.append(warn("KNARR_TRACE is on", "trace.zip holds page contents, typed text and cookies, so the session's login.",
|
|
208
|
+
"Unset it unless you are debugging, and delete the traces after."))
|
|
209
|
+
if flag("KNARR_NO_SANDBOX"):
|
|
210
|
+
results.append(warn("Chromium's sandbox is off (KNARR_NO_SANDBOX)",
|
|
211
|
+
"A page that exploits the browser then runs with your account's permissions.",
|
|
212
|
+
"Unset it unless you are in a container that can't run the sandbox."))
|
|
213
|
+
channel = (env.get("KNARR_BROWSER_CHANNEL") or "").strip()
|
|
214
|
+
results.append(info("Browser: " + (f"installed {channel}" if channel else "Playwright's Chromium"),
|
|
215
|
+
"" if channel else f"Set KNARR_BROWSER_CHANNEL=chrome to use the Chrome you have instead of `{BROWSER_COMMAND}`."))
|
|
216
|
+
state = (env.get("KNARR_STORAGE_STATE") or "").strip()
|
|
217
|
+
if state and not Path(state).expanduser().is_file():
|
|
218
|
+
results.append(fail("KNARR_STORAGE_STATE doesn't name a file", state,
|
|
219
|
+
"Point it at a Playwright storage-state file, or unset it."))
|
|
220
|
+
elif state:
|
|
221
|
+
results.append(ok("KNARR_STORAGE_STATE", "a saved login will be used"))
|
|
222
|
+
for name in ("KNARR_MAX_TURNS", "KNARR_MAX_WALL_CLOCK_SEC", "KNARR_IDLE_TIMEOUT_SEC"):
|
|
223
|
+
raw = (env.get(name) or "").strip()
|
|
224
|
+
if raw and not (raw.isascii() and raw.isdigit() and int(raw) > 0):
|
|
225
|
+
results.append(warn(f"{name}={raw!r} is not a positive whole number", "It is ignored; the default applies."))
|
|
226
|
+
results.append(_check_runs_dir(env))
|
|
227
|
+
return results
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
def _check_runs_dir(env: Mapping[str, str]) -> Result:
|
|
231
|
+
raw = (env.get(RUNS_DIR_ENV) or "").strip()
|
|
232
|
+
root = Path(raw).expanduser() if raw else Path.home() / ".knarr" / "runs"
|
|
233
|
+
try:
|
|
234
|
+
from knarr.explorer.files import make_private_dirs
|
|
235
|
+
|
|
236
|
+
make_private_dirs(root)
|
|
237
|
+
with tempfile.NamedTemporaryFile(dir=root):
|
|
238
|
+
pass
|
|
239
|
+
except OSError as exc:
|
|
240
|
+
return fail("Can't write the runs directory", f"{root}: {exc}", f"Set {RUNS_DIR_ENV} to a directory you can write.")
|
|
241
|
+
mode = root.stat().st_mode & 0o077
|
|
242
|
+
if mode:
|
|
243
|
+
return warn("The runs directory is readable by others", f"{root}: run output holds logged-in page content.",
|
|
244
|
+
f"chmod 700 {root}")
|
|
245
|
+
return ok("Runs directory", str(root))
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
# -- site profiles ------------------------------------------------------------------------------------
|
|
249
|
+
|
|
250
|
+
def _claude_rules(home: Path, cwd: Path) -> List[Tuple[Path, str]]:
|
|
251
|
+
"""The ask and deny rules in the Claude Code settings files that can be read here."""
|
|
252
|
+
found: List[Tuple[Path, str]] = []
|
|
253
|
+
for path in (home / ".claude" / "settings.json", home / ".claude" / "settings.local.json",
|
|
254
|
+
cwd / ".claude" / "settings.json", cwd / ".claude" / "settings.local.json"):
|
|
255
|
+
try:
|
|
256
|
+
permissions = json.loads(path.read_text(encoding="utf-8")).get("permissions") or {}
|
|
257
|
+
except (OSError, ValueError, AttributeError):
|
|
258
|
+
continue
|
|
259
|
+
for kind in ("ask", "deny"):
|
|
260
|
+
rules = permissions.get(kind) if isinstance(permissions, dict) else None
|
|
261
|
+
found.extend((path, rule) for rule in (rules if isinstance(rules, list) else []) if isinstance(rule, str))
|
|
262
|
+
return found
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
|
|
266
|
+
_RULE = re.compile(r"^\s*([A-Za-z_]+)\s*(?:\((.*)\))?\s*$", re.S)
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
def _rule_path(specifier: str, home: Path) -> Optional[str]:
|
|
270
|
+
"""The absolute path a Claude Code rule names, or None when it can't be told from here.
|
|
271
|
+
|
|
272
|
+
``~/x`` is under the home directory and ``//x`` is absolute. A path that is
|
|
273
|
+
relative (to the settings file or to the working directory) is not resolved:
|
|
274
|
+
the doctor can't tell which directory it means, so it doesn't count it.
|
|
275
|
+
"""
|
|
276
|
+
specifier = specifier.strip()
|
|
277
|
+
if specifier == "~" or specifier.startswith("~/"):
|
|
278
|
+
return str(home) + specifier[1:]
|
|
279
|
+
if specifier.startswith("//"):
|
|
280
|
+
return specifier[1:]
|
|
281
|
+
return None
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
def _glob_regex(pattern: str) -> "re.Pattern[str]":
|
|
285
|
+
"""A gitignore-style path pattern: ``*`` stays inside one directory, ``**`` crosses them."""
|
|
286
|
+
out, i = [], 0
|
|
287
|
+
while i < len(pattern):
|
|
288
|
+
if pattern.startswith("**/", i):
|
|
289
|
+
out.append("(?:.*/)?")
|
|
290
|
+
i += 3
|
|
291
|
+
elif pattern.startswith("**", i):
|
|
292
|
+
out.append(".*")
|
|
293
|
+
i += 2
|
|
294
|
+
elif pattern[i] == "*":
|
|
295
|
+
out.append("[^/]*")
|
|
296
|
+
i += 1
|
|
297
|
+
elif pattern[i] == "?":
|
|
298
|
+
out.append("[^/]")
|
|
299
|
+
i += 1
|
|
300
|
+
else:
|
|
301
|
+
out.append(re.escape(pattern[i]))
|
|
302
|
+
i += 1
|
|
303
|
+
return re.compile("".join(out) + r"\Z", re.S)
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
def _rule_covers(rule: str, directory: Path, home: Path) -> bool:
|
|
307
|
+
"""Whether ``rule`` (``Edit(~/.knarr/sites/**)``) is about editing files in ``directory``.
|
|
308
|
+
|
|
309
|
+
A rule for another tool (Read, Bash, WebFetch) or for another directory doesn't count,
|
|
310
|
+
however much of ``.knarr`` its text mentions.
|
|
311
|
+
"""
|
|
312
|
+
found = _RULE.match(rule)
|
|
313
|
+
if not found or found.group(1) not in EDIT_TOOLS:
|
|
314
|
+
return False
|
|
315
|
+
specifier = found.group(2)
|
|
316
|
+
if specifier is None or not specifier.strip():
|
|
317
|
+
return True # the whole tool: every edit asks, or is refused
|
|
318
|
+
path = _rule_path(specifier, home)
|
|
319
|
+
if path is None:
|
|
320
|
+
return False
|
|
321
|
+
regex = _glob_regex(path.rstrip("/") or "/")
|
|
322
|
+
# Both spellings the profile loader reads; a rule for *.yaml alone leaves .yml files open.
|
|
323
|
+
# A pattern for a parent directory covers the file too, so the parents are tried as well.
|
|
324
|
+
for suffix in (".yaml", ".yml"):
|
|
325
|
+
names = set()
|
|
326
|
+
for base in {os.path.abspath(directory), os.path.realpath(directory)}:
|
|
327
|
+
probe = Path(base) / f"profile{suffix}"
|
|
328
|
+
names |= {str(probe), *(str(parent) for parent in probe.parents)}
|
|
329
|
+
if not any(regex.match(name) for name in names):
|
|
330
|
+
return False
|
|
331
|
+
return True
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
def _suggested_rule(directory: Path, home: Path) -> str:
|
|
335
|
+
try:
|
|
336
|
+
relative = Path(os.path.abspath(directory)).relative_to(home)
|
|
337
|
+
except ValueError:
|
|
338
|
+
return "an Edit rule that covers that directory"
|
|
339
|
+
return f"Edit(~/{relative.as_posix()}/**)"
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
def check_profiles(env: Mapping[str, str], home: Optional[Path] = None, cwd: Optional[Path] = None) -> List[Result]:
|
|
343
|
+
"""Parse the site profiles, and say whether anything keeps the model from editing them."""
|
|
344
|
+
try:
|
|
345
|
+
from knarr.explorer import profiles
|
|
346
|
+
except Exception as exc: # most likely PyYAML is missing; the packages check says so
|
|
347
|
+
return [info("Skipped: the profile code can't be loaded", f"{type(exc).__name__}: {exc}")]
|
|
348
|
+
home = home or Path.home()
|
|
349
|
+
directory = profiles.profiles_dir(env)
|
|
350
|
+
if not directory.exists():
|
|
351
|
+
return [info("No site profiles", f"{directory} doesn't exist.",
|
|
352
|
+
"A profile there lets a site's POST reads through, or sets its limits, without restarting "
|
|
353
|
+
"the server; see the README, 'Site profiles'.")]
|
|
354
|
+
loaded, problems = profiles.load_profiles(directory)
|
|
355
|
+
results: List[Result] = [warn("A site profile is ignored", problem,
|
|
356
|
+
"Fix it; until then it doesn't apply, and writes stay blocked for that site.")
|
|
357
|
+
for problem in problems]
|
|
358
|
+
for origin, found in sorted(profiles.ambiguous_origins(loaded).items()):
|
|
359
|
+
results.append(warn("Two site profiles name the same origin",
|
|
360
|
+
f"{', '.join(p.path.name for p in found)}: {origin}; neither applies.",
|
|
361
|
+
"Remove the origin from one of them."))
|
|
362
|
+
for profile in loaded:
|
|
363
|
+
detail = f"{profile.path.name}: {', '.join(profile.origins)}; {profile.describe_changes()}"
|
|
364
|
+
if profile.live:
|
|
365
|
+
results.append(warn(f"Site profile {profile.name!r} lets every write through", detail,
|
|
366
|
+
"Remove 'writes: live' to block writes again."))
|
|
367
|
+
else:
|
|
368
|
+
results.append(ok(f"Site profile {profile.name!r}", detail))
|
|
369
|
+
if not loaded and not problems:
|
|
370
|
+
results.append(info("No site profiles", f"{directory} holds none."))
|
|
371
|
+
rules = _claude_rules(home, cwd or Path.cwd())
|
|
372
|
+
covering = [(path, rule) for path, rule in rules if _rule_covers(rule, directory, home)]
|
|
373
|
+
if covering:
|
|
374
|
+
results.append(ok("Claude Code is set to ask or refuse edits to your site profiles",
|
|
375
|
+
f"{covering[0][1]} in {covering[0][0]}"))
|
|
376
|
+
else:
|
|
377
|
+
near = [rule for _, rule in rules if ".knarr" in rule or str(directory) in rule]
|
|
378
|
+
results.append(warn(
|
|
379
|
+
"Nothing makes Claude Code ask before editing your site profiles",
|
|
380
|
+
f"A model that can write files could widen its own policy in {directory} before the next session."
|
|
381
|
+
+ (f" A rule mentions it ({near[0]}) but is not an ask or deny rule for editing files there."
|
|
382
|
+
if near else ""),
|
|
383
|
+
f"Add an ask or deny rule for edits to that directory to your Claude Code permissions "
|
|
384
|
+
f"(for example {_suggested_rule(directory, home)} in ~/.claude/settings.json), and confirm it with "
|
|
385
|
+
"/permissions. Only rules written as ~/path or //path are recognised here. "
|
|
386
|
+
"A shell command may still be able to write there."))
|
|
387
|
+
return results
|
|
388
|
+
|
|
389
|
+
|
|
390
|
+
# -- Chrome you borrow a login from ---------------------------------------------------------------------
|
|
391
|
+
|
|
392
|
+
def chrome_launch_command(system: Optional[str] = None) -> str:
|
|
393
|
+
system = system or platform.system()
|
|
394
|
+
binary = {"Darwin": '"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"',
|
|
395
|
+
"Linux": "google-chrome"}.get(system, "chrome")
|
|
396
|
+
return (f'{binary} --remote-debugging-port=9222 --user-data-dir="$HOME/.knarr-chrome"')
|
|
397
|
+
|
|
398
|
+
|
|
399
|
+
def check_devtools(env: Mapping[str, str]) -> List[Result]:
|
|
400
|
+
from knarr.explorer import borrow
|
|
401
|
+
|
|
402
|
+
url = (env.get("KNARR_CDP_URL") or "").strip()
|
|
403
|
+
results: List[Result] = []
|
|
404
|
+
launch = ("Start Chrome with a debugging port and a separate profile, log in to the site there and keep a tab open on it:\n"
|
|
405
|
+
f" {chrome_launch_command()}\n export KNARR_CDP_URL=http://127.0.0.1:9222\n"
|
|
406
|
+
"(Chrome 136 and later ignore the debugging port on your normal profile, hence the separate one.)")
|
|
407
|
+
if not url:
|
|
408
|
+
try:
|
|
409
|
+
borrow._get_json("http://127.0.0.1:9222", "/json/version", timeout=1)
|
|
410
|
+
results.append(info("A Chrome with a debugging port answers on http://127.0.0.1:9222",
|
|
411
|
+
"KNARR_CDP_URL isn't set, so sessions start logged out.",
|
|
412
|
+
"export KNARR_CDP_URL=http://127.0.0.1:9222 to borrow its login."))
|
|
413
|
+
except borrow.BorrowError:
|
|
414
|
+
results.append(info("KNARR_CDP_URL isn't set: sessions start logged out",
|
|
415
|
+
"Borrowing your login from a Chrome is optional (KNARR_STORAGE_STATE is the other way).", launch))
|
|
416
|
+
return results
|
|
417
|
+
try:
|
|
418
|
+
base = borrow._http_base(url)
|
|
419
|
+
except borrow.BorrowError as exc:
|
|
420
|
+
return [fail("KNARR_CDP_URL isn't valid", str(exc),
|
|
421
|
+
"Use http://127.0.0.1:9222 (or the ws:// address Chrome prints). It must be on this machine.")]
|
|
422
|
+
try:
|
|
423
|
+
version = borrow._get_json(base, "/json/version", timeout=5)
|
|
424
|
+
except borrow.BorrowError as exc:
|
|
425
|
+
return [fail("Can't reach your Chrome", str(exc), launch)]
|
|
426
|
+
results.append(ok(f"Chrome answers at {base}", str(version.get("Browser", "unknown version"))))
|
|
427
|
+
try:
|
|
428
|
+
tabs = [t for t in borrow._get_json(base, "/json/list", timeout=5) if t.get("type") == "page"]
|
|
429
|
+
results.append(ok(f"{len(tabs)} tab(s) open", "localStorage is read from a tab you have open on the site"))
|
|
430
|
+
except borrow.BorrowError as exc:
|
|
431
|
+
results.append(warn("Couldn't list the tabs", str(exc)))
|
|
432
|
+
try:
|
|
433
|
+
answer = borrow._call(version["webSocketDebuggerUrl"], "Storage.getCookies", {}, timeout=5)
|
|
434
|
+
if answer is None or "result" not in answer:
|
|
435
|
+
results.append(fail("Chrome didn't answer the cookie request", "", launch))
|
|
436
|
+
else:
|
|
437
|
+
results.append(ok("Chrome gives up its cookies over DevTools", f"{len(answer['result'].get('cookies', []))} in total; none are printed"))
|
|
438
|
+
except Exception as exc: # a refused or closed websocket
|
|
439
|
+
results.append(fail("The DevTools connection failed", f"{type(exc).__name__}: {exc}",
|
|
440
|
+
"Start Chrome with --remote-debugging-port, and no other tool holding it."))
|
|
441
|
+
return results
|
|
442
|
+
|
|
443
|
+
|
|
444
|
+
# -- the browser and the write block ---------------------------------------------------------------------
|
|
445
|
+
|
|
446
|
+
class _ProbeServer:
|
|
447
|
+
"""A local page that reads, then tries to write; records what reaches it."""
|
|
448
|
+
|
|
449
|
+
PAGE = ("<!doctype html><title>Knarr doctor</title><h1>Knarr doctor</h1><script>"
|
|
450
|
+
"fetch('/read').then(() => fetch('/write', {method: 'POST', body: 'x=1'}))"
|
|
451
|
+
".then(() => { window.__probed = true; });</script>")
|
|
452
|
+
|
|
453
|
+
def __init__(self) -> None:
|
|
454
|
+
self.hits: List[Tuple[str, str]] = []
|
|
455
|
+
outer = self
|
|
456
|
+
|
|
457
|
+
class Handler(BaseHTTPRequestHandler):
|
|
458
|
+
def _answer(self) -> None:
|
|
459
|
+
outer.hits.append((self.command, self.path))
|
|
460
|
+
length = int(self.headers.get("Content-Length") or 0)
|
|
461
|
+
if length:
|
|
462
|
+
self.rfile.read(length)
|
|
463
|
+
body = (outer.PAGE if self.path == "/" else "{}").encode()
|
|
464
|
+
self.send_response(200)
|
|
465
|
+
self.send_header("Content-Type", "text/html" if self.path == "/" else "application/json")
|
|
466
|
+
self.send_header("Content-Length", str(len(body)))
|
|
467
|
+
self.end_headers()
|
|
468
|
+
self.wfile.write(body)
|
|
469
|
+
|
|
470
|
+
do_GET = do_POST = _answer
|
|
471
|
+
|
|
472
|
+
def log_message(self, *args: Any) -> None:
|
|
473
|
+
pass
|
|
474
|
+
|
|
475
|
+
self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
|
|
476
|
+
self.url = f"http://127.0.0.1:{self._server.server_port}/"
|
|
477
|
+
threading.Thread(target=self._server.serve_forever, daemon=True).start()
|
|
478
|
+
|
|
479
|
+
def close(self) -> None:
|
|
480
|
+
self._server.shutdown()
|
|
481
|
+
self._server.server_close()
|
|
482
|
+
|
|
483
|
+
@property
|
|
484
|
+
def writes(self) -> List[Tuple[str, str]]:
|
|
485
|
+
return [h for h in self.hits if h[0] != "GET"]
|
|
486
|
+
|
|
487
|
+
|
|
488
|
+
def _explain_browser_failure(exc: BaseException, channel: Optional[str]) -> Result:
|
|
489
|
+
text = str(exc)
|
|
490
|
+
first = next((line for line in text.splitlines() if line.strip()), type(exc).__name__)
|
|
491
|
+
low = text.lower()
|
|
492
|
+
if "executable doesn't exist" in low or "playwright install" in low or ("distribution" in low and "is not found" in low):
|
|
493
|
+
if channel:
|
|
494
|
+
return fail(f"The browser {channel!r} isn't installed", first,
|
|
495
|
+
f"Install it, or unset KNARR_BROWSER_CHANNEL and run `{BROWSER_COMMAND}`.")
|
|
496
|
+
return fail("Playwright's Chromium isn't installed", first,
|
|
497
|
+
f"{BROWSER_COMMAND} (or set KNARR_BROWSER_CHANNEL=chrome to use the Chrome you have)")
|
|
498
|
+
if "sandbox" in low or "has been closed" in low:
|
|
499
|
+
return fail("The browser started and stopped at once", first,
|
|
500
|
+
"If Chromium's sandbox can't run here (a container, or another sandbox), set KNARR_NO_SANDBOX=1.")
|
|
501
|
+
return fail("The browser couldn't start or load the test page", first)
|
|
502
|
+
|
|
503
|
+
|
|
504
|
+
class _Timeout(Exception):
|
|
505
|
+
pass
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
def check_browser(env: Mapping[str, str],
|
|
509
|
+
session: Optional[Callable[..., Any]] = None) -> List[Result]:
|
|
510
|
+
"""Start the browser the way a session does, with the write block on, and load a page that writes."""
|
|
511
|
+
from knarr.explorer.write_block import WriteBlock, WritePolicy
|
|
512
|
+
|
|
513
|
+
if session is None:
|
|
514
|
+
from knarr.explorer.session import plain_session as session
|
|
515
|
+
channel = (env.get("KNARR_BROWSER_CHANNEL") or "").strip() or None
|
|
516
|
+
server = _ProbeServer()
|
|
517
|
+
block = WriteBlock(WritePolicy(block=True))
|
|
518
|
+
started = time.monotonic()
|
|
519
|
+
use_alarm = hasattr(signal, "SIGALRM") and threading.current_thread() is threading.main_thread()
|
|
520
|
+
if use_alarm:
|
|
521
|
+
def on_alarm(signum: int, frame: Any) -> None:
|
|
522
|
+
raise _Timeout()
|
|
523
|
+
|
|
524
|
+
previous = signal.signal(signal.SIGALRM, on_alarm)
|
|
525
|
+
signal.alarm(BROWSER_TEST_SECONDS)
|
|
526
|
+
try:
|
|
527
|
+
with session(server.url, channel=channel, write_block=block) as s:
|
|
528
|
+
version = s.context.browser.version
|
|
529
|
+
s.page.wait_for_function("window.__probed === true", timeout=15000)
|
|
530
|
+
s.page.wait_for_timeout(300)
|
|
531
|
+
except _Timeout:
|
|
532
|
+
return [fail("The browser test timed out", f"No result after {BROWSER_TEST_SECONDS} s.",
|
|
533
|
+
"Run it again; if it hangs, try KNARR_BROWSER_CHANNEL=chrome.")]
|
|
534
|
+
except Exception as exc:
|
|
535
|
+
return [_explain_browser_failure(exc, channel)]
|
|
536
|
+
finally:
|
|
537
|
+
if use_alarm:
|
|
538
|
+
signal.alarm(0)
|
|
539
|
+
signal.signal(signal.SIGALRM, previous)
|
|
540
|
+
server.close()
|
|
541
|
+
took = time.monotonic() - started
|
|
542
|
+
results = [ok(f"Browser starts: {'installed ' + channel if channel else 'Chromium'} {version}", f"{took:.1f} s with the sandbox on")]
|
|
543
|
+
summary = block.summary()
|
|
544
|
+
if server.writes:
|
|
545
|
+
results.append(fail("The write block let a write through",
|
|
546
|
+
f"The test page's POST reached the local server: {server.writes}",
|
|
547
|
+
"Don't use Knarr on a real site until this passes. Update Playwright and the browser, and run this again."))
|
|
548
|
+
elif summary["blocked_writes"] != 1:
|
|
549
|
+
results.append(fail("The write block didn't see the test page's POST",
|
|
550
|
+
f"blocked_writes={summary['blocked_writes']}", "Update Playwright and the browser, and run this again."))
|
|
551
|
+
else:
|
|
552
|
+
results.append(ok("Write block self-test", "a page's POST was held back, its GET went through"))
|
|
553
|
+
if ("GET", "/read") not in server.hits:
|
|
554
|
+
results.append(fail("The write block stopped a plain GET", str(server.hits)))
|
|
555
|
+
return results
|
|
556
|
+
|
|
557
|
+
|
|
558
|
+
# -- the MCP server ----------------------------------------------------------------------------------------
|
|
559
|
+
|
|
560
|
+
async def _server_tools() -> List[str]:
|
|
561
|
+
from mcp import ClientSession, StdioServerParameters
|
|
562
|
+
from mcp.client.stdio import stdio_client
|
|
563
|
+
|
|
564
|
+
params = StdioServerParameters(command=sys.executable, args=["-m", "knarr.mcp"], env=dict(os.environ))
|
|
565
|
+
async with stdio_client(params) as (read, write):
|
|
566
|
+
async with ClientSession(read, write) as client:
|
|
567
|
+
await client.initialize()
|
|
568
|
+
return sorted(tool.name for tool in (await client.list_tools()).tools)
|
|
569
|
+
|
|
570
|
+
|
|
571
|
+
def check_server(list_tools: Optional[Callable[[], Any]] = None) -> List[Result]:
|
|
572
|
+
list_tools = list_tools or _server_tools
|
|
573
|
+
try:
|
|
574
|
+
names = asyncio.run(asyncio.wait_for(list_tools(), SERVER_TEST_SECONDS))
|
|
575
|
+
except asyncio.TimeoutError:
|
|
576
|
+
return [fail("The MCP server didn't answer", f"No tool list after {SERVER_TEST_SECONDS} s.",
|
|
577
|
+
f"Run `{_server_by_hand()}` by hand and read what it prints on stderr.")]
|
|
578
|
+
except Exception as exc:
|
|
579
|
+
return [fail("The MCP server won't start", f"{type(exc).__name__}: {exc}",
|
|
580
|
+
f"Run `{_server_by_hand()}` by hand and read what it prints on stderr.")]
|
|
581
|
+
needed = {"session_start", "session_end", "read_page", "click_index", "assert_state"}
|
|
582
|
+
missing = needed - set(names)
|
|
583
|
+
if missing:
|
|
584
|
+
return [fail("The MCP server is missing tools", f"Missing: {sorted(missing)}", PACKAGE_FIX)]
|
|
585
|
+
return [ok(f"MCP server starts and lists {len(names)} tools", f"{_server_by_hand()} over stdio")]
|
|
586
|
+
|
|
587
|
+
|
|
588
|
+
def _server_by_hand() -> str:
|
|
589
|
+
"""The command that starts the same server this check started: the Python running the doctor."""
|
|
590
|
+
return f"{sys.executable} -m knarr.mcp"
|
|
591
|
+
|
|
592
|
+
|
|
593
|
+
# -- running them -----------------------------------------------------------------------------------------
|
|
594
|
+
|
|
595
|
+
SYMBOLS = {"ok": "ok ", "warn": "WARN", "fail": "FAIL", "info": "info"}
|
|
596
|
+
|
|
597
|
+
|
|
598
|
+
def run_checks(env: Mapping[str, str], *, quick: bool = False) -> List[Tuple[str, List[Result]]]:
|
|
599
|
+
sections: List[Tuple[str, List[Result]]] = [
|
|
600
|
+
("Python and uv", check_python()),
|
|
601
|
+
("Packages", check_packages()),
|
|
602
|
+
("Settings", check_settings(env)),
|
|
603
|
+
("Site profiles", check_profiles(env)),
|
|
604
|
+
("Chrome login", check_devtools(env)),
|
|
605
|
+
]
|
|
606
|
+
packages_ok = all(r.status != "fail" for _, rs in sections[:2] for r in rs)
|
|
607
|
+
if quick:
|
|
608
|
+
return sections
|
|
609
|
+
if not packages_ok:
|
|
610
|
+
sections.append(("Browser and write block", [info("Skipped: fix the packages first")]))
|
|
611
|
+
sections.append(("MCP server", [info("Skipped: fix the packages first")]))
|
|
612
|
+
return sections
|
|
613
|
+
sections.append(("Browser and write block", check_browser(env)))
|
|
614
|
+
sections.append(("MCP server", check_server()))
|
|
615
|
+
return sections
|
|
616
|
+
|
|
617
|
+
|
|
618
|
+
def render(sections: List[Tuple[str, List[Result]]]) -> str:
|
|
619
|
+
lines: List[str] = []
|
|
620
|
+
counts = {"ok": 0, "warn": 0, "fail": 0, "info": 0}
|
|
621
|
+
for title, results in sections:
|
|
622
|
+
lines.append(f"{title}")
|
|
623
|
+
for r in results:
|
|
624
|
+
counts[r.status] += 1
|
|
625
|
+
lines.append(f" {SYMBOLS[r.status]} {r.title}" + (f" - {r.detail}" if r.detail and "\n" not in r.detail else ""))
|
|
626
|
+
if r.detail and "\n" in r.detail:
|
|
627
|
+
lines.extend(f" {line}" for line in r.detail.splitlines())
|
|
628
|
+
if r.fix:
|
|
629
|
+
head, *rest = r.fix.splitlines()
|
|
630
|
+
lines.append(f" fix: {head}")
|
|
631
|
+
lines.extend(f" {line}" for line in rest)
|
|
632
|
+
lines.append("")
|
|
633
|
+
verdict = ("Everything Knarr needs works here." if not counts["fail"] and not counts["warn"] else
|
|
634
|
+
"Knarr can run here; read the warnings." if not counts["fail"] else
|
|
635
|
+
"Knarr can't run here yet: fix the FAIL lines above and run this again.")
|
|
636
|
+
lines.append(f"{counts['ok']} ok, {counts['warn']} warning(s), {counts['fail']} failure(s). {verdict}")
|
|
637
|
+
return "\n".join(lines)
|
|
638
|
+
|
|
639
|
+
|
|
640
|
+
def main(argv: Optional[Sequence[str]] = None, env: Optional[Mapping[str, str]] = None, out: Optional[TextIO] = None) -> int:
|
|
641
|
+
args = list(sys.argv[1:] if argv is None else argv)
|
|
642
|
+
out = out or sys.stdout
|
|
643
|
+
if any(a in ("-h", "--help") for a in args):
|
|
644
|
+
out.write(__doc__ or "")
|
|
645
|
+
return 0
|
|
646
|
+
unknown = [a for a in args if a != "--quick"]
|
|
647
|
+
if unknown:
|
|
648
|
+
out.write(f"Unknown option(s): {' '.join(unknown)}. Use --quick or nothing.\n")
|
|
649
|
+
return 2
|
|
650
|
+
sections = run_checks(os.environ if env is None else env, quick="--quick" in args)
|
|
651
|
+
out.write(render(sections) + "\n")
|
|
652
|
+
return 1 if any(r.status == "fail" for _, rs in sections for r in rs) else 0
|
|
653
|
+
|
|
654
|
+
|
|
655
|
+
if __name__ == "__main__":
|
|
656
|
+
sys.exit(main())
|