jev-tools-setup 0.3.0__py3-none-any.whl

jev_report.py

@@ -0,0 +1,240 @@
+"""Write LOG.md: a plain-English report of what jev-tools did and what is wrong. Stdlib only, read-only except for the output file.
+
+    python jev_report.py [--out PATH] [--last N]      (also: `jev-tools-setup report`, or the `report` skill inside Claude Code)
+
+Sources: the decision log(s) the hooks and skills append to (JSONL), ~/.jev-tools/config.json, and environment variable NAMES.
+Never included: the API key, file contents, prompts. Home directory paths are shortened to ~ and key-shaped strings are redacted,
+so the file is safe to attach to an issue.
+"""
+import argparse
+import json
+import os
+import platform
+import re
+import statistics
+import sys
+import time
+from collections import Counter
+from datetime import datetime
+from pathlib import Path
+
+HOME = Path.home()
+JEV = HOME / ".jev-tools"
+KEYISH = re.compile(r"\b(?:sk|pk|rk)[-_][A-Za-z0-9_-]{16,}|(?i:bearer)\s+[A-Za-z0-9._~+/=-]{16,}")
+INSTALLER = {"setup_start", "setup_end", "plugin_step", "key_saved", "probe_failed", "config_saved", "serve_start", "local_install"}
+
+
+def clean(text):
+    """Shorten the home path and redact anything key-shaped."""
+    return KEYISH.sub("[REDACTED]", str(text).replace(str(HOME), "~"))
+
+
+def log_files():
+    cands = [os.environ.get("JEV_LOG"), (Path(os.environ["CLAUDE_PLUGIN_DATA"]) / "log.jsonl") if os.environ.get("CLAUDE_PLUGIN_DATA") else None,
+             JEV / "log.jsonl", *sorted((HOME / ".claude" / "plugins" / "data").glob("jev-tools*/log.jsonl"))]
+    seen, out = set(), []
+    for c in cands:
+        if c and Path(c).is_file() and str(Path(c).resolve()) not in seen:
+            seen.add(str(Path(c).resolve()))
+            out.append(Path(c))
+    return out
+
+
+def load(files):
+    """All events, oldest first. The same line in two files counts once (the plugin dir and ~/.jev-tools can overlap),
+    but repeated identical lines inside one file are real repeats and all count."""
+    rows, have = [], Counter()
+    for f in files:
+        local = Counter()
+        for line in f.read_text(encoding="utf-8", errors="replace").splitlines():
+            local[line] += 1
+            if local[line] <= have[line]:
+                continue
+            have[line] += 1
+            try:
+                e = json.loads(line)
+                if isinstance(e, dict) and "event" in e:
+                    rows.append(e)
+            except ValueError:
+                pass
+    return sorted(rows, key=lambda e: e.get("t", 0))
+
+
+def when(t):
+    return datetime.fromtimestamp(t).astimezone().strftime("%Y-%m-%d %H:%M:%S") if t else "?"
+
+
+def say(e):
+    """One human sentence for one log event."""
+    k = e["event"]
+    if k == "ask":
+        return f"model call ok: {e.get('n')} question(s), {e.get('ms')} ms, {e.get('tok')} input tokens"
+    if k == "ask_error":
+        return f"model call FAILED: {e.get('err')} {e.get('msg', '')}".strip()
+    if k == "no_key":
+        return "no API key found, so the call was skipped (the hook did nothing)"
+    if k == "offline":
+        return "offline backend: model call skipped on purpose"
+    if k == "hook_error":
+        return f"{e.get('hook')} hook crashed with {e.get('err')} and failed open (your edit/prompt was not blocked)"
+    if k == "rule_check":
+        s = f"rule check on {e.get('file')}: {e.get('rules')} rule(s)"
+        if e.get("offline"):
+            s += f", {e.get('hits')} literal match(es)"
+        else:
+            s += f", top score {e.get('top')}" + (f", second look {e.get('confirm')}" if e.get("confirm") is not None else "")
+        if e.get("rule"):
+            s += f" [{e['rule'][:60]}]"
+        return s + (" (enforcing)" if e.get("enforce") else " (shadow: logged only)")
+    if k == "skill_pick":
+        s = f"skill pick: {e.get('pick')}" + (f" (p={e['p']})" if "p" in e else "")
+        return s + (" vetoed by second check" if e.get("vetoed") else " (shadow: not injected)" if e.get("shadow") else " (injected)" if e.get("pick") != "none" else "")
+    if k == "precheck":
+        return f"review pre-check: {e.get('route')} review, {e.get('flags')} flag(s)" + (" (offline patterns)" if e.get("offline") else "")
+    if k == "plugin_step":
+        return f"plugin {e.get('step')} " + ("ok" if e.get("ok") else f"FAILED: {e.get('msg', '')}")
+    if k == "config_saved":
+        return f"config saved: backend={e.get('backend')}, model={e.get('model')}, mode={e.get('mode')}"
+    if k == "key_saved":
+        return "API key validated and saved to the credentials file (the value is never logged)"
+    if k == "probe_failed":
+        return f"key/server check failed: {e.get('err')}"
+    if k == "local_install":
+        return f"local model {e.get('model')} install " + ("ok" if e.get("ok") else "FAILED or declined")
+    if k == "serve_start":
+        return f"local server started: {e.get('model')} at {e.get('url')}"
+    if k == "setup_start":
+        return f"setup started (backend flag: {e.get('backend')})"
+    if k == "setup_end":
+        return f"setup finished with exit code {e.get('rc')}"
+    if k == "state_cut":
+        return f"input trimmed to fit {e.get('model')}'s context window (was {e.get('chars')} characters)"
+    if k == "too_many_options":
+        return f"question declined: more options than {e.get('model')} can take"
+    return k + ": " + ", ".join(f"{a}={b}" for a, b in e.items() if a not in ("t", "event"))
+
+
+def classify(msg):
+    m = str(msg).lower()
+    for pat, label in ((r"401|403|unauthor|forbidden|rejected", "key rejected"), (r"429|quota|rate", "quota or rate limit"),
+                       (r"timed out|timeout", "timeout"), (r"refus|10061|connection|getaddrinfo|urlerror|name or service|unreachable", "cannot reach the server"),
+                       (r"500|502|503|504|529|overload", "server error")):
+        if re.search(pat, m):
+            return label
+    return "other"
+
+
+FIX = {
+    "key rejected": "The key was refused. Get a fresh one at https://codiv.ai/dashboard and run `jev-tools-setup` (api).",
+    "quota or rate limit": "Quota or rate limit hit. Wait, or check usage on the Codiv dashboard. Quota errors are not retried.",
+    "timeout": "The server answered too slowly. Try again; for a local server check that it is running and not still loading the model.",
+    "cannot reach the server": "Nothing is answering. API: check your network. Local: start the server with `jev-tools-setup serve` (small models) or docker compose (full model).",
+    "server error": "The server had an error or is overloaded. It usually clears by itself; hooks fail open meanwhile.",
+    "other": "See the message in the recent events table.",
+}
+
+
+def problems(rows, cfg, day, backend, mode="shadow"):
+    out, d = [], [e for e in rows if e.get("t", 0) >= day]
+    c = Counter(e["event"] for e in d)
+    if mode == "off":
+        src = "the JEV_MODE environment variable" if os.environ.get("JEV_MODE") == "off" else "the plugin option or saved config"
+        out.append(("warn", "Mode is OFF: every hook does nothing and nothing is sent", f"Set by {src}. Hooks return early, so no events are logged either.",
+                    "Unset JEV_MODE (or set it to shadow/active) and restart Claude Code."))
+    elif rows and not d:
+        out.append(("info", "No activity in the last 24 hours", "Either you have not edited files or sent prompts in a session with the plugin, or the hooks are not loading.",
+                    "Restart Claude Code and check `/plugin` shows jev-tools enabled."))
+    if not rows:
+        out.append(("warn", "No events recorded yet", "No hook or skill has run since install, or none could write a log.",
+                    "Restart Claude Code (hooks load at session start), confirm the plugin is enabled with `/plugin`, then do an edit and re-run this report."))
+    if c["no_key"] and backend == "api":
+        out.append(("error", f"API key missing ({c['no_key']} skipped calls in 24h)", "Every hook silently does nothing without a key.",
+                    "Run `jev-tools-setup` and choose api, or set OPENJEV_API_KEY."))
+    errs = Counter(classify(e.get("msg", "") or e.get("err", "")) for e in d if e["event"] == "ask_error")
+    for label, n in errs.most_common():
+        sample = next(clean(f"{e.get('err')} {e.get('msg', '')}".strip()) for e in reversed(d) if e["event"] == "ask_error" and classify(e.get("msg", "") or e.get("err", "")) == label)
+        out.append(("error", f"Model calls failing: {label} ({n} in 24h)", f"Latest: {sample}", FIX[label]))
+    hooks = Counter(e.get("hook") for e in d if e["event"] == "hook_error")
+    for h, n in hooks.most_common():
+        out.append(("error", f"The {h} hook crashed {n} time(s) in 24h", "It failed open, so nothing was blocked, but it is not doing its job.",
+                    "Send this report with the `err` text from the recent events table when you file an issue."))
+    if c["state_cut"] or c["too_many_options"]:
+        out.append(("warn", "A small local model is trimming or declining inputs", f"{c['state_cut']} trimmed, {c['too_many_options']} declined in 24h.",
+                    "Expected with Verdict/Laya (512/1024-token windows). Verdicts on long diffs are less reliable; stay in shadow mode."))
+    env_mode = os.environ.get("JEV_MODE")
+    if env_mode and cfg.get("mode") and env_mode != cfg["mode"]:
+        out.append(("warn", f"JEV_MODE={env_mode} overrides the saved mode ({cfg['mode']})", "The environment variable always wins.", "Unset JEV_MODE to use the saved mode."))
+    if backend == "offline" and c["offline"]:
+        out.append(("info", f"Offline backend: {c['offline']} model call(s) skipped in 24h", "Expected: no model is configured.", "Run `jev-tools-setup` to pick api or local."))
+    return out
+
+
+def build(last=40):
+    files, now = log_files(), time.time()
+    rows = load(files)
+    cfg = {}
+    try:
+        cfg = json.loads((JEV / "config.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        pass
+    backend = cfg.get("backend") if cfg.get("backend") in ("api", "local", "offline") else "api"
+    day = now - 86400
+    mode = os.environ.get("JEV_MODE") or os.environ.get("CLAUDE_PLUGIN_OPTION_MODE") or cfg.get("mode") or "shadow"
+    probs = problems(rows, cfg, day, backend, mode)
+    level = "error" if any(p[0] == "error" for p in probs) else "warn" if any(p[0] == "warn" for p in probs) else "ok"
+    head = {"ok": "✅ Healthy: nothing needs attention.", "warn": "⚠️ Works, but check the notes below.", "error": "❌ Something is wrong: see Problems."}[level]
+    ver = "unknown"
+    for pj in (Path(__file__).resolve().parent.parent / ".claude-plugin" / "plugin.json",):
+        try:
+            ver = json.loads(pj.read_text(encoding="utf-8")).get("version", ver)
+        except (OSError, ValueError):
+            pass
+    keysrc = [n for n in ("OPENJEV_API_KEY", "TYPESAFE_API_KEY", "CLAUDE_PLUGIN_OPTION_API_KEY") if os.environ.get(n)]
+    if (JEV / "credentials").exists():
+        keysrc.append("credentials file")
+    L = [f"# jev-tools log", "", f"_Generated {when(now)} on {platform.system()} {platform.release()}, Python {sys.version.split()[0]}, plugin {ver}._",
+         "_Contains no API key, no file contents and no prompts. Safe to attach to an issue._", "", f"## {head}", ""]
+    L += ["## Setup", "", "| | |", "|---|---|", f"| Backend | {backend}" + (f" ({cfg.get('model')})" if cfg.get("model") else "") + " |",
+          f"| Mode | {mode} (shadow = log only, active = block/inject, off = nothing sent) |",
+          f"| API key found in | {', '.join(keysrc) or 'nowhere'} |", f"| Config file | {'present' if cfg else 'absent'} |",
+          f"| Log files read | {', '.join(clean(f) for f in files) or 'none'} |", ""]
+    L += ["## Problems", ""]
+    L += [f"- {'❌' if s == 'error' else '⚠️' if s == 'warn' else 'ℹ️'} **{clean(t)}**: {clean(d)}\n  - Fix: {f}" for s, t, d, f in probs] or ["None found."]
+    d24 = [e for e in rows if e.get("t", 0) >= day]
+    asks = [e["ms"] for e in d24 if e["event"] == "ask" and isinstance(e.get("ms"), (int, float))]
+    L += ["", "## What happened", "", f"{len(rows)} event(s) in total, {len(d24)} in the last 24 hours.", "", "| Event | Last 24h | All time |", "|---|---:|---:|"]
+    allc, c24 = Counter(e["event"] for e in rows), Counter(e["event"] for e in d24)
+    L += [f"| {k} | {c24[k]} | {allc[k]} |" for k in sorted(allc, key=lambda k: -allc[k])] or ["| (none) | 0 | 0 |"]
+    if asks:
+        L += ["", f"Model calls last 24h: {len(asks)} ok, median {int(statistics.median(asks))} ms, slowest {int(max(asks))} ms."]
+    rc = [e for e in d24 if e["event"] == "rule_check"]
+    if rc:
+        flagged = [e for e in rc if (e.get("top") or 0) >= 0.8 or e.get("hits")]
+        L += [f"Rule checks last 24h: {len(rc)}, {len(flagged)} flagged a rule, enforcement {'on' if any(e.get('enforce') for e in rc) else 'off (shadow)'}."]
+    inst = [e for e in rows if e["event"] in INSTALLER]
+    if inst:
+        L += ["", "## Setup history", "", "| When | What |", "|---|---|"] + [f"| {when(e.get('t'))} | {clean(say(e))} |" for e in inst[-10:]]
+    L += ["", f"## Recent events (newest first, last {last})", "", "| When | What |", "|---|---|"]
+    L += [f"| {when(e.get('t'))} | {clean(say(e)).replace('|', '/')} |" for e in reversed(rows[-last:])] or ["| - | nothing logged yet |"]
+    L += ["", "## How to use this", "",
+          "- Something does nothing? Read **Problems** first: the usual causes are a missing key, an unreachable server, or a hook that was not reloaded (restart Claude Code).",
+          "- Hooks fail open: an outage never blocks your work, it just means the hook did nothing.",
+          "- Run `jev-tools-setup check` to test the machine, or the `status` skill for a one-screen summary. Re-run this report any time.", ""]
+    return "\n".join(L), level
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out", help=f"default {JEV / 'LOG.md'}")
+    ap.add_argument("--last", type=int, default=40)
+    a = ap.parse_args(argv)
+    text, level = build(a.last)
+    out = Path(a.out) if a.out else JEV / "LOG.md"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(text, encoding="utf-8")
+    print(f"wrote {out}  [{ {'ok': 'healthy', 'warn': 'notes', 'error': 'PROBLEMS'}[level] }]")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

jev_tools_cli.py

@@ -0,0 +1,427 @@
+"""jev-tools installer: one command to install the Claude Code plugin and choose how Jev runs. Stdlib only.
+
+    uv tool install jev-tools-setup     once (or: pipx install jev-tools-setup; no install: uvx jev-tools-setup)
+
+    jev-tools-setup check        read-only: is this machine ready? (python, claude CLI, git, network, GPU, docker)
+    jev-tools-setup              install the plugin and pick api / local / offline
+    jev-tools-setup serve        run the small local model you chose (verdict-1.4 / laya-1.0) in the foreground
+    jev-tools-setup report       write ~/.jev-tools/LOG.md: what happened, what is wrong, how to fix it
+    jev-tools-setup uninstall    remove ~/.jev-tools (key, config, log); the plugin itself: /plugin uninstall
+
+The plugin files (skills, scripts, hooks) are downloaded by the `claude` CLI from the GitHub marketplace, so terminal
+and desktop share one install. This tool adds what the plugin cannot do for itself: the backend choice and the key.
+Non-interactive flags exist for scripts and tests; the API key is only ever read from a hidden prompt or stdin, never argv.
+"""
+import argparse
+import getpass
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+MARKET = "Rcidshacker/jev-tools"
+PLUGIN = "jev-tools@jev-tools"
+HOST = "api.codiv.ai"
+LOCAL_URL = "http://127.0.0.1:8080"  # what OpenJev's docker compose listens on
+LOOPBACK = ("localhost", "127.0.0.1", "::1")
+SELF_HOST_DOCS = "https://codiv.ai/docs/guides/self-hosting"
+OPENJEV_REPO = "https://github.com/razorback16/openjev"
+# small encoder models: id -> (OpenJev extra / OPENJEV_BACKEND value, label, fp32 weight size estimate = params x 4 bytes)
+SMALL = {"verdict-1.4": ("verdict", "Verdict 151M", "about 0.6 GB"), "laya-1.0": ("laya", "Laya 421M", "about 1.7 GB")}
+SELF_HOST_CMD = "git clone https://github.com/razorback16/openjev && cd openjev && docker compose up -d"
+OFFLINE_NOTE = ("offline means no model (not no internet). Pattern-based fallbacks still run: find-files ranks by keywords, "
+                "review-precheck flags secrets/dependencies/auth/schema/test-weakening/swallowed errors (fast only for a small clean diff), "
+                "the skill hook picks by keyword, the rule hook blocks only a literal token a 'never/avoid X' rule forbids, "
+                "browser-nav gives an unsure keyword hint. rule-calibrate and any judgment that needs understanding are unavailable.")
+
+
+def run_out(cmd, timeout=20):
+    """(returncode, combined output) without ever raising. UTF-8 with replacement: Windows defaults to cp1252 and crashes on Claude's output."""
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout)
+        return r.returncode, ((r.stdout or "") + (r.stderr or "")).strip()
+    except (OSError, subprocess.TimeoutExpired) as e:
+        return 1, str(e)
+
+
+def home():
+    return Path.home() / ".jev-tools"
+
+
+def note(event, **kw):
+    """Append one line to the decision log that LOG.md is built from. Never raises, never takes secrets."""
+    try:
+        home().mkdir(exist_ok=True)
+        with (home() / "log.jsonl").open("a", encoding="utf-8") as f:
+            f.write(json.dumps({"t": int(time.time()), "event": event, **kw}) + "\n")
+    except OSError:
+        pass
+
+
+def lock_down(path):
+    """Owner-only access. icacls on Windows, mode bits elsewhere."""
+    if os.name == "nt":
+        grant = f"{os.environ.get('USERNAME', '')}:" + ("F" if path.is_file() else "(OI)(CI)F")  # dirs hand it down to new files
+        subprocess.run(["icacls", str(path), "/inheritance:r", "/grant:r", grant], capture_output=True, check=False)
+    else:
+        os.chmod(path, 0o600 if path.is_file() else 0o700)
+
+
+def save_key(key):
+    d = home()
+    d.mkdir(exist_ok=True)
+    lock_down(d)
+    p = d / "credentials"
+    fd = os.open(p, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)  # created owner-only, no window where it is readable
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(key.strip() + "\n")
+    lock_down(p)
+    return p
+
+
+def read_config():
+    try:
+        c = json.loads((home() / "config.json").read_text(encoding="utf-8"))
+        return c if isinstance(c, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def venv_python():
+    return home() / "venv" / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+
+
+def save_config(**cfg):
+    home().mkdir(exist_ok=True)
+    p = home() / "config.json"
+    p.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
+    return p
+
+
+def probe(base, key):
+    """One tiny System One call. Returns None on success or a short reason. Never follows redirects, never prints the key."""
+    u = urllib.parse.urlsplit(base)
+    if not (u.hostname in LOOPBACK or (u.hostname == HOST and u.scheme == "https")):
+        return f"refusing to contact {u.hostname!r}: only {HOST} or loopback"
+
+    class NoRedirect(urllib.request.HTTPRedirectHandler):
+        def redirect_request(self, *a, **k):
+            return None
+
+    body = json.dumps({"model": "openjev-latest", "state": "The build finished and all tests passed.",
+                       "questions": {"ok": {"type": "noul", "instructions": "The text reports a successful outcome"}}}).encode()
+    headers = {"Content-Type": "application/json", "User-Agent": "jev-tools/0.1"}
+    if key:
+        headers["Authorization"] = f"Bearer {key}"
+    try:
+        with urllib.request.build_opener(NoRedirect).open(
+                urllib.request.Request(base.rstrip("/") + "/v1/systemone", body, headers, method="POST"), timeout=20) as r:
+            return None if "answers" in json.load(r) else "unexpected response"
+    except urllib.error.HTTPError as e:
+        return {401: "key rejected (401)", 403: "key rejected (403)", 429: "quota or rate limit (429)"}.get(e.code, f"HTTP {e.code}")
+    except Exception as e:
+        return f"{type(e).__name__}: {str(e)[:80]}"
+
+
+def gpu():
+    """(name, is_blackwell) from nvidia-smi, or (None, False). Blackwell = compute capability 10.x/12.x. A heuristic, not a promise."""
+    if not shutil.which("nvidia-smi"):
+        return None, False
+    rc, text = run_out(["nvidia-smi", "--query-gpu=name,compute_cap", "--format=csv,noheader"])
+    if rc or not text:
+        return None, False
+    name, _, cap = text.splitlines()[0].partition(",")
+    try:
+        return name.strip(), int(cap.strip().split(".")[0]) >= 10
+    except ValueError:
+        return name.strip(), False
+
+
+def ask(prompt, options, default=None):
+    while True:
+        a = input(f"{prompt} [{'/'.join(options)}]{f' ({default})' if default else ''}: ").strip().lower() or default
+        if a in options:
+            return a
+        print(f"  choose one of: {', '.join(options)}")
+
+
+def install_plugin():
+    claude = shutil.which("claude")
+    if not claude:
+        note("plugin_step", step="install", ok=False, msg="claude CLI not found")
+        print("! `claude` CLI not found. Install Claude Code, then run inside it:\n"
+              f"    /plugin marketplace add {MARKET}\n    /plugin install {PLUGIN}")
+        return False
+    for args in (["marketplace", "add", MARKET], ["install", PLUGIN]):
+        rc, text = run_out([claude, "plugin", *args], timeout=180)
+        # re-running setup must not fail just because the marketplace or plugin is already there
+        if rc and "already" not in text.lower():
+            print(f"! `claude plugin {' '.join(args)}` failed:\n{text[-400:]}")
+            note("plugin_step", step=args[0], ok=False, msg=text[-200:])
+            return False
+        note("plugin_step", step=args[0], ok=True)
+        print(f"  ok  claude plugin {args[0]}")
+    return True
+
+
+def choose_backend(a):
+    if a.backend:
+        return a.backend
+    name, blackwell = gpu()
+    print("\nHow should Jev run?\n"
+          "  api      hosted OpenJev at api.codiv.ai (free tier, needs your key; sends text off-machine)\n"
+          "  local    self-hosted OpenJev on this machine (needs an NVIDIA Blackwell-class GPU and Docker)\n"
+          "  offline  no model: keyword and pattern fallbacks only, nothing is sent anywhere")
+    if name:
+        print(f"  detected GPU: {name} -> {'looks Blackwell-class' if blackwell else 'NOT Blackwell-class, so local will not run the model'}")
+    else:
+        print("  no NVIDIA GPU detected, so local will not work here")
+    return ask("Backend", ("api", "local", "offline"), "api")
+
+
+def choose_model(a):
+    if a.model:
+        return a.model
+    print("\nWhich local model?\n"
+          "  verdict-1.4    Verdict 151M: smallest, 512-token context, up to 24 options, ignores yes/no criteria. CPU or any GPU.\n"
+          "  laya-1.0       Laya 421M: 1,024-token context, about 20 options, heavier. CPU or any GPU.\n"
+          "  openjev-latest the full OpenJev model: needs an NVIDIA Blackwell-class GPU and Docker.\n"
+          "  jev-tools trims long diffs to fit the small models and starts them in shadow mode. They are unmeasured with its thresholds.")
+    return ask("Model", ("verdict-1.4", "laya-1.0", "openjev-latest"))
+
+
+def install_small(model, yes):
+    """Clone OpenJev, make a venv, install the model's extra. Streams pip output. True when everything succeeded."""
+    extra, label, size = SMALL[model]
+    repo, venv = home() / "openjev", home() / "venv"
+    print(f"\n{label} runs on the CPU or any GPU. Setup will:\n  1. git clone {OPENJEV_REPO} -> {repo}\n"
+          f"  2. create a Python venv -> {venv}\n  3. pip install openjev[{extra}]  (brings PyTorch: can be several GB)\n"
+          f"The model weights ({size} as fp32) download from Hugging Face the first time the server starts.")
+    if not yes and input("Proceed? [y/N]: ").strip().lower() != "y":
+        print("  skipped: nothing was changed")
+        return False
+    if not shutil.which("git"):
+        print("! git not found: install git, then re-run setup")
+        return False
+    steps = []
+    if not repo.exists():
+        steps.append(["git", "clone", "--depth", "1", OPENJEV_REPO, str(repo)])
+    if not venv_python().exists():
+        steps.append([sys.executable, "-m", "venv", str(venv)])
+    steps.append([str(venv_python()), "-m", "pip", "install", "-e", f"{repo}[{extra}]"])
+    for cmd in steps:
+        print(f"  $ {' '.join(cmd)}")
+        if subprocess.call(cmd):
+            print("! that step failed; fix the error above and re-run setup (finished steps are skipped)")
+            return False
+    return True
+
+
+def serve(a):
+    """Run the small local model in the foreground. Leave it open while you use Claude Code."""
+    cfg = read_config()
+    model = cfg.get("model")
+    if cfg.get("backend") != "local" or model not in SMALL or not venv_python().exists():
+        print("! nothing to serve: run `jev-tools-setup`, choose local, and pick verdict-1.4 or laya-1.0")
+        return 1
+    url = urllib.parse.urlsplit(cfg.get("base_url") or LOCAL_URL)
+    env = {**os.environ, "OPENJEV_BACKEND": SMALL[model][0], "OPENJEV_PORT": str(url.port or 8080), "OPENJEV_HOST": url.hostname or "127.0.0.1"}
+    if a.device:
+        env["OPENJEV_DEVICE"] = a.device
+    note("serve_start", model=model, url=url.geturl())
+    print(f"serving {model} on {url.geturl()}  (Ctrl-C stops it; first start downloads the weights)")
+    try:
+        return subprocess.call([str(venv_python()), "-m", "openjev"], env=env)
+    except KeyboardInterrupt:
+        return 0
+
+
+def setup(a):
+    """Run setup, then always write LOG.md so a failed attempt leaves something to read and attach."""
+    note("setup_start", backend=a.backend)
+    rc = 1
+    try:
+        rc = _setup(a)
+        return rc
+    finally:
+        note("setup_end", rc=rc)
+        report(None, quiet=True)
+        print(f"\nWhat happened is written to {home() / 'LOG.md'}  (attach it if you report a problem; `jev-tools-setup report` refreshes it)")
+
+
+def _setup(a):
+    print("jev-tools setup")
+    if not a.skip_plugin:
+        print("\n1. Installing the plugin (skills, scripts, hooks) with the claude CLI")
+        install_plugin()
+    kind = choose_backend(a)
+    cfg = {"backend": kind}
+    if kind == "api":
+        print(f"\nGet a key at https://codiv.ai/dashboard (starts with sk-codiv-). It is stored only in {home() / 'credentials'}, owner-only.")
+        key = (sys.stdin.readline() if a.key_stdin else getpass.getpass("Paste your key (hidden): ")).strip()
+        if not key:
+            print("! no key given: choose offline, or re-run setup")
+            return 1
+        err = probe(os.environ.get("OPENJEV_BASE_URL") or f"https://{HOST}", key)
+        if err:
+            note("probe_failed", err=err)
+            print(f"! the key did not work: {err}\n  nothing was saved.")
+            return 1
+        print(f"  ok  key works, saved to {save_key(key)}")
+        note("key_saved")
+    elif kind == "local":
+        model = choose_model(a)
+        cfg["model"], cfg["base_url"] = model, a.base_url or LOCAL_URL
+        if model in SMALL:
+            ok = install_small(model, a.yes)
+            note("local_install", model=model, ok=ok)
+            if not ok:
+                return 1
+            print(f"\n  ok  installed. Start the server in its own terminal and keep it open:\n        jev-tools-setup serve")
+        else:
+            name, blackwell = gpu()
+            if not blackwell:
+                print(f"! The full OpenJev model needs an NVIDIA Blackwell-class GPU (NVFP4); {'found ' + name if name else 'none found'}.\n"
+                      f"  Pick verdict-1.4 or laya-1.0 instead (they run on CPU), or api / offline. Details: {SELF_HOST_DOCS}")
+                return 1
+            if not shutil.which("docker"):
+                print(f"! Docker not found. Install it, then: {SELF_HOST_CMD}\n  Guide: {SELF_HOST_DOCS}")
+                return 1
+            print(f"\nStart the server if it is not running:\n  {SELF_HOST_CMD}\nChecking {cfg['base_url']} ...")
+            err = probe(cfg["base_url"], None)
+            print("  ok  server answers" if not err else f"! not answering yet ({err}). Config is saved; start the server, then run the `status` skill.")
+    else:
+        print(f"\n{OFFLINE_NOTE}")
+    if cfg.get("model") in SMALL and a.mode == "active":
+        print("! small models are unmeasured with jev-tools' thresholds: run the rule-calibrate skill in shadow mode before trusting active.")
+    cfg["mode"] = a.mode or ("shadow" if a.backend else ask("\nMode (shadow = log only, active = block/inject, off = nothing)", ("shadow", "active", "off"), "shadow"))
+    print(f"\nconfig saved to {save_config(**cfg)}  (mode: {cfg['mode']}; shadow only logs and never blocks)")
+    note("config_saved", backend=cfg["backend"], model=cfg.get("model"), mode=cfg["mode"])
+    print("The skill-pick hook stays OFF unless you enable it: it sends every prompt you type to the API.")
+    print("\nDone. Restart Claude Code (terminal or desktop), then run the `status` skill to confirm.")
+    return 0
+
+
+def report(a, quiet=False):
+    """Write ~/.jev-tools/LOG.md from the decision logs."""
+    import jev_report
+    out = home() / "LOG.md"
+    text, level = jev_report.build()
+    home().mkdir(exist_ok=True)
+    out.write_text(text, encoding="utf-8")
+    if not quiet:
+        print(f"wrote {out}  [{ {'ok': 'healthy', 'warn': 'notes to read', 'error': 'PROBLEMS found'}[level] }]")
+    return 0
+
+
+def uninstall(_):
+    shutil.rmtree(home(), ignore_errors=True)
+    print(f"removed {home()}. To remove the plugin: /plugin uninstall {PLUGIN}")
+    return 0
+
+
+def system_python():
+    """The `python` the hooks will get. Under uvx/pipx the tool's own venv is first on PATH, so skip it."""
+    dirs = os.environ.get("PATH", "").split(os.pathsep)
+    if sys.prefix != sys.base_prefix:
+        own = str(Path(sys.prefix).resolve())
+        dirs = [d for d in dirs if d and not str(Path(d).resolve()).startswith(own)]
+    return shutil.which("python", path=os.pathsep.join(dirs))
+
+
+def checks():
+    """Read-only prerequisite report: list of (level, name, detail, hint), level in ok|warn|fail|info. Sends and changes nothing."""
+    out = []
+    add = lambda level, name, detail, hint="": out.append((level, name, detail, hint))
+    # the hooks run the literal command `python`, so it must resolve to 3.10+ (on Windows the Store stub resolves but does not run)
+    py = system_python()
+    rc, ver = run_out([py, "-c", "import sys;print('%d.%d' % sys.version_info[:2])"]) if py else (1, "")
+    try:
+        ok = rc == 0 and tuple(int(x) for x in ver.split(".")) >= (3, 10)
+    except ValueError:
+        ok = False
+    if ok:
+        add("ok", "python on PATH", f"{ver} ({py})")
+    else:
+        add("fail", "python on PATH", f"{'found ' + py + ' but it does not run 3.10+' if py else 'not found'}",
+            "install Python 3.10+ and make sure the command `python` works (the hooks call exactly that)")
+    claude = shutil.which("claude")
+    if not claude:
+        add("fail", "claude CLI", "not found", "install Claude Code, or install the plugin by hand with /plugin inside it")
+    else:
+        rc, ver = run_out([claude, "--version"])
+        add("ok" if rc == 0 else "fail", "claude CLI", ver.splitlines()[0] if ver else claude, "" if rc == 0 else "reinstall Claude Code")
+        rc, listing = run_out([claude, "plugin", "list"])
+        if rc:
+            add("warn", "claude plugin", "`claude plugin` is not available", "update Claude Code, or use /plugin inside it")
+        else:
+            add("ok", "jev-tools plugin", "installed" if "jev-tools" in listing else "not installed yet (setup installs it)")
+    add("ok" if shutil.which("git") else "warn", "git", shutil.which("git") or "not found",
+        "" if shutil.which("git") else "review-precheck and rule-calibrate read git history; the other pieces work without it")
+    try:
+        socket.create_connection((HOST, 443), timeout=5).close()
+        add("ok", f"network to {HOST}", "reachable")
+    except OSError as e:
+        add("warn", f"network to {HOST}", str(e)[:60], "only the api backend needs it")
+    name, blackwell = gpu()
+    add("ok" if blackwell else "info", "GPU for local mode",
+        f"{name} (Blackwell-class)" if blackwell else f"{name} (not Blackwell-class: use api or offline)" if name else "no NVIDIA GPU: use api or offline")
+    add("ok" if shutil.which("docker") else "info", "docker for local mode", shutil.which("docker") or "not found (only needed for local)")
+    saved = read_config()
+    if saved.get("backend") == "local":
+        err = probe(saved.get("base_url") or LOCAL_URL, None)
+        add("ok" if not err else "warn", "local server", f"{saved.get('model')} at {saved.get('base_url')}" + ("" if not err else f": {err}"),
+            "" if not err else "start it with `jev-tools-setup serve` (small models) or docker compose (full model)")
+    cfg = home() / "config.json"
+    add("info", "setup state", f"config {'present' if cfg.exists() else 'absent'}, key file {'present' if (home() / 'credentials').exists() else 'absent'}, "
+        f"env key {'set' if os.environ.get('OPENJEV_API_KEY') or os.environ.get('TYPESAFE_API_KEY') else 'unset'}")
+    if os.environ.get("JEV_MODE"):
+        add("warn", "JEV_MODE env var", f"set to {os.environ['JEV_MODE']!r}", "it overrides the mode saved by setup; unset it to use the saved mode")
+    return out
+
+
+def check(_):
+    rows = checks()
+    tag = {"ok": "[ ok ]", "warn": "[warn]", "fail": "[FAIL]", "info": "[info]"}
+    for level, name, detail, hint in rows:
+        print(f"{tag[level]} {name:<22} {detail}" + (f"\n         -> {hint}" if hint and level in ("warn", "fail") else ""))
+    bad = sum(r[0] == "fail" for r in rows)
+    print(f"\n{'Ready to run: jev-tools-setup' if not bad else str(bad) + ' required check(s) failed: fix them, then run check again'}"
+          f" ({sum(r[0] == 'warn' for r in rows)} warning(s))")
+    return 1 if bad else 0
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] not in ("setup", "check", "serve", "report", "uninstall", "-h", "--help"):
+        argv.insert(0, "setup")  # bare `jev-tools-setup` means setup
+    ap = argparse.ArgumentParser(prog="jev-tools-setup")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("setup", help="install the plugin and configure the backend")
+    s.add_argument("--backend", choices=("api", "local", "offline"), help="skip the backend question")
+    s.add_argument("--mode", choices=("shadow", "active", "off"))
+    s.add_argument("--base-url", help="local server URL (default %s)" % LOCAL_URL)
+    s.add_argument("--model", choices=("verdict-1.4", "laya-1.0", "openjev-latest"), help="local model, skips the question")
+    s.add_argument("--yes", action="store_true", help="do not ask before downloading/installing the local model")
+    s.add_argument("--key-stdin", action="store_true", help="read the API key from one line of stdin")
+    s.add_argument("--skip-plugin", action="store_true", help="do not call the claude CLI")
+    s.set_defaults(fn=setup)
+    sv = sub.add_parser("serve", help="run the local small model (verdict-1.4 or laya-1.0) in the foreground")
+    sv.add_argument("--device", choices=("cpu", "cuda"), help="force the device (default: GPU if PyTorch sees one)")
+    sv.set_defaults(fn=serve)
+    sub.add_parser("report", help="write ~/.jev-tools/LOG.md: what happened and what is wrong").set_defaults(fn=report)
+    sub.add_parser("check", help="read-only check of everything setup needs").set_defaults(fn=check)
+    sub.add_parser("uninstall", help="remove ~/.jev-tools").set_defaults(fn=uninstall)
+    a = ap.parse_args(argv)
+    return a.fn(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

jev_tools_setup-0.3.0.dist-info/METADATA

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: jev-tools-setup
+Version: 0.3.0
+Summary: One-command installer for the jev-tools Claude Code plugin: pick the OpenJev (Codiv) API, a local model, or offline mode.
+Author-email: Rcidshacker <ruchitdas36@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Rcidshacker/jev-tools
+Project-URL: Issues, https://github.com/Rcidshacker/jev-tools/issues
+Project-URL: Changelog, https://github.com/Rcidshacker/jev-tools/blob/main/CHANGELOG.md
+Keywords: claude-code,openjev,codiv,plugin,installer
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+# jev-tools
+
+**Let a tiny decision model make the cheap, frequent judgments, so Claude doesn't have to.**
+
+A [Claude Code](https://code.claude.com) plugin for the terminal and the desktop app.
+Does this edit break a project rule? Which skill fits this prompt? Which file matters? Does this diff need a careful review?
+
+[![PyPI](https://img.shields.io/pypi/v/jev-tools-setup?label=jev-tools-setup)](https://pypi.org/project/jev-tools-setup/)
+![License MIT](https://img.shields.io/badge/license-MIT-green)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+![stdlib only](https://img.shields.io/badge/dependencies-none-lightgrey)
+![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-d97757)
+![shadow-first](https://img.shields.io/badge/ships%20in-shadow%20mode-orange)
+
+[Quick start](#-quick-start) · [Choose a backend](#-choose-how-jev-runs) · [What's inside](#-whats-inside) · [Privacy](#-privacy-what-leaves-your-machine) · [Troubleshooting](#-when-something-looks-wrong) · [Reference](#-reference)
+
+</div>
+
+---
+
+jev-tools asks **OpenJev** ([Codiv](https://codiv.ai) "System One") typed questions (yes/no, pick-one, score) and gets calibrated probabilities back instead of generated text. There is nothing to parse and nothing to hallucinate; your own code applies the thresholds. It runs against the **hosted API**, a **model on your own machine**, or in an **offline** pattern-only mode.
+
+> [!IMPORTANT]
+> **Early and shadow-first.** Everything was built and measured against a live Codiv key (numbers in [MEASUREMENTS.md](https://github.com/Rcidshacker/jev-tools/blob/main/docs/MEASUREMENTS.md)), but the samples are small and OpenJev is a young model. The plugin ships in **shadow mode**: hooks only *log* what they would have done. Nothing blocks or injects until you switch to `active`.
+> Independent project, not affiliated with Codiv, OpenJev or TypeSafe AI.
+
+Write-up with the numbers, failures and privacy notes: [I built a Claude Code plugin around a model that only answers yes/no](https://dev.to/rcids/i-built-a-claude-code-plugin-around-a-model-that-only-answers-yesno-what-worked-what-failed-1ecj) · feedback welcome in [issue #1](https://github.com/Rcidshacker/jev-tools/issues/1).
+
+## 🚀 Quick start
+
+**You need:** Python 3.10+ as the command `python` (the hooks call exactly that), the [`claude` CLI](https://code.claude.com), and [`uv`](https://docs.astral.sh/uv/) or `pipx`.
+
+```bash
+# 1. install the setup tool (once)
+uv tool install jev-tools-setup          # or: pipx install jev-tools-setup
+
+# 2. optional, read-only: is this machine ready?
+jev-tools-setup check
+
+# 3. install the plugin and choose how Jev runs
+jev-tools-setup
+```
+
+Setup installs the skills, scripts and hooks through Claude Code (so **terminal and desktop share one install**), asks which backend you want, validates it, and finishes by writing `~/.jev-tools/LOG.md`. **Restart Claude Code**, then run the `status` skill to confirm everything is wired.
+
+> Prefer a one-shot run without installing anything? `uvx jev-tools-setup check` and `uvx jev-tools-setup` work too. To run the latest unreleased code straight from GitHub, use `uvx --from git+https://github.com/Rcidshacker/jev-tools jev-tools-setup`.
+
+<details>
+<summary><b>No uv or pipx? Install the plugin by hand</b></summary>
+
+Inside Claude Code:
+
+```text
+/plugin marketplace add Rcidshacker/jev-tools
+/plugin install jev-tools@jev-tools
+```
+
+Then give it a key (or a local server) yourself, see [Reference](#-reference). Try it for one session without installing: `claude --plugin-dir /path/to/jev-tools`.
+
+</details>
+
+## 🔀 Choose how Jev runs
+
+| | **`api`** | **`local`** | **`offline`** |
+|---|---|---|---|
+| **What it is** | Hosted OpenJev at `api.codiv.ai` | A model on your machine | No model, pattern fallbacks |
+| **Best for** | Best accuracy, zero setup beyond a key | Privacy, no key, no quota | Plugin installed but nothing sent anywhere |
+| **Needs** | A free [Codiv key](https://codiv.ai/dashboard) (100M input tokens) | Verdict/Laya: any CPU or GPU. Full OpenJev: NVIDIA Blackwell-class GPU + Docker | Nothing |
+| **Leaves your machine** | Diffs, prompts, rules (see [Privacy](#-privacy-what-leaves-your-machine)) | Nothing (weights download once from Hugging Face) | Nothing |
+| **Model quality** | Full OpenJev (all measurements below) | Verdict and Laya are **small and unmeasured here** | n/a |
+
+<details>
+<summary><b>api</b>: paste a key, it is checked and stored safely</summary>
+
+Setup asks for your key in a **hidden prompt**, validates it with one live call, and stores it in `~/.jev-tools/credentials` with owner-only permissions (`chmod 600`, or `icacls` on Windows). A rejected key saves nothing. The key is never passed on a command line and never logged.
+
+</details>
+
+<details>
+<summary><b>local</b>: Verdict 151M, Laya 421M, or the full OpenJev model</summary>
+
+Setup asks which model:
+
+| Model | Size | Context | Options | Notes |
+|---|---|---|---|---|
+| `verdict-1.4` | 151M | 512 tokens | up to 24 | Smallest. Ignores a yes/no question's `criteria`. Runs on CPU or any GPU |
+| `laya-1.0` | 421M | 1,024 tokens | about 20 | Heavier. Runs on CPU or any GPU |
+| `openjev-latest` | 26B | 65,536 tokens | 255 | Needs an NVIDIA **Blackwell-class** GPU (NVFP4) and Docker ([self-hosting guide](https://codiv.ai/docs/guides/self-hosting)) |
+
+For Verdict/Laya, setup shows the plan and the download size, waits for your **yes**, then clones [OpenJev](https://github.com/razorback16/openjev) into `~/.jev-tools`, creates a venv and installs the model's extra (PyTorch comes with it and can be several GB; weights are about 0.6 GB / 1.7 GB as fp32). Start the server in its own terminal and keep it open:
+
+```bash
+jev-tools-setup serve        # add --device cpu to force the CPU
+```
+
+**What changes with a small model.** Each question is read with its own copy of the state, cut from the end at the model's window. jev-tools therefore trims long diffs and file excerpts to fit, sends fewer files per `find-files` request, caps option lists (23 for Verdict, 19 for Laya, so `browser-nav` sees fewer elements) and declines a question it cannot shrink. `review-precheck` will mostly say "full review" because its diff is usually cut. **All thresholds and measurements come from the full OpenJev model**, so keep small models in `shadow` and run the `rule-calibrate` skill before switching to `active`.
+
+> [!NOTE]
+> The small-model install follows OpenJev's documented steps but is new in 0.3.0 and has not been measured on real projects yet.
+
+</details>
+
+<details>
+<summary><b>offline</b>: "offline" means no model, not no internet</summary>
+
+Nothing is sent anywhere. Deterministic fallbacks still run, and each says what it cannot do:
+
+| Piece | Offline behaviour |
+|---|---|
+| `review-precheck` | Regex checks for secrets, dependency files, auth keywords, schema/migration changes, test weakening and swallowed errors. Says "fast" **only** for a small (30 lines or fewer) clean diff |
+| Rule hook | Blocks only a **literal token** that a "never / don't / avoid X" rule forbids (e.g. `console.log`). No judgment |
+| Skill hook | Picks by keyword match |
+| `find-files` | Ranks by keyword count (in our measurements the model was no better, see below) |
+| `browser-nav` | Suggests the element whose name matches the goal, always marked *unsure* |
+| `rule-calibrate` | Unavailable: it needs a model, and says so |
+
+These are patterns, not understanding. They miss anything phrased unusually, so keep offline in `shadow`.
+
+</details>
+
+## 🧰 What's inside
+
+| Piece | Kind | What it does |
+|---|---|---|
+| **Rule hook** `rule_enforcer.py` | `PreToolUse` on `Edit\|Write\|MultiEdit` | Reads your `CLAUDE.md` / `AGENTS.md` rules, asks whether the pending edit breaks one, re-checks any hit with a stricter question, and in `active` mode blocks the write with the rule it broke |
+| **Skill hook** `skill_picker.py` | `UserPromptSubmit` (**opt-in**) | Picks the one installed skill that fits your prompt, confirms it, and in `active` mode adds a one-line pointer to the context |
+| `find-files` | skill | Keyword candidates, then two-stage scoring, prints the most relevant files. A hint, not an oracle |
+| `browser-nav` | skill | Picks each next click from the page's interactive elements; Claude executes and judges pass/fail |
+| `review-precheck` | skill | Seven yes/no policy questions on a git diff decide *fast pass* vs *full review* |
+| `rule-calibrate` | skill | Replays recent commits against your rules: which are decisive, noisy, weak or quiet, *before* you enforce anything |
+| `status` | skill | One screen: backend, key found (by name), mode, hook state, recent events and errors |
+| `report` | skill | Writes the plain-English [`LOG.md`](#-when-something-looks-wrong) |
+
+## ⚙️ How it works
+
+```mermaid
+flowchart LR
+    A["Claude Code event<br/>edit · prompt · skill"] --> B["jev-tools script"]
+    B --> C{"backend"}
+    C -->|api| D["api.codiv.ai"]
+    C -->|local| E["Verdict · Laya · OpenJev<br/>127.0.0.1:8080"]
+    C -->|offline| F["keyword and pattern<br/>fallbacks"]
+    D --> G["typed answers<br/>yes/no · pick · score"]
+    E --> G
+    G --> H["thresholds in plain code"]
+    F --> H
+    H --> I{"mode"}
+    I -->|shadow| J["log only"]
+    I -->|active| K["block or inject"]
+```
+
+Each piece turns a fuzzy judgment into typed questions, sends them with the relevant text as `state` to `POST /v1/systemone`, and applies thresholds in ordinary code. **Every failure path is explicit:** hooks **fail open** (an outage never blocks your edit or prompt) and the review pre-check **fails safe** (an outage routes to full review). Details and the reasoning behind each threshold: [HOW_IT_WORKS.md](https://github.com/Rcidshacker/jev-tools/blob/main/docs/HOW_IT_WORKS.md).
+
+### Modes
+
+| Mode | Rule hook | Skill hook |
+|---|---|---|
+| `shadow` (default) | logs the verdict, never blocks | logs the pick, injects nothing |
+| `active` | blocks an edit flagged at ≥ 0.80 **and** confirmed at ≥ 0.70 | injects `Jev skill pick: <name>` (if enabled) |
+| `off` | does nothing, makes no call | does nothing |
+
+**Recommended path:** run in `shadow` for a week, read `LOG.md`, run `rule-calibrate` on a project, then switch that setup to `active`. Set the mode with the plugin's `mode` option or `JEV_MODE` (the variable wins).
+
+## 🔒 Privacy: what leaves your machine
+
+With the **`api`** backend this plugin sends text to a third party (`api.codiv.ai`). **`local` and `offline` send nothing.** Read this before enabling `api` on any project.
+
+| Piece | What is sent (api only) |
+|---|---|
+| Rule hook (every `Edit`/`Write`) | file name, the unified diff (up to 8,000 characters) and the text of your project rules |
+| Skill hook (**opt-in**, every prompt) | your prompt, plus the names and descriptions of your installed skills |
+| `find-files` | the query and short excerpts of candidate files |
+| `review-precheck` / `rule-calibrate` | the git diff (up to 30k characters) / recent commit hunks |
+| `browser-nav` | the goal, the URL and the names of the page's interactive elements |
+
+- **Shadow mode still sends.** The hook needs the model's answer to log it. Only `mode: off` sends nothing.
+- **A local seatbelt runs first.** Before sending, these become `[REDACTED]`: private-key blocks, vendor-style keys (`sk-`/`sk_live_`, AWS, Google, GitHub, Slack, npm), JWTs, `Bearer` tokens, credentials in connection strings, assignments to names containing password/secret/token/api key, and long hex or base64-looking strings. Files named like secrets (`.env*`, `*.pem`, `*.key`, `id_rsa*`, `credentials*`, `secrets*` …) are never read into a request. It is a pattern match: a bare token in an unusual shape, **names, emails, customer or employee records and internal business data are not caught**, and about 0.2% of ordinary code lines that mention `token`/`secret` get partly redacted. Risk reduction, not a guarantee.
+- **Retention is unknown to us.** Codiv's public API docs say nothing about how request data is stored or used. Check their terms before sending anything you would not paste into a public forum.
+- **Nothing sensitive is stored locally.** The decision log holds verdicts, probabilities, latency and token counts, never file contents and never the key.
+
+Turn it off for one project (regulated, customer, employee or client data) in that project's `.claude/settings.local.json`:
+
+```json
+{ "env": { "JEV_MODE": "off" } }
+```
+
+## 🩺 When something looks wrong
+
+`jev-tools-setup` always ends by writing **`~/.jev-tools/LOG.md`**, even when setup fails. Refresh it any time with `jev-tools-setup report`, or run the **`report` skill** inside Claude Code. It merges every decision log (the plugin data directory and `~/.jev-tools`) into plain English:
+
+- a one-line **health verdict**: ✅ healthy · ⚠️ notes · ❌ problems
+- your **setup**: backend, model, mode, which variable the key came from (never the key), which logs were read
+- **problems, each with a fix**
+- **what happened**: event counts, median latency, rule checks flagged
+- your **setup history** and the **last 40 events**, one sentence each
+
+It contains no API key, file contents or prompts; home paths show as `~` and key-shaped strings are redacted, so it is **safe to attach to an issue**.
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Hooks do nothing and nothing is logged | `JEV_MODE=off` (the variable beats the saved mode), or Claude Code was not restarted | Unset `JEV_MODE`, restart Claude Code |
+| `status` says the key is **MISSING** | No key in the environment, plugin option or credentials file | `jev-tools-setup`, choose `api` |
+| 401 / 403 in `LOG.md` | Key rejected | New key at [codiv.ai/dashboard](https://codiv.ai/dashboard), re-run setup |
+| 429 in `LOG.md` | Quota or rate limit (quota errors are not retried) | Wait, or check usage on the dashboard |
+| `python` not found, or opens the Microsoft Store | The hooks call the literal command `python` | Install Python 3.10+; `jev-tools-setup check` tests it |
+| Local server not answering | It is not running, or still loading weights | `jev-tools-setup serve` |
+| Bad edits are never blocked | You are in `shadow` (the default) | Calibrate, then switch to `active` |
+| `review-precheck` always says "full" | Offline backend, a small model cutting the diff, or an outage | `LOG.md` says which |
+
+Hooks **fail open**, so a broken install looks identical to a working one until you look at the log. That is exactly what `LOG.md` and the `status` skill are for. To remove everything: `jev-tools-setup uninstall` deletes `~/.jev-tools` (key, config, log); remove the plugin with `/plugin uninstall jev-tools@jev-tools`.
+
+## 📚 Reference
+
+<details>
+<summary><b>Giving it a key by hand</b></summary>
+
+Any one of these, never in a repo. Lookup order: environment, plugin option, then the setup credentials file.
+
+- **Environment variable:** a user-level `OPENJEV_API_KEY`. Windows: `setx OPENJEV_API_KEY "sk-codiv-..."` then restart Claude Code. macOS/Linux: export it in your shell profile.
+- **Plugin option:** Claude Code prompts for the `api_key` setting and stores it as sensitive.
+- **`jev-tools-setup`:** writes the owner-only credentials file for you.
+
+Do not put the key in `settings.json`, `CLAUDE.md` or any file in a repo. The client only sends it to `api.codiv.ai` (or loopback), refuses redirects and never logs it. `python scripts/jevlib.py` makes one live call and prints `OK`.
+
+</details>
+
+<details>
+<summary><b>Environment variables</b></summary>
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `OPENJEV_API_KEY` | none | API key (also `TYPESAFE_API_KEY`, or the plugin's `api_key` option) |
+| `OPENJEV_BASE_URL` | `https://api.codiv.ai` | Must be `api.codiv.ai` or loopback |
+| `JEV_MODE` | `shadow` | `shadow`, `active` or `off`; overrides the saved mode |
+| `JEV_SKILL_PICKER` | off | `1` enables the skill hook (also the `skill_picker` option) |
+| `JEV_THRESHOLD` | `0.80` | Rule-violation probability that can block |
+| `JEV_CONFIRM` | `0.70` | Second-look probability required to block |
+| `JEV_SKILL_MIN` | `0.60` | Minimum probability to inject a skill pick |
+| `JEV_PRECHECK_MIN` | `0.25` | Yes-probability that flags a diff for full review |
+| `JEV_LOG` | plugin data dir | Where decisions are appended (JSONL) |
+
+</details>
+
+<details>
+<summary><b>Files jev-tools writes</b></summary>
+
+| File | Holds |
+|---|---|
+| `~/.jev-tools/config.json` | `backend`, `model`, `base_url` (local only), `mode` |
+| `~/.jev-tools/credentials` | your API key, owner-only |
+| `~/.jev-tools/log.jsonl` and the plugin data dir's `log.jsonl` | one JSON line per decision: verdict, probability, latency, token counts |
+| `~/.jev-tools/LOG.md` | the plain-English report built from the logs |
+| `~/.jev-tools/openjev`, `~/.jev-tools/venv` | local small-model install |
+
+</details>
+
+<details>
+<summary><b>What we measured</b> (full OpenJev, small samples, live against Codiv)</summary>
+
+All reproducible from the scripts; method and caveats in [MEASUREMENTS.md](https://github.com/Rcidshacker/jev-tools/blob/main/docs/MEASUREMENTS.md).
+
+| Component | Result |
+|---|---|
+| Rule enforcer | 4 of 4 planted violations blocked, 4 of 4 clean edits allowed after the second-look check was added; also blocked and allowed correctly inside real headless Claude Code sessions |
+| Skill picker | 3 of 3 correct on a large real skill roster (two matches, one correct "none") |
+| Review pre-check | benign rename routed *fast*; a diff with a hardcoded key, swallowed exception and emptied tests routed *full* with the right flags |
+| Browser navigator | 5 of 5 steps correct on a synthetic login flow (never run against a real browser) |
+| File discovery | **no better than plain keyword counting** on 8 labelled queries (top-3 hits 4 to 6 of 8 vs 4 of 8); repeat runs differ by up to 2 |
+| Cost and speed | about 1 s per prompt or edit, 2 s when a violation is confirmed; about 5k input tokens per edit at 20 rules |
+
+Not measured: the small local models (Verdict, Laya) and the offline fallbacks on real projects.
+
+</details>
+
+<details>
+<summary><b>Repository layout</b></summary>
+
+```text
+.claude-plugin/plugin.json       plugin manifest and user settings (api_key, mode, skill_picker)
+.claude-plugin/marketplace.json  single-plugin marketplace so /plugin marketplace add works
+installer/jev_tools_cli.py       the jev-tools-setup command (setup, check, serve, report, uninstall)
+installer/jev_report.py          builds LOG.md (also run by the report skill)
+hooks/hooks.json                 the two hooks
+scripts/                         jevlib.py (client) and one script per piece, review_policy.json
+skills/<name>/SKILL.md           six skills
+tests/test_all.py                offline suite against a local mock of /v1/systemone
+docs/                            how it works, measurements, build log, Codiv API notes
+pyproject.toml                   packages the installer as jev-tools-setup
+```
+
+</details>
+
+## 🛠️ Development
+
+```bash
+python tests/test_all.py          # offline suite, no network, no key needed
+python scripts/jevlib.py          # one live call, needs OPENJEV_API_KEY
+uv build                          # builds the jev-tools-setup wheel and sdist
+# releases: publishing a GitHub release runs .github/workflows/publish.yml (PyPI trusted publishing, no token)
+```
+
+The tests spin up a local server that mimics `/v1/systemone`, so they prove the logic and the wire format, not OpenJev's accuracy. Accuracy claims come only from the live runs recorded in the docs. See the [CHANGELOG](https://github.com/Rcidshacker/jev-tools/blob/main/CHANGELOG.md) for what changed in each version.
+
+## 🙏 Credits
+
+Ideas and hard-won numbers borrowed, with thanks, from projects that got there first (exactly what was taken from each: [BUILD_LOG.md](https://github.com/Rcidshacker/jev-tools/blob/main/docs/BUILD_LOG.md)):
+[abide](https://github.com/coldteadotai/abide) (rule compilation, calibration verdicts, second look) ·
+[hermes-jev-skills](https://github.com/kerpopule/hermes-jev-skills) (confidence floor, two-stage retrieval) ·
+[jev-kit](https://github.com/jonathanavis96/jev-kit) (shadow-first rollout) ·
+[jevgate](https://github.com/Tech-Byte-Frontier/jevgate) (confirming before acting) ·
+[jev-skill-router](https://github.com/shimo4228/jev-skill-router) (plugin layout, honest field report on skill routing).
+The small local models are [Verdict](https://github.com/Heman10x-NGU/Verdict-open-jev) by Heman10x and [Laya](https://github.com/NandhaKishorM/laya) by Nandakishor M / Convai Innovations, served by [OpenJev](https://github.com/razorback16/openjev).
+
+Built with [Claude Code](https://claude.com/claude-code). MIT licensed, see [LICENSE](https://github.com/Rcidshacker/jev-tools/blob/main/LICENSE).

jev_tools_setup-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+jev_report.py,sha256=LrsxV90yexnrN_WWNTSjpWsroCidb3V99lXgr8h0hz0,14297
+jev_tools_cli.py,sha256=38Bc_DRTfygoDx_JRJMJo3oz3mZmNymxS3R4k8W3na0,21793
+jev_tools_setup-0.3.0.dist-info/licenses/LICENSE,sha256=obggFVbV9pdR4lZqO0Q_HmdGBuBnqnUETIuLKf_NriA,1079
+jev_tools_setup-0.3.0.dist-info/METADATA,sha256=3MZ4EzbxZjjPCg54zY_CfcRlcfY6BMxwYCw86tTPuAk,21610
+jev_tools_setup-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+jev_tools_setup-0.3.0.dist-info/entry_points.txt,sha256=6sIci6yrkypDdKQeEV2wnRIi1vygP8yjUD8mn9VXFOg,55
+jev_tools_setup-0.3.0.dist-info/top_level.txt,sha256=w2qIGmmsq6xQHDaKnWcB2hU8ZcNfnes0J9yF7-W6GM8,25
+jev_tools_setup-0.3.0.dist-info/RECORD,,

jev_tools_setup-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jev_tools_setup-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jev-tools-setup = jev_tools_cli:main

jev_tools_setup-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jev-tools contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jev_tools_setup-0.3.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+jev_report
+jev_tools_cli