gitvow 0.3.0__tar.gz → 0.5.0__tar.gz

{gitvow-0.3.0/src/gitvow.egg-info → gitvow-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.3.0
+Version: 0.5.0
 Summary: Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies.
 Author-email: Nikhil Bora <nikhil@wirevow.com>
 License: Apache-2.0

{gitvow-0.3.0 → gitvow-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitvow"
-version = "0.3.0"
+version = "0.5.0"
 description = "Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{gitvow-0.3.0 → gitvow-0.5.0}/src/gitvow/cli.py

@@ -9,10 +9,12 @@ import re
 import sys
 
 from . import __version__
+from . import snapshots as snap
 from .collect import collect, summarize_text
 from .hooks import HANDLERS, LEGACY_NOTES_REF, notes_ref
 from .install import install_repo, install_user, uninstall_repo, uninstall_user
 from .policy import PolicyError, evaluate, load_policy
+from .providers import QUESTIONS, ask
 from .redact import RedactionError, load_rules, redact
 from .report import build, render_markdown
 from .state import git
@@ -43,7 +45,7 @@ def cmd_uninstall(a: argparse.Namespace) -> int:
     done = (
         uninstall_user(os.path.expanduser("~"), a.purge_policy, a.purge_ledger)
         if a.user
-        else uninstall_repo(os.path.abspath(a.repo), a.purge_notes)
+        else uninstall_repo(os.path.abspath(a.repo), a.purge_notes, a.purge_snapshots)
     )
     print("\n".join(done))
     return 0
@@ -66,6 +68,26 @@ def cmd_check(a: argparse.Namespace) -> int:
     return 2 if d.blocks else 0
 
 
+def cmd_ask(a: argparse.Namespace) -> int:
+    """Ask every configured provider one question and show the gate's decision."""
+    try:
+        pol = load_policy(os.getcwd())
+    except PolicyError as e:
+        print(f"policy error: {e}", file=sys.stderr)
+        return 2
+    if not pol.get("providers"):
+        print("no providers configured in the active policy", file=sys.stderr)
+        return 1
+    path = a.path or (a.subject if a.question == "gate_bearing" else "")
+    answers = ask(pol, "Edit", {"file_path": path}, os.getcwd(), only=[(a.question, a.subject)])
+    for ans in answers:
+        ev = " — " + "; ".join(ans.evidence) if ans.evidence else ""
+        print(f"{ans.provider}: {ans.answer}{ev}")
+    blocked = any(x.blocks for x in answers)
+    print("decision: " + ("CONFIRM" if blocked else "ALLOW"))
+    return 2 if blocked else 0
+
+
 def cmd_show(a: argparse.Namespace) -> int:
     """Print a commit's trailers and session note."""
     rc, msg, _ = git(["log", "-1", "--format=%H%n%s%n%b", a.commit], os.getcwd())
@@ -109,6 +131,61 @@ def cmd_report(a: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_snapshots(a: argparse.Namespace) -> int:
+    cwd = os.getcwd()
+    if a.sub == "prune":
+        days = None
+        if a.older_than:
+            m = re.fullmatch(r"(\d+)([dh]?)", a.older_than)
+            if not m:
+                print("--older-than takes a number of days, e.g. 14d", file=sys.stderr)
+                return 1
+            days = int(m.group(1)) / (24 if m.group(2) == "h" else 1)
+        print(f"pruned {snap.prune(cwd, days, a.session)} snapshot(s)")
+        return 0
+    rows = snap.list_snapshots(cwd, a.session)
+    if not rows:
+        print("no snapshots" + (f" for session {a.session}" if a.session else ""))
+        return 0
+    cur = None
+    for r in rows:
+        if r["session"] != cur:
+            cur = r["session"]
+            print(f"session {cur[:8]}   {sum(1 for x in rows if x['session'] == cur)} snapshots")
+            print("  n    taken                tool        file                                  changed vs HEAD")
+        print(
+            f"  {r['n']:<4d} {r['taken']:<20s} {r['tool']:<11s} {r['file'][:37]:<37s} {r['changed_files']} file{'s' if r['changed_files'] != 1 else ''}"
+        )
+    return 0
+
+
+def _resolve_or_fail(a: argparse.Namespace) -> str | None:
+    ref = snap.resolve(os.getcwd(), a.session, a.n)
+    if not ref:
+        print(f"no snapshot {a.n} for a unique session matching {a.session!r}", file=sys.stderr)
+    return ref
+
+
+def cmd_diff(a: argparse.Namespace) -> int:
+    ref = _resolve_or_fail(a)
+    if not ref:
+        return 1
+    print(snap.diff(os.getcwd(), ref, a.full))
+    return 0
+
+
+def cmd_restore(a: argparse.Namespace) -> int:
+    ref = _resolve_or_fail(a)
+    if not ref:
+        return 1
+    rc, msg = snap.restore(os.getcwd(), ref, a.to)
+    print(
+        f"restored {ref} into {msg} (detached worktree; remove with: git worktree remove {msg})" if rc == 0 else msg,
+        file=sys.stderr if rc else sys.stdout,
+    )
+    return rc
+
+
 def cmd_push_notes(a: argparse.Namespace) -> int:
     import subprocess
 
@@ -155,6 +232,7 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--purge-notes", action="store_true")
     s.add_argument("--purge-policy", action="store_true")
     s.add_argument("--purge-ledger", action="store_true")
+    s.add_argument("--purge-snapshots", action="store_true")
     s.set_defaults(f=cmd_uninstall)
     s = sub.add_parser("check", help="dry-run the policy: gitvow check -- git push --force")
     s.add_argument("command", nargs="*")
@@ -164,6 +242,11 @@ def main(argv: list[str] | None = None) -> int:
     s = sub.add_parser("show", help="print a commit's trailers and session note")
     s.add_argument("commit", nargs="?", default="HEAD")
     s.set_defaults(f=cmd_show)
+    s = sub.add_parser("ask", help="ask configured providers a question: gitvow ask route_gate /v1/x --path src/api.py")
+    s.add_argument("question", choices=QUESTIONS)
+    s.add_argument("subject")
+    s.add_argument("--path", default="")
+    s.set_defaults(f=cmd_ask)
     s = sub.add_parser("redact", help="apply built-in redaction plus your rules files to text")
     s.add_argument("text", nargs="+")
     s.set_defaults(f=cmd_redact)
@@ -173,6 +256,24 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--json", action="store_true")
     s.add_argument("--require-notes", action="store_true")
     s.set_defaults(f=cmd_report)
+    s = sub.add_parser(
+        "snapshots", help="list working-tree snapshots taken after agent edits; 'snapshots prune' deletes"
+    )
+    s.add_argument("sub", nargs="?", choices=["prune"])
+    s.add_argument("--session")
+    s.add_argument("--all", action="store_true")
+    s.add_argument("--older-than")
+    s.set_defaults(f=cmd_snapshots)
+    s = sub.add_parser("diff", help="what the agent had changed at snapshot n: gitvow diff <session> <n>")
+    s.add_argument("session")
+    s.add_argument("n", type=int)
+    s.add_argument("--full", action="store_true")
+    s.set_defaults(f=cmd_diff)
+    s = sub.add_parser("restore", help="check a snapshot out into a detached scratch worktree")
+    s.add_argument("session")
+    s.add_argument("n", type=int)
+    s.add_argument("--to")
+    s.set_defaults(f=cmd_restore)
     s = sub.add_parser("push-notes", help="push refs/notes/gitvow/* to a remote (default origin)")
     s.add_argument("remote", nargs="?", default="origin")
     s.set_defaults(f=cmd_push_notes)

{gitvow-0.3.0 → gitvow-0.5.0}/src/gitvow/hooks/__init__.py

@@ -8,6 +8,7 @@ import re
 import time
 from typing import Any
 
+from .. import snapshots
 from ..policy import PolicyError, evaluate, load_policy, message_for
 from ..redact import RedactionError, load_rules, redact
 from ..state import git, load_state, log_event, save_state, toplevel
@@ -15,7 +16,7 @@ from ..transcript import summarize
 
 NOTES_REF_PREFIX = "gitvow"  # refs/notes/gitvow/<session-id>; gitvow 0.1 wrote the single ref refs/notes/sessions
 LEGACY_NOTES_REF = "sessions"
-NOTE_SCHEMA = 2
+NOTE_SCHEMA = 3
 COMMIT_RE = re.compile(r"\bgit\s+commit\b")
 EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
 REDACTION_UNAVAILABLE = "redaction rules invalid; nothing written for this event"
@@ -37,6 +38,8 @@ def session_start(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
             "started": st.get("started") if same_session and st.get("started") else time.strftime("%Y-%m-%dT%H:%M:%S"),
             "steps": st.get("steps", 0) if same_session else 0,
             "agent_blobs": st.get("agent_blobs", {}) if same_session else {},
+            "snapshots": st.get("snapshots", 0) if same_session else 0,
+            "last_snapshot": st.get("last_snapshot") if same_session else None,
         }
     )
     st.pop("pending_commit", None)
@@ -64,7 +67,7 @@ def pre_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]:
             2,
             f"BLOCKED: tool policy could not be loaded ({e}); refusing all tool calls until the policy is restored.",
         )
