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 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())
@@ -0,0 +1,4 @@
1
+ """The core of Knarr: the guarded tool palette, limits, trace, write block,
2
+ login borrowing and site profiles. Site-agnostic: everything here works on any
3
+ site the user can open in a browser.
4
+ """