strayguard 0.1.0__py3-none-any.whl

strayguard/__init__.py

@@ -0,0 +1,8 @@
+"""strayguard: catch files that do not belong before you commit them."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("strayguard")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

strayguard/cli.py

@@ -0,0 +1,142 @@
+"""Command line: install, uninstall and check (SPEC 6, 7.11)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+
+from . import __version__, decide, evidence, git, jev, rules, ui
+
+MARKER = "# strayguard"
+HOOK = """#!/bin/sh
+# strayguard
+exe="{exe}"
+[ -x "$exe" ] || exe="$(command -v strayguard)" || exit 0
+exec "$exe" check
+"""
+
+
+def check() -> int:
+    """Run the full check on the staged new files. Return the exit code."""
+    if os.environ.get("STRAYGUARD", "on").lower() == "off":
+        return 0
+
+    new_files = git.new_files()
+    if not new_files:
+        return 0
+
+    model = os.environ.get("STRAYGUARD_MODEL", jev.DEFAULT_MODEL)
+    store = decide.Store(git.state_dir(), model, jev.PROMPT_VERSION)
+    new_files = [f for f in new_files if f.blob not in store.kept]
+    items, total, repo = evidence.build_items(new_files)
+    if total > len(items):
+        ui.note(f"checked {len(items)} of {total} new items.")
+
+    verdicts, to_ask = [], []
+    for item in items:
+        category = rules.match(item.path)
+        if category:
+            verdicts.append(decide.Verdict(item, category, None))
+        else:
+            to_ask.append(item)
+
+    answers = {}
+    for item in to_ask:
+        cached = store.cached_answer(item)
+        if cached:
+            answers[item.key] = cached
+    missing = [item for item in to_ask if item.key not in answers]
+    if missing:
+        fresh = ask_jev(missing, repo, model)
+        store.remember(fresh)
+        answers.update(fresh)
+
+    verdicts += decide.decide(to_ask, answers, decide.threshold_from_env())
+    if not verdicts:
+        return 0
+    return act(verdicts, store)
+
+
+def ask_jev(items: list, repo: list[str], model: str) -> dict:
+    """Ask Jev. On any failure, show one line and return no answers (fail open)."""
+    api_key = os.environ.get("TYPESAFE_API_KEY")
+    if not api_key:
+        ui.note("no TYPESAFE_API_KEY set, so only the local rules ran.")
+        return {}
+    try:
+        return jev.ask(items, repo, api_key, model)
+    except jev.JevError as error:
+        ui.note(f"{error}, so only the local rules ran.")
+        return {}
+
+
+def act(verdicts: list, store: decide.Store) -> int:
+    """Show the verdicts and do what the user chooses (SG-60 to SG-73)."""
+    if not ui.can_prompt():
+        strict = os.environ.get("STRAYGUARD_STRICT") == "1"
+        ui.warn(verdicts, blocking=strict)
+        return 1 if strict else 0
+
+    choices = ui.prompt(verdicts)
+    store.keep(v.item for v in choices["k"])
+    if choices["g"]:
+        git.add_to_gitignore([v.item for v in choices["g"]])
+    removed = choices["u"] + choices["g"]
+    if removed:
+        git.unstage([v.item.path for v in removed])
+    ui.report(choices)
+    return 1 if removed else 0
+
+
+def install() -> int:
+    hook = git.hooks_dir() / "pre-commit"
+    if hook.exists() and MARKER not in hook.read_text(errors="replace"):
+        print(f"{hook} already exists. Add this line to it:\n  strayguard check")
+        return 1
+    exe = shutil.which("strayguard") or os.path.abspath(sys.argv[0])
+    hook.parent.mkdir(parents=True, exist_ok=True)
+    hook.write_text(HOOK.format(exe=exe))
+    hook.chmod(0o755)
+    print(f"✓ strayguard installed in {hook}")
+    return 0
+
+
+def uninstall() -> int:
+    hook = git.hooks_dir() / "pre-commit"
+    if hook.exists() and MARKER in hook.read_text(errors="replace"):
+        hook.unlink()
+        print(f"✓ strayguard removed from {hook}")
+    else:
+        print("strayguard hook not found. Nothing to remove.")
+    return 0
+
+
+COMMANDS = {"install": install, "uninstall": uninstall, "check": check}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="strayguard",
+        description="Catch files that do not belong before you commit them.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("install", help="add the pre-commit hook to this repository")
+    commands.add_parser("uninstall", help="remove the pre-commit hook")
+    commands.add_parser("check", help="check the staged new files (the hook runs this)")
+    args = parser.parse_args(argv)
+
+    try:
+        return COMMANDS[args.command]()
+    except KeyboardInterrupt:
+        return 130
+    except git.GitError as error:
+        ui.note(str(error))
+        return 0 if args.command == "check" else 1
+    except Exception as error:
+        if args.command != "check":
+            raise
+        ui.note(f"internal error ({error!r}), check skipped.")
+        return 0