-    d = evaluate(pol, tool, inp)
+    d = evaluate(pol, tool, inp, cwd)
     rules, warn = _rules_or_none(cwd, home)
     if d.blocks:
         payload: dict[str, Any] = {"tool": tool, "reason": d.reason, "session_id": h.get("session_id")}
@@ -160,8 +163,18 @@ def post_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
     tool = h.get("tool_name")
     inp = h.get("tool_input") or {}
     if tool in EDIT_TOOLS:
-        if inp.get("file_path"):
-            _record_agent_blob(cwd, str(inp["file_path"]))
+        fp = str(inp.get("file_path") or inp.get("notebook_path") or "")
+        if fp:
+            _record_agent_blob(cwd, fp)
+        try:
+            pol = load_policy(cwd, home)
+        except PolicyError:
+            pol = {}
+        cfg = snapshots.settings(pol)
+        if cfg.get("enabled", True):
+            ref = snapshots.take(cwd, h.get("session_id") or load_state(cwd).get("session_id"), tool, fp, cfg)
+            if ref:
+                log_event(cwd, "snapshot", {"ref": ref, "tool": tool})
         return 0, ""
     if tool != "Bash" or not COMMIT_RE.search(inp.get("command", "")):
         return 0, ""
@@ -194,6 +207,7 @@ def post_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
         "files_in_commit": [ln.strip() for ln in files.splitlines()[:-1]][:50] if files else [],
         "files_written_by_agent_this_session": [f["path"] for f in attribution["files"] if f["agent_wrote"]][:50],
         "attribution": attribution,
+        "snapshot": st.get("last_snapshot"),
         "transcript": "kept local; see ledger",
         "redaction": "secrets/PII patterns, high-entropy tokens and custom rules replaced at write time",
     }

{gitvow-0.3.0 → gitvow-0.5.0}/src/gitvow/install.py

@@ -189,7 +189,7 @@ def install_repo(repo: str, cmd_prefix: str = "gitvow") -> list[str]:
     ]
 
 
-def uninstall_repo(repo: str, purge_notes: bool = False) -> list[str]:
+def uninstall_repo(repo: str, purge_notes: bool = False, purge_snapshots: bool = False) -> list[str]:
     done = []
     unmerge_settings(os.path.join(repo, ".claude", "settings.json"))
     rc, cur, _ = git(["config", "--get", "core.hooksPath"], repo)
@@ -210,5 +210,9 @@ def uninstall_repo(repo: str, purge_notes: bool = False) -> list[str]:
         for ref in refs.split():
             git(["update-ref", "-d", ref], repo)
         done.append(f"{len(refs.split())} local session note ref(s) deleted (remote copies untouched)")
+    if purge_snapshots:
+        from . import snapshots as _snap
+
+        done.append(f"{_snap.purge_all(repo)} snapshot ref(s) deleted")
     done.append(".gitvow removed; commit trailers already in history remain")
     return done

