loom-code 0.1.1__py3-none-any.whl

loom_code/file_history.py

@@ -0,0 +1,322 @@
+"""File-touch history — what happened the last time we changed a file.
+
+The data foundation for *anticipation* (the loom-code differentiator
+over a stateless coder): before the agent touches ``foo.py`` again, it
+can be reminded "last time you edited this, the change was marked bad"
+or "you've edited this 6 times — it's a hotspot." Cursor's index knows
+what the code IS; this knows what HAPPENED to it, across runs.
+
+One JSON file per project — ``<root>/.loom/file_history.json`` — same
+convention as the rest of loom-code's per-project state (notebook,
+memory.db, code_index.db, last_session.txt). Schema:
+
+    {
+      "version": 1,
+      "files": {
+        "src/auth.py": {
+          "touch_count": 6,
+          "success_count": 4,
+          "fail_count": 1,
+          "last_touched_at": "2026-05-29T18:40:00Z",
+          "last_outcome": "success" | "fail" | "unknown",
+          "last_summary": "<one-line gist of the turn that touched it>"
+        },
+        ...
+      }
+    }
+
+Outcome is the SAME signal the self-improvement loop uses — the
+moved-on heuristic / ``/good`` / ``/bad`` (success: bool). We don't
+yet parse test output for a finer signal; that's a future refinement
+(the schema's ``last_outcome`` already has room for "fail" from a
+detected test break). ``unknown`` is recorded when a turn touched
+files but no success/failure was ever attributed (e.g. the user
+quit mid-judgement).
+
+Everything here is best-effort: a malformed file, a disk error, a
+concurrent writer — none may ever break a turn. Reads return an empty
+history; writes silently no-op. Anticipation degrading to silence is
+correct; a crash is not.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+_SCHEMA_VERSION = 1
+_HISTORY_FILENAME = "file_history.json"
+
+# Cap the number of files we track — a runaway monorepo touch history
+# would bloat the JSON + the recall prompt. We keep the most-recently-
+# touched N; older untouched entries fall off. 500 covers any real
+# working set without the file growing unbounded.
+_MAX_FILES = 500
+
+
+@dataclass(frozen=True)
+class FileRecord:
+    """One file's accumulated touch history."""
+
+    path: str
+    touch_count: int
+    success_count: int
+    fail_count: int
+    last_touched_at: str
+    last_outcome: str  # "success" | "fail" | "unknown"
+    last_summary: str
+
+
+def _history_path(root: Path | str) -> Path:
+    return Path(root) / ".loom" / _HISTORY_FILENAME
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+def _load(root: Path | str) -> dict[str, Any]:
+    """Load the raw history dict, or a fresh empty one. Never raises —
+    a corrupt/absent file yields an empty history so the caller always
+    gets a usable structure."""
+    path = _history_path(root)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"version": _SCHEMA_VERSION, "files": {}}
+    if not isinstance(data, dict) or not isinstance(
+        data.get("files"), dict
+    ):
+        return {"version": _SCHEMA_VERSION, "files": {}}
+    return data
+
+
+def _save(root: Path | str, data: dict[str, Any]) -> None:
+    """Persist the history dict. Best-effort: a disk error silently
+    no-ops (the history is a convenience, never load-bearing)."""
+    path = _history_path(root)
+    try:
+        path.parent.mkdir(exist_ok=True)
+        path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    except OSError:
+        pass
+
+
+def _prune(files: dict[str, Any]) -> dict[str, Any]:
+    """Keep the most-recently-touched ``_MAX_FILES`` entries so the
+    store can't grow without bound on a huge repo."""
+    if len(files) <= _MAX_FILES:
+        return files
+    ordered = sorted(
+        files.items(),
+        key=lambda kv: kv[1].get("last_touched_at", ""),
+        reverse=True,
+    )
+    return dict(ordered[:_MAX_FILES])
+
+
+def record_touches(
+    root: Path | str,
+    paths: list[str],
+    *,
+    outcome: str,
+    summary: str = "",
+) -> None:
+    """Record that ``paths`` were edited this turn with ``outcome``
+    (``"success"`` / ``"fail"`` / ``"unknown"``).
+
+    Idempotent per call, additive across calls: each path's
+    ``touch_count`` increments and the matching outcome counter bumps.
+    ``summary`` is a one-line gist of the turn (the user's prompt,
+    typically) so recall can say *why* the file was touched. Dedupes
+    ``paths`` so one turn editing the same file twice counts once.
+
+    Best-effort — never raises."""
+    if not paths:
+        return
+    if outcome not in ("success", "fail", "unknown"):
+        outcome = "unknown"
+    summary = summary.replace("\n", " ").strip()[:200]
+    now = _now_iso()
+
+    data = _load(root)
+    files: dict[str, Any] = data.get("files", {})
+    for path in dict.fromkeys(paths):  # dedupe, preserve order
+        rec = files.get(path) or {
+            "touch_count": 0,
+            "success_count": 0,
+            "fail_count": 0,
+            "last_touched_at": "",
+            "last_outcome": "unknown",
+            "last_summary": "",
+        }
+        rec["touch_count"] = int(rec.get("touch_count", 0)) + 1
+        if outcome == "success":
+            rec["success_count"] = int(rec.get("success_count", 0)) + 1
+        elif outcome == "fail":
+            rec["fail_count"] = int(rec.get("fail_count", 0)) + 1
+        rec["last_touched_at"] = now
+        rec["last_outcome"] = outcome
+        if summary:
+            rec["last_summary"] = summary
+        files[path] = rec
+
+    data["files"] = _prune(files)
+    data["version"] = _SCHEMA_VERSION
+    _save(root, data)
+
+
+def update_last_outcome(
+    root: Path | str, paths: list[str], outcome: str
+) -> None:
+    """Revise the outcome of the MOST RECENT touch of ``paths`` without
+    incrementing the touch count.
+
+    The flow that needs this: a turn records its touches as
+    ``"unknown"`` immediately (so a crash before judgement still leaves
+    a record), then the moved-on / ``/good`` / ``/bad`` signal arrives
+    a turn later and revises it to success/fail. We move the count from
+    unknown into the right bucket rather than double-counting the touch.
+
+    Best-effort — never raises."""
+    if not paths or outcome not in ("success", "fail"):
+        return
+    data = _load(root)
+    files: dict[str, Any] = data.get("files", {})
+    changed = False
+    for path in dict.fromkeys(paths):
+        rec = files.get(path)
+        if rec is None:
+            continue
+        # Only revise if the last recorded outcome was unknown — don't
+        # clobber an already-judged touch (idempotent re-attribution).
+        if rec.get("last_outcome") != "unknown":
+            continue
+        if outcome == "success":
+            rec["success_count"] = int(rec.get("success_count", 0)) + 1
+        else:
+            rec["fail_count"] = int(rec.get("fail_count", 0)) + 1
+        rec["last_outcome"] = outcome
+        files[path] = rec
+        changed = True
+    if changed:
+        data["files"] = files
+        _save(root, data)
+
+
+def history_for(root: Path | str, paths: list[str]) -> list[FileRecord]:
+    """Return the recorded history for each of ``paths`` that has any.
+
+    Used by proactive recall (Phase 2b) to answer "what happened last
+    time we touched the files this prompt is about." Order matches the
+    input; paths with no history are omitted. Never raises."""
+    data = _load(root)
+    files: dict[str, Any] = data.get("files", {})
+    out: list[FileRecord] = []
+    for path in paths:
+        rec = files.get(path)
+        if rec is None:
+            continue
+        out.append(
+            FileRecord(
+                path=path,
+                touch_count=int(rec.get("touch_count", 0)),
+                success_count=int(rec.get("success_count", 0)),
+                fail_count=int(rec.get("fail_count", 0)),
+                last_touched_at=str(rec.get("last_touched_at", "")),
+                last_outcome=str(rec.get("last_outcome", "unknown")),
+                last_summary=str(rec.get("last_summary", "")),
+            )
+        )
+    return out
+
+
+def candidate_paths_from_prompt(
+    root: Path | str, prompt: str
+) -> list[str]:
+    """Best-effort extract the tracked file paths a prompt is ABOUT.
+
+    Matches any tracked path that appears verbatim in the prompt (the
+    common case: "fix the bug in src/auth.py"), plus a basename match
+    ("the auth.py change broke") so a user who names the file without
+    its dir still gets the warning. Only returns paths that actually
+    have history — this is the candidate set for proactive recall.
+    Cheap string containment; no embedding. Never raises."""
+    if not prompt:
+        return []
+    data = _load(root)
+    tracked = list(data.get("files", {}).keys())
+    if not tracked:
+        return []
+    low = prompt.lower()
+    hits: list[str] = []
+    for path in tracked:
+        p_low = path.lower()
+        base = path.rsplit("/", 1)[-1].lower()
+        # Full path mentioned, or the basename as a whole word-ish
+        # token (guard against "a.py" matching inside "data.py" by
+        # requiring the basename to be reasonably specific).
+        if p_low in low or (len(base) >= 5 and base in low):
+            hits.append(path)
+    return hits
+
+
+def anticipation_block(records: list[FileRecord]) -> str:
+    """Render file-touch records into a proactive-recall working block.
+
+    Only surfaces records WORTH warning about — a prior failure, or a
+    churn hotspot (touched many times). A clean, once-touched file
+    produces nothing (silence is correct; noise trains the user to
+    ignore the section). Returns "" when nothing's notable."""
+    notable: list[FileRecord] = []
+    for r in records:
+        if r.last_outcome == "fail" or r.fail_count > 0:
+            notable.append(r)
+        elif r.touch_count >= 4:  # churn hotspot
+            notable.append(r)
+    if not notable:
+        return ""
+    lines = ["# What happened last time"]
+    lines.append(
+        "You're about to work on files with relevant history. "
+        "Heed it before repeating a past mistake."
+    )
+    for r in notable:
+        if r.last_outcome == "fail" or r.fail_count > 0:
+            why = f" ({r.last_summary})" if r.last_summary else ""
+            note = (
+                f"- `{r.path}` — last change was marked BAD{why}. "
+                f"Touched {r.touch_count}×, {r.fail_count} failed. "
+                "Be extra careful + verify."
+            )
+        else:
+            note = (
+                f"- `{r.path}` — churn hotspot ({r.touch_count} edits). "
+                "Fragile / frequently-revised; tread carefully."
+            )
+        lines.append(note)
+    return "\n".join(lines)
+
+
+def all_records(root: Path | str) -> list[FileRecord]:
+    """Every tracked file, most-recently-touched first. For a future
+    'hotspots' view / the desktop anticipation surface (Phase 2c)."""
+    data = _load(root)
+    files: dict[str, Any] = data.get("files", {})
+    recs = [
+        FileRecord(
+            path=p,
+            touch_count=int(r.get("touch_count", 0)),
+            success_count=int(r.get("success_count", 0)),
+            fail_count=int(r.get("fail_count", 0)),
+            last_touched_at=str(r.get("last_touched_at", "")),
+            last_outcome=str(r.get("last_outcome", "unknown")),
+            last_summary=str(r.get("last_summary", "")),
+        )
+        for p, r in files.items()
+    ]
+    recs.sort(key=lambda r: r.last_touched_at, reverse=True)
+    return recs

