bashboy 0.1.0__py3-none-any.whl

bashboy/hooks/claude.py

@@ -0,0 +1,92 @@
+"""Claude Code ``PreToolUse`` hook adapter.
+
+Contract (from Claude Code hooks):
+
+* read one JSON object from stdin;
+* **deny** -> print a ``hookSpecificOutput`` payload with
+  ``permissionDecision: "deny"``;
+* **allow** -> print *nothing* so the host's normal permission flow continues;
+* always exit 0, even on malformed input or an internal error (fail closed:
+  an internal error emits a deny payload).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TextIO
+
+from ..classify import classify_command
+
+
+def _load(raw: str) -> dict | None:
+    try:
+        payload = json.loads(raw)
+    except Exception:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def parse_hook_payload(raw: str) -> str | None:
+    """Return the command from a hook payload, or ``None``. Never raises."""
+    payload = _load(raw)
+    if payload is None:
+        return None
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return None
+    for key in ("command", "cmd"):
+        value = tool_input.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def parse_hook_cwd(raw: str) -> str | None:
+    """Return the working directory from a hook payload, or ``None``.
+
+    Claude Code carries ``cwd`` at the top level; some hosts nest it under
+    ``tool_input``. Both are accepted.
+    """
+    payload = _load(raw)
+    if payload is None:
+        return None
+    candidates = [payload.get("cwd")]
+    tool_input = payload.get("tool_input")
+    if isinstance(tool_input, dict):
+        candidates.append(tool_input.get("cwd"))
+    for candidate in candidates:
+        if isinstance(candidate, str) and candidate.strip():
+            return candidate.strip()
+    return None
+
+
+def deny_payload(reason: str) -> dict[str, object]:
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }
+
+
+def run_hook(stdin: TextIO, stdout: TextIO) -> int:
+    """Classify the command on stdin, emit a deny payload only when denying."""
+    try:
+        raw = stdin.read()
+        command = parse_hook_payload(raw)
+        if not command:
+            return 0
+        result = classify_command(command, cwd=parse_hook_cwd(raw))
+        if result.decision == "deny":
+            stdout.write(json.dumps(deny_payload(result.reason)) + "\n")
+            stdout.flush()
+        return 0
+    except Exception as exc:  # noqa: BLE001 - fail closed, but never break the host
+        try:
+            reason = f"BashBoy internal error: {type(exc).__name__}"
+            stdout.write(json.dumps(deny_payload(reason)) + "\n")
+            stdout.flush()
+        except Exception:
+            pass
+        return 0

bashboy/installers/__init__.py

@@ -0,0 +1,38 @@
+"""Host installers.
+
+Shared file-writing helpers live here. The CLI imports the individual installers
+lazily so ``bashboy check`` never pays for them.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Write ``text`` to ``path`` via a temp file in the same directory + ``os.replace``.
+
+    A crash mid-write can never leave a truncated host config behind.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handle = tempfile.NamedTemporaryFile(
+        "w",
+        encoding="utf-8",
+        newline="\n",
+        dir=str(path.parent),
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        delete=False,
+    )
+    try:
+        with handle as stream:
+            stream.write(text)
+        os.replace(handle.name, path)
+    except BaseException:
+        try:
+            os.unlink(handle.name)
+        except OSError:
+            pass
+        raise

bashboy/installers/claude.py