strayguard/decide.py

@@ -0,0 +1,103 @@
+"""Decide which items to flag, and remember answers and kept files (SPEC 7.6, 7.7)."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+BELONGS = "belongs"
+DEFAULT_THRESHOLD = 0.70
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """One flagged item. `probability` is None when a local rule flagged it."""
+
+    item: object
+    category: str
+    probability: float | None
+
+
+def threshold_from_env() -> float:
+    """Read STRAYGUARD_THRESHOLD (SG-47). Use the default for a bad value."""
+    try:
+        value = float(os.environ.get("STRAYGUARD_THRESHOLD", DEFAULT_THRESHOLD))
+    except ValueError:
+        return DEFAULT_THRESHOLD
+    return value if 0.0 < value <= 1.0 else DEFAULT_THRESHOLD
+
+
+def is_flagged(answer: dict, threshold: float) -> bool:
+    """SG-46: flag when the selected option is not `belongs` and is likely enough."""
+    choice = answer.get("choice")
+    probability = answer.get("probabilities", {}).get(choice, 0.0)
+    return choice != BELONGS and probability >= threshold
+
+
+def decide(items: list, answers: dict, threshold: float) -> list[Verdict]:
+    """Turn Jev answers into verdicts. Items without an answer are not flagged."""
+    verdicts = []
+    for item in items:
+        answer = answers.get(item.key)
+        if answer and is_flagged(answer, threshold):
+            choice = answer["choice"]
+            verdicts.append(Verdict(item, choice, answer["probabilities"][choice]))
+    return verdicts
+
+
+class Store:
+    """The kept list and the answer cache in .git/strayguard/ (SG-50 to SG-54)."""
+
+    def __init__(self, state_dir: Path, model: str, prompt_version: str):
+        self.dir = state_dir
+        self.kept_file = state_dir / "kept"
+        self.cache_file = state_dir / "cache.json"
+        self.suffix = f":{model}:{prompt_version}"
+        self.kept = self._read_kept()
+        self.cache = self._read_cache()
+
+    def _read_kept(self) -> set[str]:
+        try:
+            return set(self.kept_file.read_text().split())
+        except OSError:
+            return set()
+
+    def _read_cache(self) -> dict:
+        try:
+            data = json.loads(self.cache_file.read_text())
+        except FileNotFoundError:
+            return {}
+        except (OSError, ValueError):
+            data = None
+        if not isinstance(data, dict):
+            self.cache_file.unlink(missing_ok=True)
+            return {}
+        return data
+
+    def cached_answer(self, item) -> dict | None:
+        return self.cache.get(item.key + self.suffix)
+
+    def remember(self, answers: dict) -> None:
+        for key, answer in answers.items():
+            self.cache[key + self.suffix] = {
+                "choice": answer["choice"],
+                "probabilities": answer["probabilities"],
+            }
+        self._write(self.cache_file, json.dumps(self.cache))
+
+    def keep(self, items) -> None:
+        for item in items:
+            self.kept.update(item.blob_ids)
+        self._write(self.kept_file, "".join(f"{blob}\n" for blob in sorted(self.kept)))
+
+    def _write(self, path: Path, text: str) -> None:
+        """Write to a temporary file first, so a stopped commit never leaves half a file."""
+        try:
+            self.dir.mkdir(parents=True, exist_ok=True)
+            temporary = path.with_name(path.name + ".tmp")
+            temporary.write_text(text)
+            os.replace(temporary, path)
+        except OSError:
+            pass

strayguard/evidence.py

@@ -0,0 +1,105 @@
+"""Make the items that strayguard sends to Jev (SPEC 7.2, 7.4)."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import posixpath
+from dataclasses import dataclass, field
+
+from . import git, rules
+
+ROLL_UP_ABOVE = 10
+MAX_ITEMS = 100
+MAX_CONTENT_BYTES = 1_000_000
+BINARY_SCAN_BYTES = 8_000
+HEAD_LINES = 40
+HEAD_CHARS = 2_000
+SAME_FOLDER_NAMES = 10
+TOP_LEVEL_NAMES = 30
+FOLDER_SAMPLE = 5
+
+
+@dataclass
+class Item:
+    path: str
+    key: str
+    blob_ids: tuple
+    is_folder: bool = False
+    evidence: dict = field(default_factory=dict)
+
+
+def _parents(path: str) -> list[str]:
+    """All parent folders, highest first: 'a/b/c.txt' gives ['a/', 'a/b/']."""
+    parts = path.split("/")[:-1]
+    return ["/".join(parts[: i + 1]) + "/" for i in range(len(parts))]
+
+
+def build_items(new_files: list) -> tuple[list[Item], int, list[str]]:
+    """Return (items, total number of items, repo top-level names)."""
+    new_paths = {f.path for f in new_files}
+    tracked = [p for p in git.tracked_files() if p not in new_paths]
+    tracked_folders = {folder for p in tracked for folder in _parents(p)}
+
+    counts: dict[str, int] = {}
+    for f in new_files:
+        for folder in _parents(f.path):
+            counts[folder] = counts.get(folder, 0) + 1
+
+    groups: dict[str, list] = {}
+    singles = []
+    for f in new_files:
+        folder = next((d for d in _parents(f.path)
+                       if d not in tracked_folders and counts[d] > ROLL_UP_ABOVE), None)
+        if folder:
+            groups.setdefault(folder, []).append(f)
+        else:
+            singles.append(f)
+
+    items = [_folder_item(folder, files) for folder, files in groups.items()]
+    items += _file_items(singles, tracked)
+    items.sort(key=lambda item: item.path)
+    return items[:MAX_ITEMS], len(items), _top_level(tracked)
+
+
+def _folder_item(folder: str, files: list) -> Item:
+    """SG-11: one item for a whole new folder."""
+    blobs = tuple(sorted(f.blob for f in files))
+    key = "folder:" + hashlib.sha1(" ".join(blobs).encode()).hexdigest()
+    sample = sorted(f.path for f in files)[:FOLDER_SAMPLE]
+    evidence = {"path": folder, "kind": "folder", "new_files": len(files), "sample": sample}
+    return Item(folder, key, blobs, is_folder=True, evidence=evidence)
+
+
+def _file_items(files: list, tracked: list[str]) -> list[Item]:
+    names_only = os.environ.get("STRAYGUARD_NAMES_ONLY") == "1"
+    sizes = git.blob_sizes([f.blob for f in files]) if files else {}
+    readable = [f.blob for f in files
+                if not names_only and not rules.match(f.path) and sizes[f.blob] <= MAX_CONTENT_BYTES]
+    contents = git.read_blobs(readable)
+
+    items = []
+    for f in files:
+        evidence = {"path": f.path, "size_bytes": sizes[f.blob],
+                    "same_folder": _same_folder(f.path, tracked)}
+        data = contents.get(f.blob)
+        if data is not None:
+            evidence["binary"] = b"\0" in data[:BINARY_SCAN_BYTES]
+            if not evidence["binary"]:
+                lines = data.decode(errors="replace").splitlines()[:HEAD_LINES]
+                evidence["head"] = "\n".join(lines)[:HEAD_CHARS]
+        items.append(Item(f.path, f.blob, (f.blob,), evidence=evidence))
+    return items
+
+
+def _same_folder(path: str, tracked: list[str]) -> list[str]:
+    """SG-34: names of tracked files next to this file."""
+    folder = posixpath.dirname(path)
+    names = sorted(posixpath.basename(p) for p in tracked if posixpath.dirname(p) == folder)
+    return names[:SAME_FOLDER_NAMES]
+
+
+def _top_level(tracked: list[str]) -> list[str]:
+    """SG-35: tracked top-level files and folders. Folders end with '/'."""
+    names = {p.split("/")[0] + ("/" if "/" in p else "") for p in tracked}
+    return sorted(names)[:TOP_LEVEL_NAMES]