loom_code/file_tools.py

@@ -0,0 +1,93 @@
+"""loom-code's file tools — Claude-Code-style path boundary.
+
+The built-in loomflow ``read_tool`` hard-refuses any path outside its
+workdir (``_resolve_within`` raises). That makes "point at a file one
+directory up" impossible — the tool returns "file not found" no matter
+what path the model passes. Claude Code instead lets the tool reach
+any path the OS allows and puts the boundary in the PERMISSION layer:
+reads are lenient (in-project auto-allowed, outside approvable), writes
+are strict (outside always confirmed).
+
+This module builds loom-code's ``read`` tool to that model:
+
+* Resolve the path with :func:`loom_code.paths.resolve_path` (``~``,
+  cwd-relative, absolute) — one canonical resolver.
+* IN the project → read normally.
+* OUTSIDE the project → allowed only when the user REFERENCED the file
+  this session (``@``-mention / pasted path → :mod:`loom_code.consent`)
+  or a config rule permits it. Reads never mutate, so — matching Claude
+  Code — an outside read the user asked for goes straight through
+  rather than nagging; a self-initiated outside read the user never
+  named is refused (prompt-injection guard).
+
+The underlying read is delegated to a loomflow ``read_tool`` rooted at
+the filesystem root, so an absolute path never "escapes" it — the
+containment decision has already been made here.
+
+Edit/Write keep their existing loom-code wrappers (``edit_tool.py``),
+which already consent-gate outside writes and always show a diff.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from loomflow import tool
+from loomflow.tools import read_tool as _loomflow_read_tool
+
+from .paths import is_within, resolve_path
+
+
+def loom_read_tool(workdir: Path | str) -> Any:
+    """A ``read`` tool whose boundary is policy, not the cwd.
+
+    In-project reads behave exactly as before. An outside-project read
+    is permitted when the user referenced that file this session (see
+    :mod:`loom_code.consent`); otherwise it's refused with a message
+    telling the model to ask the user to reference the file — so a
+    prompt-injected "read ~/.ssh/id_rsa" the user never named fails.
+    """
+    root = Path(workdir).resolve()
+    anchor = root.anchor or "/"
+    # Delegate the actual read to a loomflow tool rooted at the
+    # filesystem anchor ("/"), so an already-resolved absolute path is
+    # always accepted by its own ``_resolve_within`` (nothing escapes
+    # the root). The containment decision is made HERE, not there.
+    inner = _loomflow_read_tool(Path(anchor))
+
+    async def read(
+        path: str,
+        offset: int = 0,
+        limit: int | None = None,
+    ) -> str:
+        target = resolve_path(path, root)
+        if not is_within(target, root):
+            from . import consent
+
+            if not consent.is_granted(target):
+                return (
+                    f"ERROR: {path} is outside the project and was not "
+                    "referenced by the user. Ask the user to share the "
+                    "file (they can paste its path or @-mention it); "
+                    "do not read outside the project on your own."
+                )
+        # Hand the inner ("/"-rooted) tool a path relative to ITS root:
+        # the absolute target with the leading anchor stripped.
+        rel = str(target)
+        if rel.startswith(anchor):
+            rel = rel[len(anchor):]
+        return await inner.fn(path=rel, offset=offset, limit=limit)
+
+    return tool(
+        name="read",
+        description=(
+            "Read a text file, returned with line numbers. The path may "
+            "be relative to the project, absolute, or start with ~. "
+            "Files the user referenced this session (pasted a path or "
+            "@-mentioned) are readable even outside the project; other "
+            "outside paths are refused — ask the user to share the file "
+            "rather than reading outside the project yourself. Args: "
+            "path, offset=0, limit=None."
+        ),
+    )(read)

loom_code/git_hook.py

@@ -0,0 +1,200 @@
+"""Install / uninstall loom-code's debounced post-commit hook.
+
+The hook (a small shell wrapper around ``python -m
+loom_code._post_commit``) counts commits since the last refresh
+per indexer and runs an incremental rebuild every N commits
+(default 5). See :mod:`loom_code._post_commit` for the actual
+refresh logic.
+
+Why this lives in loom-code and not graphify / loominit
+individually: there's only ONE ``.git/hooks/post-commit`` slot
+per repo. A shared hook that checks which indexers are set up
+and refreshes whichever apply lets ``/graphify on`` and
+``/loominit`` coexist without clobbering each other.
+
+The installer is idempotent. It marks its lines with a
+``# loom-code-hook`` sentinel so subsequent installs detect the
+prior hook and skip; uninstall removes those lines and leaves
+any other hook content (other tools, manual scripts) intact.
+"""
+
+from __future__ import annotations
+
+import stat
+import sys
+from pathlib import Path
+
+# Sentinel comment we write to mark our section of the hook.
+# Anything between this sentinel and the next blank line is
+# considered loom-code's; the rest is left alone on uninstall.
+_MARKER = "# loom-code-hook"
+_HOOK_NAME = "post-commit"
+
+
+def _git_hooks_dir(project_root: Path) -> Path | None:
+    """Resolve the git hooks directory for ``project_root`` — or
+    ``None`` if this isn't a git repo. Respects ``core.hooksPath``
+    when set (some teams move hooks out of ``.git/``)."""
+    git_dir = project_root / ".git"
+    if not git_dir.exists():
+        return None
+    # Honour ``git config core.hooksPath`` if set. Sub-projects in
+    # a workspace + teams using shared-hook tooling rely on this.
+    import subprocess
+    try:
+        result = subprocess.run(
+            ["git", "config", "--get", "core.hooksPath"],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (subprocess.SubprocessError, OSError):
+        result = None
+    if result is not None and result.returncode == 0 and result.stdout.strip():
+        hooks_path = result.stdout.strip()
+        # Relative paths are relative to the worktree root, not .git.
+        return (project_root / hooks_path).resolve()
+    # Default: .git/hooks (or hooks/ inside a bare repo).
+    if git_dir.is_dir():
+        return git_dir / "hooks"
+    # ``.git`` could be a file (worktree / submodule). Resolve.
+    return _resolve_dotgit_file(git_dir) / "hooks"
+
+
+def _resolve_dotgit_file(git_file: Path) -> Path:
+    """Worktrees + submodules: ``.git`` is a regular file with a
+    ``gitdir: <abs path>`` pointer. Follow it to the real git dir."""
+    text = git_file.read_text(encoding="utf-8").strip()
+    for line in text.splitlines():
+        if line.startswith("gitdir:"):
+            return Path(line.split(":", 1)[1].strip())
+    return git_file.parent  # fallback
+
+
+def is_installed(project_root: Path) -> bool:
+    """True iff the loom-code section is present in the post-commit
+    hook for this project."""
+    hooks_dir = _git_hooks_dir(project_root)
+    if hooks_dir is None:
+        return False
+    hook_path = hooks_dir / _HOOK_NAME
+    if not hook_path.is_file():
+        return False
+    return _MARKER in hook_path.read_text(encoding="utf-8")
+
+
+def install(project_root: Path) -> str:
+    """Install (or refresh) the loom-code post-commit hook.
+
+    Returns a status string suitable for printing to the user:
+    ``"installed"`` (newly added), ``"updated"`` (replaced an
+    existing loom-code section), ``"skipped: not a git repo"``,
+    or ``"skipped: <reason>"`` on failure.
+
+    Idempotent — calling on an already-installed repo
+    just refreshes the section in case the marker / runner
+    path changed between loom-code versions.
+    """
+    hooks_dir = _git_hooks_dir(project_root)
+    if hooks_dir is None:
+        return "skipped: not a git repo"
+    try:
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        return f"skipped: cannot mkdir {hooks_dir}: {exc}"
+    hook_path = hooks_dir / _HOOK_NAME
+
+    # The line we want present. Background (``&``) + stdout/err
+    # redirect so the hook never blocks the commit or spams the
+    # terminal. ``sys.executable`` pins to whichever Python
+    # loom-code is running in — avoids the "wrong python on PATH"
+    # class of bug.
+    loomcode_block = (
+        f"{_MARKER}\n"
+        f"exec {sys.executable} -m loom_code._post_commit "
+        f'"$(git rev-parse --show-toplevel)" '
+        f">/dev/null 2>&1 &\n"
+    )
+
+    updated = False
+    if hook_path.is_file():
+        existing = hook_path.read_text(encoding="utf-8")
+        if _MARKER in existing:
+            # Replace the existing section.
+            existing = _strip_loomcode_section(existing)
+            updated = True
+        # Append our block to whatever else is there.
+        new_content = existing.rstrip() + "\n\n" + loomcode_block
+    else:
+        new_content = "#!/bin/sh\n" + loomcode_block
+
+    try:
+        hook_path.write_text(new_content, encoding="utf-8")
+        # Mark executable (mode 0o755) — git won't run a hook
+        # without +x on POSIX.
+        st = hook_path.stat()
+        exec_bits = stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+        hook_path.chmod(st.st_mode | exec_bits)
+    except OSError as exc:
+        return f"skipped: write failed: {exc}"
+    return "updated" if updated else "installed"
+
+
+def uninstall(project_root: Path) -> str:
+    """Remove loom-code's section from the post-commit hook.
+    Leaves other tools' hook lines intact. Returns ``"removed"``,
+    ``"not present"``, or ``"skipped: <reason>"``."""
+    hooks_dir = _git_hooks_dir(project_root)
+    if hooks_dir is None:
+        return "skipped: not a git repo"
+    hook_path = hooks_dir / _HOOK_NAME
+    if not hook_path.is_file():
+        return "not present"
+    existing = hook_path.read_text(encoding="utf-8")
+    if _MARKER not in existing:
+        return "not present"
+    stripped = _strip_loomcode_section(existing)
+    # If only the shebang remains (or empty), drop the file entirely
+    # so we don't leave a no-op behind that other tools might find.
+    if stripped.strip() in ("", "#!/bin/sh"):
+        try:
+            hook_path.unlink()
+        except OSError as exc:
+            return f"skipped: unlink failed: {exc}"
+    else:
+        try:
+            hook_path.write_text(stripped, encoding="utf-8")
+        except OSError as exc:
+            return f"skipped: write failed: {exc}"
+    return "removed"
+
+
+def _strip_loomcode_section(content: str) -> str:
+    """Remove the ``_MARKER`` line + the ``exec ...`` line that
+    follows it. Preserves everything else in the hook file."""
+    lines = content.splitlines()
+    out: list[str] = []
+    skip_count = 0
+    for line in lines:
+        if skip_count > 0:
+            skip_count -= 1
+            continue
+        if line.strip() == _MARKER:
+            # Skip this line + the exec line that comes right
+            # after. Two-line block per ``install()``.
+            skip_count = 1
+            continue
+        out.append(line)
+    # Collapse any resulting double blank lines.
+    cleaned: list[str] = []
+    prev_blank = False
+    for line in out:
+        if not line.strip():
+            if prev_blank:
+                continue
+            prev_blank = True
+        else:
+            prev_blank = False
+        cleaned.append(line)
+    return "\n".join(cleaned).rstrip() + "\n"