keywright 0.0.1__py3-none-any.whl

keywright/setup/claude_code.py

@@ -0,0 +1,176 @@
+"""`kw setup claude-code`: the hazard hook, the session hook, per-subcommand permission rules,
+the skill, and (optionally) the MCP registration, in ~/.claude/settings.json and ~/.claude.json."""
+
+from __future__ import annotations
+
+import json
+import shlex
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from .. import __version__
+from .common import (
+    Changes,
+    binary_path,
+    claude_dir,
+    drop_rules,
+    ensure_rules,
+    read_json,
+    remove_hooks,
+    set_hook,
+)
+
+# Subcommands an agent may run unprompted. `ping` belongs here precisely because it is what an
+# agent reaches for when nobody is at the keyboard: a permission prompt on it would block on the
+# person it exists to go and fetch. It authorizes nothing and the broker rate-limits it.
+OPERATIONAL = ("run", "put", "get", "capture", "request", "status", "resources", "tools", "tool", "guide",
+               "guides", "ping", "session", "version", "hazards")
+MCP_NAMES = ("gatekeeper", "keywright")
+LEGACY_HOOK_FILE = "hooks/gatekeeper-hazards.py"
+
+
+def allow_rules() -> list[str]:
+    return [f"Bash({name} {sub} *)" for name in ("kw", "keywright") for sub in OPERATIONAL] + \
+           [f"Bash({name} {sub})" for name in ("kw", "keywright") for sub in OPERATIONAL]
+
+
+def _is_our_rule(rule: str) -> bool:
+    return rule.startswith(("Bash(kw ", "Bash(keywright ")) or rule in (f"mcp__{n}__*" for n in MCP_NAMES)
+
+
+def skill_text() -> str:
+    return (Path(__file__).resolve().parent.parent / "skill" / "SKILL.md").read_text()
+
+
+def apply(*, mcp: str = "keep", url: str | None = None, token: str | None = None, dry_run: bool = False,
+          bash_timeout: bool = True, out=None) -> int:
+    """mcp: keep (leave any MCP registration alone) | user (register at user scope via `claude mcp add`)
+    | remove (drop every gatekeeper/keywright MCP entry and its blanket allow rule)."""
+    import sys
+
+    out = out or sys.stdout
+    ch = Changes(dry_run)
+    home = claude_dir()
+    settings_path = home / "settings.json"
+    settings = read_json(settings_path)
+    kw = binary_path()
+
+    set_hook(settings, "PreToolUse", "Bash", f"{shlex.quote(kw)} hazards --hook", timeout=10,
+             status="Keywright hazard check")
+    set_hook(settings, "SessionStart", None, f"{shlex.quote(kw)} session-start --hook", timeout=10)
+    ensure_rules(settings, "allow", allow_rules())
+    if bash_timeout:
+        env = settings.setdefault("env", {})
+        if "BASH_DEFAULT_TIMEOUT_MS" not in env:
+            env["BASH_DEFAULT_TIMEOUT_MS"] = "600000"
+        # Claude Code caps a Bash call at 10 minutes; a longer approval wait would push the call into
+        # the background. Keep kw's default wait inside that cap, leaving room for the command itself.
+        if "KW_WAIT" not in env:
+            env["KW_WAIT"] = "540"
+    if mcp == "remove":
+        drop_rules(settings, "allow", lambda r: r in (f"mcp__{n}__*" for n in MCP_NAMES))
+    ch.edit_json(settings_path, settings)
+
+    legacy = home / LEGACY_HOOK_FILE
+    if legacy.exists():
+        ch.note(f"remove the copied hook file {legacy} (the hook now runs `{kw} hazards --hook`)")
+        if not dry_run:
+            legacy.unlink()
+
+    skill_path = home / "skills" / "keywright" / "SKILL.md"
+    ch.edit_text(skill_path, skill_text())
+
+    claude_json = Path.home() / ".claude.json"
+    if mcp == "remove":
+        data = read_json(claude_json)
+        removed = 0
+        for proj in (data.get("projects") or {}).values():
+            servers = proj.get("mcpServers") if isinstance(proj, dict) else None
+            for name in MCP_NAMES:
+                if servers and name in servers:
+                    del servers[name]
+                    removed += 1
+        top = data.get("mcpServers") or {}
+        for name in MCP_NAMES:
+            if name in top:
+                del top[name]
+                removed += 1
+        if removed:
+            ch.note(f"drop {removed} MCP registration(s) from {claude_json}")
+            ch.edit_json(claude_json, data)
+    elif mcp == "user":
+        if not (url and token):
+            raise SystemExit("--mcp user needs a profile (run `kw login` first)")
+        cmd = ["claude", "mcp", "add", "--scope", "user", "--transport", "http", "keywright", url,
+               "--header", f"Authorization: Bearer {token}"]
+        ch.note("run: claude mcp add --scope user --transport http keywright <url> --header 'Authorization: Bearer …'")
+        if not dry_run:
+            subprocess.run(cmd, check=False)
+    n = ch.apply(out)
+    out.write(f"keywright {__version__}: Claude Code setup {'previewed' if dry_run else 'applied'} "
+              f"({n} file(s) changed). Open /hooks once or start a new session to load it.\n")
+    return 0
+
+
+def uninstall(*, keep_config: bool = True, dry_run: bool = False, out=None) -> int:
+    import sys
+
+    out = out or sys.stdout
+    ch = Changes(dry_run)
+    home = claude_dir()
+    settings_path = home / "settings.json"
+    settings = read_json(settings_path)
+    remove_hooks(settings)
+    drop_rules(settings, "allow", _is_our_rule)
+    env = settings.get("env") or {}
+    env.pop("BASH_DEFAULT_TIMEOUT_MS", None)
+    env.pop("KW_WAIT", None)
+    if not env and "env" in settings:
+        del settings["env"]
+    ch.edit_json(settings_path, settings)
+    skill = home / "skills" / "keywright" / "SKILL.md"
+    if skill.exists():
+        ch.note(f"remove {skill}")
+        if not dry_run:
+            skill.unlink()
+    ch.apply(out)
+    return 0
+
+
+def describe(settings: dict[str, Any]) -> dict[str, Any]:
+    """What `kw setup check` reports about a settings document."""
+    from .common import find_hooks
+
+    allow = (settings.get("permissions") or {}).get("allow") or []
+    return {
+        "hooks": find_hooks(settings),
+        "allow_rules": [r for r in allow if _is_our_rule(r)],
+        "bash_timeout": (settings.get("env") or {}).get("BASH_DEFAULT_TIMEOUT_MS"),
+        "kw_wait": (settings.get("env") or {}).get("KW_WAIT"),
+    }
+
+
+def skill_version(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    for line in path.read_text().splitlines()[:8]:
+        if line.startswith("keywright-version:"):
+            return line.split(":", 1)[1].strip()
+    return "unknown"
+
+
+def mcp_registrations() -> list[str]:
+    data = read_json(Path.home() / ".claude.json")
+    found = []
+    for name in MCP_NAMES:
+        if name in (data.get("mcpServers") or {}):
+            found.append(f"user:{name}")
+        for proj, cfg in (data.get("projects") or {}).items():
+            if isinstance(cfg, dict) and name in (cfg.get("mcpServers") or {}):
+                found.append(f"{proj}:{name}")
+    return found
+
+
+def as_json(data: Any) -> str:
+    return json.dumps(data, indent=2)

keywright/setup/codex.py

@@ -0,0 +1,62 @@
+"""`kw setup codex`: teach Codex the CLI through a marked section in ~/.codex/AGENTS.md; MCP
+registration only on request (Codex has MCP, the CLI is simply the better fit for long approvals)."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from .claude_code import skill_text
+from .common import Changes
+
+BEGIN = "<!-- keywright:begin -->"
+END = "<!-- keywright:end -->"
+
+
+def codex_home() -> Path:
+    return Path(os.environ.get("CODEX_HOME") or str(Path.home() / ".codex"))
+
+
+def _section() -> str:
+    body = skill_text().split("---", 2)[-1].strip()
+    return f"{BEGIN}\n{body}\n{END}\n"
+
+
+def apply(*, mcp: str = "none", url: str | None = None, dry_run: bool = False, out=None) -> int:
+    out = out or sys.stdout
+    ch = Changes(dry_run)
+    path = codex_home() / "AGENTS.md"
+    text = path.read_text() if path.exists() else ""
+    if BEGIN in text and END in text:
+        head, _, tail = text.partition(BEGIN)
+        _, _, tail = tail.partition(END)
+        text = head + _section() + tail.lstrip("\n")
+    else:
+        text = (text.rstrip("\n") + "\n\n" if text.strip() else "") + _section()
+    ch.edit_text(path, text)
+    if mcp == "keep":
+        if not url:
+            raise SystemExit("--mcp keep needs a profile (run `kw login` first)")
+        ch.note("run: codex mcp add keywright --url <url> --bearer-token-env-var KEYWRIGHT_TOKEN "
+                "(export KEYWRIGHT_TOKEN in the shell that starts Codex)")
+        if not dry_run:
+            subprocess.run(["codex", "mcp", "add", "keywright", "--url", url, "--bearer-token-env-var",
+                            "KEYWRIGHT_TOKEN"], check=False)
+    ch.apply(out)
+    return 0
+
+
+def uninstall(*, dry_run: bool = False, out=None) -> int:
+    out = out or sys.stdout
+    ch = Changes(dry_run)
+    path = codex_home() / "AGENTS.md"
+    if path.exists():
+        text = path.read_text()
+        if BEGIN in text:
+            head, _, tail = text.partition(BEGIN)
+            _, _, tail = tail.partition(END)
+            ch.edit_text(path, head.rstrip("\n") + ("\n" + tail if tail.strip() else "\n"))
+    ch.apply(out)
+    return 0

keywright/setup/common.py

@@ -0,0 +1,146 @@
+"""Shared edit machinery: JSON read/merge/write with a timestamped backup, a diff for --dry-run,
+and the markers by which our own hook entries and rules are recognized on later runs."""
+
+from __future__ import annotations
+
+import difflib
+import json
+import os
+import shutil
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+OUR_HOOK_MARKERS = ("kw hazards --hook", "keywright hazards --hook", "gatekeeper-hazards.py",
+                    "kw session-start --hook", "keywright session-start --hook")
+
+
+class Changes:
+    """Collects file edits; applies them (with backups) or prints them (dry run)."""
+
+    def __init__(self, dry_run: bool):
+        self.dry_run = dry_run
+        self.edits: list[tuple[Path, str, str]] = []  # path, before, after
+        self.notes: list[str] = []
+
+    def note(self, text: str) -> None:
+        self.notes.append(text)
+
+    def edit_json(self, path: Path, data: Any) -> None:
+        before = path.read_text() if path.exists() else ""
+        after = json.dumps(data, indent=2) + "\n"
+        if before != after:
+            self.edits.append((path, before, after))
+
+    def edit_text(self, path: Path, after: str) -> None:
+        before = path.read_text() if path.exists() else ""
+        if before != after:
+            self.edits.append((path, before, after))
+
+    def apply(self, out=sys.stdout) -> int:
+        for path, before, after in self.edits:
+            if self.dry_run:
+                diff = difflib.unified_diff(before.splitlines(keepends=True), after.splitlines(keepends=True),
+                                            fromfile=str(path), tofile=str(path))
+                out.write("".join(diff) or f"(create {path})\n")
+                continue
+            path.parent.mkdir(parents=True, exist_ok=True)
+            if path.exists():
+                shutil.copy2(path, path.with_name(f"{path.name}.bak-{int(time.time())}"))
+            tmp = path.with_name(path.name + ".tmp")
+            tmp.write_text(after)
+            os.replace(tmp, path)
+            out.write(f"wrote {path}\n")
+        for n in self.notes:
+            out.write(("would " if self.dry_run else "") + n + "\n")
+        return len(self.edits)
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text() or "{}")
+    except ValueError as e:
+        raise SystemExit(f"{path} is not valid JSON ({e}); fix it before running setup") from e
+    if not isinstance(data, dict):
+        raise SystemExit(f"{path} does not hold a JSON object")
+    return data
+
+
+def binary_path() -> str:
+    """Absolute path of the `kw` script, so hooks work even when ~/.local/bin is not on PATH."""
+    for name in ("kw", "keywright"):
+        p = shutil.which(name)
+        if p:
+            return p
+    return "kw"
+
+
+def set_hook(settings: dict[str, Any], event: str, matcher: str | None, command: str, *, timeout: int = 10,
+             status: str | None = None) -> None:
+    """Add or replace our hook entry for `event`; other people's hooks are untouched."""
+    hooks = settings.setdefault("hooks", {})
+    entries: list[dict[str, Any]] = hooks.setdefault(event, [])
+    ours = {"type": "command", "command": command, "timeout": timeout}
+    if status:
+        ours["statusMessage"] = status
+    for entry in entries:
+        if (entry.get("matcher") or None) != matcher:
+            continue
+        inner = entry.setdefault("hooks", [])
+        inner[:] = [h for h in inner if not _is_ours(h)]
+        inner.append(ours)
+        return
+    entry = {"hooks": [ours]}
+    if matcher:
+        entry["matcher"] = matcher
+    entries.append(entry)
+
+
+def remove_hooks(settings: dict[str, Any]) -> None:
+    hooks = settings.get("hooks") or {}
+    for event, entries in list(hooks.items()):
+        for entry in entries:
+            entry["hooks"] = [h for h in entry.get("hooks", []) if not _is_ours(h)]
+        hooks[event] = [e for e in entries if e.get("hooks")]
+        if not hooks[event]:
+            del hooks[event]
+    if not hooks and "hooks" in settings:
+        del settings["hooks"]
+
+
+def _is_ours(h: dict[str, Any]) -> bool:
+    cmd = str(h.get("command") or "")
+    return any(m in cmd for m in OUR_HOOK_MARKERS)
+
+
+def find_hooks(settings: dict[str, Any]) -> list[str]:
+    out = []
+    for entries in (settings.get("hooks") or {}).values():
+        for entry in entries:
+            for h in entry.get("hooks", []):
+                if _is_ours(h):
+                    out.append(str(h.get("command")))
+    return out
+
+
+def ensure_rules(settings: dict[str, Any], key: str, rules: list[str]) -> None:
+    perms = settings.setdefault("permissions", {})
+    have: list[str] = perms.setdefault(key, [])
+    for r in rules:
+        if r not in have:
+            have.append(r)
+
+
+def drop_rules(settings: dict[str, Any], key: str, predicate) -> None:
+    perms = settings.get("permissions") or {}
+    if key in perms:
+        perms[key] = [r for r in perms[key] if not predicate(r)]
+        if not perms[key]:
+            del perms[key]
+
+
+def claude_dir() -> Path:
+    return Path(os.environ.get("CLAUDE_CONFIG_DIR") or str(Path.home() / ".claude"))

keywright/skill/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: keywright
+description: Use `kw` to run commands and move files on brokered SSH hosts, and to call brokered MCP tools, through Keywright. Every call is checked against the human's rules; some prompt the human on their phone. Read this before the first `kw` call in a session.
+keywright-version: 0.0.1
+---
+
+# Keywright: reaching hosts and tools through `kw`
+
+Keywright brokers access to SSH hosts and MCP servers. The credentials live on the broker, never on
+this machine. `kw` is the command you use; the human approves what needs approving.
+
+## First call
+
+`kw guide` prints this guide; `kw guides` is an alias.
+
+```bash
+kw resources            # every brokered host and MCP server, and your standing on each
+kw session              # which conversation your calls are attributed to
+```
+
+Under Codex, there can be two approval layers. The local sandbox must permit `kw` to reach the
+broker before Keywright can request approval on the phone. If sandbox network access is blocked,
+request execution permission through the agent's normal approval mechanism, scoped to the needed
+subcommand or resource (for example `kw resources` or `kw run dev-host`). Do not disable the sandbox
+or grant blanket shell access. A local execution approval does not grant access on the broker.
+
+Broker connection/handshake attempts stop after 15 seconds, plus up to one second for worker cleanup.
+After connecting, each response gets its operation timeout plus 30 seconds; approval polling and
+remote commands retain their longer waits. A timeout does not prove a sandbox problem: check the
+broker URL, DNS, proxy and network reachability. Do not blindly retry a command whose outcome is unknown.
+
+`kw session` prefers `KW_SESSION`, then a valid `CODEX_THREAD_ID` when Codex supplies it, then a
+per-process identity. Thread metadata keeps identity stable across sandbox boundaries. Availability
+depends on the Codex host; process identity may span conversations, and hidden ancestry without
+metadata yields `none` (no session-scoped approvals). Existing process-scoped approvals do not carry
+over when a conversation starts using a thread identity.
+
+## Running commands
+
+```bash
+kw run <host> -r "why" -- journalctl -u myapp -n 50
+kw run <host> -r "why" -c 'docker ps | grep api'      # a pipeline or loop; approved one line at a time
+kw put <host> /etc/app/app.env --file app.env -r "why"   # or content on stdin
+kw get <host> /etc/app/app.env                            # content on stdout; -o FILE to save
+kw capture <host> --to <host2>:/root/.env -- cat /run/secret   # output goes host to host, never to you
+```
+
+- Remote stdout is your stdout, remote stderr your stderr, so `kw run h -- cat f | grep x` works.
+- One `kw:` line on stderr afterwards names the audit row, what allowed the call, and whether output
+  was truncated (output is capped at 1 MiB and decoded as UTF-8).
+- Prefer the `--` form: a plain command classifies narrowly (`ssh/<host>/exec/journalctl`). `-c` and
+  anything with pipes, substitution or loops needs the host-wide `**` pattern and is approved exactly,
+  one command line at a time.
+- Prefer `kw put`/`kw get` over shell redirection: they classify by path and never put file contents
+  in the human's prompt.
+- Quoting through `kw run -c` → ssh → `pct exec`/`docker exec` → a shell mangles inner quotes. For
+  anything non-trivial `kw put` a script to the host and run it by path.
+- Always pass `-r`: it is what the human reads on their phone.
+
+## Approvals
+
+When a call needs approval, `kw` asks the human and waits (default 900 s; `KW_WAIT` changes it), printing a heartbeat on
+stderr with whether the notification was delivered. Give the Bash tool a timeout of at least the
+wait plus the command's own runtime. Under Claude Code the setup sets `KW_WAIT=540` because a Bash call
+is capped at 10 minutes; a longer wait would push the call into the background and out of your control.
+When a call exits 3, `kw status <id> --wait 540` keeps waiting and names the command to re-issue.
+
+Exit codes tell you what happened:
+
+| exit | meaning |
+|---|---|
+| 0 | ran; remote command exited 0 |
+| 1 | ran; remote command exited nonzero (code in the `kw:` line, or `--json`) |
+| 3 | approval still pending: the request id is printed; `kw status <id> --wait 900` later; when it reports approved it names the command to re-issue. `--no-wait` returns this at once |
+| 4 | denied, refused, locked, recently denied, or rate-limited. Do not retry without new instructions from the user |
+| 5 | unknown host, tool or request |
+| 6 | could not reach the broker, bad token, or the call's outcome is unknown: check with the user before repeating anything |
+| 7 | the broker could not run it (SSH failed, write refused): the `kw:` line names the stage |
+
+Approval is once and exact by default: the same command line, once. Ask for several exact steps in
+one prompt when you know them: `kw request -r "why" --ops ops.json` where the file is a JSON list of
+`{"host","command"}`, `{"host","put","content"}`, `{"host","get"}` or capture objects. Patterns
+(`kw request --pattern ssh/nvr/exec/journalctl`) ask for standing scope instead.
+
+Destructive operations are flagged whatever access exists: recursive deletes of system or home
+directories, disk formatting, destroying guests, volumes or pools, force pushes, powering off, and
+touching key material or login configuration. The worst are refused outright (exit 4); the rest
+always prompt and are approved once. Never reword a command to get around a flag; tell the user.
+
+`kw status <id>` reports approval only; it never resumes a command. If a call returned 6 after the
+human approved it, the command may or may not have run: ask the user, or check the audit log through
+them, before running it again.
+
+## When you need the human, not a host
+
+```bash
+kw ping "Traefik cert: ACME DNS-01 or the existing wildcard? Both work, you have a preference."
+```
+
+This reaches the same phone as an approval prompt and stays on the Keywright dashboard until they
+clear it. It does **not** bring back an answer and does not wait. So: send it, ask the question in
+the conversation, and stop. They come to you.
+
+Use it when you would otherwise sit idle while they are away from the keyboard: a choice only they
+can make, a question you cannot answer from the repo, or work finished and waiting on their eyes.
+
+Do not use it to narrate progress, and do not use it to chase a pending approval - that request is
+already on their phone. One ping per thing you need: sending the same message twice folds into the
+one already waiting, and a second different ping inside a minute exits 4. `--where` overrides the
+host and directory it reports; by default it sends both so they know which conversation to open.
+
+## Brokered MCP tools
+
+```bash
+kw tools                          # names, e.g. ha__ha_get_state
+kw tool ha --list                 # schemas for one server, on demand
+kw tool ha ha_get_state entity_id=light.kitchen -r "why"
+kw tool ha call_service --args '{"service":"light.turn_on","entity_id":"light.kitchen"}' -r "why"
+```
+
+## Models through Keywright
+
+A gateway of kind `llm` in `kw resources` brokers model calls: the provider keys stay on the broker.
+`kw llm <gateway>` prints the `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` lines that route an SDK
+through it with your Keywright token. A call names a model; a model you have no lease on asks the
+human and waits (`X-Keywright-Wait` seconds, `X-Keywright-Reason` for the prompt), then answers
+`403 approval_required` with a request id if they have not decided yet. Every lease has a spend
+ceiling; a 4xx from the gateway saying budget exceeded means the ceiling, not a bug. Ask with
+`kw request --pattern llm/<gateway>/model/<model>` ahead of time when you know what you need.
+
+## What `kw` will not do for you
+
+`kw setup`, `kw login` and `kw logout` change this machine's own gate and are for the human. If the
+setup looks wrong, say so instead of fixing it.