{gitvow-0.3.0 → gitvow-0.5.0}/src/gitvow/policy.py

@@ -10,6 +10,8 @@ import subprocess
 from dataclasses import dataclass
 from typing import Any
 
+from . import providers as _providers
+
 DEFAULT_POLICY_PATH = os.path.join(os.path.dirname(__file__), "default_policy.json")
 
 
@@ -63,9 +65,21 @@ def _validate(pol: dict[str, Any], path: str) -> None:
                 re.compile(pat)
             except re.error as e:
                 raise PolicyError(f"{path}: bad regex in {key}: {pat} ({e})") from e
-
-
-def evaluate(pol: dict[str, Any], tool: str, tool_input: dict[str, Any]) -> Decision:
+    snap = pol.get("snapshots", {})
+    if not isinstance(snap, dict) or not isinstance(snap.get("exclude", []), list):
+        raise PolicyError(f"{path}: snapshots must be an object with an optional 'exclude' list")
+    provs = pol.get("providers", [])
+    if not isinstance(provs, list):
+        raise PolicyError(f"{path}: providers must be a list")
+    for prov in provs:
+        if not isinstance(prov, dict) or not prov.get("name") or not prov.get("command"):
+            raise PolicyError(f"{path}: each provider needs 'name' and 'command'")
+        bad = [q for q in prov.get("questions", []) if q not in _providers.QUESTIONS]
+        if bad:
+            raise PolicyError(f"{path}: provider {prov['name']} lists unknown questions {bad}")
+
+
+def evaluate(pol: dict[str, Any], tool: str, tool_input: dict[str, Any], cwd: str | None = None) -> Decision:
     text = tool_input.get("command", "") if tool == "Bash" else ""
     path = tool_input.get("file_path", "") or tool_input.get("notebook_path", "")
     if tool == "Bash":
@@ -85,6 +99,10 @@ def evaluate(pol: dict[str, Any], tool: str, tool_input: dict[str, Any]) -> Deci
         allow = pol.get("mcp_allow", [])
         if allow and not any(re.fullmatch(p, tool) for p in allow):
             return Decision("confirm", "MCP tool not on allow list", tool)
+    if pol.get("providers") and tool in ("Edit", "Write", "MultiEdit", "NotebookEdit"):
+        hits = [a for a in _providers.ask(pol, tool, tool_input, cwd) if a.blocks]
+        if hits:
+            return Decision("confirm", "; ".join(h.text() for h in hits[:3]), path)
     clf = pol.get("llm_classifier") or {}
     if clf.get("enabled") and clf.get("command"):
         return _classify(clf["command"], tool, tool_input, text or path or tool)

gitvow-0.5.0/src/gitvow/providers.py

@@ -0,0 +1,126 @@
+"""Providers: external programs the gate asks factual questions (gate_bearing, route_gate, route_callers)."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import subprocess
+from dataclasses import dataclass, field
+from typing import Any
+
+PROTOCOL = 1
+QUESTIONS = ("gate_bearing", "route_gate", "route_callers")
+EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
+ROUTE_RE = re.compile(r"""["'`](/[A-Za-z0-9_\-./{}:*$]*)["'`]""")
+
+
+@dataclass
+class Answer:
+    provider: str
+    question: str
+    subject: str
+    answer: str  # yes | no | unknown | failed
+    evidence: list[str] = field(default_factory=list)
+
+    @property
+    def blocks(self) -> bool:
+        return self.answer in ("yes", "failed")
+
+    def text(self) -> str:
+        why = "; ".join(self.evidence[:4]) if self.evidence else ""
+        if self.answer == "failed":
+            return f"provider {self.provider} unavailable for {self.question} {self.subject}"
+        return f"provider {self.provider}: {self.question} {self.subject}" + (f": {why}" if why else "")
+
+
+def route_literals(text: str) -> list[str]:
+    """Quoted strings that look like routes: begin with '/', no spaces, at least one more character."""
+    out: list[str] = []
+    for m in ROUTE_RE.finditer(text or ""):
+        r = m.group(1)
+        if len(r) > 1 and not r.startswith("//") and "." not in os.path.basename(r) and r not in out:
+            out.append(r)
+    return out
+
+
+def questions_for(tool: str, tool_input: dict[str, Any]) -> list[tuple[str, str]]:
+    """(question, subject) pairs the gate should ask for this tool call."""
+    if tool not in EDIT_TOOLS:
+        return []
+    path = tool_input.get("file_path") or tool_input.get("notebook_path") or ""
+    qs: list[tuple[str, str]] = []
+    if path:
+        qs.append(("gate_bearing", path))
+    old, new = "", ""
+    if tool == "Edit":
+        old, new = str(tool_input.get("old_string") or ""), str(tool_input.get("new_string") or "")
+    elif tool == "MultiEdit":
+        for e in tool_input.get("edits") or []:
+            old += "\n" + str(e.get("old_string") or "")
+            new += "\n" + str(e.get("new_string") or "")
+    elif tool == "Write":
+        new = str(tool_input.get("content") or "")
+    before, after = set(route_literals(old)), set(route_literals(new))
+    qs += [("route_gate", r) for r in sorted(after - before)]
+    qs += [("route_callers", r) for r in sorted(before - after)]
+    return qs
+
+
+def _run(prov: dict[str, Any], question: str, subject: str, repo: str, path: str, tool: str) -> Answer:
+    name = str(prov.get("name") or "provider")
+    req = {
+        "protocol": PROTOCOL,
+        "question": question,
+        "subject": subject,
+        "repo": repo,
+        "path": path,
+        "tool_name": tool,
+    }
+    try:
+        argv = shlex.split(str(prov.get("command") or ""))
+        if not argv:
+            return Answer(name, question, subject, "failed", ["empty command"])
+        r = subprocess.run(
+            argv,
+            input=json.dumps(req),
+            capture_output=True,
+            text=True,
+            timeout=float(prov.get("timeout") or 10),
+            check=False,
+            cwd=repo or None,
+        )
+        if r.returncode != 0:
+            return Answer(name, question, subject, "failed", [f"exit {r.returncode}"])
+        data = json.loads(r.stdout)
+        ans = str(data.get("answer", "unknown")).lower()
+        if ans not in ("yes", "no", "unknown"):
+            return Answer(name, question, subject, "failed", ["bad answer"])
+        ev = [str(e)[:200] for e in (data.get("evidence") or [])[:8]]
+        return Answer(name, question, subject, ans, ev)
+    except (OSError, subprocess.TimeoutExpired, ValueError, AttributeError) as e:
+        return Answer(name, question, subject, "failed", [type(e).__name__])
+
+
+def ask(
+    pol: dict[str, Any],
+    tool: str,
+    tool_input: dict[str, Any],
+    cwd: str | None = None,
+    only: list[tuple[str, str]] | None = None,
+) -> list[Answer]:
+    provs = pol.get("providers") or []
+    if not provs:
+        return []
+    repo = cwd or os.getcwd()
+    path = str(tool_input.get("file_path") or tool_input.get("notebook_path") or "")
+    if path and os.path.isabs(path):
+        rel = os.path.relpath(path, repo)
+        path = rel if not rel.startswith("..") else path
+    answers: list[Answer] = []
+    for q, subj in only if only is not None else questions_for(tool, {**tool_input, "file_path": path}):
+        for prov in provs:
+            if q in (prov.get("questions") or QUESTIONS):
+                answers.append(_run(prov, q, subj, repo, path, tool))
+    return answers

{gitvow-0.3.0 → gitvow-0.5.0}/src/gitvow/selftest.py

@@ -6,6 +6,7 @@ import json
 import os
 import shutil
 import subprocess
+import sys
 import tempfile
 
 from .hooks import post_tool_use, pre_tool_use, session_start, stop
@@ -66,9 +67,37 @@ def run() -> int:
                 "deny: destructive MCP tool",
             )
         )