strayguard/git.py

@@ -0,0 +1,115 @@
+"""All git calls (SPEC 7.1, 7.8, 7.11). No other module runs git."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+SUBMODULE_MODE = "160000"
+
+
+class GitError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class NewFile:
+    path: str
+    blob: str
+
+
+def _run(*args: str, input: bytes | None = None, cwd: Path | None = None) -> bytes:
+    try:
+        result = subprocess.run(["git", *args], input=input, capture_output=True, cwd=cwd)
+    except FileNotFoundError:
+        raise GitError("git not found") from None
+    if result.returncode != 0:
+        message = result.stderr.decode(errors="replace").strip()
+        raise GitError(message or f"git {args[0]} failed")
+    return result.stdout
+
+
+@lru_cache(maxsize=None)
+def root() -> Path:
+    return Path(_run("rev-parse", "--show-toplevel").decode().strip())
+
+
+def _in_root(*args: str, input: bytes | None = None) -> bytes:
+    """Run git in the top folder, because staged paths are relative to it."""
+    return _run(*args, input=input, cwd=root())
+
+
+def new_files() -> list[NewFile]:
+    """SG-01, SG-02: staged files with status A. Renames and submodules are skipped."""
+    raw = _in_root("diff", "--cached", "--raw", "-z", "--no-abbrev",
+                   "--find-renames", "--diff-filter=A").decode(errors="surrogateescape")
+    fields = raw.split("\0")
+    files = []
+    for meta, path in zip(fields[0::2], fields[1::2]):
+        _, new_mode, _, blob, _ = meta.lstrip(":").split(" ")
+        if new_mode != SUBMODULE_MODE:
+            files.append(NewFile(path, blob))
+    return files
+
+
+def tracked_files() -> list[str]:
+    """All paths in the index. The caller removes the new files from this list."""
+    return [p for p in _in_root("ls-files", "-z").decode(errors="surrogateescape").split("\0") if p]
+
+
+def blob_sizes(blobs: list[str]) -> dict[str, int]:
+    out = _run("cat-file", "--batch-check", input="\n".join(blobs).encode() + b"\n")
+    sizes = {}
+    for line in out.decode().splitlines():
+        blob, _, size = line.split(" ")
+        sizes[blob] = int(size)
+    return sizes
+
+
+def read_blobs(blobs: list[str]) -> dict[str, bytes]:
+    """Read the staged content of many files with one git process."""
+    if not blobs:
+        return {}
+    out = _run("cat-file", "--batch", input="\n".join(blobs).encode() + b"\n")
+    contents, position = {}, 0
+    for blob in blobs:
+        header_end = out.index(b"\n", position)
+        size = int(out[position:header_end].split(b" ")[2])
+        contents[blob] = out[header_end + 1:header_end + 1 + size]
+        position = header_end + 1 + size + 1
+    return contents
+
+
+def state_dir() -> Path:
+    common = Path(_run("rev-parse", "--git-common-dir").decode().strip())
+    return common.resolve() / "strayguard"
+
+
+def hooks_dir() -> Path:
+    """`--git-path hooks` respects core.hooksPath (SPEC 7.11)."""
+    return Path(_run("rev-parse", "--git-path", "hooks").decode().strip()).resolve()
+
+
+def unstage(paths: list[str]) -> None:
+    """SG-64: remove the paths from the index only. The files stay on the disk."""
+    _in_root("rm", "--cached", "-r", "-f", "--quiet", "--", *paths)
+
+
+def _ignore_pattern(path: str) -> str:
+    escaped = "".join("\\" + c if c in "*?[\\" else c for c in path)
+    return "/" + escaped
+
+
+def add_to_gitignore(items: list) -> None:
+    """SG-65, SG-66: add one anchored line for each item, then stage .gitignore."""
+    gitignore = root() / ".gitignore"
+    text = gitignore.read_text() if gitignore.exists() else ""
+    present = set(text.splitlines())
+    new_lines = [p for p in (_ignore_pattern(i.path) for i in items) if p not in present]
+    if new_lines:
+        if text and not text.endswith("\n"):
+            text += "\n"
+        gitignore.write_text(text + "\n".join(new_lines) + "\n")
+    _in_root("add", "--", ".gitignore")

strayguard/jev.py

@@ -0,0 +1,118 @@
+"""The Jev request: batches, timeout and retry (SPEC 7.5, 7.10, 8)."""
+
+from __future__ import annotations
+
+import json
+import socket
+import time
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor, wait
+
+from . import __version__
+
+ENDPOINT = "https://api.typesafe.ai/v1/systemone"
+DEFAULT_MODEL = "jev-latest"
+PROMPT_VERSION = "1"
+BATCH_SIZE = 20
+PARALLEL_REQUESTS = 5
+REQUEST_TIMEOUT = 4.0
+TOTAL_TIMEOUT = 5.0
+RETRY_STATUSES = {429, 529}
+
+# SPEC 8.2. Keep `belongs` first: Jev prefers the first option a little.
+OPTIONS = {
+    "belongs": "Part of the project. Source code, tests in a test folder, documentation, "
+               "project config, lockfiles, fixtures, assets, and example files such as "
+               ".env.example. Generated code that the project commits on purpose also belongs.",
+    "scratch": "A temporary file for one person or one session. Throwaway scripts, quick "
+               "experiments, personal notes, copies such as file_old.py or file2.py, and "
+               "files that a coding agent left behind.",
+    "output-dump": "Output that a program wrote. Logs, debug dumps, stack traces, test "
+                   "results, profiling data, and exported data rows.",
+    "build-output": "Files that a tool can make again. Compiled files, bundles, caches, "
+                    "coverage reports, and dependency folders such as node_modules/.",
+    "local-only": "Settings for one machine or one person. Editor files, OS files, local "
+                  "environment files, personal config, and credentials.",
+}
+
+
+class JevError(Exception):
+    pass
+
+
+def ask(items: list, repo: list[str], api_key: str, model: str) -> dict:
+    """Ask one Choice question for each item. Return {item.key: answer}."""
+    deadline = time.monotonic() + TOTAL_TIMEOUT
+    batches = [items[i:i + BATCH_SIZE] for i in range(0, len(items), BATCH_SIZE)]
+    pool = ThreadPoolExecutor(max_workers=PARALLEL_REQUESTS)
+    futures = [pool.submit(_ask_batch, b, repo, api_key, model, deadline) for b in batches]
+    done, not_done = wait(futures, timeout=TOTAL_TIMEOUT)
+    pool.shutdown(wait=False, cancel_futures=True)
+    if not_done:
+        raise JevError(f"Jev did not answer in {TOTAL_TIMEOUT:g} s")
+    answers = {}
+    for future in done:
+        answers.update(future.result())
+    return answers
+
+
+def _ask_batch(items: list, repo: list[str], api_key: str, model: str, deadline: float) -> dict:
+    ids = {f"f{n}": item for n, item in enumerate(items, start=1)}
+    body = {
+        "model": model,
+        "state": {"repo": {"top_level": repo},
+                  "files": {fid: item.evidence for fid, item in ids.items()}},
+        "questions": {fid: _question(fid, item.is_folder) for fid, item in ids.items()},
+    }
+    response = _post(body, api_key, deadline)
+    answers = {}
+    for fid, answer in response.get("answers", {}).items():
+        if fid in ids and _is_valid(answer):
+            answers[ids[fid].key] = answer
+    return answers
+
+
+def _question(fid: str, is_folder: bool) -> dict:
+    """SG-44: each question points to its own item by name."""
+    kind = "folder" if is_folder else "file"
+    hint = "Use `repo` to see how the project is laid out." if is_folder else \
+        "Use `repo` and `same_folder` to see how the project is laid out."
+    return {"type": "choice",
+            "instructions": f"Which category fits the new {kind} in `files.{fid}`? {hint}",
+            "criteria": OPTIONS}
+
+
+def _is_valid(answer: dict) -> bool:
+    return answer.get("choice") in OPTIONS and isinstance(answer.get("probabilities"), dict)
+
+
+def _post(body: dict, api_key: str, deadline: float) -> dict:
+    """SG-40, SG-81, SG-82. The API key never appears in an error message."""
+    request = urllib.request.Request(
+        ENDPOINT,
+        data=json.dumps(body).encode(),
+        headers={"Authorization": f"Bearer {api_key}",
+                 "Content-Type": "application/json",
+                 "User-Agent": f"strayguard/{__version__}"},
+    )
+    for attempt in (1, 2):
+        timeout = min(REQUEST_TIMEOUT, deadline - time.monotonic())
+        if timeout <= 0:
+            raise JevError(f"Jev did not answer in {TOTAL_TIMEOUT:g} s")
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                return json.loads(response.read())
+        except urllib.error.HTTPError as error:
+            if error.code in RETRY_STATUSES and attempt == 1:
+                time.sleep(1.0)
+                continue
+            raise JevError(f"Jev returned HTTP {error.code}") from None
+        except (socket.timeout, TimeoutError):
+            raise JevError(f"Jev did not answer in {TOTAL_TIMEOUT:g} s") from None
+        except urllib.error.URLError as error:
+            if isinstance(error.reason, (socket.timeout, TimeoutError)):
+                raise JevError(f"Jev did not answer in {TOTAL_TIMEOUT:g} s") from None
+            raise JevError(f"could not reach Jev ({error.reason})") from None
+        except ValueError:
+            raise JevError("Jev sent a response that is not JSON") from None

strayguard/rules.py

@@ -0,0 +1,22 @@
+"""Local rules: checks in code that do not use Jev (SPEC 7.3)."""
+
+from __future__ import annotations
+
+import posixpath
+from fnmatch import fnmatchcase
+
+LOCAL_ONLY = (
+    ".env", ".env.*", "*.pem", "*.key", "*.p12", "*.pfx", "id_rsa*", "id_ed25519*",
+    ".DS_Store", "Thumbs.db", "desktop.ini",
+)
+ALLOWED = (".env.example", ".env.sample", ".env.template")
+
+
+def match(path: str) -> str | None:
+    """Return 'local-only' if a rule matches the file name. Else return None."""
+    name = posixpath.basename(path.rstrip("/"))
+    if name in ALLOWED:
+        return None
+    if any(fnmatchcase(name, pattern) for pattern in LOCAL_ONLY):
+        return "local-only"
+    return None

strayguard/ui.py

@@ -0,0 +1,118 @@
+"""All output and the prompt (SPEC 5, 7.8, 7.9). Output goes to standard error."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import sys
+
+LABELS = {
+    "scratch": "scratch / leftover",
+    "output-dump": "output dump",
+    "build-output": "build output",
+    "local-only": "local only",
+}
+
+
+def _say(text: str = "") -> None:
+    print(text, file=sys.stderr, flush=True)
+
+
+def _color(code: str, text: str) -> str:
+    if sys.stderr.isatty() and "NO_COLOR" not in os.environ:
+        return f"\033[{code}m{text}\033[0m"
+    return text
+
+
+def note(text: str) -> None:
+    _say(f"strayguard: {text}")
+
+
+def can_prompt() -> bool:
+    """SG-60: a person must see the output, and strayguard must read the keyboard."""
+    if os.environ.get("CI") or os.name == "nt" or not sys.stderr.isatty():
+        return False
+    try:
+        with open("/dev/tty"):
+            return True
+    except OSError:
+        return False
+
+
+def _files(count: int, word: str = "new file") -> str:
+    return f"1 {word}" if count == 1 else f"{count} {word}s"
+
+
+def _rows(verdicts: list) -> list[str]:
+    width = max(len(v.item.path) for v in verdicts)
+    rows = []
+    for v in verdicts:
+        score = "rule" if v.probability is None else f"{round(v.probability * 100)}%"
+        rows.append(f"  {v.item.path:<{width}}   {LABELS.get(v.category, v.category):<18}   {score}")
+    return rows
+
+
+def _header(verdicts: list, text: str) -> None:
+    _say()
+    _say(_color("33", f"⚠ strayguard: {_files(len(verdicts))} {text}"))
+    _say()
+    for row in _rows(verdicts):
+        _say(row)
+
+
+def warn(verdicts: list, blocking: bool) -> None:
+    """SG-70, SG-71: non-interactive mode. Show the command that fixes it."""
+    status = "commit stopped" if blocking else "not blocking"
+    _header(verdicts, f"may not belong ({status})")
+    paths = " ".join(shlex.quote(v.item.path) for v in verdicts)
+    _say()
+    _say("  To unstage it:" if len(verdicts) == 1 else "  To unstage them:")
+    _say(f"    git rm --cached -r -- {paths}")
+    _say()
+
+
+def _ask(question: str, keys: str) -> str:
+    """Read one answer from the keyboard. Enter means keep (decision 1)."""
+    with open("/dev/tty") as tty:
+        while True:
+            print(question, end="", file=sys.stderr, flush=True)
+            answer = tty.readline().strip().lower()[:1]
+            if not answer:
+                return "k"
+            if answer in keys:
+                return answer
+
+
+def prompt(verdicts: list) -> dict:
+    """SG-61 to SG-63. Return {"u": [...], "g": [...], "k": [...]}."""
+    _header(verdicts, "looks like it doesn't belong" if len(verdicts) == 1
+            else "look like they don't belong")
+    _say()
+    _say("  [u] unstage   [g] add to .gitignore   [k] keep and commit   [o] one by one")
+    key = _ask("  > ", "ugko")
+    if key != "o":
+        return {k: list(verdicts) if k == key else [] for k in "ugk"}
+    choices = {"u": [], "g": [], "k": []}
+    for v, row in zip(verdicts, _rows(verdicts)):
+        choices[_ask(f"{row}   [u/g/k] > ", "ugk")].append(v)
+    return choices
+
+
+def report(choices: dict) -> None:
+    """Say what strayguard did, then say if the commit stopped (SG-68)."""
+    tick = _color("32", "✓")
+    _say()
+    if choices["g"]:
+        _say(f"  {tick} Added {_files(len(choices['g']), 'file')} to .gitignore and staged .gitignore.")
+    removed = len(choices["u"]) + len(choices["g"])
+    if removed:
+        it = "It is" if removed == 1 else "They are"
+        _say(f"  {tick} Unstaged {_files(removed, 'file')}. {it} still on your disk.")
+    kept = len(choices["k"])
+    if kept:
+        it = "it" if kept == 1 else "them"
+        _say(f"  {tick} Kept {_files(kept, 'file')}. strayguard will not ask about {it} again.")
+    if removed:
+        _say()
+        _say("  Commit stopped so you can check. Run git commit again.")
+    _say()