@@ -0,0 +1,135 @@
+"""Claude Code installer: merge a PreToolUse hook into ``settings.json``.
+
+The merge is idempotent and non-clobbering: unrelated keys and unrelated hook
+events survive, and an existing BashBoy handler is updated in place rather than
+duplicated. The file is backed up before the first write and replaced
+atomically.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from pathlib import Path
+
+from ..config import ConfigError, load_config
+from . import atomic_write_text
+
+MATCHER = "Bash|PowerShell"
+STATUS_MESSAGE = "BashBoy: checking command"
+
+
+def default_settings_path() -> Path:
+    return Path.home() / ".claude" / "settings.json"
+
+
+def _resolve_path(settings_path: Path | str | None) -> Path:
+    return Path(settings_path) if settings_path else default_settings_path()
+
+
+def _load_settings(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError(f"cannot read {path}: {exc}") from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(
+            f"{path}: not valid JSON ({exc}); refusing to modify it"
+        ) from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: expected a JSON object; refusing to modify it")
+    return data
+
+
+def build_handler(timeout_s: int = 15, from_spec: str | None = None) -> dict:
+    args = ["bashboy", "check", "--claude-hook"]
+    if from_spec:
+        args = ["--from", from_spec, *args]
+    return {
+        "type": "command",
+        "command": "uvx",
+        "args": args,
+        "timeout": int(timeout_s),
+        "statusMessage": STATUS_MESSAGE,
+    }
+
+
+def _is_bashboy_handler(candidate: object) -> bool:
+    if not isinstance(candidate, dict):
+        return False
+    args = candidate.get("args")
+    return isinstance(args, list) and "bashboy" in args and "--claude-hook" in args
+
+
+def merge_handler(settings: dict, handler: dict) -> dict:
+    """Return ``settings`` with ``handler`` present exactly once under PreToolUse."""
+    hooks = settings.get("hooks")
+    if hooks is None:
+        hooks = {}
+        settings["hooks"] = hooks
+    elif not isinstance(hooks, dict):
+        raise ConfigError("settings 'hooks' must be a JSON object")
+
+    entries = hooks.get("PreToolUse")
+    if entries is None:
+        entries = []
+        hooks["PreToolUse"] = entries
+    elif not isinstance(entries, list):
+        raise ConfigError("settings 'hooks.PreToolUse' must be a JSON array")
+
+    target = None
+    for entry in entries:
+        if isinstance(entry, dict) and entry.get("matcher") == MATCHER:
+            target = entry
+            break
+
+    if target is None:
+        entries.append({"matcher": MATCHER, "hooks": [handler]})
+        return settings
+
+    existing = target.get("hooks")
+    if not isinstance(existing, list):
+        existing = []
+        target["hooks"] = existing
+
+    for index, candidate in enumerate(existing):
+        if _is_bashboy_handler(candidate):
+            updated = dict(candidate)
+            updated.update(handler)
+            existing[index] = updated
+            return settings
+
+    existing.append(handler)
+    return settings
+
+
+def install_claude(
+    settings_path: Path | str | None = None,
+    *,
+    from_spec: str | None = None,
+    dry_run: bool = False,
+) -> dict:
+    """Merge the BashBoy hook and (unless ``dry_run``) write the settings file."""
+    path = _resolve_path(settings_path)
+    cfg = load_config()
+    settings = _load_settings(path)
+    merged = merge_handler(settings, build_handler(cfg.claude.timeout_s, from_spec))
+
+    if dry_run:
+        return merged
+
+    if path.exists():
+        backup = Path(str(path) + ".bak")
+        try:
+            shutil.copyfile(path, backup)
+        except OSError as exc:
+            raise ConfigError(f"cannot back up {path}: {exc}") from exc
+        print(f"bashboy: backup at {backup}", file=sys.stderr)
+
+    atomic_write_text(path, json.dumps(merged, indent=2, ensure_ascii=False) + "\n")
+    return merged

bashboy/installers/opencode.py

@@ -0,0 +1,199 @@
+"""OpenCode installer: write the deny-only plugin and register it.
+
+V2 registers through ``Plugin.define`` / ``ctx.tool.hook("execute.before")``; V1
+used ``server()`` returning ``"tool.execute.before"``. Both delegate to the same
+helper, so the verdict logic exists once.
+
+The plugin never passes the command through a shell: it is one ``execFile`` argv
+element with ``shell: false``. ENOENT, non-zero exit without JSON, invalid JSON,
+and timeouts all throw (fail closed).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from .. import __version__
+from ..config import ConfigError, load_config
+from . import atomic_write_text
+
+_PLUGIN_TEMPLATE = """/**
+ * BashBoy plugin for OpenCode - deny-only shell command gate.
+ *
+ * Generated by `bashboy install --opencode` (bashboy VERSION_PLACEHOLDER). Re-run that
+ * command to rewrite this file; change policy in ~/.bashboy/config.toml instead.
+ *
+ * Only a denial is expressed. An allow means "no objection" and lets the host's
+ * normal permission flow continue.
+ */
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import { Plugin } from "@opencode/plugin"
+
+const run = promisify(execFile)
+const TIMEOUT_MS = TIMEOUT_MS_PLACEHOLDER
+type AnyRecord = Record<string, any>
+
+function isShellTool(tool: unknown): boolean {
+  const id = String(tool ?? "").toLowerCase()
+  return id === "bash" || id === "shell"
+}
+
+/**
+ * Ask bashboy for a verdict and throw only when it says deny.
+ * Any inability to get a clear verdict also throws (fail closed).
+ */
+async function classify(command: string, cwd: unknown): Promise<void> {
+  const dir = typeof cwd === "string" && cwd.length > 0 ? cwd : process.cwd()
+  let stdout = ""
+
+  try {
+    const result = await run(
+      "uvx",
+      ["bashboy", "check", "--json", "--command", command, "--cwd", dir],
+      { shell: false, timeout: TIMEOUT_MS, windowsHide: true },
+    )
+    stdout = String((result as AnyRecord).stdout ?? "")
+  } catch (error: any) {
+    const fromError = String(error?.stdout ?? "")
+    if (fromError.trim().length === 0) {
+      const detail = error?.code ?? error?.message ?? "unknown error"
+      throw new Error("BashBoy could not verify this command: " + String(detail))
+    }
+    // bashboy exits 1 for deny, so a valid deny payload arrives via error.stdout.
+    stdout = fromError
+  }
+
+  let verdict: AnyRecord
+  try {
+    verdict = JSON.parse(stdout)
+  } catch {
+    throw new Error("BashBoy could not verify this command: invalid JSON from bashboy")
+  }
+
+  if (verdict?.decision === "deny") {
+    throw new Error("BashBoy blocked this command: " + String(verdict?.reason ?? "denied"))
+  }
+  if (verdict?.decision === "allow") {
+    return
+  }
+  throw new Error("BashBoy could not verify this command: unexpected verdict")
+}
+
+export default {
+  ...Plugin.define({
+    id: "bashboy",
+    async setup(ctx: any) {
+      await ctx.tool.hook("execute.before", async (event: any) => {
+        if (!isShellTool(event?.tool)) return
+        const input = event?.input ?? {}
+        const command = input.command
+        if (typeof command !== "string" || command.trim().length === 0) return
+        await classify(command, input.cwd)
+      })
+    },
+  }),
+
+  // V1 fallback: same helper, different registration shape.
+  async server() {
+    return {
+      "tool.execute.before": async (input: any, output: any) => {
+        if (!isShellTool(input?.tool)) return
+        const args = output?.args ?? {}
+        const command = args.command
+        if (typeof command !== "string" || command.trim().length === 0) return
+        await classify(command, args.cwd)
+      },
+    }
+  },
+}
+"""
+
+PLUGIN_SOURCE = _PLUGIN_TEMPLATE.replace("VERSION_PLACEHOLDER", __version__).replace(
+    "TIMEOUT_MS_PLACEHOLDER", "15000"
+)
+
+
+def default_config_dir() -> Path:
+    return Path.home() / ".config" / "opencode"
+
+
+def _same_path(left: str, right: str) -> bool:
+    return os.path.normcase(os.path.abspath(left)) == os.path.normcase(os.path.abspath(right))
+
+
+def _load_config(config_file: Path) -> dict:
+    if not config_file.exists():
+        return {"$schema": "https://opencode.ai/config.json"}
+    try:
+        raw = config_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError(f"cannot read {config_file}: {exc}") from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(
+            f"{config_file}: not valid JSON ({exc}); refusing to modify it"
+        ) from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{config_file}: expected a JSON object; refusing to modify it")
+    return data
+
+
+def install_opencode(config_dir: Path | str | None = None, *, dry_run: bool = False) -> dict:
+    base = Path(config_dir) if config_dir else default_config_dir()
+    plugin_path = base / "plugins" / "bashboy.ts"
+    config_file = base / "opencode.json"
+    plugin_target = str(plugin_path)
+
+    cfg = load_config()
+    source = _PLUGIN_TEMPLATE.replace("VERSION_PLACEHOLDER", __version__).replace(
+        "TIMEOUT_MS_PLACEHOLDER", str(int(cfg.opencode.timeout_ms))
+    )
+
+    config = _load_config(config_file)
+    # V2 documents ``plugins``; V1 used ``plugin``. Preserve whichever is already
+    # there and never write both keys.
+    if "plugins" in config:
+        key = "plugins"
+    elif "plugin" in config:
+        key = "plugin"
+    else:
+        key = "plugins"
+
+    entries = config.get(key)
+    if entries is None:
+        entries = []
+        config[key] = entries
+    elif not isinstance(entries, list):
+        raise ConfigError(f"{config_file}: '{key}' must be a JSON array")
+
+    if not any(
+        isinstance(entry, str) and _same_path(entry, plugin_target) for entry in entries
+    ):
+        entries.append(plugin_target)
+
+    result = {
+        "plugin_path": plugin_target,
+        "plugin_source": source,
+        "config": config,
+    }
+
+    if dry_run:
+        return result
+
+    if config_file.exists():
+        backup = Path(str(config_file) + ".bak")
+        try:
+            shutil.copyfile(config_file, backup)
+        except OSError as exc:
+            raise ConfigError(f"cannot back up {config_file}: {exc}") from exc
+        print(f"bashboy: backup at {backup}", file=sys.stderr)
+
+    atomic_write_text(plugin_path, source)
+    atomic_write_text(config_file, json.dumps(config, indent=2, ensure_ascii=False) + "\n")
+    return result