+        prov = (
+            f'{sys.executable} -c "import sys,json;q=json.load(sys.stdin);'
+            "print(json.dumps({'answer':'yes' if q['question']=='route_gate' else 'no',"
+            "'evidence':['route not covered by authorization (selftest provider)']}))\""
+        )
+        os.makedirs(os.path.join(repo, ".gitvow"), exist_ok=True)
+        with open(os.path.join(repo, ".gitvow", "policy.json"), "w") as fh:
+            json.dump({"providers": [{"name": "selftest", "command": prov}]}, fh)
+        code, msg = pre_tool_use(
+            {
+                **base,
+                "tool_name": "Edit",
+                "tool_input": {"file_path": "api.py", "old_string": "", "new_string": '"/v1/new"'},
+            },
+            home,
+        )
+        results.append((code == 2 and "route not covered" in msg, "confirm: provider says new route is unauthorised"))
+        os.remove(os.path.join(repo, ".gitvow", "policy.json"))
         with open(os.path.join(repo, "a.txt"), "a") as fh:
             fh.write("b\n")
         post_tool_use({**base, "tool_name": "Edit", "tool_input": {"file_path": "a.txt"}}, home)
+        snaps = g("for-each-ref", "--format=%(refname)", "refs/gitvow/snapshots/").splitlines()
+        results.append(
+            (len(snaps) == 1 and snaps[0].endswith("/selftest-session/1"), "snapshot taken after the agent edit")
+        )
+        results.append(
+            (
+                g("show", f"{snaps[0]}:a.txt") == "a\nb" if snaps else False,
+                "snapshot holds the agent's version of the file",
+            )
+        )
         with open(os.path.join(repo, "a.txt"), "a") as fh:
             fh.write("human\n")
         pre_tool_use({**base, "tool_name": "Bash", "tool_input": {"command": "git commit -m x"}}, home)

gitvow-0.5.0/src/gitvow/snapshots.py