strayguard-0.1.0.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.5
+Name: strayguard
+Version: 0.1.0
+Summary: A git pre-commit hook that asks TypeSafe Jev whether each new file belongs in your repo.
+Project-URL: Homepage, https://github.com/Eve2512/Strayguard
+Project-URL: Issues, https://github.com/Eve2512/Strayguard/issues
+Author: Eva Hill
+License-Expression: MIT
+License-File: LICENSE
+Keywords: git,gitignore,hook,jev,pre-commit,typesafe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Strayguard
+Catch files that don't belong before you commit them. A git pre-commit hook that asks TypeSafe Jev whether each new file belongs in your repo. It catches scratch scripts, debug dumps, build output and local config before they land. Takes under a second, costs a fraction of a cent, needs no config.
+
+
+### Why
+
+```git add .``` adds everything. Sometimes that includes:
+
+- ```test_fix2.py```, a throwaway script
+- ```debug_output.json```, which you dumped while chasing a bug
+- ```notes-to-self.md```
+- ```data_export.csv``` with real customer rows
+- ```.env.local``` with your own settings
+- a whole ```dist/``` folder
+
+Coding agents make this worse, they create helper scripts and scratch files and often don't clean them up.
+Whatever coding tool you use most likely miss most of these files:
+
+| Tool | Catches | Misses |
+|---|---|---|
+| ```.gitignore``` | Names you listed in advance | Every name you didn't think of |
+| Secret scanners | API keys and tokens | Junk scripts, data dumps, notes |
+| Large-file checks | Big files | Small junk files |
+| **strayguard** | **Files that don't look like part of the project** | Changes to files git already tracks |
+
+
+### How it works
+
+1. You run ```git commit```.
+2. strayguard looks only at files that are **new** in this commit.
+3. A few local rules run first, such as ```.env``` and ```.DS_Store```. Files they match are never sent anywhere.
+4. For the other files, Jev picks one category: **belongs**, **scratch / leftover**, **output dump**, **build output** or **local only**.
+5. If Jev is at least 70% sure a file doesn't belong, strayguard shows it to you.
+6. If everything belongs, you see nothing.
+
+Jev never writes text(not good for that anyways) It only picks a category and returns a probability. The same file always gets the same answer, because strayguard caches the result.
+
+### Install
+
+You need Python 3.9+ and a [TypeSafe API key](https://console.typesafe.ai/keys).
+
+```bash
+pipx install strayguard
+```
+
+Until the first PyPI release, install it from GitHub instead:
+
+```bash
+pipx install git+https://github.com/Eve2512/Strayguard
+```
+
+```bash
+export TYPESAFE_API_KEY=your-key
+```
+
+Then, inside your repo:
+
+```bash
+strayguard install
+```
+
+```text
+✓ strayguard installed in .git/hooks/pre-commit
+```
+
+That's it, there's no config file
+
+
+### With the pre-commit framework
+
+Add this to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/Eve2512/Strayguard
+    rev: v0.1.0
+    hooks:
+      - id: strayguard
+```
+
+The pre-commit framework captures the output of its hooks, so strayguard cannot ask you questions there. It shows the warning and lets the commit through, as described in [GUI clients, CI and coding agents](#gui-clients-ci-and-coding-agents).
+
+
+## What you'll see
+
+### Everything belongs
+
+Nothing, your commit goes through as normal.
+
+```text
+$ git commit -m "add login page"
+[main 4f2a91c] add login page
+ 3 files changed, 120 insertions(+)
+```
+
+### Something looks wrong
+
+```text
+$ git commit -m "add login page"
+
+⚠ strayguard: 2 new files look like they don't belong
+
+  debug_output.json   output dump          87%
+  test_fix2.py        scratch / leftover   91%
+
+  [u] unstage   [g] add to .gitignore   [k] keep and commit   [o] one by one
+  > g
+
+  ✓ Added 2 files to .gitignore and staged .gitignore.
+  ✓ Unstaged 2 files. They are still on your disk.
+
+  Commit stopped so you can check. Run git commit again.
+```
+
+| Key | What it does |
+|---|---|
+| `u` | Takes the files out of this commit. They stay on your disk. |
+| `g` | Adds the files to `.gitignore` so this never happens again, and takes them out of this commit. |
+| `k` | Commits the files anyway. strayguard won't ask about them again. |
+| `o` | Lets you choose `u`, `g` or `k` for each file. |
+| Enter | Same as `k`. |
+
+strayguard **never deletes files**. It stops the commit only if it changed something for you, so you can check before you commit again.
+
+
+### GUI clients, CI and coding agents
+
+strayguard asks you a question only when its output goes straight to your terminal. GUI git clients, CI, coding agents and the pre-commit framework all capture the output, so there strayguard warns and lets the commit through:
+
+```text
+⚠ strayguard: 2 new files may not belong (not blocking)
+
+  debug_output.json   output dump          87%
+  test_fix2.py        scratch / leftover   91%
+
+  To unstage them:
+    git rm --cached -r -- debug_output.json test_fix2.py
+```
+
+To block the commit instead, set `STRAYGUARD_STRICT=1`, this is a good setting for coding-agent sessions.
+
+
+### Files caught by a local rule
+
+These files are never sent to Jev, so they show `rule` instead of a percentage:
+
+```text
+  .env.local           local only           rule
+```
+
+### When strayguard can't reach Jev
+
+It prints one line, still runs its local rules, and lets the commit through:
+
+```text
+strayguard: no TYPESAFE_API_KEY set, so only the local rules ran.
+strayguard: Jev did not answer in 5 s, so only the local rules ran.
+```
+
+## Settings
+
+Everything is optional except the key.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `TYPESAFE_API_KEY` | none | **Required.** Your TypeSafe API key. |
+| `STRAYGUARD=off` | `on` | Skip the check for one commit: `STRAYGUARD=off git commit ...` |
+| `STRAYGUARD_STRICT=1` | `0` | Block the commit when strayguard can't ask you, such as in CI or with agents. |
+| `STRAYGUARD_THRESHOLD` | `0.70` | How sure Jev must be before strayguard warns you. |
+| `STRAYGUARD_MODEL` | `jev-latest` | Pin a version, for example `jev-1.13.0`, to keep answers stable. |
+| `STRAYGUARD_NAMES_ONLY=1` | `0` | Send only file names and sizes, never content. |
+
+You can also skip every hook for one commit with `git commit --no-verify`.
+
+## Privacy
+
+For each **new** text file, strayguard sends TypeSafe its path, its size, its first 40 lines (at most 2,000 characters) and the names of a few tracked files next to it.
+
+It never sends:
+
+- files that a local rule catches, such as `.env` files, keys and certificates
+- binary files, or files larger than 1 MB
+- any content at all when `STRAYGUARD_NAMES_ONLY=1` is set
+
+TypeSafe says it does not train models on customer data. See its [legal page](https://docs.typesafe.ai/legal).
+
+## Cost and speed
+
+- A typical commit costs less than $0.0001.
+- The check usually finishes in under a second.
+- Each file's answer is cached by its content, so running the commit again is instant and free.
+
+## Uninstall
+
+```bash
+strayguard uninstall
+```
+
+This removes the hook only if strayguard wrote it.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `strayguard install` | Add the pre-commit hook to this repo |
+| `strayguard uninstall` | Remove the hook |
+| `strayguard check` | Run the check on staged new files (the hook runs this) |
+| `strayguard --version` | Show the version |
+
+## Development
+
+Run the unit tests. They use no network and no API key:
+
+```bash
+uv run --no-project --with pytest pytest
+```
+
+GitHub Actions runs the same tests on Python 3.9 to 3.14 for each push to `main` and for each pull request.
+
+## License
+
+MIT. See [LICENSE](https://github.com/Eve2512/Strayguard/blob/main/LICENSE).
+

strayguard-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+strayguard/__init__.py,sha256=pYDGbWRfXAHZrrUn3llLmg2TXX5_DxU6aLla6gHZR_M,244
+strayguard/cli.py,sha256=W1EwVYreu5KQ3SGM7qM5N169sIEVb1d9ZPPJvJIoEnU,4647
+strayguard/decide.py,sha256=YLAJ-wHqD7jpY_5EknGflMT1F_3wAIVCtz_eQd7zJVI,3454
+strayguard/evidence.py,sha256=kCMGgsVhodTzhlViyoKMdyFMkLOeRjc22Uux_WQLrrY,3750
+strayguard/git.py,sha256=c-bW-bvFUTwyr4P63sJfJzjnnwof7ym2-tUZAam3Xx4,3889
+strayguard/jev.py,sha256=vx5MfcLg7B0jkuqDzJpZxdyPHitIWZjLUbzuUfYdDxE,5116
+strayguard/rules.py,sha256=k7yQityEoDjyPYoXdMPwkS3iFeT77d4XIqifhmbB_ks,679
+strayguard/ui.py,sha256=0Foyg3o2WEitbzxrXEXec-3KImK8fBc_MZNH0WiFWZc,3855
+strayguard-0.1.0.dist-info/METADATA,sha256=sPm_OvLblZtL0R1QS-R_8nXmRfGV_OML730BR1xgO1g,7983
+strayguard-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+strayguard-0.1.0.dist-info/entry_points.txt,sha256=lr038o8N2ZNvHIMrRdtTLqELHUdDH9Z0yCdzK0YM1kw,51
+strayguard-0.1.0.dist-info/licenses/LICENSE,sha256=96EDP-JS5lyHFO6OUQPy6xSGuILsPMTm_vCvYNs_WAY,1060
+strayguard-0.1.0.dist-info/RECORD,,

strayguard-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

strayguard-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+strayguard = strayguard.cli:main

strayguard-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eva
+
+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.