bashboy/provider.py

@@ -0,0 +1,215 @@
+"""Clocked model client for the `clocked/fill` endpoint.
+
+The response envelope is **unverified**, so parsing is deliberately tolerant:
+:func:`extract_field` walks nested dicts/lists looking for a named field and
+unwraps the common value containers. Anything that cannot be resolved to a
+clear ``allow``/``deny`` raises :class:`ProviderMalformed`, which the classifier
+turns into a closed failure.
+
+No retries, no cache: a slow or broken provider must become a ``deny``, not a
+hang and not an ``allow``.
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import urllib.error
+import urllib.request
+import uuid
+from collections import deque
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .config import ProviderConfig
+
+Transport = Callable[[str, bytes, dict[str, str], float], tuple[int, bytes]]
+
+RUBRIC = (
+    "You are a shell-command safety classifier gating an AI coding agent. "
+    "Decide whether the command may run. Deny commands that delete or overwrite data outside "
+    "the working tree, escalate privileges destructively, format or partition disks, disable "
+    "security controls, exfiltrate secrets or credentials, or pipe unreviewed remote content "
+    "(curl/wget output) into a shell. Allow ordinary build, test, git, and read-only operations, "
+    "and writes inside the working directory. Prefer deny when the command's effect cannot be "
+    "determined from the text alone."
+)
+
+_VERDICTS = frozenset({"allow", "deny"})
+_VALUE_KEYS = ("value", "text", "answer", "label", "result", "content")
+_NAME_KEYS = ("name", "key", "id", "field")
+
+
+class ProviderError(Exception):
+    """Any provider failure. Callers must fail closed."""
+
+
+class ProviderTimeout(ProviderError):
+    """The provider did not answer within the configured timeout."""
+
+
+class ProviderMalformed(ProviderError):
+    """The provider answered, but not with a usable verdict."""
+
+
+@dataclass
+class Verdict:
+    decision: str
+    risk: str | None
+    reason: str
+
+
+def build_request_body(cwd: str, command: str) -> dict[str, object]:
+    return {
+        "text": f"cwd: {cwd}\ncommand: {command}",
+        "instructions": RUBRIC,
+        "fields": {
+            "verdict": {
+                "type": "choice",
+                "options": ["allow", "deny"],
+                "description": "May this shell command run?",
+            },
+            "risk": {
+                "type": "score",
+                "levels": ["low", "medium", "high", "critical"],
+                "description": "How damaging would this command be if wrong?",
+            },
+            "reason": {
+                "type": "generate",
+                "max_tokens": 80,
+                "format": "text",
+                "description": "One short sentence explaining the verdict.",
+            },
+        },
+    }
+
+
+def _unwrap(value: Any) -> Any:
+    if isinstance(value, dict):
+        for key in _VALUE_KEYS:
+            if key in value:
+                return _unwrap(value[key])
+        return value
+    if isinstance(value, list):
+        if len(value) == 1:
+            return _unwrap(value[0])
+        return value
+    return value
+
+
+def _named_field_matches(node: dict, target: str) -> bool:
+    for name_key in _NAME_KEYS:
+        for key, value in node.items():
+            if (
+                isinstance(key, str)
+                and key.lower() == name_key
+                and isinstance(value, str)
+                and value.lower() == target
+            ):
+                return True
+    return False
+
+
+def extract_field(payload: object, key: str) -> object | None:
+    """Find ``key`` anywhere in ``payload`` (breadth-first) and unwrap its value."""
+    target = key.lower()
+    queue: deque[Any] = deque([payload])
+    while queue:
+        node = queue.popleft()
+        if isinstance(node, dict):
+            for node_key, value in node.items():
+                if isinstance(node_key, str) and node_key.lower() == target:
+                    return _unwrap(value)
+            if _named_field_matches(node, target):
+                for value_key in _VALUE_KEYS:
+                    if value_key in node:
+                        return _unwrap(node[value_key])
+            queue.extend(node.values())
+        elif isinstance(node, list):
+            queue.extend(node)
+    return None
+
+
+def urllib_transport(
+    url: str, body: bytes, headers: dict[str, str], timeout: float
+) -> tuple[int, bytes]:
+    """POST ``body`` to ``url`` with the stdlib, mapping failures to ProviderError."""
+    request = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return int(response.status), response.read()
+    except urllib.error.HTTPError as exc:
+        raise ProviderError(f"provider returned HTTP {exc.code}") from exc
+    except urllib.error.URLError as exc:
+        reason = getattr(exc, "reason", None)
+        if isinstance(reason, TimeoutError):
+            raise ProviderTimeout(f"provider request timed out after {timeout}s") from exc
+        raise ProviderError(f"provider request failed: {reason or exc}") from exc
+    except TimeoutError as exc:
+        raise ProviderTimeout(f"provider request timed out after {timeout}s") from exc
+    except OSError as exc:
+        raise ProviderError(f"provider transport error: {exc}") from exc
+
+
+class Provider:
+    """Minimal client for the clocked/fill endpoint."""
+
+    def __init__(
+        self,
+        cfg: ProviderConfig,
+        transport: Transport | None = None,
+        key: str | None = None,
+    ) -> None:
+        self.cfg = cfg
+        self._transport: Transport = transport or urllib_transport
+        self._key = key
+
+    def classify(self, cwd: str, command: str) -> Verdict:
+        key = (self._key or "").strip()
+        if not key:
+            raise ProviderError(f"no API key configured (env {self.cfg.api_key_env})")
+
+        body = build_request_body(cwd, command)
+        encoded = json.dumps(body).encode("utf-8")
+        headers = {
+            "Authorization": f"Bearer {key}",
+            "Content-Type": "application/json",
+            "Idempotency-Key": str(uuid.uuid4()),
+        }
+        timeout = max(int(self.cfg.timeout_ms), 0) / 1000.0
+
+        try:
+            status, raw = self._transport(self.cfg.endpoint, encoded, headers, timeout)
+        except ProviderError:
+            raise
+        except TimeoutError as exc:
+            raise ProviderTimeout(f"provider request timed out after {timeout}s") from exc
+        except OSError as exc:
+            raise ProviderError(f"provider transport error: {exc}") from exc
+        except Exception as exc:  # defensive: never let a transport bug look like success
+            raise ProviderError(f"provider transport error: {exc}") from exc
+
+        if not 200 <= int(status) < 300:
+            raise ProviderError(f"provider returned HTTP {status}")
+
+        try:
+            payload = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise ProviderMalformed(f"provider returned a non-JSON body: {exc}") from exc
+
+        raw_verdict = extract_field(payload, "verdict")
+        verdict = raw_verdict.strip().lower() if isinstance(raw_verdict, str) else None
+        if verdict not in _VERDICTS:
+            raise ProviderMalformed(f"unrecognized verdict: {raw_verdict!r}")
+
+        raw_risk = extract_field(payload, "risk")
+        risk = raw_risk.strip() if isinstance(raw_risk, str) and raw_risk.strip() else None
+
+        raw_reason = extract_field(payload, "reason")
+        reason = (
+            raw_reason.strip()
+            if isinstance(raw_reason, str) and raw_reason.strip()
+            else "model verdict"
+        )
+
+        return Verdict(decision=verdict, risk=risk, reason=reason)