@@ -0,0 +1,183 @@
+"""Working-tree snapshots after agent edits: commits under refs/gitvow/snapshots/<session>/<n>, parented on HEAD."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import subprocess
+import tempfile
+import time
+from typing import Any
+
+from .state import git, git_dir, load_state, save_state, toplevel
+
+REF_PREFIX = "refs/gitvow/snapshots"
+DEFAULTS: dict[str, Any] = {
+    "enabled": True,
+    "max_per_session": 200,
+    "exclude": [".env*", "*.pem", "*.key", "*secret*", "*credential*", ".gitvow/**", ".claude/**"],
+}
+
+
+def settings(pol: dict[str, Any] | None) -> dict[str, Any]:
+    out = dict(DEFAULTS)
+    out.update((pol or {}).get("snapshots") or {})
+    return out
+
+
+def _safe(session_id: str | None) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]", "_", session_id or "unknown")
+
+
+def ref_for(session_id: str | None, n: int) -> str:
+    return f"{REF_PREFIX}/{_safe(session_id)}/{n}"
+
+
+def take(cwd: str, session_id: str | None, tool: str, file_path: str, cfg: dict[str, Any]) -> str | None:
+    """Write the working tree (minus ignored and excluded paths) as a commit and point a new session ref at it."""
+    top = toplevel(cwd)
+    gd = git_dir(cwd)
+    if not top or not gd:
+        return None
+    rc, head, _ = git(["rev-parse", "--verify", "HEAD"], top)
+    parent = head if rc == 0 else None
+    st = load_state(cwd)
+    n = int(st.get("snapshots", 0)) + 1
+    fd, tmp_index = tempfile.mkstemp(prefix="gitvow-index-", dir=gd)
+    os.close(fd)
+    os.remove(tmp_index)
+    env = {**os.environ, "GIT_INDEX_FILE": tmp_index}
+    try:
+        if parent:
+            subprocess.run(["git", "read-tree", parent], cwd=top, env=env, capture_output=True, check=False)
+        pathspec = ["--", "."] + [f":(exclude,glob){p}" for p in cfg.get("exclude", [])]
+        r = subprocess.run(
+            ["git", "add", "-A", *pathspec], cwd=top, env=env, capture_output=True, text=True, timeout=60, check=False
+        )
+        if r.returncode != 0:
+            return None
+        r = subprocess.run(["git", "write-tree"], cwd=top, env=env, capture_output=True, text=True, check=False)
+        if r.returncode != 0:
+            return None
+        tree = r.stdout.strip()
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    finally:
+        with contextlib.suppress(OSError):
+            os.remove(tmp_index)
+    rel = os.path.relpath(os.path.realpath(file_path), os.path.realpath(top)) if file_path else ""
+    msg = json.dumps(
+        {
+            "gitvow": "snapshot",
+            "session": session_id,
+            "n": n,
+            "tool": tool,
+            "file": rel,
+            "taken": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        }
+    )
+    args = ["commit-tree", tree, "-m", msg] + (["-p", parent] if parent else [])
+    rc, commit, _ = git(args, top)
+    if rc != 0:
+        return None
+    ref = ref_for(session_id, n)
+    git(["update-ref", ref, commit], top)
+    st["snapshots"] = n
+    st["last_snapshot"] = ref
+    save_state(cwd, st)
+    keep = int(cfg.get("max_per_session", 200))
+    if n > keep:
+        git(["update-ref", "-d", ref_for(session_id, n - keep)], top)
+    return ref
+
+
+def list_snapshots(cwd: str, session_id: str | None = None) -> list[dict[str, Any]]:
+    top = toplevel(cwd) or cwd
+    prefix = f"{REF_PREFIX}/{_safe(session_id)}/" if session_id else REF_PREFIX + "/"
+    rc, out, _ = git(["for-each-ref", "--format=%(refname)%09%(objectname)%09%(contents:subject)", prefix], top)
+    rows: list[dict[str, Any]] = []
+    if rc != 0:
+        return rows
+    for line in out.splitlines():
+        parts = line.split("\t", 2)
+        if len(parts) < 3:
+            continue
+        ref, commit, subject = parts
+        try:
+            meta = json.loads(subject)
+        except json.JSONDecodeError:
+            meta = {}
+        _, stat, _ = git(["diff", "--shortstat", f"{commit}^", commit], top)
+        m = re.match(r"\s*(\d+) file", stat or "")
+        rows.append(
+            {
+                "ref": ref,
+                "commit": commit,
+                "session": meta.get("session") or ref.split("/")[-2],
+                "n": int(meta.get("n") or ref.split("/")[-1]),
+                "tool": meta.get("tool", ""),
+                "file": meta.get("file", ""),
+                "taken": meta.get("taken", ""),
+                "changed_files": int(m.group(1)) if m else 0,
+            }
+        )
+    rows.sort(key=lambda r: (r["session"], r["n"]))
+    return rows
+
+
+def resolve(cwd: str, session_prefix: str, n: int) -> str | None:
+    """Full ref for a session id or unique prefix and a snapshot number."""
+    top = toplevel(cwd) or cwd
+    rc, out, _ = git(["for-each-ref", "--format=%(refname)", REF_PREFIX + "/"], top)
+    if rc != 0:
+        return None
+    hits = {r.rsplit("/", 1)[0] for r in out.split() if r.split("/")[-2].startswith(_safe(session_prefix))}
+    if len(hits) != 1:
+        return None
+    ref = f"{hits.pop()}/{n}"
+    rc, _, _ = git(["rev-parse", "--verify", "--quiet", ref], top)
+    return ref if rc == 0 else None
+
+
+def diff(cwd: str, ref: str, full: bool = False) -> str:
+    top = toplevel(cwd) or cwd
+    args = ["diff"] + ([] if full else ["--stat"]) + [f"{ref}^", ref]
+    rc, out, err = git(args, top)
+    return out if rc == 0 else err
+
+
+def restore(cwd: str, ref: str, to: str | None = None) -> tuple[int, str]:
+    top = toplevel(cwd) or cwd
+    if not to:
+        sess, n = ref.split("/")[-2], ref.split("/")[-1]
+        to = os.path.join(tempfile.gettempdir(), "gitvow-restore", f"{sess[:8]}-{n}")
+    if os.path.exists(to) and os.listdir(to):
+        return 1, f"{to} exists and is not empty; choose another --to"
+    os.makedirs(os.path.dirname(to) or ".", exist_ok=True)
+    rc, _, err = git(["worktree", "add", "--detach", to, ref], top)
+    if rc != 0:
+        return 1, err
+    return 0, to
+
+
+def prune(cwd: str, older_than_days: float | None = None, session_id: str | None = None) -> int:
+    top = toplevel(cwd) or cwd
+    cutoff = time.time() - (older_than_days or 0) * 86400 if older_than_days is not None else None
+    removed = 0
+    for row in list_snapshots(cwd, session_id):
+        if cutoff is not None:
+            try:
+                taken = time.mktime(time.strptime(row["taken"], "%Y-%m-%dT%H:%M:%S"))
+            except (ValueError, TypeError):
+                taken = 0
+            if taken > cutoff:
+                continue
+        git(["update-ref", "-d", row["ref"]], top)
+        removed += 1
+    return removed
+
+
+def purge_all(cwd: str) -> int:
+    return prune(cwd, None, None)

{gitvow-0.3.0 → gitvow-0.5.0/src/gitvow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.3.0
+Version: 0.5.0
 Summary: Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies.
 Author-email: Nikhil Bora <nikhil@wirevow.com>
 License: Apache-2.0

{gitvow-0.3.0 → gitvow-0.5.0}/src/gitvow.egg-info/SOURCES.txt

@@ -8,9 +8,11 @@ src/gitvow/collect.py
 src/gitvow/default_policy.json
 src/gitvow/install.py
 src/gitvow/policy.py
+src/gitvow/providers.py
 src/gitvow/redact.py
 src/gitvow/report.py
 src/gitvow/selftest.py
+src/gitvow/snapshots.py
 src/gitvow/state.py
 src/gitvow/transcript.py
 src/gitvow.egg-info/PKG-INFO
@@ -25,5 +27,7 @@ tests/test_hooks.py
 tests/test_install_cli.py
 tests/test_packaging.py
 tests/test_policy.py
+tests/test_providers.py
 tests/test_redact.py
-tests/test_report.py
+tests/test_report.py
+tests/test_snapshots.py

{gitvow-0.3.0 → gitvow-0.5.0}/tests/test_hooks.py

@@ -43,7 +43,7 @@ def test_commit_flow_trailer_note_and_attribution(repo, home, payload, transcrip
     note = git(repo, "notes", "--ref=gitvow/sess-1", "show", "HEAD")
     assert note.startswith("gitvow-session")
     data = json.loads(note.split("\n", 1)[1])
-    assert data["schema"] == 2 and data["step"] == 1 and data["tools_used"] == ["Bash", "Edit"]
+    assert data["schema"] == 3 and data["step"] == 1 and data["tools_used"] == ["Bash", "Edit"]
     assert "[github-token]" in data["last_stated_plan"] and "[email:" in data["last_stated_plan"]
     assert "ghp_" not in note and "ops@example.com" not in note
     att = data["attribution"]

gitvow-0.5.0/tests/test_providers.py

@@ -0,0 +1,160 @@
+import json
+import sys
+from pathlib import Path
+
+from gitvow import cli
+from gitvow.hooks import pre_tool_use
+from gitvow.policy import evaluate
+from gitvow.providers import questions_for, route_literals
+
+ROOT = Path(__file__).resolve().parents[1]
+EXAMPLE = ROOT / "examples" / "providers" / "static_facts.py"
+
+
+def test_route_literals_and_questions():
+    txt = 'a = "/v1/orders"; b = \'/v1/orders/{id}\'; c = "/static/app.js"; d = "//comment"; e = "/"; f = "/v1/orders"'
+    assert route_literals(txt) == ["/v1/orders", "/v1/orders/{id}"]
+    qs = questions_for(
+        "Edit",
+        {"file_path": "api.py", "old_string": '@app.get("/old")', "new_string": '@app.get("/new")\n@app.get("/old2")'},
+    )
+    assert qs == [
+        ("gate_bearing", "api.py"),
+        ("route_gate", "/new"),
+        ("route_gate", "/old2"),
+        ("route_callers", "/old"),
+    ]
+    assert questions_for("Write", {"file_path": "x.py", "content": 'r("/w")'}) == [
+        ("gate_bearing", "x.py"),
+        ("route_gate", "/w"),
+    ]
+    assert questions_for("Bash", {"command": 'echo "/v1/x"'}) == []
+
+
+def _facts(tmp_path):
+    f = tmp_path / "facts.json"
+    f.write_text(
+        json.dumps(
+            {
+                "gate_bearing": ["auth/AuthorizeWhitelistedPaths.java", "deploy/values/production-*.yaml"],
+                "whitelist_file": "auth/AuthorizeWhitelistedPaths.java",
+                "authorized_routes": ["/v1/orders", "/v1/orders/{id}"],
+                "callers": {"/v1/orders": ["client-orch (OrdersClient.java:88)"]},
+            }
+        )
+    )
+    return f
+
+
+def _policy(tmp_path, command):
+    return {"providers": [{"name": "facts", "command": command}]}
+
+
+def test_provider_confirms_with_evidence(tmp_path):
+    pol = _policy(tmp_path, f"{sys.executable} {EXAMPLE} --facts {_facts(tmp_path)}")
+    d = evaluate(
+        pol,
+        "Edit",
+        {"file_path": "src/api/Orders.java", "old_string": "x", "new_string": '@Path("/v1/orders/export")'},
+        str(tmp_path),
+    )
+    assert d.outcome == "confirm" and "not covered by any authorization rule" in d.reason
+    assert "AuthorizeWhitelistedPaths.java" in d.reason
+    d = evaluate(
+        pol,
+        "Edit",
+        {"file_path": "src/api/Orders.java", "old_string": "x", "new_string": '@Path("/v1/orders/{id}")'},
+        str(tmp_path),
+    )
+    assert d.outcome == "allow"  # listed as authorized
+    d = evaluate(
+        pol,
+        "Edit",
+        {"file_path": "src/api/Orders.java", "old_string": '@Path("/v1/orders")', "new_string": ""},
+        str(tmp_path),
+    )
+    assert d.outcome == "confirm" and "client-orch" in d.reason
+    d = evaluate(
+        pol,
+        "Write",
+        {"file_path": str(tmp_path / "deploy/values/production-in.yaml"), "content": "a: 1"},
+        str(tmp_path),
+    )
+    assert d.outcome == "confirm" and "gate-bearing" in d.reason
+    assert (
+        evaluate(pol, "Edit", {"file_path": "README.md", "old_string": "a", "new_string": "b"}, str(tmp_path)).outcome
+        == "allow"
+    )
+    assert evaluate(pol, "Bash", {"command": 'echo "/v1/new"'}, str(tmp_path)).outcome == "allow"
+
+
+def test_provider_failure_means_confirm(tmp_path):
+    for cmd in (
+        "/nonexistent/provider",
+        f"{sys.executable} -c \"print('not json')\"",
+        f"{sys.executable} -c 'import sys; sys.exit(3)'",
+        "",
+    ):
+        pol = _policy(tmp_path, cmd)
+        d = evaluate(pol, "Edit", {"file_path": "a.py", "old_string": "", "new_string": ""}, str(tmp_path))
+        assert d.outcome == "confirm" and "unavailable" in d.reason, cmd
+    pol = _policy(tmp_path, f"{sys.executable} -c 'import time; time.sleep(5)'")
+    pol["providers"][0]["timeout"] = 0.5
+    assert evaluate(pol, "Edit", {"file_path": "a.py"}, str(tmp_path)).outcome == "confirm"
+
+
+def test_unknown_answer_does_not_block(tmp_path):
+    pol = _policy(tmp_path, f'{sys.executable} -c "print(\'{{\\"answer\\": \\"unknown\\"}}\')"')
+    assert evaluate(pol, "Edit", {"file_path": "a.py"}, str(tmp_path)).outcome == "allow"
+
+
+def test_provider_questions_filter_and_validation(tmp_path):
+    from gitvow.policy import PolicyError, load_policy
+
+    (tmp_path / ".gitvow").mkdir()
+    (tmp_path / ".gitvow" / "policy.json").write_text(
+        json.dumps({"providers": [{"name": "x", "command": "y", "questions": ["nope"]}]})
+    )
+    try:
+        load_policy(str(tmp_path), str(tmp_path / "h"))
+        raise AssertionError("expected PolicyError")
+    except PolicyError as e:
+        assert "unknown questions" in str(e)
+    (tmp_path / ".gitvow" / "policy.json").write_text(json.dumps({"providers": [{"name": "x"}]}))
+    try:
+        load_policy(str(tmp_path), str(tmp_path / "h"))
+        raise AssertionError("expected PolicyError")
+    except PolicyError:
+        pass
+    pol = _policy(tmp_path, f"{sys.executable} {EXAMPLE} --facts {_facts(tmp_path)}")
+    pol["providers"][0]["questions"] = ["gate_bearing"]  # route questions not asked of this provider
+    d = evaluate(pol, "Edit", {"file_path": "a.py", "old_string": "", "new_string": '"/v1/zzz"'}, str(tmp_path))
+    assert d.outcome == "allow"
+
+
+def test_hook_and_cli_ask_end_to_end(repo, home, payload, tmp_path, monkeypatch, capsys):
+    facts = _facts(tmp_path)
+    (repo / ".gitvow").mkdir()
+    (repo / ".gitvow" / "policy.json").write_text(
+        json.dumps({"providers": [{"name": "facts", "command": f"{sys.executable} {EXAMPLE} --facts {facts}"}]})
+    )
+    code, msg = pre_tool_use(
+        payload(
+            "PreToolUse",
+            "Edit",
+            {"file_path": str(repo / "src/Orders.java"), "old_string": "", "new_string": '@Path("/v1/orders/export")'},
+        ),
+        str(home),
+    )
+    assert code == 2 and "CONFIRMATION REQUIRED" in msg and "AuthorizeWhitelistedPaths.java" in msg
+    log = (repo / ".git" / "gitvow-hooks.log").read_text()
+    assert '"kind": "confirm_required"' in log and "provider facts" in log
+    monkeypatch.chdir(repo)
+    assert cli.main(["ask", "route_gate", "/v1/orders/export", "--path", "src/Orders.java"]) == 2
+    out = capsys.readouterr().out
+    assert "facts: yes" in out and "decision: CONFIRM" in out
+    assert cli.main(["ask", "route_gate", "/v1/orders"]) == 0
+    assert "decision: ALLOW" in capsys.readouterr().out
+    assert cli.main(["ask", "gate_bearing", "auth/AuthorizeWhitelistedPaths.java"]) == 2
+    (repo / ".gitvow" / "policy.json").write_text("{}")
+    assert cli.main(["ask", "gate_bearing", "x"]) == 1

gitvow-0.5.0/tests/test_snapshots.py

@@ -0,0 +1,136 @@
+import json
+import os
+
+from gitvow import cli
+from gitvow.hooks import post_tool_use, pre_tool_use, session_start
+from gitvow.install import _write_git_hook, uninstall_repo
+from tests.conftest import git
+
+
+def _edit(repo, home, payload, name, content, tool="Edit"):
+    (repo / name).parent.mkdir(parents=True, exist_ok=True)
+    (repo / name).write_text(content)
+    post_tool_use(payload("PostToolUse", tool, {"file_path": str(repo / name)}), str(home))
+
+
+def test_snapshot_per_edit_with_head_parent_and_exclusions(repo, home, payload):
+    session_start(payload("SessionStart"), str(home))
+    (repo / ".gitignore").write_text("build/\n")
+    (repo / "build").mkdir()
+    (repo / "build" / "out.o").write_text("bin")
+    (repo / ".env").write_text("SECRET=1\n")
+    _edit(repo, home, payload, "calc.py", "def add(a, b):\n    return a + b\n")
+    _edit(repo, home, payload, "calc.py", "def add(a, b):\n    return a + b\n\ndef sub(a, b):\n    return a - b\n")
+    refs = git(repo, "for-each-ref", "--format=%(refname)", "refs/gitvow/snapshots/").split()
+    assert refs == ["refs/gitvow/snapshots/sess-1/1", "refs/gitvow/snapshots/sess-1/2"]
+    head = git(repo, "rev-parse", "HEAD")
+    assert git(repo, "rev-parse", "refs/gitvow/snapshots/sess-1/1^") == head  # parented on HEAD at the time
+    assert git(repo, "show", "refs/gitvow/snapshots/sess-1/1:calc.py") == "def add(a, b):\n    return a + b"
+    assert "sub" in git(repo, "show", "refs/gitvow/snapshots/sess-1/2:calc.py")
+    tree = git(repo, "ls-tree", "-r", "--name-only", "refs/gitvow/snapshots/sess-1/2")
+    assert "calc.py" in tree and ".gitignore" in tree and "build/out.o" not in tree and ".env" not in tree
+    (repo / ".gitvow").mkdir(exist_ok=True)
+    (repo / ".gitvow" / "policy.json").write_text("{}")
+    _edit(repo, home, payload, "calc.py", "v3\n")
+    assert ".gitvow/policy.json" not in git(repo, "ls-tree", "-r", "--name-only", "refs/gitvow/snapshots/sess-1/3")
+    assert git(repo, "status", "--short").count("\n") >= 0  # the real index was never touched
+    assert "calc.py" not in git(repo, "diff", "--cached", "--name-only")
+    st = json.loads((repo / ".git" / "gitvow-session.json").read_text())
+    assert st["snapshots"] == 2 and st["last_snapshot"] == "refs/gitvow/snapshots/sess-1/2"
+    assert '"kind": "snapshot"' in (repo / ".git" / "gitvow-hooks.log").read_text()
+
+
+def test_note_names_last_snapshot_and_new_session_restarts_numbering(repo, home, payload):
+    session_start(payload("SessionStart"), str(home))
+    _edit(repo, home, payload, "a.txt", "agent\n")
+    _write_git_hook(str(repo / ".gitvow" / "git-hooks"))
+    git(repo, "config", "core.hooksPath", ".gitvow/git-hooks")
+    pre_tool_use(payload("PreToolUse", "Bash", {"command": "git commit -m x"}), str(home))
+    git(repo, "commit", "-qam", "agent commit")
+    post_tool_use(payload("PostToolUse", "Bash", {"command": "git commit -m x"}), str(home))
+    note = json.loads(git(repo, "notes", "--ref=gitvow/sess-1", "show", "HEAD").split("\n", 1)[1])
+    assert note["schema"] == 3 and note["snapshot"] == "refs/gitvow/snapshots/sess-1/1"
+    p = payload("SessionStart")
+    p["session_id"] = "sess-2"
+    session_start(p, str(home))
+    (repo / "a.txt").write_text("two\n")
+    post_tool_use({**p, "tool_name": "Write", "tool_input": {"file_path": str(repo / "a.txt")}}, str(home))
+    assert git(repo, "rev-parse", "--verify", "refs/gitvow/snapshots/sess-2/1")
+
+
+def test_cli_list_diff_restore_prune(repo, home, payload, monkeypatch, capsys, tmp_path):
+    session_start(payload("SessionStart"), str(home))
+    _edit(repo, home, payload, "calc.py", "v1\n")
+    _edit(repo, home, payload, "calc.py", "v2\n", tool="Write")
+    (repo / "calc.py").write_text("human v3\n")
+    monkeypatch.chdir(repo)
+    assert cli.main(["snapshots"]) == 0
+    out = capsys.readouterr().out
+    assert "session sess-1   2 snapshots" in out and "Write" in out and "calc.py" in out
+    assert cli.main(["diff", "sess", "1"]) == 0
+    assert "calc.py" in capsys.readouterr().out
+    assert cli.main(["diff", "sess", "1", "--full"]) == 0
+    assert "+v1" in capsys.readouterr().out
+    dest = tmp_path / "restore-here"
+    assert cli.main(["restore", "sess", "1", "--to", str(dest)]) == 0
+    assert (dest / "calc.py").read_text() == "v1\n"
+    assert (repo / "calc.py").read_text() == "human v3\n"  # the real tree is untouched
+    assert cli.main(["restore", "sess", "1", "--to", str(dest)]) == 1  # refuses a non-empty dir
+    assert cli.main(["diff", "nope", "1"]) == 1
+    assert cli.main(["diff", "sess", "9"]) == 1
+    git(repo, "worktree", "remove", "--force", str(dest))
+    assert cli.main(["snapshots", "prune", "--older-than", "14d"]) == 0
+    assert "pruned 0" in capsys.readouterr().out
+    assert cli.main(["snapshots", "prune", "--session", "sess-1"]) == 0
+    assert "pruned 2" in capsys.readouterr().out
+    assert cli.main(["snapshots"]) == 0 and "no snapshots" in capsys.readouterr().out
+
+
+def test_retention_disable_and_purge(repo, home, payload):
+    (repo / ".gitvow").mkdir()
+    (repo / ".gitvow" / "policy.json").write_text(json.dumps({"snapshots": {"max_per_session": 2}}))
+    session_start(payload("SessionStart"), str(home))
+    for i in range(4):
+        _edit(repo, home, payload, "a.txt", f"v{i}\n")
+    refs = git(repo, "for-each-ref", "--format=%(refname)", "refs/gitvow/snapshots/").split()
+    assert [r.split("/")[-1] for r in refs] == ["3", "4"]
+    (repo / ".gitvow" / "policy.json").write_text(json.dumps({"snapshots": {"enabled": False}}))
+    _edit(repo, home, payload, "a.txt", "v9\n")
+    assert len(git(repo, "for-each-ref", "refs/gitvow/snapshots/").split("\n")) == 2
+    uninstall_repo(str(repo), purge_snapshots=True)
+    assert git(repo, "for-each-ref", "refs/gitvow/snapshots/") == ""
+
+
+def test_pre_push_does_not_push_snapshots(repo, home, payload, tmp_path):
+    remote = tmp_path / "remote.git"
+    git(remote.parent, "init", "-q", "--bare", str(remote))
+    git(repo, "remote", "add", "origin", str(remote))
+    _write_git_hook(str(repo / ".gitvow" / "git-hooks"))
+    git(repo, "config", "core.hooksPath", ".gitvow/git-hooks")
+    session_start(payload("SessionStart"), str(home))
+    _edit(repo, home, payload, "a.txt", "x\n")
+    git(repo, "notes", "--ref=gitvow/sess-1", "add", "-m", "gitvow-session\n{}", "HEAD")
+    git(repo, "push", "-q", "origin", git(repo, "branch", "--show-current"))
+    remote_refs = git(remote, "for-each-ref", "--format=%(refname)")
+    assert "refs/notes/gitvow/sess-1" in remote_refs and "snapshots" not in remote_refs
+
+
+def test_invalid_snapshots_policy_fails_closed(repo, home, payload):
+    (repo / ".gitvow").mkdir()
+    (repo / ".gitvow" / "policy.json").write_text(json.dumps({"snapshots": "yes please"}))
+    code, msg = pre_tool_use(payload("PreToolUse", "Bash", {"command": "ls"}), str(home))
+    assert code == 2 and "snapshots must be an object" in msg
+
+
+def test_snapshot_in_repo_without_commits(tmp_path, home, payload):
+    r = tmp_path / "fresh"
+    r.mkdir()
+    git(r, "init", "-q")
+    (r / "f.txt").write_text("first\n")
+    p = payload("SessionStart")
+    p["cwd"] = str(r)
+    session_start(p, str(home))
+    post_tool_use({**p, "tool_name": "Write", "tool_input": {"file_path": str(r / "f.txt")}}, str(home))
+    ref = git(r, "for-each-ref", "--format=%(refname)", "refs/gitvow/snapshots/")
+    assert ref.endswith("/1") and git(r, "show", f"{ref}:f.txt") == "first"
+    assert os.path.exists(r / ".git")